Maxwell input file
Maxwell Input File
Input file variable description
Calculation mode and parallelization strategy
At the beginning of the input file, the basic option variable CalculationMode selects the run mode of Octopus and has always to be set. In case of a parallel run, there are some variables to set the proper parallelization options. For Maxwell propagation, parallelization in domains is possible, but parallelization in states is not needed, as there are always 3 or 6 states, depending on the Hamiltonian (see below).
# Calculation mode of the octopus run
CalculationMode = td
Multisystem setup
The Maxwell system is now implemented in Octopus' multisystem framework, which allows to calculate several different systems, which can interact with each other.
Currently implemented system types are:
- electronic: An electronic system. (only partly implemented)
- maxwell: A maxwell system.
- classical_particle: A classical particle. Used for testing purposes only.
- charged_particle: A charged classical particle.
- multisystem: A system containing other systems.
- dftbplus: A DFTB+ system
- linear_medium: A linear medium for classical electrodynamics.
Definition of the systems
In this tutorial, we will use a pure Maxwell system:
ExperimentalFeatures = yes
%Systems
'Maxwell' | maxwell
%
Subsequently, variables relating to a named system are prefixed by the system name. However, this prefix is not mandatory for calculations considering only one system.
Maxwell box variables and parameters
The Maxwell box is only defined as a parallelepiped box.
Maxwell options
The Maxwell options determine the Maxwell propagation scheme. First, the Maxwell propagation operator options consist of the type of MaxwellHamiltonianOperator, which can be set as a vacuum Maxwell-Hamiltonian (faraday_ampere) or a Maxwell-Hamiltonian in linear medium (faraday_ampere_medium).
Currently, the Maxwell system does not define its own propagator, but uses the system default propagator, defined in TDSystemPropagator. So far, only the exponential midpoint is implemented.
The Maxwell Boundary conditions can be chosen for each direction differently with MaxwellBoundaryConditions. Possible choices are zero and absorbing boundary conditions, as well as plane waves and constant field boundary conditions. Additionally to the boundary condition, the code can include absorbing boundaries. This means that all outgoing waves are absorbed while all incoming signals still arise at the boundaries and propagate into the simulation box. The absorbing boundaries can be achieved by a mask function or by a perfectly matched layer (PML) calculation with additional parameters. For more information on the physical meaning of these parameters, please refer to the Maxwell-TDDFT paper.
# ----- Maxwell calculation variables -----------------------
# Type of Maxwell Hamiltonian operator
# - faraday_ampere (3x3 for vacuum calculation)
# - faraday_ampere_medium (6x6 for medium calculation)
MaxwellHamiltonianOperator = faraday_ampere
# Options for the Maxwell derivative stencil and the exponential expanison of the time propagator
# - Maxwell.DerivativesStencil = stencil_star
# - Maxwell.DerivativesStencil = stencil_starplus
# - Maxwell.DerivativesStencil = stencil_cube
Maxwell.DerivativesStencil = stencil_starplus
Maxwell.DerivativesOrder = 4
Maxwell.TDExpOrder = 4
# Maxwell boundary conditions for each dimension
# - MaxwellBoundaryConditions = zero (Boundaries are set to zero.)
# - MaxwellBoundaryConditions = constant (Boundaries are set to a constant.)
# - MaxwellBoundaryConditions = mirror_pec (Perfect electric conductor.)
# - MaxwellBoundaryConditions = mirror_pmc (Perfect magnetic conductor.)
# - MaxwellBoundaryConditions = plane_waves (Boundaries feed in plane waves.)
%MaxwellBoundaryConditions
plane_waves | plane_waves | plane_waves
%
# Maxwell absorbing boundaries options
# - MaxwellAbsorbingBoundaries = not_absorbing (zero boundary condition)
# - MaxwellAbsorbingBoundaries = mask (Maxwell field is muliplied by a mask function)
# - MaxwellAbsorbingBoundaries = cpml (Maxwell PML with convolution method)
%MaxwellAbsorbingBoundaries
not_absorbing | not_absorbing | not_absorbing
%
# Absorbing boundary width for the Maxwell mask function (if using masked boundaries)
MaxwellABWidth = 5.0
# Parameters to tune the Maxwell PML (they have safe defaults)
# - numerical tests show best performance for MaxwellABPMLPower between 2 and 3
# - MaxwellABPMLReflectionError
MaxwellABPMLPower = 2.0
MaxwellABPMLReflectionError = 1e-16
Output options
The output option OutputFormat can be used exactly as in the case of TDDFT calculations, with the exception that some formats are inconsistent with a Maxwell calculation (like xyz). It is possible to chose multiple formats. The Maxwell output options are defined in the MaxwellOutput block (written to output_iter every MaxwellOutputInterval steps) and through the MaxwellTDOutput (written to td.general every step).
# ----- Maxwell output variables ----------------------------------------------------------------
# Maxwell output variables are written every MaxwellOutputInterval time steps into the output_iter folder
# %MaxwellOutput
# electric_field (electric field output)
# magnetic_field (magnetic field output)
# trans_electric_field (transverse electric field output)
# trans_magnetic_field (transverse magnetic field output)
# long_electric_field (longitudinal electric field output)
# long_magnetic_field (longitudinal magnetic field output)
# div_electric_field (divergence of the electric field output)
# div_magnetic_field (divergence of the magnetic field output)
# maxwell_vector_potential (vector potential output)
# poynting_vector (poynting vector output)
# maxwell_energy_density (electromagnetic energy density output)
# maxwell_current (electromagnetic current density on the Maxwell grid)
# external_current (external current density on the Maxwell grid)
# electric_dipole_potential (electric dipole potential output)
# electric_quadrupole_potential (electric quadrupole potential output)
# charge_density (electromagnetic charge density via div(E))
# %
%MaxwellOutput
electric_field
magnetic_field
%
# Output interval steps for the Maxwell variables. After MaxwellOutputInterval steps,
# the Maxwell variables on the grid are written into the output_iter folder
MaxwellOutputInterval = 1
# Output of the scalar Maxwell variables for each time step, written into the td.general folder
# - MaxwellTDOutput = maxwell_energy (electromagnetic and Maxwell-matter energies)
# - MaxwellTDOutput = maxwell_total_e_field (electric field at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_total_b_field (magnetic field at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_longitudinal_e_field (longitudinal electric at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_longitudinal_b_field (longitudinal magnetic field at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_transverse_e_field (transverse field at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_transverse_b_field (transverse field at all points given by MaxwellFieldsCoordinate)
# - MaxwellTDOutput = maxwell_mean_poynting (mean poynting vector in each direction)
# - MaxwellTDOutput = maxwell_poynting_surface (mean poynting vector of boundary surfaces)
MaxwellTDOutput = maxwell_energy + maxwell_total_e_field
# Coordinates of the grid points, which corresponding electromagnetic field values are
# written into td.general/maxwell_fields
%MaxwellFieldsCoordinate
0.00 | 0.00 | 0.00
1.00 | 0.00 | 1.00
%
Time step variables
The TDTimeStep option in general defines the time step used for each system. For the stability of the time propagation, it is recommended for Maxwell systems to always fulfill the Courant condition. In some cases larger time steps are possible but this should be checked case by case.
# ----- Time step variables ---------------------------------------------------------------------
TDSystemPropagator = exp_mid
# Time step of the propagation
# TDTimeStep should be equal or smaller than the Courant criterion, which is here
# S_Courant = 1 / (sqrt(c^2/dx_mx^2 + c^2/dx_mx^2 + c^2/dx_mx^2))
TDTimeStep = 0.002
# Total simulation time
TDPropagationTime = 0.4
Maxwell field variables
The incident plane waves can be defined at the boundaries using the MaxwellIncidentWaves block. This block defines the incoming wave type and complex electric field amplitude, and a Maxwell envelope function name, which must be defined in a separate block. Multiple plane waves can be defined, and their superposition gives the final incident wave result at the boundary. This plane waves boundaries are evaluated at each timestep, and give the boundary conditions for the propagation inside the box. To use them MaxwellBoundaryConditions must be set to “plane_waves” in the necessary directions.
The MaxwellFunctions block reads the additional required information for the plane wave pulse, for each envelope function name given in the MaxwellIncidentWaves block.
Inside the simulation box, the initial electromagnetic field is set up by the UserDefinedInitialMaxwellStates block. If the pulse parameters are such that it is completely outside the box at the initial time, this variables does not need to be set, as the default initial field inside the box is zero.
In case of MaxwellPlaneWavesInBox = yes
, the code uses the initial analytical plane wave values
also inside the simulation box. Hence, there is no Maxwell field propagation
and the values are set analytically.
# ----- Maxwell field variables -----------------------------------------------------------------
# Plane waves input block
# - Column 1: input method (in this example, a a predefined Maxwell function)
# - Column 2: electric field complex amplitude in the x- direction
# - Column 3: electric field complex amplitude in the y- direction
# - Column 4: electric field complex amplitude in the z- direction
# - Column 5: Maxwell function name
%MaxwellIncidentWaves
plane_wave_mx_function | Ex1 | Ey1 | Ez1 | "plane_waves_func_1"
plane_wave_mx_function | Ex2 | Ey2 | Ez2 | "plane_waves_func_2"
%
# Predefined Maxwell function
# - Column 1: Maxwell function name that corresponds to MaxwellIncidentWaves
# - Column 2: envelope function of the plane wave pulse
# - Column 3: wavevector component in x-direction
# - Column 4: wavevector component in y-direction
# - Column 5: wavevector component in z-direction
# - Column 6: pulse shift in x-direction
# - Column 7: pulse shift in y-direction
# - Column 8: pulse shift in z-direction
# - Column 9: pulse width
# kxl, kx2, ky1, ky1, ky2, kz1, kz2 = wavevectors in x,y,z-direction for EM fields 1 and 2
# psx1, psx2, psy1, psy2, psz1, psz2 = spatial shift of pulse 1 and 2 in x,y,z-direction
# pw1, pw2 = pulse width of pulse 1 and 2
%MaxwellFunctions
"plane_waves_func_1" | mxf_cosinoidal_wave | kx1 | ky1 | kz1 | psx1 | psy1 | psz1 | pw1
"plane_waves_func_2" | mxf_cosinoidal_wave | kx2 | ky2 | kz2 | psx2 | psy2 | psz2 | pw2
%
# Definition of the initial EM field inside the box:
# - Column 1: input type (formula, file or "use_incident_waves")
# If input type is formula or file:
# - Column 2: field component
# - Column 3: what kind of Maxwell field
# - Column 4: analytic formula or file input for the field component
%UserDefinedInitialMaxwellStates
use_incident_waves
%
# If incident plane waves should be used to calculate the analytical Maxwell field inside the simulation box (no propagation, only evaluation of the plane waves)
MaxwellPlaneWavesInBox = no
External current
An external current can be switched that adds an external current contribution to the internal current. Such an external current is calculated analytically by the UserDefinedMaxwellExternalCurrent block. This block defines the spatial profile and frequency of each external current contribution, and it sets an envelope function name, that must be defined in a separate TDFunctions block.
# ----- External current options ------------------------
# Switch on external current density
ExternalCurrent = yes
# External current parameters
# - Column 1: input option for the td function which is here a predefined function
# - Column 2: spatial distribution of the current in x-direction
# - Column 3: spatial distribution of the current in y-direction
# - Column 4: spatial distribution of the current in z-direction
# - Column 5: frequency of the temporal current density pulse
# - Column 6: name of the temporal current pulse envelope function
%UserDefinedMaxwellExternalCurrent
current_td_function | "jx(x.y,z)" | "jy(x,y,z)" | "jz(x,y,z)" | omega | "env_func"
%
# Function in time
# - Column 1: name of the envelope function
# - Column 2: function type
# - Column 3: amplitude
# - Column 4: envelope function width
# - Column 5: shift of the function f(t-t0)
# t0 = time shift of the current density signal
# tw = width of the current density signal in time
%TDFunctions
"env_func” | tdf_gaussian | 1.0 | tw | t0
%
Linear Medium
Different shapes of linear media can be included in the calculation either through a simple box, or through a file describing more complex geometries. For more information check the Linear Medium tutorial.