The input file is divided up into a number of sections dealing with various aspects of simulation design. Each section consists of a section header, contained in square brackets, followed by the input parameters belonging to that section. Sections are not required unless so noted.
[Title]
[Control]
[Grid]
[Regions]
[Objects]
[Boundaries]
[Objects] section
[Potentials]
[Materials]
[Medium Models]
[Objects] section
[Circuit Models]
[Volume Models]
[Liner Models]
[Subgrid Models]
[Substrate Models]
[External Fields]
[Particle Species]
[Particle Creation]
[Particle Collapse]
[Particle Migration]
[Particle Extraction]
fileread option
[Particle Interaction]
[Particle Diagnostics]
[Particle Targets]
[Functions]
[Probes]
Descriptions for the parameters for each of these sections follow. Except
for the [Control] section, the parameters must appear in the same order
as that given in the examples. Also, except for the [Control] section,
all parameters must appear, except those designated with an asterisk (*)
in the input examples, which are optional. The sections themselves may appear
in any order in the input file.
A good way to set up a simulation is to copy and edit the examples from this manual. Note that, while the keywords themselves must appear with the exact spelling indicated, their values, when alphanumeric, may appear as lowercase or uppercase or even mixed. The spelling of section headers must be exactly the same as shown: with individual words beginning in uppercase letters.
Blank lines and lines beginning with a semicolon `;' in the input file are ignored. A semicolon may be placed anywhere on a line to insert a comment. Everything after the semicolon on the line is ignored.
The order in which the input sections appear below is one possible order in which they might appear in an input file.
The [Title] section of the input file specifies a title to be
used in all output files for identification of the simulation. If not
specified, the default generic title used is: "LSP simulation". The
input file name and the time-stamp generated at the beginning of the
simulation run are appended to the title. The simulation title must be
contained within double quotes.
[Title] simulation_title "This is a title"
The [Control] section of the input file specifies the timestep,
simulation time, algorithmic and diagnostic parameters, etc. In this
section (and only this one), the parameters may be specified in any
order. All of these parameters are optional and are not required to run
a simulation. However, without some minimal parameters, such as a time
limit and a timestep specification, nothing meaningful would be
calculated. There are many parameters from which to select. The
parameters are listed alphabetically and discussed individually below.
[Control] courant_multiplier 0.9 time_limit_ns 20.0 time_bias_coefficient 0.5 time_bias_iterations 4 probe_interval 5 dump_interval_ns 10.0 particle_movie_interval 100 restart_interval_ns 10.0 number_of_processes 8 balance_interval_ns 1.0 load_balance_flag ON region_balance_flag OFF report_timing_flag ON rename_restart_flag ON
Any positive value of courant_multiplier will cause the code to determine
the simulation timestep by searching the grid for the smallest Courant-limited
timestep, assuming cartesian coordinates, and multiplying it by the value of the
courant_multiplier. In cylindrical coordinates (see section CYLINDRICAL), a value of about 0.9 or less is required for stability.
In cartesian coordinates, a value of 1 can be used. The input value for the
time_step parameter (see section time_step (real)) will take
precedence if it is smaller than the internally calculated value.
Number of timesteps for a simulation run. This parameter takes precedence over
time_limit if it is reached first. If it is used in a restart operation,
the simulation will execute that number of timesteps more from the
previous run unless the time_limit parameter is reached first. In other
words, on restarts, it is not the cumulative timestep count for the simulation,
but simply the number of timesteps executed for that run.
Options for this parameter are:
time_limit:
time_limit_ns:
time_limit_cm:
The value of number_of_steps, if it is reached first, takes precedence
over time_limit.
Options for this parameter are:
time_step:
time_step_ns:
time_step_cm:
If dump_restart_flag is ON, automatically dump the restart file(s)
at the end of the simulation, that is, at termination time (see section time_limit (real)).
Default: OFF
Maximum wall-clock time between restart dumps in hours.
Default: 1.e9 hours (i.e., infinite)
If rename_restart_flag is ON, alternate the filename extension on
successive restart dumps between .dat and .alt. This is a safety
measure in case the run is interrupted unintentionally during the output of the
restart dump. An uncorrupted restart dump will remain with only the amount of
calculation between those two restart dumps having been lost.
Default: OFF
Options for this parameter are:
restart_interval:
restart_interval_time:
restart_interval_ns:
restart_interval_cm:
Default: 1.e+9 (no dumps)
When running on a multiple-processor computer, LSP can move domain boundaries to rebalance the computational load among the processors. This parameter sets the interval at which the code checks to see if load balancing is needed. (see section load_balance_flag (flag) and section region_balance_flag (flag).)
Options for this parameter are:
balance_interval:
balance_interval_time:
balance_interval_ns:
balance_interval_cm:
Default: 1.e+9 (no rebalances)
If load_balance_flag is ON, check the load balance between
processes every balance_interval intervals (see section balance_interval (real)). The rebalance procedure, if needed, is performed
only within regions, rather than between regions
(see section region_balance_flag (flag)).
Default: ON
Number of processes to be used for the simulation. On a multiple-processor computer, each process is typically started on a different processor, if available. The number must be equal to the total number of domains into which the simulation space has been divided.
If region_balance_flag is ON, perform load balancing
across regions as well as within regions. This enables processes to
migrate between regions. The load_balance_flag must also be
ON for this option.
Default: OFF
If initial_balance_flag is ON, perform load balancing shortly
after run initialization, either at t=0, or when restarting a simulation. This
is useful in the latter case when changing the number of processes to be used,
or when the override_balance_flag is set to ON, that is, whenever
the simulation may not be in a balanced state. The load_balance_flag
must also be ON for this option.
Default: OFF
The override_balance_flag only effects restart runs from previously
generated restart dumps in which load-balancing has occurred.
If override_balance_flag is ON, any load-balancing information
on the restart file is ignored, and the simulation is continued in the domain
configuration specified on the input file. If the load_balance_flag is
left ON, however, load-balancing will continue at the next opportunity.
Default: OFF
Information on the CPU time taken for the field solution and the particle algorithm are accumulated over this interval prior to the load-balance evaluation, which depends on these data.
Default: 1
The value for the applied_current parameter is used to initialize the Y-
or Theta-component of magnetic fields in the simulation space. The primary use
of this parameter is in conjunction with the hysteresis volume model to
start the simulation with B and H fields at some values on the lower
end of the hysteresis curve (see section hysteresis).
Default: 0.0
This parameter is used in the quasi-neutral field solution to set the value
of the total background conductivity which is applied to electron currents.
(see section QUASINEUTRAL_FIELDS).
Default: 1.e13 in inverse seconds
This parameter is used in the quasi-neutral field solution to set the value
of the electron density in the background plasma. (see section QUASINEUTRAL_FIELDS).
Default: 1.e10 in number/cubic-centimeter
If cold_test_flag is ON, run the simulation without particles.
Any particle-creation statements in the input file are ignored.
Default: OFF
Maximum number of iterations to be used in any of the various iterative field
solutions. Fewer iterations are used when the solution satisfies the convergence
criterion. A warning message is usually printed if this limit is reached without
convergence. This parameter can be used instead of implicit_iterations
or potential_iterations.
Convergence criterion for any of the various iterative field solutions. Values
typically range from 1.e-3 to 1.e-7, possibly smaller, depending on the type of
field solution being used. This parameter can be used instead of
implicit_tolerance or potential_tolerance.
Default: 1.e-3
If dielectric_kill_flag is ON, kill any particles that impact a
dielectric material, whether it is a volume model (see section Volume Models Input)
or a medium model of method 0 (see section Medium Models Input).
Default: ON
Applies temporal smoothing to the electric field applied to particles.
The value, in the range 0--1, multiplies the old electric field.
This parameter should not be used with implicit particles, that is, when
the DIRECT_IMPLICIT compiler option is defined (see section DIRECT_IMPLICIT).
Default: 0.0 (no filtering)
Diffusion coefficient for spatial damping applied to electric field advance in the explicit field solver (Ref.[1]). Typical values are in the range 0.1 to 0.25.
Default: 0.0 (no filtering)
If field_advance_flag is OFF, run the simulation without
advancing the fields. Particles are created and advanced in whatever
fields exist when the simulation starts.
Default: ON
If field_initialization_flag is ON, initialize the fields with
one of the static solutions prior to temporal advancement with a dynamic field
solver. This can be useful for some simulations such as pre-setting a potential
across charged plates and then proceeding from that point with a fully
electromagnetic field solution. Use of this option is the only instance where
both the STATIC_FIELDS and DYNAMIC_FIELDS compiler options are
used concurrently (see section STATIC_FIELDS and
see section DYNAMIC_FIELDS).
Default: OFF
This parameter is used in the quasi-neutral field solution to set the value
of the conductivity which is applied to ion currents. This simply multiplies
the value of the electron conductivity, which is determined by the
background_electron_conductivity parameter above. Value should never be
zero. (see section QUASINEUTRAL_FIELDS).
Default: 1.0
Applies temporal smoothing to the magnetic field applied to particles.
The value, in the range 0--1, multiplies the old magnetic field.
This parameter should not be used with implicit particles, that is, when
the DIRECT_IMPLICIT compiler option is defined (see section DIRECT_IMPLICIT).
Default: 0.0 (no filtering)
Diffusion coefficient for spatial damping applied to magnetic field advance in the explicit field solver. Typical values are in the range 0.1 to 0.25.
Default: 0.0 (no filtering)
Used in 3-D cylindrical coordinates, to avoid the Courant instability limit on
the timestep due to small grid-spacing in the
(Y) coordinate near the axis. THETA dependence is dropped from
the field equations inside a radius defined by the small_radius_exclusion
value. Should be used with caution.
A time_bias_coefficient value of 0 gives the unbiased (explicit)
algorithm. Biasing causes the electromagnetic fields to damp at a rate
which increases with wavenumber. It can be useful in damping numerical
noise and instabilities (see Ref.[4]). The implicit equations are
solved iteratively.
Number of iterations to be used in time-bias algorithm. Usually, the
number of iterations needs to increase with the value of
time_bias_coefficient. Commonly used values are:
time_bias_coefficient time_bias_iterations
0.125 2-3
0.25 3-4
0.5 4-6
0.75 6-16
More iterations cause the field-solver to run slower.
Damping parameter in temporal filtering algorithm to suppress short-wavelength
electromagnetic fields (see Ref.[9]). Requires the
TEMPORAL_FILTER compiler directive (see section TEMPORAL_FILTER). A value of 0 recovers the undamped leapfrog
algorithm. This filtering is only appropriate in certain simulation conditions.
For example, it is never used with any static-fields solution. It can be used
with the explicit-fields solution only if time-biasing is not being used. It
can also be used with the "exact" version of the implicit-fields solution.
Default: 0.0 (no filtering)
Applies temporal smoothing of the error currents in the direct-implicit method. The range of this parameter is 0 to 1. Higher values give more smoothing and are generally recommended for higher density plasmas.
Default: 0.0 (no smoothing)
Initial acceleration factor for the ADI field solution. The code will adjust this parameter, if necessary, to help convergence.
Default: 0.0
Maximum number of iterations to be used in the ADI method of advancing fields.
Requires either the IMPLICIT_FIELDS or the DIRECT_IMPLICIT
compiler directive. The ADI field solver is used with the direct-implicit
particle push (Ref.[2]). See section DIRECT_IMPLICIT. Fewer iterations will be used if convergence is
reached. A warning message is printed if this limit is reached without
convergence. Also, a printout of the number of iterations used can be
obtained using the print_convergence_flag, or the iteration count
can be put onto the time history file by requesting a convergence
iterations probe (see section Convergence Probes). Iteration numbers greater
than 10 usually indicate a problem with convergence. In this case, reducing
the simulation timestep is recommended.
An adjustment parameter for the minimum value of omega (acceleration parameter) used in the ADI static field solution. The method is designed to cycle through values of omega which cover the theoretical range of eigenvalues associated with the discretization of the problem space. However, it has been found that this process can be optimized somewhat by raising the minimum value slightly, thereby narrowing the entire range of omegas used. This is done by specifying an adjustment parameter less than 1.0 and can only be determined by trial-and-error. A representative number found in an early investigation was 0.25.
Default: 1.0
Number of subcycles to be used in the ADI method of the static field solution.
Requires either the IMPLICIT_FIELDS or the DIRECT_IMPLICIT and
the STATIC_FIELDS compiler directives. This governs the spacing of omega
values which go into the static ADI solution during the iterative process. That
is, the higher the number of subcycles specified, then the more discrete values
of omega are used to cover the range of eigenvalues in the solution. The user
can increase this number if the ADI solution is not converging well.
Default: 4
Convergence criterion for the ADI field solution. The default value is 1.e-3,
but it is suggested that a more typical value to use would be around 1.e-5.
See section IMPLICIT_FIELDS.
Acceleration factor for the ADI field solution. The value should be between 1 and 2 for stability.
Default: 1.0 (no acceleration)
Maximum number of iterations to be used in the static field solution,
when the STATIC_FIELDS compiler directive has been defined
(see section STATIC_FIELDS). Fewer iterations will
be used if convergence is reached. A warning message is printed if this
limit is reached without convergence. Also, a printout of the number of
iterations used can be obtained using the print_convergence_flag,
or the iteration count can be put onto the time history file by requesting
a convergence iterations probe (see section Convergence Probes).
Convergence criterion for the static field solution (see section STATIC_FIELDS). The convergence criterion is that all non-zero
values of the potential must have a relative error of less than the
potential_tolerance value. A typical value is 1.e-5.
Number of timesteps between ionization events. This applies to all species that are being ionized (see section ionization).
Default: 1
Number of timesteps between scattering events, when the scattering model is
being used (see section SCATTERING_ON). Used for all
species. If the FLUID_PHYSICS compiler directive is defined, then
scattering_interval must be 1.
Default: 1
Number of timesteps between migrations of particles from kinetic to
fluid, when the fluid-physics model is being used
(see section FLUID_PHYSICS).
See section Particle Migration Input.
Default: 0
Used in the fluid model for a dense plasma (see section fluid_species_flag (flag)[optional]). At each timestep, the fluid-electron particle
momenta are averaged with this fraction of the ensemble momentum interpolated
from the grid. Smaller values (order < 0.01) can reduce numerical diffusion of
momentum and are recommended for ion species. Larger values (> 0.1) have a
stabilizing effect on grid noise and are recommended for electron species.
These can be set separately by using the fluid_electron_streaming_factor
and fluid_ion_streaming_factor keywords. The FLUID_PHYSICS
compiler directive must be invoked for this to have any effect
(see section FLUID_PHYSICS).
Defaults: 0.1 for electron species and 0.01 for ion species.
Used in the fluid model for a dense plasma
(see section fluid_species_flag (flag)[optional]). The heat flux
cannot exceed this fraction of the maximum possible flux carried by the
thermal distribution. This parameter is usually only important
for intense-laser plasmas. The FLUID_PHYSICS compiler directive must
be invoked for this to have any effect (see section FLUID_PHYSICS).
Default: 0.2
Number of timesteps between migrations of particles from fluid to
kinetic, when the fluid-physics model is being used
(see section FLUID_PHYSICS).
See section Particle Migration Input.
Default: 0
If pdv_term_flag is OFF, execute the fluid physics model
without the PdV heating term. Use only when the FLUID_PHYSICS
compiler directive is on (see section FLUID_PHYSICS).
Default: ON
If vcrossb_flag is ON, include the V-cross-B term in the
application of the air-chemistry conductivity model.
Default: ON
If surface_viscosity_flag is ON, the fluid pressure gradients
tangential to solid material surfaces are set to zero (full viscosity). The
pressure gradients normal to surfaces are always zero.
Default: ON
If moving_frame_velocity is non-zero, the moving frame-of-reference model
is put into effect. The velocity is in user units. In order to use this feature,
which models motion in the z-coordinate, the gridding in z must be strictly
uniform and no domain splits are permitted across that coordinate direction.
Default: 0.0
If moving_frame_start_time is non-zero, the moving frame-of-reference
model will begin at that simulation time. Until that time, the simulation will
proceed as if stable before moving at the velocity indicated above.
Default: 0.0
If dump_accelerations_flag is ON, output fluid accelerations
to the vector fields dump file for each species. The SCATTERING_ON
compiler directive must be invoked for these quantities to be available,
otherwise no values are written (see section SCATTERING_ON).
Default: OFF
If dump_bfield_flag is ON, output magnetic fields to the vector
fields dump file.
Default: ON
If dump_charge_density_flag is ON, output particle charge densities to
the scalar dump file. The CHARGE_DENSITY compiler directive is needed
to generate these quantities (see section CHARGE_DENSITY).
If no values are available, nothing is written to the dump file.
Default: OFF
If dump_conductivity_flag is ON, output conductivities to
the fields dump file. The USE_CONDUCTIVITY compiler directive is needed
to generate these quantities (see section USE_CONDUCTIVITY).
If no values are available, nothing is written to the dump file.
Default: OFF
If dump_current_density_flag is ON, output particle current densities to
the vector fields dump file.
Default: OFF
If dump_energy_deposition_flag is ON, output tenuous medium energy loss
to the scalar dump file. If none are available, no values are written.
Default: OFF
Dump intervals for field, particle, extraction, and diagnostic data. The
intervals for each of these can be specified independently using the
field_dump_interval, particle_dump_interval,
extraction_dump_interval, and diagnostic_dump_interval
keywords, respectively. These specific intervals default to the value
of dump_interval. Each of these keywords has the same alternate
forms as those for dump_interval, shown below.
Options for this parameter are:
dump_interval:
dump_interval_time:
dump_interval_ns:
dump_interval_cm:
Default: 1.e+9 (no dumps)
If dump_montecarlo_diagnostics_flag is ON, output nu*dt
distributions for the montecarlo energy loss particle scattering model
to the diagnostic dump file. If none are available, no values are written.
This option is relevant only when the montecarlo_scattering_flag has
been defined for some particle species and the appropriate interaction file
has been provided in the [Particle Interaction] section of input
(see section Particle Interaction Input). Also, the SCATTERING_ON compiler
directive must be defined in order for this option to be relevant
(see section SCATTERING_ON).
Default: OFF
If dump_number_densities_flag is ON, output particle number
densities to the scalar dump file. The NUMBER_DENSITIES compiler
directive is needed to generate these quantities
(see section NUMBER_DENSITIES).
If no values are available, nothing is written to the dump file.
Default: OFF
If dump_ohmic_quantities_flag is ON, output quantities associated
with the ohmic medium model to the scalar dump file. If no values are available,
nothing is written to the dump file. These quanitities are generated when the
conductivity option is used in a method 0, method 1 or
method 4 medium of the TENUOUS type (see section conductivity (flag)[optional]). The quantities related to the ohmic medium
model include the background plasma electron density, the momentum transfer
frequency (in inverse seconds), the plasma electron temperature (in eV), and
the resulting conductivity. The USE_OHMIC_TERMS compiler directive is
required to generate these quantities (see section USE_OHMIC_TERMS). If no values are available, nothing is written to
the dump file.
Default: OFF
If dump_plasma_quantities_flag is ON, output plasma densities,
temperatures, and collision frequencies, by species, to the scalar dump file.
The SCATTERING_ON compiler directive must be defined to obtain
non-zero values (see section SCATTERING_ON). If no values
are available, nothing is written to the dump file.
Default: OFF
If dump_potential_flag is ON, output electric potentials to
the scalar dump file. If none are available, no values are written.
Default: OFF
If dump_rbtheta_current_flag is ON, output the product
to the scalar dump file. The CYLINDRICAL or CYL_R_Z compiler
directive must be defined in order for this to be used (see section CYLINDRICAL or section CYL_R_Z). Units are amperes.
Default: OFF
If dump_rho_background_flag is ON, output the result of the
so-called rho-background evaluation to the scalar dump file. This calculation
shows the divergence of the electric field minus rho, which is a measure of
charge conservation. The CHARGE_DENSITY compiler directive is required
to generate these quantities (see section CHARGE_DENSITY).
If no values are available, nothing is written to the dump file.
Default: OFF
Specifies discrete timesteps at which dumps are output. These dumps will be produced in addition to those generated by any of the regular intervals used.
The list of timesteps is terminated by an end keyword, e.g.,
dump_steps 100 1000 5000 20000 end
Dump steps for field, particle, extraction, and diagnostic data can be specified
independently using the field_dump_steps, particle_dump_steps,
extraction_dump_steps, and diagnostic_dump_steps keywords. They
also have the same alternate forms as dump_steps above. Any use of them
will add to the list of generically specified steps for those dumps.
If dump_substrates_flag is ON, output substrate
temperature and sorbate-to-metal ratio. If more than one instance of
the substrate model is present, they are added on to the same
file. These files are dumped at intervals given by the
diagnostic_dump_interval or its associated parameters
(see section dump_interval (integer)).
Default: OFF
If dump_surface_depositions_flag is ON, output accumulated surface
charge, temperature, and/or energy deposited by particles (the compiler
directives CHARGE_DEPOSITION, KELVIN_DEPOSITION, and/or
ENERGY_DEPOSITION must be on) periodically to surface deposition dumps
(see section Compiler Directives). These can be viewed with the P4 postprocessor
(see section P4 Postprocessor). If no depositions are invoked with a compiler
directive, no files are written. These files are dumped at intervals given by
the diagnostic_dump_interval or its associated parameters
(see section dump_interval (integer)).
Default: OFF
Specifies discrete times at which dumps are output. These dumps will be produced in addition to those generated by any of the regular intervals used.
Options for this parameter are:
dump_times:
dump_times_ns:
dump_times_cm:
The list of times is terminated by an end keyword, e.g.,
dump_times_ns 0.5 2.0 10.0 30.0 end
Dump times for field, particle, extraction, and diagnostic data can be specified
independently using the field_dump_times, particle_dump_times,
extraction_dump_times, and diagnostic_dump_times keywords. They
also have the same alternate forms as dump_times above. Any use of them
will add to the list of generically specified times for those dumps.
If dump_velocities_flag is ON, output fluid mean velocities
to the vector fields dump file for each species. The SCATTERING_ON
compiler directive must be invoked for these quantities to be available,
otherwise no values are written (see section SCATTERING_ON).
Default: OFF
If extract_photons_flag is ON, output photons produced by the
Monte Carlo transport model to a binary file. A method 4 medium model
must be active for this to happen. The format for this data is defined in the
section under "File Formats" (see section Primary Output Data File). The data is
broken up onto separate files, depending on the extraction_dump_interval
or its related control parameters.
Default: OFF
If extract_primaries_flag is ON, output primaries going into the
Monte Carlo transport model to a binary file. A method 4 medium model
must be active for this to happen. The format for this data is defined in the
section under "File Formats" (see section Primary Output Data File). The data is
broken up onto separate files, depending on the extraction_dump_interval
or its related control parameters.
If extract_secondaries_flag is ON, output secondaries produced by
the Monte Carlo transport model to a binary file. A method 4 medium model
must be active for this to happen. The resulting data is used only for creation
of secondaries within the simulation and is not intended for post-processing,
as the data is lost after secondary particle creation. See section Particle Creation Input.
Default: OFF
Specifies the field components to be output to the field movie dumps. These
can be EX|EY|EZ|BX|BY|BZ|JX|JY|JZ|SX|SY|SZ, where E represents
electric field, B magnetic field, J current density, and S
conductivity. An example is:
field_movie_components Ex Ez By
Specifies the direction normal to the plane from which data are
extracted from a 3-D simulation to make a 2-D field component movie, and the
coordinate value of the plane. The direction can be X|Y|Z. This
parameter is ignored in 1-D or 2-D simulations. An example is:
field_movie_coordinate Y 3.14
Options for this parameter are:
field_movie_interval:
field_movie_interval_time:
field_movie_interval_ns:
field_movie_interval_cm:
Default: 1.e+9 (no dumps)
Specifies the particle components to be output to the particle movie dumps.
These can be Q|X|Y|Z|VX|VY|VZ (charge, position, and velocity).
An example is:
particle_movie_components x y z
which is the default.
Options for this parameter are:
particle_movie_interval:
particle_movie_interval_time:
particle_movie_interval_ns:
particle_movie_interval_cm:
Default: 1.e+9 (no dumps)
Specifies the type of output format to be used in the photon output data dumps.
This can have the values ASCII or BINARY. The ASCII format
is useful for reading printed output directly or for plotting with a graphical
output utility such as gnuplot. The BINARY format is intended for more
compact files to be post-processed by an appropriate utility. An example is:
photon_output_format ASCII
Default: BINARY
Specifies the type of output format to be used in the output data dumps of
primaries entering the ITS (method 4) medium model.
This can have the values ASCII or BINARY. The ASCII format
is useful for reading printed output directly or for plotting with a graphical
output utility such as gnuplot. The BINARY format is intended for more
compact files to be post-processed by an appropriate utility. An example is:
primary_output_format ASCII
Default: BINARY
Number of timesteps between probe samples on the time-history file.
Default: 1
Specifies the scalar quantities to be output to the scalar movie dumps. These can be selected from the following options:
potential:
STATIC_FIELDS compiler
directive be defined (see section STATIC_FIELDS).
charge_density:
CHARGE_DENSITY compiler
directive be defined (see section CHARGE_DENSITY).
number_densities:
NUMBER_DENSITIES compiler
directive be defined (see section NUMBER_DENSITIES).
energy_deposition:
ENERGY_DEPOSITION
compiler directive be defined (see section ENERGY_DEPOSITION).
plasma_quantities:
SCATTERING_ON compiler directive be defined
(see section SCATTERING_ON).
ohmic_quantities:
USE_OHMIC_TERMS compiler directive be defined (see section USE_OHMIC_TERMS).
rbtheta_current:
CYLINDRICAL or CYL_R_Z
compiler directive must be defined (see section CYLINDRICAL).
rho_background:
CHARGE_DENSITY compiler directive is required to
generate these quantities (see section CHARGE_DENSITY).
An example is:
scalar_movie_components number_densities
The default is no scalar components selected.
Specifies the direction normal to the plane from which data are
extracted from a 3-D simulation to make a 2-D scalar movie, and the
coordinate value of the plane. The direction can be X|Y|Z. This
parameter is ignored in 1-D or 2-D simulations. An example is:
scalar_movie_coordinate Z 12.5
Options for this parameter are:
scalar_movie_interval:
scalar_movie_interval_time:
scalar_movie_interval_ns:
scalar_movie_interval_cm:
Default: 1.e+9 (no dumps)
Spatial skip interval for the x-coordinate direction in field dumps and scalar dumps. Used to reduce the size of data dumps.
Default: 1 (no skipping)
Spatial skip interval for the y-coordinate direction in field dumps and scalar dumps. Used to reduce the size of data dumps.
Default: 1 (no skipping)
Spatial skip interval for the z-coordinate direction in field dumps and scalar dumps. Used to reduce the size of data dumps.
Default: 1 (no skipping)
Specifies the type of output format to be used for the structure output data
dump, which contains information on all conductor and dielectric structures in
the simulation space. This can have the values ASCII or BINARY.
The ASCII format is useful for reading printed output directly or for
plotting with a graphical output utility such as gnuplot. The BINARY
format files are more compact and are intended for examination using the P4
postprocessor (see section P4 Postprocessor). The ASCII format file will
have the name `struct.dat' to distinguish it from the BINARY
version, which will have the name `struct.p4'. An example is:
structure_output_format ASCII
Default: BINARY
This parameter, when used, will cause a different kind of output from the usual target dumps. That is, because it is a movie interval, it is intended to be quite short, and all the data is output sequentially onto a single file while being refreshed after each dump, so that the resulting data can be treated as a "streak image" when displayed properly. Note that, while the usual target dumps described for target models (see section Particle Targets Input) will still appear, they will not contain cumulative data and therefore may not be useful.
Options for this parameter are:
target_movie_interval:
target_movie_interval_time:
target_movie_interval_ns:
target_movie_interval_cm:
Default: infinite (no dumps)
Specifies the type of output format to be used in the target model data dumps.
This can have the values ASCII or BINARY. The ASCII format
is useful for reading printed output directly or for plotting with a graphical
output utility such as gnuplot. The BINARY format is intended for
examination using the P4 postprocessor (see section P4 Postprocessor). The
ASCII format file names will have the suffix `dat' to distinguish
them from the BINARY versions, which will have the extension `p4'.
An example is:
target_output_format BINARY
Default: BINARY
If domain_boundary_check is ON, checks boundary cells to
ensure that a boundary condition has been set. If cells without boundary
conditions are found, the simulation stops with a printed message
indicating the area which is at fault.
Default: ON
If particle_cyclotron_check is ON, all particles are examined to
ensure that their cyclotron frequency does not exceed the orbital limit for the
timestep being used, about 1/6th of a complete orbit. When a violation occurs,
the simulation stops with a message indicating the domain which is at fault.
Default: OFF
If particle_motion_check is ON, all particles are examined
to ensure that their linear motion in one timestep does not exceed cell sizes.
When a violation occurs, the simulation stops with a message indicating the
domain which is at fault.
Default: OFF
If print_control_flag is ON, write the control data structure
to standard output.
Default: OFF
If print_convergence_flag is ON, write convergence
information for iterative field algorithms to standard output.
Default: OFF
If print_grid_flag is ON, write grid coordinates and spacing
to standard output.
Default: OFF
If print_region_flag is ON, write region parameters to standard
output.
Default: OFF
If dump_timing_flag is ON, output immediate CPU (wall-clock)
run-time performance data for all domains onto a history file with the name
`histcpuN.p4', where N is an integer. This data is divided into
categories for field solution, particle solution, and communication (data
exchange) between processes. The value of N will be 1 at the beginning
of a simulation, and a new and different file will be opened each time that a
restart run is performed, each with an incremented value of N. Thereby,
all of the timing files are automatically preserved through subsequent restarts
of a complete simulation. All timing data are in seconds.
Default: OFF
If report_timing_flag is ON, include cumulative CPU (wall-clock)
run-time performance data in the reports for all domains. Shown are timing
measurements in various categories including field solution, particle solution,
diagnostics, and inter-process communication. In addition, the total time is
included, which will be slightly greater than the sum of the sub-categories
due to start-up time. All timing data are in seconds.
Default: OFF
The [Grid] section of input defines the overall simulation space and
the grid-spacing within it. More than one grid may be specified, but along
the common boundary between any two grids, the grid-points must match up.
The coordinate system used for the spatial grid is determined by compiler
directives. Cartesian, cylindrical, or spherical coordinates may be used,
in 1, 2, or 3 dimensions. The relevant compiler directive options are
CARTESIAN, CAR_ONE, CAR_X_Y, CAR_X_Z,
CYLINDRICAL, CYL_ONE, CYL_R_Z, CYL_R_TH,
SPHERICAL, SPH_ONE, and SPH_R_TH. The default is 3-D
cartesian coordinates.
When more than one grid is specified, they should be numbered consecutively in the input file, each beginning with an identifier in this format:
gridN
where each `N' is a unique identification number. When only one grid is present, this line is not required.
The lines that follow describe the grid dimensions and spacing in the three coordinate directions:
xmin XMIN xmax XMAX x-cells NX ymin YMIN ymax YMAX y-cells NY zmin ZMIN zmax ZMAX z-cells NZ
where `XMIN', `XMAX', `YMIN', `YMAX', `ZMIN',
`ZMAX' are the coordinate limits of the grid, and `NX', `NY',
`NZ' are the number of cells in each direction. In cylindrical and
spherical coordinates, `x' can be replaced by `r' and `y'
can be replaced by `th', denoting theta. In spherical coordinates,
`z' can be replaced by `phi'.
Spatial dimensions are in units of length, except for rotational coordinates
(the y or th coordinates in cylindrical or spherical geometries
and the z or phi coordinates in spherical geometry), which are
in radians. The units of length are dependent upon which system of units has
been specified by the user (see section User Units). For 1-D and 2-D simulations,
those coordinates not used in the simulation (called virtual coordinates) are
ignored and are not required in the definition of the grid.
There is the option, called non-uniform gridding, which allows the cell-size
to vary in a piecewise linear manner along any of the three coordinates. For
example, a series of intervals are specified by stating the xmin and
xmax and the number of cells in each interval. The code uses this
information to complete the grid.
An example of the format for the x coordinate is:
xmin XMIN xmax XMAX x-cells NX dx-start DX x-intervals length L1 for N1 length L2 for N2 ... ... end
where `DX' is the size of the first cell at `XMIN',
`L1' is the length of the first interval, with `N1' cells, etc.
The sum of the lengths `L1+L2+...' must add up to `XMAX-XMIN' in
this case, and the sum of the cells `N1+N2+...' must add up to `NX'.
The cell-size at the start of each successive interval matches that at the end
of the preceding interval, although a new dx-start may be introduced at
any point in the sequence of intervals.
A complete example of the [Grid] input section for a 3-D simulation with
non-uniform spacing could look like this:
[Grid] grid1 xmin 0.0 xmax 0.5 x-cells 35 dx-start 0.01 x-intervals length 0.2 for 20 length 0.3 for 15 end ymin -0.5 ymax 0.5 y-cells 70 dy-start 0.03 y-intervals length 0.3 for 15 length 0.4 for 40 length 0.3 for 15 end zmin 0.0 zmax 2.1 z-cells 110 dz-start 0.042 z-intervals length 1.3 for 50 dz-start 0.01 length 0.4 for 40 length 0.4 for 20 end
The [Regions] section describes the way that the simulation space is to
be broken up into zones or domains for individual processing. The decomposition
of the simulation space into regions and domains is described in
section Introduction. When more than one domain or region is required in a
simulation, the compiler directive MULTI_PROCESS must be defined, since
a separate process (task) is needed for each domain (see section MULTI_PROCESS).
Multiple regions are numbered consecutively in the input file:
region1 ... region2 ... region3 ...
Each region (assuming 3-D) has the following format:
region1 xmin XMIN xmax XMAX ymin YMIN ymax YMAX zmin ZMIN zmax ZMAX number_of_domains NDOM split_direction DIR number_of_cells NCELLS
where `XMIN', `XMAX', `YMIN', `YMAX', `ZMIN',
`ZMAX' are the coordinate limits of the region, and should not exceed the
limits of the defined grid in the [Grid] section of input.
In cylindrical and spherical coordinates, x can be replaced by r
and y can be replaced by th. In spherical coordinates, `z'
can be replaced by `phi'. Spatial dimensions are in units of length,
except for rotational coordinates (the y or th coordinates in
cylindrical or spherical geometries and the z or phi coordinates
in spherical geometry), which are in radians. The units of length are dependent
upon which system of units has been specified by the user (see section User Units).
For 1-D and 2-D simulations, the coordinates not used in the simulation are
ignored and are not required in the definition of the grid. All coordinates are
optional and if any do not appear, the region will inherit values from the grid
to which it belongs. However, the user should be careful not to create any
ambiguities in the way regions are defined in relation to the defined grid.
The final part of the region input specifies how the region is divided into
domains. For these parameters, `NDOM' is the number of domains into which
the region is subdivided and `DIR' gives the coordinate direction along
which the region is divided into domains, and can have the values X|Y|Z.
The number_of_cells parameter is either a list of the number of cells
thickness for each domain, or simply has the value auto, in which case
the code divides the number of cells along the split direction as evenly as
possible among the domains. If a list of numbers is given, there must be one
per domain, and they must add up to the total number of cells in the split
direction of the region. This may be difficult to use if that number is not
known. The minimum value for the number of cells in any linear dimension of a
domain that can be used depends on the field solution method being used. For
example, with the explicit field solver, the smallest value is limited to 3
cells. With the implicit field solver or any of the static solutions, the
number is 2. If the number_of_domains parameter has a value of 1 or is
not present, the split_direction and number_of_cells parameters
are not required.
If load-balancing within regions is turned on (see section load_balance_flag (flag)), then the code will adjust the number of cells in each domain as needed to try to get a more even distribution of the computational load. If load-balancing between regions is turned on (see section region_balance_flag (flag)), then the code will, in addition, move processes from one region to another as needed.
The number of domains, but not the number of regions, can be altered from input
prior to a restart as long as the compiler directive MULTI_PROCESS was
defined to begin with (see section Running LSP). Doing so, however, may cause the
simulation to run in an unbalanced state until the next load-balance occurs.
The sizes and distribution of domains can also be altered. However, manually
setting the domain configuration from input prior to a restart requires that
either the automatic load-balance algorithm be turned off, or that the
override_balance_flag is set to ON (see section override_balance_flag (flag)).
Material structures can be created within the simulation grid using geometric
shapes specified in the [Objects] section of the input file. Complex
shapes can be built by adding conducting and nonconducting (vacuum or material)
objects together. The effect of a list of successive objects is cumulative:
an object defines the cells within its boundaries to have specified properties,
overriding any properties set by objects which appear before it in the list.
This is a versatile model, but is not a full Computational Solid Geometry (CSG)
model.
Each object has a conductor flag associated with it, and may also have a
medium (see section Medium Models Input) and electrostatic potential assigned to it.
For an outlet boundary the potential values are specified by the
potentials parameters in the outlet boundary input (see section Outlet Boundaries). If the electrostatic field solver is used (see section STATIC_FIELDS), the potential values are specified in the
[Potentials] section of the input file (see section Potentials Input).
Note: In order to set guard-cell properties, conducting objects
within the simulation space which are in contact with the boundary must
be extended through the boundary to encompass the two guard cells at each
boundary, rather than stopping at the boundary. The converse applies when
the SOLID object qualifier (see section SOLID) is used to
make the entire space conducting: in that case, subsequent nonconducting
objects within the simulation space which are in contact with the boundary
should be extended through the boundary, into coordinates outside
the simulation space in order to create an opening, if that is the desired
result. Otherwise, the effect is such that a conducting wall remains at that
boundary of the simulation space.
Objects should be numbered consecutively in the input file as a matter of good practice for determining where errors occur (the code uses these index numbers when reporting input errors). The objects are processed by the code in the order that they appear in the input file, regardless of index numbering. The beginning of each object has the format
objectN SHAPE conductor on|off medium M * potential P *
where `N' is the object number, `SHAPE' is the geometric
shape, `M' an integer indicating the associated medium (0 for none),
and `P' an integer indicating the associated potential (0 for none). The
medium and potential parameters are optional with default values of 0.
In addition to the sequence of objects listed in the Objects Input section,
there may appear the keywords intersect and end inserted around
any group of objects. This causes those objects to be collectively combined
as an intersection, resulting in a material structure only where they overlap.
All of the objects in an intersected group must therefore have exactly the same
attributes listed above, which are, the conductor flag, medium identifier, and
potential index. The object types FOIL and WIRE cannot appear in
these intersections.
Example:
object1 BLOCK conductor on potential 1 ... intersect object2 SPHERE conductor on medium 1 ... object3 BLOCK conductor on medium 1 ... end object4 BLOCK conductor off ...
Here, objects 2 and 3 are intersected to produce a hemisphere of a conducting material described by the medium of index 1.
Some shapes (BLOCK and FOIL) define grid-conformal objects and
so depend completely on which coordinate system (cartesian, cylindrical, or
spherical) has been defined for the simulation. Other shapes (CONE,
PARABOLOID, PARALLELEPIPED, SPHERE, TORUS) are
independent of the geometry, while two of the shapes (TRILATERAL and
QUADRILATERAL) describe two-dimensional polygons which are swept through
the third dimension to make a complete solid figure. The FUNCTION
designation depends completely on the defined coordinate system.
One option, SOLID, is not a shape itself, but is used to set conductor,
medium and potential flags for the entire simulation grid. If used, it should
be the first object, since otherwise it will override all previously defined
objects. It is usually followed by objects which "hollow out" a cavity by
virtue of the conductor off feature.
When it is necessary to construct a series of similar shapes, it is possible to use additional instructions after an object to repeat the object a number of times, translated by some constant distance in succession. The format is:
repeat N times, with X Y Z
where `N' is the number of additional objects generated and
`X Y Z' is the spatial translation vector to be used each time. The object
types SOLID and FUNCTION can not be repeated and the repetition
construct can not appear within an intersection construct.
object4 BLOCK conductor on potential 0 from 2.0 0.0 0.0 to 5.0 0.0 1.5 repeat 5 times, with 0.0 0.0 5.0
The shapes and their associated parameters
A grid-conformal block. In cartesian coordinates, this is a rectangular
region. In cylindrical or spherical geometries, it may appear wedge-shaped.
The from, to parameters give the lower and upper limits
in each of the three coordinates, respectively. (Coordinate-system dependent shape).
object1 BLOCK ; central conductor conductor on medium 0 potential 0 from 0.0 -1.0 4.82 to 5.6 1.0 10.33
Defines a generalized cone with a circular base whose center is at the location
defined by the base parameter while the apex parameter defines
the location of the apex, and the edge parameter defines a point on the
edge of base such that the base, apex, and edge points
define a plane perpendicular to the plane of the base. (Coordinate-system independent shape).
object3 CONE ; conical cathode conductor on medium 0 potential 0 base 0.0 0.0 0.0 apex 0.0 0.0 4.0 edge 1.0 0.0 0.0
Defines a cylinder with the center of the base at the base
coordinates, and with the specified height and radius
values. The cylinder's orientation is given by the polar_angle and
azimuthal_angle parameters, whose format is
polar_angle|azimuthal_angle AXIS ANGLE
where `AXIS' can be X|Y|Z and the `ANGLE' is in
degrees. This orientation is performed in cartesian coordinates, even if the
simulation coordinates are non-cartesian. The two axes must not be the same.
Optionally, a cylindrical section can be constructed by the presence of two
parameters, start_angle and sweep_angle, which indicate a
possibly limited extent in the cylinder. This angle is assumed to be zero in
the direction of the azimuthal `AXIS' after rotation. (Coordinate-system independent shape).
object4 CYLINDER ; beam pipe conductor off medium 0 potential 0 base 0.0 0.0 -1.0 polar_angle Z 0.0 azimuthal_angle X 0.0 height 10.0 radius 0.49 start_angle 0 sweep_angle 360 *
Defines a thin foil. One of the from coordinates must be the same
as the to coordinate, i.e., the values define a planar
surface. This shape must be a conductor. It cannot be associated with a
medium model. In order to use a medium model for particle scattering
purposes, the BLOCK shape should be used with a thickness of at
least one cell. (Coordinate-system dependent shape).
object62 FOIL ; thin foil anode conductor on potential 0 from 23.0 0.0952 56.67 to 23.0 0.2856 69.67
Allows the user complete generality in defining structural shapes. The index
of the function defined in the [Functions] section of input to be used
directly follows the FUNCTION keyword. The only requirement is that the
function must have at least the same number of independent variables as there
are real dimensions in the simulation grid so that the resulting shape is well
defined. The material properties will be defined in cells where the function
has a positive value. Although the function is assumed to use the coordinate
values of the simulation coordinate grid as the independent variables, there
is an option to cause the function to utilize transformed cartesian coordinates
as the input variables. The optional keyword is `coordinates' followed
by either `cartesian' or `default' in the position shown in the
example. (See section Functions Input.)
object8 FUNCTION 4 coordinates default * conductor on medium 2
Defines a paraboloid with the tip at the origin coordinates, and with
the specified height and radius values at the large end. The
orientation is given by the polar_angle and azimuthal_angle
parameters, whose format is
polar_angle|azimuthal_angle AXIS ANGLE
where `AXIS' can be X|Y|Z and the `ANGLE' is in
degrees. This orientation is performed in cartesian coordinates, even if the
simulation coordinates are non-cartesian. The two axes must not be the same.
The resulting orientation vector points from the origin to the large end. (Coordinate-system independent shape).
object9 PARABOLOID conductor on medium 0 potential 0 origin 5.0 0.0 0.0 polar_angle Z 0.0 azimuthal_angle X 0.0 height 8.0 radius 3.0
Defines a parallelepiped using the from coordinates as one of the
corners, and three sets of to coordinates which give the end-points of
the three edges that extend from that corner. (Coordinate-system independent shape).
object6 PARALLELEPIPED ; cathode conductor on medium 1 potential 0 from -1.0 -1.0 2.5 to 1.0 -1.0 2.5 to -1.0 1.0 0.5 to -1.0 -1.0 5.0
Defines a 2-D triangle which is then swept in the direction normal to the plane
in which it lies. This figure is specified using three sets of coordinates,
the first designated by the from keyword followed by two to sets
of coordinates, defining the three corners of the triangle, and finally the
designated sweep direction (X|Y|Z). This is a little redundant but is
meant to emphasize the fact that the result is a solid three-dimensional figure.
(Coordinate-system dependent shape).
object3 TRILATERAL conductor on medium 0 potential 0 from 10.0 0.0 0.0 to 5.0 0.0 0.0 to 10.0 0.0 3.75 sweep_direction Y
Defines a 2-D quadrilateral which is then swept in the direction normal to
the plane of the quadrilateral. The quadrilateral is specified using the
from coordinates to give one of the corners, followed by three sets
of to coordinates giving the other three corners in the order:
adjacent corner, opposite corner, adjacent corner. (Coordinate-system dependent shape).
object2 QUADRILATERAL ; upper anode conductor on medium 0 potential 0 from 15.0 0.0 10.0 to 5.6 0.0 11.33 to 5.6 0.0 14.33 to 15.0 0.0 14.33 sweep_direction Y
The SOLID option is not a shape per se. Its purpose is to set
conductor, medium and potential flags for the entire simulation grid. One
possibility is to set the entire grid to conducting, thereby
avoiding the need to define conducting objects to set conducting
boundary conditions. Vacuum spaces can then be carved out using
conductor off flags. If SOLID is used, it should be the
first object, since otherwise it will overwrite all previously defined flags.
object1 SOLID ; set all cells to conductors conductor on medium 0 potential 0
Defines a sphere with the center and radius parameters.
(Coordinate-system independent shape).
object2 SPHERE ; cathode electrode conductor on medium 0 potential 0 center 0.0 1.0 2.0 radius 0.5
Defines a torus with the center, major_radius and
minor_radius parameters. The torus's orientation is given by the
polar_angle and azimuthal_angle parameters, whose format is
polar_angle|azimuthal_angle AXIS ANGLE
where `AXIS' can be X|Y|Z and the `ANGLE' is in
degrees. This orientation is performed in cartesian coordinates, even if the
simulation coordinates are non-cartesian. The two axes must not be the same.
Optionally, a toroidal section can be constructed by the presence of two
parameters, start_angle and sweep_angle, which indicate a
possibly limited extent in the torus. This angle is assumed to be zero in
the direction of the azimuthal `AXIS' after rotation. (Coordinate-system independent shape).
object5 TORUS conductor on medium 0 potential 0 center 9.0 0.0 3.0 polar_angle Z 30.0 azimuthal_angle X 0.0 major_radius 2.0 minor_radius 0.7 start_angle -90 sweep_angle 180 *
Defines a thin wire. Two of the from coordinates must be the same as
the corresponding to coordinates, i.e., the values define a conformal
one-dimensional object. This object must be a conductor. It cannot be associated
with a medium model. This should not be used as an accurate model for a specific
inductance. As an approximation, the characteristic cross-section of such an
object is on the order of the grid spacing containing it. (Coordinate-system dependent shape).
object62 WIRE ; thin connector conductor on potential 0 from 2.5 0.0 12.0 to 2.5 0.0 18.0
A boundary is defined as a grid-conformal surface which coincides with an
outer surface of the simulation space. Except for the r=0 axis in cylindrical
coordinates and the polar axis in spherical coordinates, boundary conditions
must be explicitly defined by the user at each grid boundary.
Conducting boundaries are created using conducting objects which cover the
desired area, or by using the SOLID object to make all cells
conducting. In order to set guard-cell properties, conducting objects
within the simulation space which are in contact with the boundary need to
extend through the boundary to encompass the two guard cells, rather than
stopping at the boundary (see section Objects Input). The converse applies when
the SOLID object qualifier (see section SOLID) is used to
make the entire simulation space conducting: in that case, subsequent
nonconducting objects within the simulation space which are in contact with
the boundary need to extend through the boundary in order for nonconducting
boundary conditions to be used. A nonconducting boundary must be an Outlet,
Symmetry, Periodic, or Freespace boundary. The type must be specified in
the [Boundaries] section of the input file: it is not sufficient
to put a nonconducting object through the boundary.
If the control variable domain_boundary_check is ON
(see section domain_boundary_check (flag)), the code
checks that a boundary condition has been defined for each boundary cell.
An outlet boundary is a port which allows electromagnetic waves to leave the simulation space, and optionally allows user-specified waves to enter.
Example of a purely outgoing wave absorbing boundary (no incoming waves):
outlet from 0.0,-0.5, 0.0 to 0.5, 0.5, 0.0 phase_velocity 1 * drive_model NONE
Example of a boundary with an incoming TEM (transverse electromagnetic) wave
whose temporal dependence is given by function1 (see section Functions Input)
with no absorption of the outgoing wave:
outlet from 0.0,-0.5, 0.0 to 0.5, 0.5, 0.0 phase_velocity 1 * no_absorption on * drive_model POTENTIAL potentials 1 0.0 2 -1.0 end temporal_function 1 frequency 0.0 *
Example of a boundary in a cylindrical-geometry simulation with a coax aligned
with the Z axis. The coax is attached to the external circuit model
identified by circuit1 (see section Circuit Models Input):
outlet from 9.0, 0.0, 0.0 to 12.0, 6.2832, 0.0 phase_velocity 1 * drive_model ANALYTIC_TEM geometry COAXIAL modes 1 0 0 inner_radius 9.0 outer_radius 12.0 circuit 1 * connection_rank 1 * voltage_measurement from 12.0 0.0 0.0 to 9.0 0.0 0.0
Waves can be launched in which the component of electric field carrying the wave
is in the direction of a virtual coordinate of the simulation space. Here is an
example of an outlet boundary that launches a TEM (transverse electromagnetic)
wave in a 1-dimensional simulation. In this case the real coordinate is in the
x-direction while y and z are virtual coordinates. Here the modes 0 0 1
indicates that the z-component of electric field is the carrier, and the
function indicated by the temporal_function parameter which is contained
in the [Functions] section of input (see section Functions Input) determines
the time dependence of the magnitude of the field.
outlet from 0.0 0.0 0.0 to 0.0 0.0 0.0 phase_velocity 1 * drive_model ANALYTIC_TEM geometry flat modes 0 0 1 temporal_function 1
Example of a boundary with a rectangular opening through which a TM (transverse magnetic) wave is launched:
outlet from 9.0, 0.0, 0.0 to 12.0, 4.0, 0.0 phase_velocity 1.6 * drive_model WAVEGUIDE TM geometry RECTANGULAR modes 0 1 0 temporal_function 1 * frequency 9.e9 ; Cycles/sec
Example of a boundary with a two-dimensional opening through which an analytic laser-driven focused wave is launched:
outlet from -2.0e-3 -2.0e-3 0.0 to 2.0e-3 2.0e-3 0.0 phase_velocity 1 drive_model LASER reference_point 0.0 0.0 5.4e-3 ; focal spot position components 1 1 0 phases 0 1.5708 0 ; polarization control (radians) temporal_function 1 analytic_function 2 ; [Functions] function1 ; temporal ramp type 0 data_pairs 0.0 0.0 1.e-5 1.e8 end ; function2 ; analytic laser function type 19 coefficients 4.0e-4; wavelength 2.0e-4; spot-size (radius)
The resulting wave has a gaussian shape which is symmetric about the axis of
propagation. The user should insure that the outlet opening is large enough
to accomodate this wave, that is, the electric field strength should be near
zero at the outer conducting walls. The reference_point parameter gives
the location of the "waist" of the beam, usually within the simulation space.
Two other important parameters are actually the coefficients associated with
the special type 19 function designed specifically for this model. These
are the wavelength and the gaussian radius at the waist.
WARNING - For this model, when using 3-d cylindrical coordinates, the
components and phases parameters are used in a cartesian sense.
This allows full control of the polarization - linear to circular. Also, for
this case, the x and y values of the reference_point must be zero.
The from-to coordinates remain cylindrical.
The parameters associated with an outlet boundary
The parameters from, to, specify the lower and upper
limits of the outlet area. The area should completely cover the opening.
Phase velocity of waves going through boundary, normalized to c. The value is usually 1 unless the boundary is in a dielectric medium. The default value is 1.
If no_absorption is ON, the boundary does not absorb any
outgoing (scattered) wave present. This may be useful under some conditions but
must be used with caution as it can cause instability of the simulation.
Default: OFF
Specifies the type of wave to be launched into the simulation space:
NONE:
POTENTIAL:
ANALYTIC_TEM type. The only restriction on this drive
model is that the spatial extent of the outlet boundary must be contained
within a single grid instance (see section Grid Input).
ANALYTIC_TEM:
POTENTIAL type is
that it can span more than one grid.
WAVEGUIDE:
LASER:
Used only when drive_model is POTENTIAL. Indexed list of potential
values to be assigned to electrodes forming the transmission-line opening. These
values are used to set boundary-conditions for the 2-D numerical solution of the
TEM (transverse electromagnetic) fields at the boundary. The potential value for
index 1 is assigned to objects having potential index 1, etc. (see section Objects Input). These indices are local to each outlet boundary. Thus, an object's
potential index may refer to a different potential for different outlets. Only
the potential difference between the different electrodes within a particular
outlet has any physical significance. The maximum number of distinct potentials
that can be defined is 3.
The values in this list are usually integral, and are such that values
assigned to adjacent electrodes differ by (+/-)1. This is because the
actual value of the potential is the product of this difference and the
number given by the temporal_function associated with the boundary.
Specifies the geometry of the opening when an analytic model is used for
the incoming wave. For drive_model ANALYTIC_TEM, can have the
values FLAT or COAXIAL. For drive_model WAVEGUIDE,
can have the values RECTANGULAR or CIRCULAR.
Specifies the X, Y, and Z mode-numbers when an analytic
model is used for the incoming wave. For a TEM (transverse electromagnetic)
wave, set to 1 for the component of electic field carrying the wave, 0 in other
directions.
Specifies the radius of the inner conductor when
drive_model is ANALYTIC_TEM and geometry is COAXIAL.
Specifies the radius of the outer conductor when
drive_model is ANALYTIC_TEM and geometry is COAXIAL.
Integer which refers to the circuit model attached to the outlet boundary
(see section Circuit Models Input). A value of zero or NONE means no
circuit model is attached.
This parameter is used only if a circuit has been attached to the outlet and
is an integer which specifies the "connection rank" within the circuit model
attached to the outlet boundary. This parameter is only necessary in rare cases
where the attached network circuit model has multiple connection points to the
simulation grid. The rank numbers are assigned to the grid connections in the
order that they appear in the junctions list, beginning with 1
(see section Circuit Models Input). The user must determine these numbers correctly,
since they do not appear anywhere explicitly.
Used only if the circuit index is nonzero. Gives the end-points of the
path to be used to measure the voltage when connecting a circuit model to
an outlet boundary of the simulation. The path should be between two
conductors at different potentials and its direction depends upon which
drive_model is being used. For the POTENTIAL model, the path
should go from lower potential to higher potential according to how the
values in potentials have been assigned to the conductors. For the
ANALYTIC_TEM model, the direction is from the outer conductor to the
inner conductor when COAXIAL geometry is specified, and from the
conductor at the higher coordinate to the conductor at the lower coordinate
when FLAT geometry is specified.
The format is:
voltage_measurement from X1 Y1 Z1 to X2 Y2 Z2
The path must be along a grid-line; i.e, only one coordinate value differs between the two sets.
Integer which refers to the function specifying the time-dependence of
the voltage magnitude for the incoming wave (see section Functions Input). If a
circuit model is attached to the boundary, the time-dependence is specified
in the [Circuit Models] input section, and the temporal_function
parameter is not used here. Note that, in either case, if the drive_model
is type ANALYTIC_TEM, the prescribed voltage is understood to be that
of the electrode at the lower coordinate relative to the one at the higher
coordinate (or the inner electrode to the outer one). This parameter must be
used when a wave source is required but no circuit model has been attached.
Specifies the incoming wave frequency in Hz when drive_model is
WAVEGUIDE. May also be optionally defined for other drive models.
Specifies a time delay of the temporal dependence for any voltage-driven model,
that is, when a temporal_function is specified.
A symmetry boundary is a planar boundary which imposes mirror symmetry
on the fields and particles. There is no net current flow through the
boundary, and the magnetic field in the plane of symmetry is zero. The
from, to parameters give the lower and upper limits of the
boundary coordinates. A symmetry boundary is illegal at zero radius in
non-cartesian coordinates.
Example:
symmetry from 0.0, -0.5, 0.0 to 0.0, 0.5, 2.5
Specifies the simulation coordinates over which periodic boundary conditions
are imposed on fields and particles, in the direction specified by the
normal parameter. The from to parameters give the lower and upper
limits of the boundary coordinates.
Example:
periodic from 0.0, 0.0, 0.0 to 2.0, 5.0, 5.0 normal X
Specifies the simulation coordinates over which freespace boundary conditions
are imposed on fields and particles. The from, to parameters
give the lower and upper limits of the boundary coordinates. Actually the
coordinates should correspond exactly to the simulation grid coordinate limits,
except where the freespace model is not meant to be applied, for example, where
there is a ground plane or some other boundary model. There are three models
available for freespace simulation: the one-way wave absorbing model, which is
only reliable for point sources, the perfectly matched layer uniaxial version,
and the convolutional version of the PML, which is the most general and
reliable of the three. For the first model the outer boundary must be left open,
whereas for the other two, the parts of the outer boundary on which freespace
modelling is applied must be set as a conducting boundary, as if it were a
cavity simulation. In both PML models the parts of the simulation grid covered
by the absorbing layers are within the outer boundary, and these parts should
be set up by the user to be clear of any scattering objects. In general, using
a larger value for number_of_cells will result in better absorption, at
the cost of memory for the extra cells required. The grid spacing normal to the
boundaries should be uniform in these layers. Use of either PML model requires
that the compiler directive FREESPACE_PML be defined
(see section FREESPACE_PML).
Example of the one-way wave absorbing model:
freespace from -2.0, -2.0, 0.0 to 2.0, 2.0, 5.0 model_type WAVEABC phase_velocity 1.0 * reference_point 0.0 0.0 2.5 *
Example of the uniaxial perfectly matched layer (PML) model:
freespace from -2.0, -2.0, 0.0 to 2.0, 2.0, 5.0 model_type UNIAXIAL number_of_cells 8
Example of the convolutional PML model:
freespace from -2.0, -2.0, 0.0 to 2.0, 2.0, 5.0 model_type CFSPML number_of_cells 5
The [Potentials] section is used in conjunction with an electrostatic
field solver. The code must be compiled with the STATIC_FIELDS compiler
directive or one of its variants (see section Compiler Directives). Dirichlet
boundary conditions are set using the potential index associated with
each object (see section Objects Input). An object with potential index `N'
is given the value of the potentialN parameter. The units of potential
are dependent upon which system of units has been specified by the user
(see section User Units). However, if the circuit model is used, or if a temporal
function is used, then the potential will be the product of these in
combination, so these values should be simply (+/-)1. The maximum number of
iterations allowed is given by the potential_iterations parameter in
the [Control] section of input (see section Control Input). The convergence
criterion for static solution is given by potential_tolerance, which is
also specified in the [Control] section. The circuit and
temporal_function parameters are optional and are used for time-dependent
variations in the applied potentials. They may appear after any non-zero
potential. The circuit parameter is used in conjunction with the
[Circuit Models] section of input (see section Circuit Models Input) in
order to vary the voltage (relative to zero) according to the amount of charge
deposited on conductors of that potential. In cases where more than one
potential has a circuit model associated with them, they must not be the
same circuit model (with the same index). Any circuit model invoked here will
supersede the effect of the temporal_function parameter, if present.
The maximum number of distinct potentials that can be used is 3.
Example of a constant potential:
[Control] potential_iterations 500 potential_tolerance 0.001 ; [Potentials] potential1 0.0 potential2 500.0
Example of a potential obtained from a circuit model:
[Potentials] potential1 0.0 potential2 1.0 circuit 1
Example of a time-varying potential described by a function:
[Potentials] potential1 0.0 potential2 1.0 temporal_function 2
The [Materials] section is used to specify materials contained in the
medium models. They provide the various physical properties necessary for the
functioning of the energy-loss and scattering phenomena associated with those
models. Note that these materials are generally metals and that specification
of materials is only required for those not already contained on internal
tables. Gas materials used for the conductivity model can not be entered
here and are limited to those available in the internal table
(see section gas_material (string)).
The materials already available are:
carbon
aluminum
iron
copper
molybdenum
silver
tantalum
tungsten
rhenium
gold
Any other materials can be entered in this section. An example of the format is as follows:
[Materials] material lead atomic_number 82 atomic_weight 207.19 ionization_potential 810; eV specific_heat 0.13; J/gK material zinc atomic_number 30 atomic_weight 65.39 ionization_potential 320; eV specific_heat 0.38; J/gK
The parameters associated with a material are self-explanatory.
The [Medium Models] section is used to specify physical properties
associated with objects in order to apply energy-loss and scattering models
to particles and to specify electromagnetic properties (dielectric constant,
conductivity, etc.) (see section Objects Input). Individual entries are numbered
consecutively by appending an integer index to the medium keyword.
Objects with medium index `N' are given the properties of that medium.
The parameters associated with a medium
A variety of different medium models are available to the user, which are
differentiated by the "method" specified. These are indicated by the numerals
0 through 4 and are explained in their individual sections below.
Briefly, the methods are as follows:
method 0:
method 1:
method 2:
method 3:
method 4:
This is a sub-classification of some of the medium methods, which
modifies the way that particles within the medium are treated. This can take
the values DENSE or TENUOUS. The DENSE option is used to
model objects such as thin foils through which particles can pass, or solid
(thick) boundaries, which particles strike and are then either absorbed or
backscattered. An important use of the DENSE model is to compute the
heating of a surface. The effect on the particles is determined by the medium
method being used and its various parameters described in their sections below.
The TENUOUS option is used when the effect of the medium (e.g., a gas
cell) extends over many particle steps. This option is available for
method 0, method 1 and method 4 medium models. All others
are considered to be type DENSE.
Assigns a relative dielectric constant to the medium, thereby modeling a
dielectric material when a value greater than 1.0 is specified. The compiler
directive USE_PERMITTIVITY must be defined in order for this parameter
to take effect (see section USE_PERMITTIVITY). The default value of unity means no dielectric material
is present.
Default: 1.0
Assigns a surface conductivity to the medium if it is a dielectric. The units are dependent upon which system of units has been specified by the user (see section User Units).
Default: 0.0
Assigns a relative magnetic permeability to the medium, thereby modeling
a paramagnetic material when a value greater than 1.0 is specified. The
compiler directive USE_PERMEABILITY must be defined in order for
this parameter to take effect (see section USE_PERMEABILITY).
The default value of unity means no paramagnetic material is present.
Default: 1.0
When zero_forces_flag on is used, the field forces on particles inside
the medium are set to zero. This is a refinement which results in more accurate
calculation of particle energies. This parameter is optional because it should
not be used when there is any particle emission also taking place on the surface
of the medium.
Default: OFF
Mass density of a solid material in user units (see section User Units).
Transparency of a solid material mesh, as opposed to a foil. This is the
fraction of particles which pass through without being scattered. This
parameter applies only to method 1 and method 2 models, but
cannot be used with method 4, since that method involves detailed
particle tracking. This is a probablistic parameter. The default value of
zero causes the scattering process to be applied to all particles.
Default: 0.0
Initial temperature of the medium in kelvins. This parameter applies to
method 0, method 1, method 3, and method 4 models.
The default value is 300 degrees kelvin.
Default: 300.0
Specifies the composition of the gaseous medium using the format
gas_material NAME
where `NAME' is a material name from the list below. The material names currently available are:
helium
air
neon
argon
krypton
fluorine
xenon
sf6
This parameter is required for the gas conductivity model, and is appropriate
only for a TENUOUS medium type. However, the components parameter
may be used instead (see below).
Specifies the choice between two conductivity models available for air.
This can be either GENERIC or EEDF. The first was developed for
general use with beam transport simulations, and the second has been used for
m