Go to the first, previous, next, last section, table of contents.


Input Variables

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]
Simulation title which, when specified, overrides the default code-generated title
[Control]
Timestep, time limit, algorithmic and diagnostic parameters (required)
[Grid]
Defines overall simulation grid coordinates and spacing (required)
[Regions]
Specifies zones into which the simulation space is broken up
[Objects]
Geometrically shaped objects which describe the simulation structure
[Boundaries]
Boundary conditions on the simulation other than conducting boundaries, which are specified in the [Objects] section
[Potentials]
Iteration parameters and boundary values for the electrostatic field solver
[Materials]
Allows for user_specified materials beyond those which are available internally
[Medium Models]
Specifies material properties associated with structural objects defined in the [Objects] section
[Circuit Models]
Circuit models used as adjuncts to the simulation grid
[Volume Models]
Grid-conformal rectangular regions of dielectrics, magnetic materials, current drive, etc.
[Liner Models]
Parameters for a simple imploding liner
[Subgrid Models]
Specifies parameters for the so-called subgrid models, such as a smooth slope
[Substrate Models]
Neutral ion source model for a metallic plate embedded in a ceramic material
[External Fields]
Specifies externally applied electric and/or magnetic fields
[Particle Species]
Specifies parameters such as charge, mass, etc. for each particle species present (required for particles)
[Particle Creation]
Particle generation models: injection, emission, etc. (required for particles)
[Particle Collapse]
Control parameters for reduction of particle number by coalescence of macro-particles
[Particle Migration]
Control parameters for electron migration between kinetic and fluid states
[Particle Extraction]
Used to generate data files of particles crossing specified planes, e.g., for subsequent use in a slice transport code or as input to LSP using the fileread option
[Particle Interaction]
Controls interactions between particle species for ionization and scattering models
[Particle Diagnostics]
Used to generate data files containing particle diagnostic measurements as functions of some specified variable
[Particle Targets]
Used to generate 2-D diagnostic maps of cumulative fluence, energy, and divergence of particles passing through target planes
[Functions]
Specifies tabulated or analytic functions to be used during the simulation
[Probes]
Time-sampled diagnostics for field and particle measurements

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.

Title Input

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.

An example is:

[Title]
simulation_title "This is a title"

Control Input

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.

An example is:

[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

Temporal Parameters

courant_multiplier (real)

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_steps (integer)

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.

time_limit (real)

Options for this parameter are:

time_limit:
Total physical time in user units to run the simulation; that is, the time at which the simulation stops running.
time_limit_ns:
Total physical time in ns to run the simulation.
time_limit_cm:
Total physical time to run the simulation in units of 1 cm/c, where c is the velocity of light. Since relativistic electrons travel at about c, this is sometimes a convenient way of specifying the simulation time.

The value of number_of_steps, if it is reached first, takes precedence over time_limit.

time_step (real)

Options for this parameter are:

time_step:
Physical timestep in user units.
time_step_ns:
Physical timestep in ns.
time_step_cm:
Physical timestep in units of 1 cm/c, where c is the velocity of light. Since relativistic electrons travel at about c, this is sometimes a convenient way of specifying the timestep.

Simulation Restarts

dump_restart_flag (flag)

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_restart_dump_time (real)

Maximum wall-clock time between restart dumps in hours.

Default: 1.e9 hours (i.e., infinite)

rename_restart_flag (flag)

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

restart_interval (real)

Options for this parameter are:

restart_interval:
Number of timesteps between restart dumps.
restart_interval_time:
Interval in user units between restart dumps.
restart_interval_ns:
Interval in ns between restart dumps.
restart_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between restart dumps.

Default: 1.e+9 (no dumps)

Parallel Processing

balance_interval (real)

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:
Number of timesteps between load-balance checks.
balance_interval_time:
Interval in user units between load-balance checks.
balance_interval_ns:
Interval in ns between load-balance checks.
balance_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between load-balance checks.

Default: 1.e+9 (no rebalances)

load_balance_flag (flag)

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 (integer)

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.

region_balance_flag (flag)

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

initial_balance_flag (flag)

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

override_balance_flag (flag)

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

load_timing_interval (integer)

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

Field Solution and Modification

applied_current (real)

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

background_electron_conductivity (real)

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

background_plasma_density (real)

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

cold_test_flag (flag)

If cold_test_flag is ON, run the simulation without particles. Any particle-creation statements in the input file are ignored.

Default: OFF

convergence_iterations (integer)

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_tolerance (real)

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

dielectric_kill_flag (flag)

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

electric_force_filtering_parameter (real)

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)

electric_spatial_filtering_parameter (real)

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)

field_advance_flag (flag)

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

field_initialization_flag (flag)

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

ion_conductivity_factor (real)

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

magnetic_force_filtering_parameter (real)

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)

magnetic_spatial_filtering_parameter (real)

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)

small_radius_exclusion (real)

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.

time_bias_coefficient (real)

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.

time_bias_iterations (integer)

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.

temporal_filtering_parameter (real)

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)

Implicit Field Algorithm

error_current_filtering_parameter (real)

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)

implicit_acceleration_parameter (real)

Initial acceleration factor for the ADI field solution. The code will adjust this parameter, if necessary, to help convergence.

Default: 0.0

implicit_iterations (integer)

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.

implicit_omega_min_factor (real)

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

implicit_subcycles (integer)

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

implicit_tolerance (real)

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.

Static Field Algorithm

acceleration_parameter (real)

Acceleration factor for the ADI field solution. The value should be between 1 and 2 for stability.

Default: 1.0 (no acceleration)

potential_iterations (integer)

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).

potential_tolerance (real)

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.

Particle Collision Algorithm

ionization_interval (integer)

Number of timesteps between ionization events. This applies to all species that are being ionized (see section ionization).

Default: 1

scattering_interval (integer)

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

Fluid Physics Algorithm

fluid_migration_interval (integer)

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

fluid_streaming_factor (real)

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.

flux_limit_fraction (real)

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

kinetic_migration_interval (integer)

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

pdv_term_flag (flag)

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

vcrossb_flag (flag)

If vcrossb_flag is ON, include the V-cross-B term in the application of the air-chemistry conductivity model.

Default: ON

surface_viscosity_flag (flag)

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

Moving Frame Algorithm

moving_frame_velocity (real)

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

moving_frame_start_time (real)

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

Diagnostic Output

dump_accelerations_flag (flag)

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

dump_bfield_flag (flag)

If dump_bfield_flag is ON, output magnetic fields to the vector fields dump file.

Default: ON

dump_charge_density_flag (flag)

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

dump_conductivity_flag (flag)

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

dump_current_density_flag (flag)

If dump_current_density_flag is ON, output particle current densities to the vector fields dump file.

Default: OFF

dump_energy_deposition_flag (flag)

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_interval (integer)

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:
Number of timesteps between output dumps for fields, particles, etc.
dump_interval_time:
Interval in user units between output dumps for fields, particles, etc.
dump_interval_ns:
Interval in ns between output dumps for fields, particles, etc.
dump_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between output dumps for fields, particles, etc.

Default: 1.e+9 (no dumps)

dump_montecarlo_diagnostics_flag (flag)

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

dump_number_densities_flag (flag)

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

dump_ohmic_quantities_flag (flag)

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

dump_plasma_quantities_flag (flag)

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

dump_potential_flag (flag)

If dump_potential_flag is ON, output electric potentials to the scalar dump file. If none are available, no values are written.

Default: OFF

dump_rbtheta_current_flag (flag)

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

dump_rho_background_flag (flag)

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

dump_steps (integer)

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.

dump_substrates_flag (flag)

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

dump_surface_depositions_flag (flag)

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

dump_times (real)

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:
Times in user units at which output dumps are desired.
dump_times_ns:
Times in ns at which output dumps are desired.
dump_times_cm:
Times in units of 1 cm/c, where c is the velocity of light at which output dumps are desired.

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.

dump_velocities_flag (flag)

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

extract_photons_flag (flag)

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

extract_primaries_flag (flag)

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.

extract_secondaries_flag (flag)

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

field_movie_components (strings)

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

field_movie_coordinate (string & real)

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

field_movie_interval (integer)

Options for this parameter are:

field_movie_interval:
Number of timesteps between field movie frames.
field_movie_interval_time:
Interval in user units between field movie frames.
field_movie_interval_ns:
Interval in ns between field movie frames.
field_movie_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between field movie frames.

Default: 1.e+9 (no dumps)

particle_movie_components (strings)

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.

particle_movie_interval (integer)

Options for this parameter are:

particle_movie_interval:
Number of timesteps between particle movie frames.
particle_movie_interval_time:
Interval in user units between particle movie frames.
particle_movie_interval_ns:
Interval in ns between particle movie frames.
particle_movie_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between particle movie frames.

Default: 1.e+9 (no dumps)

photon_output_format (string)

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

primary_output_format (string)

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

probe_interval (integer)

Number of timesteps between probe samples on the time-history file.

Default: 1

scalar_movie_components (strings)

Specifies the scalar quantities to be output to the scalar movie dumps. These can be selected from the following options:

potential:
The electric potential, which requires the STATIC_FIELDS compiler directive be defined (see section STATIC_FIELDS).
charge_density:
The total charge density, which requires the CHARGE_DENSITY compiler directive be defined (see section CHARGE_DENSITY).
number_densities:
Number densities by species, which requires the NUMBER_DENSITIES compiler directive be defined (see section NUMBER_DENSITIES).
energy_deposition:
Energy deposition in a medium, which requires the ENERGY_DEPOSITION compiler directive be defined (see section ENERGY_DEPOSITION).
plasma_quantities:
Plasma densities, temperatures, and collision frequencies, by species. These require the SCATTERING_ON compiler directive be defined (see section SCATTERING_ON).
ohmic_quantities:
Various ohmic medium quantities such as conductivity, free electron density, collision frequency, and plasma temperature. These require the USE_OHMIC_TERMS compiler directive be defined (see section USE_OHMIC_TERMS).
rbtheta_current:
This measures the radius*B-theta current. It is only possible to measure in cylindrical coordinates, therefore the CYLINDRICAL or CYL_R_Z compiler directive must be defined (see section CYLINDRICAL).
rho_background:
Evaluation of charge conservation, that is, divergence of the electric field minus rho. The 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.

scalar_movie_coordinate (string & real)

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

scalar_movie_interval (integer)

Options for this parameter are:

scalar_movie_interval:
Number of timesteps between scalar movie frames.
scalar_movie_interval_time:
Interval in user units between scalar movie frames.
scalar_movie_interval_ns:
Interval in ns between scalar movie frames.
scalar_movie_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between scalar movie frames.

Default: 1.e+9 (no dumps)

spatial_skip_x (integer)

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_y (integer)

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_z (integer)

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)

structure_output_format (string)

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

target_movie_interval (integer)

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:
Number of timesteps between target movie frames.
target_movie_interval_time:
Interval in user units between target movie frames.
target_movie_interval_ns:
Interval in ns between target movie frames.
target_movie_interval_cm:
Interval in units of 1 cm/c, where c is the velocity of light between target movie frames.

Default: infinite (no dumps)

target_output_format (string)

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

Numerical Checks and Reports

domain_boundary_check (flag)

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

particle_cyclotron_check (flag)

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

particle_motion_check (flag)

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

print_control_flag (flag)

If print_control_flag is ON, write the control data structure to standard output.

Default: OFF

print_convergence_flag (flag)

If print_convergence_flag is ON, write convergence information for iterative field algorithms to standard output.

Default: OFF

print_grid_flag (flag)

If print_grid_flag is ON, write grid coordinates and spacing to standard output.

Default: OFF

print_region_flag (flag)

If print_region_flag is ON, write region parameters to standard output.

Default: OFF

dump_timing_flag (flag)

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

report_timing_flag (flag)

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

Grid Input

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

Regions Input

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)).

Objects Input

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.

Example:

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

BLOCK

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).

Example:

object1 BLOCK ; central conductor
conductor on medium 0 potential 0
from 0.0 -1.0  4.82
to   5.6  1.0 10.33

CONE

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).

Example:

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

CYLINDER

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).

Example:

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 *

FOIL

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).

Example:

object62 FOIL ; thin foil anode
 conductor on potential 0
 from 23.0 0.0952 56.67
 to   23.0 0.2856 69.67

FUNCTION

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.)

Example:

object8 FUNCTION 4
 coordinates default *
 conductor on medium 2

PARABOLOID

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).

Example:

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

PARALLELEPIPED

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).

Example:

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

TRILATERAL

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).

Example:

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

QUADRILATERAL

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).

Example:

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

SOLID

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.

Example:

object1 SOLID ; set all cells to conductors
 conductor on medium 0 potential 0

SPHERE

Defines a sphere with the center and radius parameters. (Coordinate-system independent shape).

Example:

object2 SPHERE ; cathode electrode
 conductor on medium 0 potential 0
 center 0.0 1.0 2.0
 radius 0.5

TORUS

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).

Example:

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 *

WIRE

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).

Example:

object62 WIRE ; thin connector
 conductor on potential 0
 from 2.5 0.0 12.0
 to   2.5 0.0 18.0

Boundaries Input

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.

Outlet Boundaries

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

from to (real)

The parameters from, to, specify the lower and upper limits of the outlet area. The area should completely cover the opening.

phase_velocity (real)[optional]

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.

no_absorption (flag)[optional]

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

drive_model (string)

Specifies the type of wave to be launched into the simulation space:

NONE:
No incoming wave.
POTENTIAL:
Uses a numerical solution for the potential. This is generally more versatile to use than the 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:
Uses an analytic TEM (transverse electromagnetic) wave solution for either flat or coaxial electrodes. In this case, the voltage applied 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). The only advantage of this model over the POTENTIAL type is that it can span more than one grid.
WAVEGUIDE:
Uses an analytic TE- (transverse electric) or TM-wave (transverse magnetic) solution for either rectangular or circular electrodes.
LASER:
A special analytic Gaussian function is used to approximate a focused (convergent) wave from a laser source. Only the wavelength and spot size (defined as the gaussian radius) are entered as coefficients in the function. All other parameters such as beam waist location and polarization are specified in the outlet boundary input. The analytic function 19 (index number) is associated with this function (see section Functions Input).

potentials (real)

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.

geometry (string)

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.

modes (integer)

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.

inner_radius (real)

Specifies the radius of the inner conductor when drive_model is ANALYTIC_TEM and geometry is COAXIAL.

outer_radius (real)

Specifies the radius of the outer conductor when drive_model is ANALYTIC_TEM and geometry is COAXIAL.

circuit (integer)[optional]

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.

connection_rank (integer)[optional]

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.

voltage_measurement (real)

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.

temporal_function (integer)[optional]

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.

frequency (real)[optional]

Specifies the incoming wave frequency in Hz when drive_model is WAVEGUIDE. May also be optionally defined for other drive models.

time_delay (real)[optional]

Specifies a time delay of the temporal dependence for any voltage-driven model, that is, when a temporal_function is specified.

Symmetry Boundaries

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

Periodic Boundaries

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

Freespace Boundaries

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

Potentials Input

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

Materials Input

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:

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.

Medium Models Input

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

method (integer)

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:
Used to indicate the presence of dielectrics or gas conductivity models.
method 1:
Analytic approximations for scattering and energy loss.
method 2:
Mono-energetic scattering and secondary emission on foils, using lookup tables.
method 3:
Backscattering of primaries and secondaries on solid materials, using lookup tables.
method 4:
Monte Carlo transport techniques for scattering, energy loss, and photon generation, using the ITS kernel (Ref.[5]).

type (string)

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.

dielectric_constant (real)[optional]

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

surface_conductivity (real)[optional]

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

permeability (real)[optional]

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

zero_forces_flag (flag)[optional]

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

density (real)

Mass density of a solid material in user units (see section User Units).

transparency (real)[optional]

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

temperature (real)[optional]

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

gas_material (string)

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:

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).

air_model (string)[optional]

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 microwave stimulation (without beam-impact ionization). Present only for a TENUOUS medium type. In order to use this option, the USE_OHMIC_TERMS compiler directive must be defined (see section USE_OHMIC_TERMS).

Default: GENERIC

water_content (real)[optional]

Specifies the amount of water vapour present when using the EEDF option for the conductivity model of air. This is expressed as the number density fraction of the total and can have values between 0.0 and 0.04. Present only for a TENUOUS medium type. In order to use this option, the USE_OHMIC_TERMS compiler directive must be defined (see section USE_OHMIC_TERMS).

Default: 0.0

diffusion_length (real)[optional]

Specifies the characteristic diffusion length for any diffusion terms, if present, in the conductivity model. The diffusion term is active for helium, air, and argon gasses only. Present only for a TENUOUS medium type. In order to use this option, the USE_OHMIC_TERMS compiler directive must be defined (see section USE_OHMIC_TERMS).

Default: 1.0

species (integer)[optional]

Species identification for application of the type TENUOUS medium. Available for the method 1 model only. This enables the model to be applied to an ion species rather than electrons, if desired. In that case all electrons entering the medium are assumed to be low energy and will be absorbed automatically. Note that the model will be applied to any other species present with similar charge and mass as the selected species. If not specified, the default value is the species designated by the PRIMARY_SPECIES compiler directive (see section PRIMARY_SPECIES=#).

gas_density (real)

Number density for a gaseous medium (i.e., type TENUOUS). Available for the method 0 and method 1 models only. Method 4 uses the density contained on the XGEN file.

spatial_function (integer)[optional]

Integer identifying the function used to specify the spatial dependence of the gas density. Used in conjunction with the reference_point and spatial_flags parameters. The gas_density is multiplied by the spatial dependence, if present, when a more complex description of the density is required. Otherwise, the density is simply a constant value. This can be a function of multiple variables corresponding to x, y, or z. Present only for a TENUOUS medium type. (See section Functions Input.) Available for the method 0 and method 1 models only.

reference_point (real)[optional]

A vector which sets the reference point for the spatial dependence function. This must be present when the spatial_function parameter is used (unless its value is 0). Available for the method 0 and method 1 models only.

spatial_flags (flag)[optional]

A set of integers with values 0 (=no) or 1 (=yes) indicating the dimensions (X|Y|Z) on which the spatial dependence function is based. If more than one of these are set to 1 simultaneously, then the spatial dependence is radial from the reference point. This must be present when the spatial_function parameter is used (unless its value is 0). Available for the method 0 and method 1 models only.

conductivity (flag)[optional]

If conductivity is ON, a plasma current is generated using an Ohm's Law model. The conductivity is computed from the electron density and the collision frequency. The electron density has contributions from beam-impact and avalanche ionization. Both electron-neutral and electron-ion (Coulomb) collisions are included in the collision frequency. At present, this model has been implemented for gas materials (helium, air, neon, argon, krypton, fluorine, xenon, sf6) and an argon/krypton/fluorine mixture (see section components (string)). The last one was developed for the KrF laser device. Present only for a TENUOUS medium type. In order to use this option, the USE_OHMIC_TERMS compiler directive must be defined (see section USE_OHMIC_TERMS).

electron_density (real)[optional]

The E/p model (E is the electric field strength, p is the gas pressure) used to model avalanche breakdown for the calculation of conductivity requires a "seed" population of free electrons. This parameter gives the initial free electron number density. Present only for a TENUOUS medium type. At present, the spatial dependence function, if present, is applied to the electron density in the same way as the gas density above.

Default: 1.0e3

polar_angle (string & real)[optional]

Specifies the polar axis and the polar angle (in degrees) at which the surface normal is tilted with respect to that axis. A value of zero means that the surface normal is in the direction of the polar axis. A value of 180 means that the surface normal is opposite to the direction of that axis. The user must ensure that the angle is consistent with the actual simulation geometry. `AXIS' can take the values X|Y|Z. In cylindrical coordinates, rotation about the Y axis is not defined. This parameter is required for method 2 and method 3 and is optional and ignored for method 1 and method 4. The format is:

polar_angle AXIS ANGLE

azimuthal_angle (string & real)[optional]

Specifies the azimuthal angle (in degrees) at which the surface normal is rotated around the polar axis, measured from the azimuthal axis. A value of zero means that, if the polar axis is Z and the azimuthal axis is X, then the normal to the surface is in the X-Z plane. The user must ensure that the angle is consistent with the actual simulation geometry. `AXIS' can take the values X|Y|Z but must not be the same as the polar axis. The format is:

azimuthal_angle AXIS ANGLE

extract_photons_flag (flag)[optional]

Selectively turns the extraction of photons on or off for this instance of a method 4 medium model. The default value is whatever the extract_photons_flag is set to in the [Control] section of input (see section Control Input).

extract_primaries_flag (flag)[optional]

Selectively turns the extraction of primaries on or off for this instance of a method 4 medium model. The default value is whatever the extract_primaries_flag is set to in the [Control] section of input (see section Control Input).

extract_secondaries_flag (flag)[optional]

Selectively turns the extraction of secondaries on or off for this instance of a method 4 medium model. The default value is whatever the extract_secondaries_flag is set to in the [Control] section of input (see section Control Input).

collision_energies (integer)

Number of energies between minimum_energy and maximum_energy in internal energy-loss and scattering tables. Interpolation is then used to obtain values for specific particle energies.

minimum_energy (real)

Minimum energy, in eV, used in internal energy-loss and scattering lookup tables.

Default: 0.0

maximum_energy (real)

Maximum energy, in eV, used in internal energy-loss and scattering lookup tables.

Default: 1.e+9

components (string)

Specifies the composition of the medium using the format

components
 NAME1 fraction FRACTION1
 NAME2 fraction FRACTION2
end

where `NAME1', `NAME2' are material names from the list below, and `FRACTION1', `FRACTION2' are fractions of each by volume. The material names currently available are:

For each material, an internal table has values for parameters such as atomic number, atomic weight, ionization potential, and specific heat. This list of components is required only if either the conductivity model, the scattering model, or the energy-loss model is being invoked.

In addition to these materials, if a material is required which is not on the list, the user can define it in the [Materials] section of input (see section Materials Input). However, only solid materials of the DENSE type can be utilized in this way for scattering and energy-loss, and not a TENUOUS gas for the conductivity model.

method 0

Used for simple material properties only, where no particle scattering or energy-loss models are applied. For solid materials, particles entering will be absorbed automatically, as opposed to other methods which may or may not stop particles, depending on the result of an energy-loss calculation or some other criterion. This method can be used to specify a conductivity model in a gaseous material (TENUOUS medium type), or to specify dielectric materials (see section dielectric_constant (real)[optional]) or paramagnetic materials (see section permeability (real)[optional]) which directly affect only the electromagnetic fields.

Example of a medium specifying dielectric material only:

[Medium Models]
medium1
method 0
dielectric_constant 7.0 *
surface_conductivity 0 *

Example of a medium specifying a gas conductivity model only:

[Medium Models]
medium1
type TENUOUS
method 0
conductivity on *
electron_density 1.0e5 *
temperature 300 *
gas_material air *
air_model EEDF *
water_content 0.04 *
diffusion_length 12.0 *

method 1

Applies internally-computed energy loss and/or small-angle multiple scattering to electrons. The method 1 parameters used to set up the internal scattering tables are described below:

Example of a dense medium using internally-computed Moliere scattering and Moller energy-loss tables:

[Medium Models]
; slanted surface target
medium1
method 1
type DENSE
dielectric_constant 1.0 *
density 8.96 ; g/cc for Cu
thickness 10.0 *
temperature 300.0 *
collision_energies 40 
minimum_energy 1.6e8 ; eV
maximum_energy 2.0e8 ; eV
scattering on
scatter_angles 20
poloidal_angles 20
energy_loss on
components
 copper fraction 1.0
end

Example of a tenuous (gas) medium using the conductivity model:

[Medium Models]
medium1
method 1
type TENUOUS
species 1 *
gas_density 1.186e16 ; 1/cc for air at 1 torr
spatial_function 0 *
reference_point 0 0 0 *
spatial_flags 0 0 0 *
conductivity on *
electron_density 3.5e7 ; 1/cc *
temperature 300 *
collision_energies 40
minimum_energy 1.6e8 ; eV
maximum_energy 2.0e8 ; eV
scattering off
energy_loss off
components
 air fraction 1.0
end

thickness (real)[optional]

Specifies the medium thickness (in units of length) where a foil model is intended. This is the critical parameter in determining the effect on particles passing through the foil, rather than by any dimensions specified for an object (usually one cell thick) in the [Objects] section that is associated with the foil model. For boundaries where one just wants to compute the surface temperature rise, one can use an arbitrarily large value. Present only for a DENSE medium.

scattering (flag)

If scattering is ON, apply multiple scattering to particles passing through the medium.

scatter_angles (integer)

Number of scattering angles to compute for each energy (see section collision_energies (integer)). These angles are used to form a lookup table.

poloidal_angles (integer)

Number of poloidal angles to use. There is no poloidal dependence in the scattering cross section: this number is used to compute sines and cosines of poloidal angles which can be selected randomly when generating scattered values.

energy_loss (flag)

If energy_loss is ON, apply energy-loss model to particles passing through the medium. This option is required to generate surface temperatures or measurable energy deposition.

method 2

Applies user-supplied scattering tables to a monoenergetic primary electron beam incident on a solid material. It is useful in treating large-angle scattering (e.g., backscattering from a foil) and secondary emission of electrons and positrons. The scattering tables and probabilities can be computed from the Integrated Tiger Series codes (Ref.[5]). The format for these tables is given in section Method 2 Scattering File. The monoenergetic primary electron species is species1 or the species designated by the PRIMARY_SPECIES compiler directive (see section PRIMARY_SPECIES=#).

The parameters associated with this model

Example of a medium using 2-D scattering lookup tables for a foil:

[Medium Models]
medium1
method 2
dielectric_constant 1.0 *
zero_forces_flag on *
density 16.6 ; g/cc
transparency 0.5 *
polar_angle Z 180
azimuthal_angle X 0
primary_probability 0.99636
electron_probability 0.0399
positron_probability 0.0
primary_data_file cupri.tab
electron_data_file cusec.tab
positron_data_file cupos.tab

primary_probability (real)

The probability, in the range 0 to 1, that an incident primary electron passes through the foil. This probability is usually obtained from the same calculation that produces the scattering tables.

electron_probability (real)

The probability, in the range 0 to 1, that a secondary electron will escape the front or back side of the foil. These electrons belong to the species designated by the species parameter of the secondary emission model (see section secondary).

positron_probability (real)

The probability, in the range 0 to 1, that a secondary positron will escape the front or back side of the foil. These positrons belong to the species designated by the speciesA parameter of the secondary emission model (see section secondary).

primary_data_file (string)

The file containing the energy and angle lookup data for the primary electrons (see section Method 2 Scattering File).

primary_data_file cupri.tab

electron_data_file (string)

The file containing the energy and angle lookup data for the secondary electrons (see section Method 2 Scattering File).

electron_data_file cusec.tab

positron_data_file (string)

The file containing the energy and angle lookup data for the secondary positrons (see section Method 2 Scattering File).

positron_data_file cupos.tab

method 3

Applies backscattering to primary and secondary electrons which have impinged upon a solid material. The user-supplied scattering tables and probabilities can be computed from the Integrated Tiger Series codes (Ref.[5]). The table format is given in section Method 3 Backscattering File. The primary electron species is species1 or the species designated by the PRIMARY_SPECIES compiler directive (see section PRIMARY_SPECIES=#). The backscattered electrons belong to the species designated by the species parameter of the backscatter model (see section backscatter).

The parameters associated with this model

Example of a medium using 4-D backscattering lookup tables:

[Medium Models]
medium1
method 3
dielectric_constant 1.0 *
density 16.6 ; g/cc for Ta
temperature 300.0 *
polar_angle Z 270
azimuthal_angle X 0
collision_energies 40 
minimum_energy 1.0e6 ; eV
maximum_energy 2.0e8 ; eV
backscatter_data_file tantalum.tab
energy_loss on
components
 tantalum fraction 1.0
end

backscatter_data_file (string)

The file containing the energy and angle lookup data for all backscattering events (see section Method 3 Backscattering File).

backscatter_data_file tantalum.tab

method 4

Applies detailed Monte Carlo transport to any electrons which enter this medium. The user-supplied data file is generated by the XGEN member of the Integrated Tiger Series codes (Ref.[5]). See section Method 4 Cross Section File. The medium may be a tenuous gas or a solid material, in which case secondaries may be produced. Any reemitted secondary electrons belong to the species designated by the species parameter of the secondary emission model (see section secondary). For the TENUOUS option, energy lost from the impacting particles can be accumulated in the individual cells of the medium for diagnostic purposes, so long as the code is compiled with the ENERGY_DEPOSITION compiler directive (see section ENERGY_DEPOSITION).

The parameters associated with this model

Example of a medium using detailed Monte Carlo transport model:

[Medium Models]
medium1
method 4
type DENSE *
dielectric_constant 1.0 *
temperature 300.0 *
extract_photons_flag on *
extract_primaries_flag off *
extract_secondaries_flag off *
xgen_data_file xgen.dat
photon_cutoff_energy 1.0e4; eV
components
 aluminum fraction 1.0
end

Example of a tenuous (gas) medium using Monte Carlo transport model:

[Medium Models]
medium1
method 4
type TENUOUS
conductivity on *
electron_density 5.0e8 *
temperature 300 *
xgen_data_file KrF.dat
photon_cutoff_energy 3.0e3; 3 keV
components
 argon fraction 0.95
 krypton fraction 0.045
 fluorine fraction 0.005
end

xgen_data_file (string)

The file containing the electron energy-loss and scattering data for the material. The format for this table is that produced by the XGEN program, which is part of the Integrated Tiger Series codes (see section Method 4 Cross Section File).

xgen_data_file xgen.dat

photon_cutoff_energy (real)

Specifies the photon cutoff energy in eV.

Circuit Models Input

The [Circuit Models] section of the input file specifies the parameters of lumped-element circuit models which serve as adjuncts to the main part of the calculation in the defined simulation space. Three types of circuit model are available. The first is the static type and is used in conjunction with the iterative electrostatic field solver. The second is the transmission-line type and is attached to the simulation grid at an outlet boundary. The third is the network type, which enables configuration of more complexity and is also attached to an outlet boundary. Instances of the circuit model are identified by appending an integer index to the circuit keyword. This index is used as the identifier wherever the circuit model is referred to elsewhere in the input description.

For the static type, the specified circuit model is associated with the electrostatic fields through the [Potentials] section of input (see section Potentials Input). The source voltage is a constant, unless a voltage_function is specified, which takes precedence. The static circuit model can be defined as an open circuit which has only capacitance or an R-C circuit which also has an associated resistance.

Example:

[Potentials]
potential1  0.0
potential2  1.0 circuit 1
;
[Circuit Models]
circuit1 static *
capacitance 0.0
resistance 4.0 ; 4 ohms
voltage 1000.0 *
voltage_function 0 *

The transmission-line type of circuit model consists of a sequence of sections, each with a defined impedance, the end of which is attached to an outlet boundary (see section Outlet Boundaries). This is commonly used to model the changes of impedance in the various stages of a pulsed-power transmission line leading up to the device being modeled in the simulation.

Example:

[Boundaries]
outlet
from -10.0,-10.0, 0.0
to    10.0, 10.0, 0.0
phase_velocity 1
drive_model POTENTIAL
potentials
 1  0.0
 2 -1.0
end
circuit 1
voltage_measurement
 from 10.0 0.0 0.0
 to    5.0 0.0 0.0
;
[Circuit Models]
circuit1
 transmission-line *
segments
 length 10.0 impedance 2.3
   dielectric_constant 1.0 *
 length 5.0 impedance 60.7
   dielectric_constant 1.0 *
end
termination voltage_application *
 voltage_function 1 *
startup_time 0.0 *
frequency 0.0 *
impedance_product_function 0 *

Boundary conditions for the initial end of the transmission line model can be defined by use of the termination parameter. The other end of the transmission line is the one which is connected to the simulation grid at an outlet boundary. See the section below on the termination parameter for the various types of boundary condition available.

Example using the LCR model:

[Circuit Models]
circuit1
segments
 length 40.0 impedance 1.9
end
termination LCR
 capacitance 105.0 ; nF
 inductance 21.0 ; nH
 resistance 0.2 ; ohm
 voltage -250
startup_time 1.3

Example using the liner model:

[Circuit Models]
circuit1
segments
 length 8.0 impedance 13.5
end
termination liner 1

The network type of circuit model is more general in allowing construction of loops and other configurations which are beyond the capabilities of a simple transmission line. The modeling for network circuits was adapted from the BERTHA code (Ref.[13]).

Example:

[Circuit Models]
circuit1 network
elements
 1 transit_time 0.1 impedance 0.1
 2 transit_time 1.0 impedance 0.2
 3 transit_time 1.0 impedance 10.0
 4 transit_time 1.36 impedance 1.89
 5 transit_time 0.1 impedance 0.1
end
junctions
 VOLTAGE_APPLICATION 1
  voltage 200
 RESISTIVE_LOAD 2
  resistance 1.e9
 SERIES_RESISTOR 1 5
  resistance 0.2
 SIMPLE_JUNCTION 2 3
 PARALLEL_TEE 5 3 4
 GRID_CONNECTION 4
end

The parameters associated with a circuit model

segments

Specifies the parameters for each section of the transmission line model using the format:

segments
 length L1 impedance Z1 dielectric_constant EPS1
 length L2 impedance Z2 dielectric_constant EPS2
 ...
end

where `L1' is the physical length of the segment, `Z1' is the impedance of the segment in user units (see section User Units), and `EPS1' is the relative dielectric constant of the segment. The first segment is the one farthest from the simulation boundary. The last segment must have the same impedance as the outlet boundary to which it is attached. The outward-going wave reaching the first segment sees a matched termination unless the termination parameter specifies some other condition, e.g. SHORT, in which case it sees a short circuit termination. The dielectric_constant parameter is optional and has a default value of 1.

elements

Specifies the parameters for each element of the network model using the format:

elements
 1 transit_time T1 impedance Z1
 2 transit_time T2 impedance Z2
 3 capacitance C1
 4 inductance L1
 ...
end

where `T1' is the transit time of the element and `Z1' is the impedance of the element. Lengths may be used instead of transit times. Note that here each element is numbered for identification and are not necessarily order dependent, unlike transmission line segments which are order dependent.

Also, for convenience, instead of a characteristic impedance, any element can be indicated as a lumped capacitor or inductor by using the keywords capacitance or inductance. In either case, the transit time keyword and value may be omitted and, if present, are ignored and treated as zero.

junctions

Defines the configuration of the network, specifying how the elements are linked together by using the format:

junctions
 RESISTIVE_LOAD 1
 SIMPLE_JUNCTION 1 2
 GRID_CONNECTION 2
end

which is a list describing the type of junction and identifying the elements, by index number, that are to be associated at these junctions. The junction types available and their definition are as follows:

VOLTAGE_APPLICATION:
An end of an element is a matched termination where a voltage is to be applied from an infinite source. A voltage_function should be supplied in the input sequence after the element identifier.
RESISTIVE_LOAD:
An end of an element is terminated with a resistance. The resistance can be either a constant value or time-dependent (see below) and is specified after the element identifier.
SIMPLE_JUNCTION:
Two elements with different impedances are joined.
PARALLEL_RESISTOR:
Two elements are joined with a resistance between them in parallel. The resistance can be either a constant value or time-dependent (see below).
SERIES_RESISTOR:
Two elements are joined with a resistance between them in series. The resistance can be either a constant value or time-dependent (see below).
PARALLEL_TEE:
Three elements are joined such that all three grounds are connected to each other. Known as a "current adder."
SERIES_TEE:
Three elements are joined such that the ground of the first element is connected to an opposing ground and the hot of the first element is connected to an opposing hot, but ground is connected to hot between the second and third elements. Known as a "voltage adder."
PARALLEL_TEE_WITH_PARALLEL_RESISTOR:
Three elements are joined in parallel with a resistor. The resistance can be either a constant value or time-dependent (see below).
FOUR_WAY:
Four elements are joined in parallel.
GRID_CONNECTION:
At least one of the elements should be connected to the simulation grid at an outlet boundary with matched impedance such that waves pass freely between them. The code does not check for this, so if no connection is made then the circuit model will run on its own without any interaction with the simulation proper.
TERMINATION:
Use one of the termination models at an end of an element.

termination (string)[optional]

Specifies one of several types of boundary condition at the initial end of the transmission line, that is, the end away from the simulation grid. Any of these can also be applied to a network junction TERMINATION type. The termination types available are:

MATCHED:
The default condition, that is, a matched termination.
VOLTAGE_APPLICATION:
A voltage is to be applied from an infinite source.
OPEN:
An open-ended circuit, as if the line is truncated with infinite impedance.
SHORT:
A short-circuit, or zero impedance condition.
CHARGED:
An open-circuit termination with the addition that the entire length of the first transmission line segment is pre-charged to the value of the voltage parameter (see below).
LCR:
An LCR circuit, which is characterized by a lumped capacitance, inductance, and resistance, all in series, with an open-circuit termination. The capacitor is initially charged with a voltage obtained from the voltage parameter or by evaluating the voltage_function at t=0.
LINER:
Uses the imploding-liner model, the parameters of which are contained in the [Liner Models] section of input (see section Liner Models Input). This option must be followed by an integer index identifying the liner model.

Note that the formats for these terminations are slightly different for transmission lines and networks in the above examples. For transmission lines, the termination keyword and its associated parameters follow the entire sequence of segments, whereas for networks, the termination type and its parameters directly follow the junction with which they are associated, while omitting the actual termination keyword.

capacitance (real)[optional]

This specifies the capacitance of either the static circuit model, or as part of the termination LCR option of the transmission-line or network models.

inductance (real)[optional]

This specifies the inductance in the termination LCR option of the transmission-line or network models.

resistance (real)[optional]

This specifies the resistance of either the static circuit model, or as part of the termination LCR option of the transmission-line or network models, or any of the network junction types involving a resistance. This parameter can be replaced by a resistance_function, which is explained below.

resistance_function (integer)[optional]

This specifies the resistance for any of the network junction types which involve resistance as a function of time, that is, it may be used in place of the constant-valued resistance explained above. Specifically, when used in conjuction with the SERIES_RESISTOR junction model, it acts as an opening or closing switch by defining the appropriate functional prescription in the [Functions] section of input.

voltage (real)[optional]

Value of the voltage for cases in which an initial constant charge is appropriate. These are, for example, the static circuit type or either of the "dynamic" models in which a CHARGED or LCR termination is specified.

voltage_function (integer)[optional]

Integer index which refers to the function in the [Functions] section specifying the time-dependence of the inward-going (towards the simulation grid) voltage at the first circuit model element (see section Functions Input). This should only be used with the static circuit type, the transmission-line type with the termination parameter set to VOLTAGE_APPLICATION, CHARGED, or LCR, or the network circuit wherever a junction type is set to VOLTAGE_APPLICATION or TERMINATION where the termination type is either of CHARGED, LCR, or again, VOLTAGE_APPLICATION. For the static circuit or the termination LCR case, the function determines only the initial voltage (at t=0) on the capacitor. If voltage_function is 0, no voltage is applied, and is otherwise ignored when the termination parameter is any other kind.

startup_time (real)[optional]

Allows the circuit model calculation to be started prior to the main calculation in the simulation grid; e.g., in a case where the simulation is driven by the circuit model voltage, it may take a significant amount of time for a nonzero voltage to reach the simulation boundary. The units for time are dependent upon which system of units has been specified by the user (see section User Units), but the number should be positive. The user must insure that the actual transit time for the sum of the element lengths specified is not exceeded.

frequency (real)[optional]

Specifies the incoming wave frequency in Hz. The amplitude is determined by either the voltage parameter or the voltage_function parameter below, depending on which is specified.

impedance_product_function (integer)[optional]

Index of a function in the [Functions] section which specifies a time-varying multiplier applied to the impedance of the first element of the circuit model (see section Functions Input). However, the resulting impedance mismatch affects only the outgoing wave, not the incoming voltage pulse. If impedance_product_function is 0, no multiplier is applied.

Volume Models Input

The [Volume Models] section of the input file provides a number of models which can be applied over grid-conformal blocks of the simulation space. Entries in this section are numbered consecutively by appending an integer index to the volume keyword. Most of these models are intended to be used only with dynamic field solution, rather than static field solution. The dielectric model is the only volume model that can be invoked while using a static field solver. The models currently available are described below.

Examples are:

[Volume Models]
volume1
dipole Z
from 2.0,  0.0,    12.5
to   2.0,  0.2618, 13.0
total_current 2.5e5 ; amps
temporal_function 2 *
secondary_function 3 *
spatial_function 0 *
reference_point 0 0 0 *
spatial_flags 0 0 0 *

volume2
conductivity Z
from 2.0 0.0 1.0
to   2.0 0.5 4.0
sigma 10.0
temporal_function 0 *

volume3
ferrite
from 0.5 0.9 0.0
to   0.9 2.0 10.0
permeability 285.0 8.0 ; static and infinite values
resonances
 sine_coefficient 0.0 cosine_coefficient 5.21e10
 decay_rate 1.88e8 frequency 0.0
end

When it is necessary to construct a repetitive series of similar volume models, it is possible to use additional instructions after a single instance that repeats the model 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 volumes generated and `X Y Z' is the spatial translation vector to be used each time.

Example:

volume1
dielectric
from 0.0 0.0 0.0
to   5.0 1.5 4.0
dielectric_constant 6.5
temporal_function 0 *
repeat 2 times, with 0.0 0.0 8.0

conductivity

The conductivity model creates an Ohm's-Law current density within the specified volume; i.e., for the i'th component of the electric field. The format is

[Volume Models]
volume1
conductivity COMP
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
sigma VALUE
temporal_function M *
spatial_function N *
reference_point RX RY RZ *
spatial_flags LX LY LZ *

where `COMP' is the electric field component (X|Y|Z) affected, `XMIN', `YMIN', `ZMIN' and `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume, `VALUE' is the conductivity value, and `M' is the function index specifying the time-dependence of the conductivity multiplier (see section Functions Input). Additional options include a spatially-dependent function which also acts as a conductivity multiplier, the reference point for that spatial dependence, and three logical flags set to zeros or ones indicating which coordinates are dependent upon the spatial function. These must be present if the spatial function index is non-zero. Any use of spatial dependence in the conductivity model requires the USE_CONDUCTIVITY compiler directive be defined. See section USE_CONDUCTIVITY. Caution must be taken when applying the conductivity model over a volume containing dielectric material. In that case the user must use a value of sigma that has been divided by the relative dielectric constant which has been applied to the volume. However, when both USE_CONDUCTIVITY and USE_PERMITTIVITY compiler directives have been defined, this is not the case, as the permittivity of the dielectric is correctly accounted for in the conductivity of the overlapping volume. The units of conductivity are dependent on which system of units has been specified by the user (see section User Units).

dielectric

The dielectric model creates a specified volume of material with a spatially uniform value of permittivity. The format is

volume2
dielectric
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
dielectric_constant VALUE *
temporal_function N *

where `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume, `VALUE' is the relative dielectric constant, and `N' is the function index specifying the time-dependence of the dielectric value multiplier (see section Functions Input).

When using this model with the ADI field solver (see section IMPLICIT_FIELDS), the compiler directive USE_PERMITTIVITY must be defined. See section USE_PERMITTIVITY.

A more general way to specify dielectric materials is through a medium model associated with structural objects (see section Objects Input).

dipole

The dipole model places an externally-applied current density within the specified volume. The format is

volume1
dipole COMP
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
total_current VALUE
temporal_function M *
secondary_function S *
spatial_function N *
reference_point RX RY RZ *
spatial_flags LX LY LZ *

where `COMP' is the component direction of the current density (X|Y|Z), `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume, `VALUE' is the total current value, and `M' is the function index specifying the time-dependence of the current multiplier, if present (see section Functions Input). Additional options include specification of a secondary temporal function (which results in a product function with the primary temporal function), a spatially-dependent function which also acts as a current multiplier, the reference point for that spatial dependence, and three logical flags set to zeros or ones indicating which coordinates are dependent upon the spatial function. These must be present if the spatial function index is non-zero.

ferrite

The ferrite model creates a linear dispersive magnetic material in the specified volume. The "recursive-convolution" method (Ref.[11]) is used to perform the necessary convolution in an efficient manner. Usually, the response function is approximated by a sum of single-pole Debye relaxations and double-pole Lorentzian resonances.

The ferrite model cannot be used with the ADI field solver (see section IMPLICIT_FIELDS).

The format is:

volume1
ferrite
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
permeability MU_STATIC MU_INF
resonances
 sine_coefficient S1 cosine_coefficient C1
 decay_rate DELTA1 frequency FREQ1
 sine_coefficient S2 cosine_coefficient C2
 decay_rate DELTA2 frequency FREQ2
 ...
end

where `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume, `MU_STATIC' is the limiting value of the magnetic permeability for zero frequency, `MU_INF' is the limiting value of the magnetic permeability for infinite frequency, `S1' and `C1' are the coefficients in the representation of the response function and `FREQ1', `DELTA1' are the resonant frequency (in rads/sec) and decay rate (1/sec) of the first resonance. Up to MAX_RESONANCES (see section MAX_RESONANCES=#) relaxations/resonances can be specified between the resonances and end keywords.

hysteresis

The magnetic hysteresis model utilizes both magnetic induction and magnetic intensity in the cells in order to model magnetic hysteresis phenomena. The format is

volume1
hysteresis
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
data_file FILE

where `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume and `FILE' is the name of the data file containing a series of B-H hysteresis curves. The format for this file is defined in the section under "File Formats" in section Hysteresis Data File.

When using this model, the compiler directive MAGNETIC_HYSTERESIS must be defined. See section MAGNETIC_HYSTERESIS. In addition, the B and H magnetic fields in the model can be initially set to some values at the lower extremity of the hysteresis curve at the onset of the simulation by using the applied_current parameter in the [Control] section of input (see section applied_current (real)).

paramagnetic

The paramagnetic model places a magnetic permeability within the specified volume. The format is

volume1
paramagnetic
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
permeability MU_REAL
liner M *
temporal_function N *

where `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are diagonally opposite corners of the volume, `MU_REAL' is the value of the magnetic permeability. The optional parameter liner is used to invoke a simple imploding-liner model. It specifies an integer `M' which refers to the linerM entry in the [Liner Models] section (see section Liner Models Input). The liner model dynamically changes the permeability from its initial value. The optional parameter temporal_function specifies an integer `N' which is the index of a function which multiplies the permeability (see section Functions Input).

When using this model with the ADI field solver (see section IMPLICIT_FIELDS), the compiler directive USE_PERMEABILITY must be defined. See section USE_PERMEABILITY.

A more general way to specify paramagnetic materials is through a medium model associated with structural objects (see section Objects Input).

Liner Models Input

The [Liner Models] section of the input file specifies parameters for a simple imploding-liner model. Entries in this section are numbered consecutively by appending an integer index to the liner keyword. This integer may be used in the paramagnetic model to obtain a dynamically changing magnetic permeability over a specified volume (see section paramagnetic). This allows a self-consistent treatment of the changing inductance of the liner region. The user must ensure that the liner dimensions are consistent with the actual geometry.

The format is:

[Liner Models]
liner1
mass M
length L
outer_radius RO
inner_radius RI
final_radius RF

where `M' is the mass of the liner, `L' is the length of the liner, `RO' is the outer radius of the can containing the liner, `RI' is the initial inner radius of the liner, and `RF' is the final radius of the liner after implosion. Note that RF is smaller than RI, causing the impedance to increase as the liner implodes.

Subgrid Models Input

The [Subgrid Models] section of the input file provides a means of modeling structure electromagnetically on scales which are smaller than the gridding provides; for example a smooth non-conformal surface which cannot be accomplished with ordinary stair-stepping techniques. This is an idea taken from Jurgens et al. (Ref.[8]), where it was used in scattering simulations on spherical bodies in a 3-D cartesian mesh.

At present, the only use of this technique is for a flat surface sloped in any two coordinate directions, but not all three. This model, although it is useful for eliminating undesirable wave distortion which may result from a stair-stepped model, is not suitable for particle charge conservation, and should only be used in areas of the simulation where particles do not occur. Also, it has not yet been implemented for static fields solutions or implicit fields solutions. When using this model, the compiler directive USE_SUBCELLS must be defined. See section USE_SUBCELLS.

Example:

[Subgrid Models]
subgrid1 SLOPE ; pierce electrode
normal0 Z
normal1 -X
from 8.25 0 13.0
to 17.25 0 17.0

where the two normal parameters control the orientation and the from to coordinates merely indicate the space in which the model is located. These are not necessarily the two end-points of the slope. The actual orientation is determined by the normal parameters which are understood to give the signed direction normal to the conducting surface. The user does not ordinarily place any other structural objects explicitly within the coordinate boundaries indicated by the subgrid model (see section Objects Input).

Substrate Models Input

The [Substrate Models] section of the input file provides a means of emitting ion species which exist as absorbed material in a specially prepared metal plate. Entries in this section are numbered consecutively by appending an integer index to the substrate keyword. The only model currently available is described below. Note that the number of materials is three. The first material is the metallic plate; the second is the ceramic backing; the third is an aluminum oxide sleeve. The production of ions from the substrate is stimulated by energy deposition on the surface. Therefore, the substrate model must be imbedded in a structural surface of conductor material in order to function correctly. This model may not be available in all releases of the LSP code.

Example:

[Particle Species]
species2 ; Hydrogen
charge 0
mass 1837.0

[Substrate Models]
; Hydrogen source - materials: Metal, Ceramic, Aluminum
substrate1
atomic_weight_of_metallic_layer 45.0
densities_of_materials 3.00 5.53 3.80 ; g/cc
radii_of_materials 0.1 0.07 0.2
depth_of_metallic_layer 6.0e-1
depth_of_ceramic_layer 14.0e-1
radial_resolution 50
axial_resolution 50
initial_temperature 300.0 ; kelvin
ratio_H_to_M 1.0 ; ratio of absorbed hydrogen to metal ions
reference_point 0. 0. 5.0
alignment_axis -Z
interval 10
species 2 *
minimum_charge 0.0 *
movie_tag 0 *
movie_fraction 0.0 *

External Fields Input

External fields are user-prescribed fields which are added to the self-consistent electromagnetic fields produced by the simulation, exclusively for the purpose of affecting particle forces. Single values, 1-D arrays, 2-D arrays, and 3-D arrays of electric or magnetic fields can be used. For 1-D arrays the field values are described by an input function as described below. For 2-D and 3-D arrays the field values are read from user-supplied data files. The coordinate values for the external fields on these files need not match the LSP simulation grid, as they are interpolated onto it.

For 2-D field arrays, the data file contains cylindrical Bz, Br data. Two formats are supported: one produced by the BFIELD code which can be in either ASCII text or binary form (see section BFIELD Magnetic Field File), and an ASCII text file produced by the SNL ATHETA code (see section ATHETA Magnetic Field File). In both cases, the data are transformed into Bx, By, Bz when using a cartesian simulation grid.

For 3-D fields, an ASCII file produced by the MAG3D code can be accepted (see section MAG3D Magnetic Field File), or a similar binary file produced by MAFCO may be utilized (see section MAFCO Magnetic Field File). The latter file type is produced by the mafco code contained internally in the LSP package.

The parameters associated with external field input

Example of single-value input:

[External Fields]
external1
 type COMPONENT
 field B Z 300.0
 temporal_function 0 *

where the qualifier COMPONENT indicates the single-value option.

Example of 1-D array input:

[External Fields]
external1
 type ANALYTIC
 field B Z
 spatial_function 1
 from 0.0 0.0 0.0 *
 to   8.0 8.0 8.0 *
 reference_point 0.0 0.0 0.0 *
 alignment_axis Z *
 symmetry_direction NONE *
 temporal_function 0 *
;
[Functions]
; external field data for the laser diode
function1
type 0
data_pairs
 -6.00E+00    6.7315E+02
 -4.30E+00    7.1863E+02
 -2.60E+00    7.6390E+02
 -9.00E-01    8.0763E+02
  8.00E-01    8.4832E+02
  2.50E+00    8.8445E+02
  4.20E+00    9.1476E+02
  5.90E+00    9.3843E+02
end

Example of 1-D array input with bilateral symmetry:

[External Fields]
external1
 type ANALYTIC
 field B Z
 spatial_function 1
 reference_point 0.0 0.0 0.0 *
 alignment_axis Z *
 symmetry_direction Y *
 temporal_function 0 *

Example of 1-D array input with axial symmetry:

[External Fields]
external1
 type ANALYTIC
 field B Z
 spatial_function 1
 reference_point 0.0 0.0 0.0 *
 alignment_axis Z *
 symmetry_direction THETA *
 order 6 *
 temporal_function 0 *

Example of data file input:

[External Fields]
external1
 type DATAFILE FILETYPE FILENAME
 format binary *
 reference_point 0.0 0.0 50.0 *
 alignment_axis Z *
 temporal_function 0 *

type (string)

Specifies the type of external fields input. It can take the values COMPONENT for a single value, ANALYTIC for a 1-D array of field values, or DATAFILE for a 2-D or 3-D array of values supplied in an external file.

For the ANALYTIC option, the 1-D array is a tabulated function (see section Functions Input) specified by the spatial_function parameter. The first column of the table gives the spatial coordinate and the second gives the magnetic field.

For the DATAFILE option, which indicates 2- or 3-dimensional data contained on a user-supplied file, FILETYPE specifies one of the available file types (BFIELD|ATHETA|MAG3D|MAFCO), and FILENAME is the name of the file supplied by the user. An explanation of the various file types is explained in the section on File Formats. (See section File Formats.)

For the ANALYTIC and DATAFILE options, either one or both of the compiler directives EXTERNAL_BFIELDS or EXTERNAL_EFIELDS must be defined at compilation time, depending on which of those fields are indicated by the field parameter described below (see section EXTERNAL_BFIELDS, see section EXTERNAL_EFIELDS). Also, note that the use of multiple instances of either of these types (of the same field) requires that the definition of EXTERNAL_BFIELDS or EXTERNAL_EFIELDS is set to the number of instances requested on input.

field (string)

Specifies an external magnetic or electric field (B|E). The format for this parameter when the COMPONENT option is in effect is

field B X|Y|Z VALUE

which specifies the value `VALUE' for the X|Y|Z component of the external magnetic field, or,

field E X|Y|Z VALUE

which specifies the value `VALUE' for the X|Y|Z component of the external electric field.

For the ANALYTIC option, a `VALUE' does not appear.

For the DATAFILE option, this parameter need not appear since all of the file options involve only magnetic fields.

where `FILENAME' is the name of the datafile. The various file formats are given in section File Formats. For the BFIELD specification, the optional keyword FORMAT may be present to indicate that the file is either type ASCII or binary with ASCII being the default.

format (string)[optional]

Format for data file to be read - ASCII or binary.

Default: ASCII

from to (real)[optional]

The parameters from, to, specify the lower and upper coordinate limits of the volume over which the field is applied. They are optional, and if not specified, the field is applied everywhere. These parameters are ignored for the simple COMPONENT type.

reference_point (real)[optional]

The origin for the external field is shifted to the coordinates of reference_point on the simulation grid.

alignment_axis (string)[optional]

For a 1-D external field, specifies the direction (X|Y|Z) of the spatial coordinate in the field data, and the field component. For a 2-D external field, specifies the direction in the simulation grid (X|Y|Z) corresponding to the Z direction in the field data file. This parameter has no effect for 3-D data contained in the MAG3D or MAFCO formats under the DATAFILE option.

Default: Z

symmetry_direction (string)[optional]

For the ANALYTIC option only, the transverse components of the magnetic field are calculated analytically according to which option is specified:

symmetry_direction DIR

where `DIR' can have the values NONE|X|Y|Z|THETA. The value NONE indicates that no transverse components are calculated. Use of the THETA option produces an analytic expansion for the off-axis cylindrically symmetric fields, based upon the axial field specified in the spatial_function. Use of one of the X|Y|Z tokens will result in a single component of transverse field being calculated. Note that this component should not be the same as the main component given by the alignment_axis parameter.

Default: NONE

order (integer)[optional]

For the THETA option of the symmetry_direction parameter only, the order parameter indicates the order of the expansion used in the evaluation of the transverse dependence for axial symmetry. The value used should not exceed 6. Generally, use of higher orders requires more highly resolved and accurate data in the spatial_function.

Default: 2

temporal_function (integer)[optional]

Integer identifying the time-dependent function used to multiply the external field value(s). For the COMPONENT option, there are no restrictions in the use of this parameter when multiple instances of external field are required. However, with the more complex descriptions, designated by the ANALYTIC and DATAFILE options, use of multiple instances of either of these types (of the same field) are restricted to a single temporal dependence given by this parameter in the first instance. For no time-dependence, set the value to 0. (See section Functions Input.)

Particle Species Input

The [Particle Species] section specifies the particle species to be used in the simulation and their properties. Each species is identified by the integer index appended to the species keyword. This integer is used elsewhere in the input file to refer to that species. If ionization (see section ionization) or photoionization (see section photoionization) is being used, then each ionization state is treated as a separate species, and successively higher ionization states must be listed in sequence (i.e., if species3 is neutral, then the first ionization state should be species4, etc.)

Example:

[Particle Species]
species1
charge  -1
mass     1.0
fluid_species_flag off *
migrant_species_flag off *
implicit_species_flag off *
particle_motion_flag on *
particle_forces_option averaged *
transverse_weighting_flag on *
particle_kinematics_option standard *
montecarlo_scattering_flag off *
selection_ratio 0.5 *
species2
charge  +1
mass  1836.0
atomic_number 1 *
selection_ratio 1.0 *

Example when using the ionization model (see section ionization):

[Particle Species]
species1
charge -1
mass  1.0
fluid_species_flag off *
particle_forces_option primary *
species2
charge +1
mass  1836.0
atomic_number 1 *
species3
charge 0
mass  3674.0
atomic_number 2 *
species4
charge +1
mass  3673.0
atomic_number 2 *

Example when using the higherstate model (see section higherstate):

[Particle Species]
species1
charge  -1
mass   1.0
fluid_species_flag off *
particle_forces_option averaged *
; Nitrogen ions
species2
charge  +1
mass 27540.0
atomic_number 7 *
species3
charge  +2
mass 27539.0
atomic_number 7 *

Example of implicit species:

[Particle Species]
species1
charge  -1
mass   1.0
implicit_species_flag on *
particle_motion_flag on *
particle_forces_option primary *
montecarlo_scattering_flag on *
implicit_filtering_parameter 1.0 *
selection_ratio 0.2 *

charge (real)

Gives the charge state for each species, normalized to that for a positron. Thus, an electron is -1, and a proton is +1 (plus-sign optional) and a neutral is 0.

mass (real)

Gives the mass for each species, normalized to that for a positron. Thus, an electron is 1, and a proton is 1836.

atomic_number (real)[optional]

Atomic number of ion species. Used with the ionization model (see section ionization), the photoionization model (see section photoionization), or with the higherstate model (see section higherstate), that is, any particle creation model which involves the transition into a higher charge state (ionization or stripping).

fluid_species_flag (flag)[optional]

Indicates which charged-particle species are treated as fluid particles when the fluid physics (see section FLUID_PHYSICS) portion of the collisional plasma scattering model (see section SCATTERING_ON) has been invoked. This option is particularly useful in the direct-implicit algorithm when the product of the species plasma frequency and timestep is large. Numerical cooling will occur in this case if the species is treated kineticly.

Default: OFF

migrant_species_flag (flag)[optional]

Indicates which electron species are treated as "migrating" species for the hybrid plasma migration model, which is an optional feature of the fluid physics portion of the collisional plasma scattering model. Only particles which belong to a species which has been designated as a migrant species have the ability to transform into one of the opposite type. That is, kinetic type electrons become fluid electron species, and vice-versa. This process is described in the Particle Migration section of input (see section Particle Migration Input).

Default: ON

implicit_species_flag (flag)[optional]

Indicates which species undergo implicit advancement in the particle kinematics. The DIRECT_IMPLICIT compiler directive must be defined in order for this option to be relevant (see section DIRECT_IMPLICIT).

Default: ON

particle_motion_flag (flag)[optional]

For species with particle_motion_flag set to OFF, the particle positions never change. This may be useful for analysis of pure scattering phenomena.

Default: ON

particle_forces_option (string)[optional]

Selects the method by which the fields effect particle forces. The option AVERAGED will cause the spatially averaged fields at grid node positions to be used. The option PRIMARY or STAGGERED will use the fields directly calculated from the E-M solution on the particles. Additionally, the particle_forces_option can be set to NONE, in which case, the particle positions will be advanced but not their momenta. The AVERAGED option is good for momentum conservation, in that there are no "self forces" on the particles. The PRIMARY option produces an energy-conserving push that is not susceptible to the so called Debye-length numerical instability. The simulation is numerically stable even for grid size larger than the plasma skin depth, although resolution of this parameter is desirable. The magnetic field in this case is still provided by the averaged values as for the AVERAGED option. The PRIMARY option is recommended (and is the default) when the EXTENDED_PARTICLES compiler directive has been defined (see section EXTENDED_PARTICLES). This choice is required for species that have been designated for implicit advancement.

Default: AVERAGED for explicit species, PRIMARY for implicit species or when EXTENDED_PARTICLES is defined.

transverse_weighting_flag (flag)[optional]

Used to modify the spatial weighting scheme for particle forces due to fields. This can be set to OFF under simulation conditions where a continuous beam would produce a "saw-tooth" instability. Ordinarily, this flag is left ON. This flag applies to explicit species only, and is ignored for implicit species. Also, this flag is ignored if the EXTENDED_PARTICLES compiler directive is defined and the particle_forces_option is set to PRIMARY.

Default: ON

particle_kinematics_option (string)[optional]

Used for the selection of multiple options in the method of advancing particle momentum. The STANDARD option uses the familiar "leap-frog" technique with the magnetic field rotation splitting the electric field push into two separate halves. The IMPLICIT option does the electric and magnetic advancements simultaneously. The PARAXIAL option is a simplified calculation appropriate only for paraxial beams. This parameter applies to explicit species only, and is ignored for implicit species.

Default: STANDARD

montecarlo_scattering_flag (flag)[optional]

Indicates which species (usually electrons) undergo random montecarlo scattering in the collisional plasma model. If this is set to OFF, the scattering is done in an averaged way and results in an energy distribution that is not as accurate. In order to use this option, the appropriate interaction file must be provided in the [Particle Interaction] section of input (see section Particle Interaction Input). The SCATTERING_ON compiler directive must be defined in order for this option to be relevant (see section SCATTERING_ON).

Default: OFF

implicit_filtering_parameter (real)[optional]

Damping factor for the "c0-d1" particle push (Ref.[3]). The default value is 1, giving maximum damping (d1 scheme). A value of 0 gives the undamped, reversible c0 scheme. This parameter applies to implicit species only.

Default: 1 (maximum damping - d1 scheme)

selection_ratio (integer)[optional]

Causes a random selection of particles of this species during output of the particle dumps such that the number selected is a fraction of the total according to this ratio.

Default: 1.0

Particle Creation Input

Particles can be introduced into the simulation in several ways. The following table lists the keywords used to invoke the available models:

emission:
emission from a surface, using either the child-langmuir, field-limited, source-limited or stimulated models discussed below
injection:
injection through a boundary (e.g., a beam)
secondary:
secondary emission of electrons and positrons from a surface as a result of either a method 2 medium or a method 4 medium (see section Medium Models Input)
backscatter:
backscatter is applied to particles, primary or secondary, which have impinged upon a method 3 medium (see section Medium Models Input)
desorption:
thermal and/or stimulated desorption of neutrals and ions from a surface
ionization:
collisional ionization, usually applied to neutral ion species (charge 0)
higherstate:
currently this is a specialized ion-ion stripping model
photoionization:
ionization of neutral or charged species by photons
plasma:
plasma existing in the simulation space at the start of the simulation
excitation:
conversion of electrons from a low energy state to an excited state by laser acceleration
fragmentation:
conversion of heavier molecules into smaller ones by bond breaking
fileread:
injection using particle data from a previously created file
fission:
numerical particle splitting in regions where the physics is hampered by the coarseness of particle statistics (e.g., emission from the surface of a dense plasma)
trajectory:
tracer particles which produce an output file giving their trajectory and the fields acting on them.

All of these models are invoked from the [Particle Creation] section of the input file. The following sections describe generic and model-specific parameters for the models. Sample models follow the first section.

Particle Creation Parameters

Parameters which are common to more than one model

from to (real)

The parameters from, to, specify the lower and upper limits of the area or volume over which the creation model is applied. See the sections on the individual models to determine how to use these parameters.

normal (string)

Specifies a particle direction (e.g., injection, fileread). Can take the values X, -X, Y, -Y, Z, -Z.

interval (integer)

Number of timesteps between application of particle-creation model.

species (integer)

Integer identifying species to be created, or for any of the stripping models, the species which is acted upon to create the next higher ionized state. These last are the ionization, higherstate, and photoionization models. In such cases, the identified species on the Particle Species Input list must be followed by a species corresponding to its next higher state, that is, with a charge greater by 1 and with a mass which is smaller by 1. (See section Particle Species Input.)

electron_species (integer)

Integer identifying the species to which the newly created electron produced in an ionization event belongs. The electrons may be either of kinetic or fluid type (provided the compiler directive FLUID_PHYSICS is defined). (See section Particle Species Input.)

discrete_numbers (integer)[optional]

For the emission, injection and plasma models, this specifies the number of particles per cell in the X|Y|Z directions, respectively. The value in the direction of injection or emission is usually 1. Two numbers may be entered in the case of 2D simulations and are understood to correspond to the actual dimensions used. This input item defaults to a single particle per cell.

Default: 1 1 1

centroid1&2_function (integer) [optional]

Integers identifying the functions (centroid1_function and centroid2_function) used to specify the time-dependence of the injected beam centroid position in the two directions transverse to the injection direction, relative to the reference_point below. The two directions are in cyclic order (X, Y, Z) with the injection direction. However, for cylindrical coordinates, where the injection direction is Z, the transverse directions for these functions are understood to be in a cartesian sense, that is, X and Y. These parameters are optional and may be omitted (or set to zero) if there is no centroid motion. See section Functions Input.

reference_point (real)

The origin for particle coordinates is shifted to the coordinates of reference_point on the simulation grid. The number of values which follow this parameter may correspond to the actual number of dimensions defined for the simulation (1, 2, or 3), although all three values may be present when a reduced number of dimensions is used.

drift_momentum (real)

Specifies constant momentum values in the X, Y, Z directions which are applied to every particle in units of gamma-beta. This parameter conflicts with the drift_velocity parameter and they should not both appear in the same instance of a Particle Creation Input.

drift_velocity (real)

Specifies constant velocity values in the X, Y, Z directions which are applied to every particle in user units (length/time). This parameter conflicts with the drift_momentum parameter and they should not both appear in the same instance of a Particle Creation Input.

random (flag)

If ON, randomize the particle initial position within the cell where it is created.

medium (integer)[optional]

Specifies a medium index for which the model is applied; that is, only those cells which contain that specific medium identifier will participate in the process associated with the model. The parameter appears in this form for the emission and desorption models. When it is not used or set to 0, it is ignored and all cells within the defined volume will participate. Note that other particle creation models may contain medium identifiers which are mandatory, in which case they are listed in their appropriate Particle Creation Input subsections.

charge_factor (real)[optional]

A multiplier applied to the emitted charge after it has been calculated from the appropriate model. This can be used to suppress particle creation when desirable.

thermal_energy (real)[optional]

Thermal energy (in eV) used to add a Gaussian distribution to the momentum or to set the temperature in the case of a fluid species.

Default: 0.0

slice_times (integer)[optional]

A list of times (in user units) at which injected particles (from either the injection or fileread models) are tagged for particle-slice diagnostics (see section Particle-Slice Probes).

movie_tag (integer)[optional]

Integer (0 < movie_tag < 8) used to identify the particles created with the current model in the movie file. (See section P4 Postprocessor.)

Default: 0 (no tag)

movie_fraction (real)[optional]

Fraction of particles created which will be tagged for output to the movie file. (See section P4 Postprocessor.)

Default: 0.0 (no particles tagged)

emission (child-langmuir)

Child-Langmuir emission is the standard space-charge-limited emission model. There are two sub-models which differ only in the method used to determine the onset of emission. These are the field-stress and thermal breakdown methods (see section threshold (real)). Use of the thermal breakdown method requires that the compiler directive KELVIN_DEPOSITION be defined (see section KELVIN_DEPOSITION). Model-specific parameters

Example of Child-Langmuir emission:

emission child-langmuir field-stress
from 6.9, 0.0, 0.8
to   7.35, 6.283, 1.95
interval 2
species 1
discrete_numbers 1 1 1 *
random off
medium 0 *
inclusion vacuum *
threshold 25.55 *
charge_factor 1.0 *
surface_factor 0.66667 *
thermal_energy 0.0 *
movie_tag 1 *
movie_fraction 0.2 *

Example of Child-Langmuir emission with temporal dependence for breakdown:

emission child-langmuir field-stress
from 1.0, 0.0, 1.0
to   1.5, 3.0, 1.5
interval 1
species 1
random off
medium 0 *
threshold 25 *
breakdown_function 1 *
surface_factor 1.0 *
thermal_energy 0.0 *
movie_tag 0 *
movie_fraction 0.0 *

Example of Child-Langmuir emission with thermal breakdown:

emission child-langmuir thermal
from 0.0, 0.0, 0.0
to   5.0, 5.0, 2.5
interval 1
species 1
random off
medium 1 *
threshold 400 *
surface_factor 1.0 *
thermal_energy 0.0 *
movie_tag 0 *
movie_fraction 0.0 *

from to (real)

These coordinate parameters describe a volume of the simulation space over which the model is applied. The test cells within this volume which can cause emission are solid surface cells (conductor or dielectric) or adjoining vacuum cells, depending upon the method specified for the inclusion parameter below. In either case, particles can only be created at surface interfaces between solid cells and vacuum cells.

inclusion (string)[optional]

This parameter prescribes the rule that determines which cell surfaces are emitters within the from to range described above. The possible values are either SOLID or VACUUM, such that only cells of those types within the specified coordinates become candidates for emission. The vacuum option is not available for the stimulated model (see section emission (stimulated)).

Default: SOLID

threshold (real)

For child-langmuir field-stress, the threshold is the value of electric field stress at which breakdown occurs, that is, when emission begins. For child-langmuir thermal, the threshold is the surface temperature (in kelvins) at which emission is initiated. For the latter case, if a non-zero value is specified, the KELVIN_DEPOSITION compiler directive must be defined (see section KELVIN_DEPOSITION). The surface temperature is computed from the energy deposited by electrons (or positrons) and the specific heat of the surface material. Note: A solid medium model is required in order to generate the necessary surface-temperature data (see section Medium Models Input).

breakdown_function (integer)[optional]

A time-dependent function which defines the multiplier applied to the emitted charge as a means of delaying the onset of space-charge-limited emission after surface breakdown has been achieved. Use of this option requires that the compiler directive DELAY_BREAKDOWN be defined (see section DELAY_BREAKDOWN).

surface_factor (real)[optional]

A multiplier applied to the surface fields at emission cells prior to calculating the emitted charge. For standard Child-Langmuir emission, the value is 2/3.

Default: 2/3

emission (field-limited)

Field-limited emission is a variant of the Child-Langmuir model where, instead of emitting enough current to reduce the field at the surface to zero, the code emits enough current to reduce the surface field to the threshold value. This model was developed for the PBFA-II lithium ion source.

Generic parameters are described in section Particle Creation Parameters.

Example:

emission field-limited
from 4.05, 0.0, 0.0
to   6.90, 6.283, 0.05
interval 8
species 2 ; lithium ions
random off
medium 0 *
threshold 6000.0 *
charge_factor 1.0 *
surface_factor 1.0 *
thermal_energy 0.0 *
movie_tag 3 *
movie_fraction 0.1 *

emission (source-limited)

Source-limited emission is the same as Child-Langmuir emission, but does not allow more than the specified source_current_density to be produced.

Generic parameters are described in section Particle Creation Parameters.

Example:

emission source-limited
from -1.0, -1.0, 0.0
to    1.0,  1.0, 0.0
interval 1
species 1
discrete_numbers 2 2 1 *
random off
medium 0 *
threshold 0.1 *
charge_factor 1.0 *
surface_factor 1.0 *
thermal_energy 0.0 *
source_current_density 20.0 ; amps/sq-cm
movie_tag 0 *
movie_fraction 0.0 *

emission (stimulated)

Stimulated emission is defined as the creation of (initially) stationary charge at a surface in a specified ratio to the amount of charge hitting the surface. Either the CHARGE_DEPOSITION or the STIMULUS_DEPOSITION compiler directive must be defined in order to use this model (see section CHARGE_DEPOSITION) or (see section STIMULUS_DEPOSITION). The use of the STIMULUS_DEPOSITION compiler directive is linked with the stimulating_species parameter described below. A surface temperature threshold can be specified, below which no emission occurs. In order to use the temperature threshold, the KELVIN_DEPOSITION compiler directive must be defined (see section KELVIN_DEPOSITION). The surface temperature is computed from the energy deposited by electrons (or positrons) and the specific heat of the surface material. Note: A solid medium model is required in order to generate the necessary surface-temperature data (see section Medium Models Input). Caution: if a stimulated emission surface is only one cell thick, it will behave such that the physical parameters of those cells will act on both sides of the surface. In order to make the two sides react to physical conditions independently, the material should be at least two cells thick.

The model-specific parameters

As an example, this type of emission was used to model the production of ions, through beam-impact ionization, from a surface where a neutral layer was desorbed through beam heating of the surface. In this case, the charge_factor is given by the ionization cross section times the areal density of the desorbed layer.

Example:

emission stimulated
from 0.0, -0.15, 1.45
to   0.15, 0.15, 1.65
interval 30
species 2 ; ions
stimulating_species 1 *
random OFF
medium 0 *
threshold 400.0 ; kelvins *
charge_factor 0.01 *
surface_factor 1.0 *
thermal_energy 0.0 *
minimum_charge 0.0 *
movie_tag 1 *
movie_fraction 0.2 *

from to (real)

For stimulated emission, these coordinate parameters describe a volume of the simulation space over which the model is applied. The test cells within this volume which can cause emission are solid material cells. Any actual particle creation can only take place on exposed surfaces of those cells.

stimulating_species (integer)[optional]

Integer identifying the stimulating species; that is, the particle species which, through deposition on an emission surface, causes the stimulation of the emitted species. If used, the compiler directive STIMULUS_DEPOSITION must be defined (see section STIMULUS_DEPOSITION). When this parameter is not used, all species present can contribute to the stimulating process, as long as the CHARGE_DEPOSITION compiler directive has been defined (see section CHARGE_DEPOSITION). (See section Particle Species Input.)

charge_factor (real)[optional]

For stimulated emission, specifies the ratio of charge generated at the surface to the charge incident on the surface.

injection

The injection model introduces particles with prescribed current density and momentum from a boundary.

The model-specific parameters

Example:

; Beam injection
injection
from 0.0, 0.0, 0.0
to   0.5, 0.5, 0.0
normal Z
interval 1
species 1
discrete_numbers 1 1 1 *
random ON
temporal_function 1
spatial_function 2 *
radius_function 0 *
drift_momentum 0 0 0 *
spatial_momentum_function 3 *
temporal_momentum_function 0 *
centroid1_function 0 *
centroid2_function 0 *
reference_point 0. 0. 0.
spatial_flags 1 1 0 ; radial dependence
deflection1_angle -3.0 *
deflection2_angle 0.0 *
deflection1_function 0 *
deflection2_function 0 *
convergence on, focal_length 6.0
rotation on, omega 0.09
thermal_energy 9000.0 * ; eV
slice_times *
 0.0 50.0
end
movie_tag 1 *
movie_fraction 0.25 *

from to (real)

For injection, these coordinates should define a plane and the normal parameter should be set to (+/-) X|Y|Z to give the direction of injection.

temporal_function (integer)

Integer identifying the function used to specify the time-dependence of the beam current density. (See section Functions Input.)

spatial_function (integer)

Integer identifying the function used to specify the spatial dependence of the beam density. Used in conjunction with the reference_point and spatial_flags parameters. The spatial_function is multiplied by the temporal_function to form a complete description of the beam's current density. Therefore, the function value should be set to unity if there is no spatial dependence. Typically this function is intended to specify the radial dependence of the injected particle beam. However, a 2-D function may be specified for more complex beam cross sections. This function is optional and is ignored when the index is set to zero. (See section Functions Input.) (See section Functions Input.)

radius_function (integer)[optional]

Integer identifying the function used to specify the temporal dependence of the beam radius. Used in conjunction with the reference_point and spatial_flags parameters. The radius_function truncates the radial extent of the beam, regardless of the description given by the spatial_function. This function is optional and is ignored when the index is set to zero. (See section Functions Input.)

spatial_momentum_function (integer)

Integer identifying the function used to specify the spatial variation of the injected particle momentum, which is actually in units of gamma-beta. Used in conjunction with the reference_point and spatial_flags parameters. The resulting values replace any drift momentum specified in the normal direction. This function is optional and is ignored when the index is set to zero. (See section Functions Input.)

temporal_momentum_function (integer)

Integer identifying the function used to specify the temporal dependence of the injected particle momentum, which is actually in units of gamma-beta. The resulting values replace any drift momentum specified in the normal direction. This function is optional and is ignored when the index is set to zero. If defined, it supersedes the spatial_momentum_function. (See section Functions Input.)

spatial_flags (flag)

A set of flags for each of the dimensions (X|Y|Z) with ON or OFF values indicating the coordinates on which the spatial functions are dependent. If two of these are ON simultaneously, which is often the case, then the spatial dependence is radial. The exception to this rule is when a 2-D function is specified, in which case the two dimensions are independent arguments of the spatial function.

deflection1&2_angle (real)[optional]

Deflection angles are in degrees and will cause the injected beam to be deflected from its primary direction of propagation by these angles in the corresponding transverse directions, which are in cyclical order (X,Y,Z) from the primary direction.

deflection1&2_function (integer)[optional]

Integers identifying functions used to specify temporal dependence for the deflection angles. These function supersede the constant values above, and should give values in degrees. (See section Functions Input.)

convergence (flag)

If convergence is ON, indicates radial convergence of injected beam, and must be followed by the focal_length parameter.

focal_length (real)

Distance from the injection point at which the injected beam would converge to a focus if it were force-free.

rotation (flag)

If rotation is ON, indicates rotation of injected beam, and must be followed by the omega parameter.

omega (real)

Angular rotation frequency of injected beam, in units of (rad/sec)/c, where c is the velocity of light in cm/sec. The beam is injected as a rigid rotor.

secondary

This model provides for emission of secondary electrons in one of two different ways, depending upon which medium model is being used in the emitting surfaces. The two models are the method 2 and the method 4 medium types (see section Medium Models Input).

The method 2 medium model was developed for a foil target that is being bombarded by a monoenergetic primary electron beam (see section PRIMARY_SPECIES=#). The foil medium must be a solid material. Both electron and positron secondaries may be treated. This model does NOT produce secondaries in guard cells. See section method 2.

For the method 4 medium model, there is no restriction on the incident electron energy, or on the shape of the target. Only electron secondaries can be treated. This model does allow secondary electron production in guard cells. See section method 4.

The model-specific parameters

Example:

secondary
from 0.0, 0.0, 5.0
to   3.0, 3.0, 5.05
interval 1
species 2
movie_tag 2 *
speciesA 3 *
movie_tag 3 *
medium 1
movie_fraction 1.0 *

from to (real)

For the secondary model, these coordinate parameters describe a volume of the simulation space over which the model is applied. The cells within this volume which can cause particle creation are solid material cells only, associated with a method 2 or method 4 medium model.

speciesA (integer)[optional]

Integer identifying the secondary positron species (for method 2 medium only). (See section Particle Species Input.)

medium (integer)

Integer identifying the medium model associated with secondary emission. (See section Medium Models Input.)

backscatter

The backscatter model is a multiple-energy, multiple-angle treatment of particles which impinge upon a material surface which has been designated as a method 3 medium. The species affected include secondary electrons as well as primaries, although primaries are thereby converted into secondaries. The necessary scattering tables must have been supplied to the medium model on input. The table format is given in section Method 3 Backscattering File.

The model-specific parameters

Example:

backscatter
from 0.0, 0.0, 0.0
to   1.0, 1.0, 1.0
species 2
movie_tag 0 *
movie_fraction 0.0 *

The species number should be that of the secondaries.

from to (real)

For the backscatter model, these coordinate parameters describe a volume of the simulation space over which the model is applied. The cells within this volume which can cause particle creation are solid material cells only, associated with a method 3 medium model.

desorption

Creates particles, usually neutral species, on exposed surfaces that are being struck by energetic electrons. Use of this model requires that the compiler directive DESORPTION_ON be defined (see section DESORPTION_ON). Stimulated desorption requires a method 1, method 3, or method 4 medium for the surface in order for surface heating to take place. Charged ion species may optionally be created along with the neutral species, as a result of stimulated desorption. Caution: if a stimulated desorption surface is only one cell thick, it will behave such that the physical parameters of those cells will act on both sides of the surface. In order to make the two sides react to physical conditions independently, the material should be at least two cells thick.

The model-specific parameters

Example:

desorption
from 0.0, 0.0, 7.0
to   1.0, 1.0, 8.0
interval 10
species 1
movie_tag 1 *
ion_species 2 * ; optional input - charged ions with same mass as neutrals
movie_tag 2 *
stimulated_ion_fraction 0.1 *
thermal_ion_fraction 0.0 *
electron_species 0 *
movie_tag 0 *
medium 0 *
monolayers 5.0
threshold temperature 400 *
binding_energy 7.0 ; eV
maximum_desorption_rate 1.5 ; monolayers/ns
stimulated_cross_section 1.e-14 ; cm^2
sampling_rate 1.0 *
thermal_energy 1000.0 * ; eV
minimum_charge 0.01 *
movie_fraction 0.0 *

from to (real)

For the desorption model, these coordinate parameters describe a volume of the simulation space over which the model is applied. The cells within this volume which can cause particle creation are solid material cells only, associated with a method 1 or method 3 medium model. Any actual particle creation takes place on exposed surfaces of those cells.

ion_species (integer)[optional]

Parameter identifying the species of desorbed ions, which is normally the first ionized state of the neutral species adsorbed on the surface. If not specified, no ions are produced.

ion_species N FRACTION

where `N' is the species number and `FRACTION' is the fraction of the total particles produced which are ions.

stimulated_ion_fraction (real)[optional]

Parameter which determines the fractional amount of the stimulated desorption that goes into the ionized state as specified by ion_species.

thermal_ion_fraction (real)[optional]

Parameter which determines the fractional amount of the thermal desorption that goes into the ionized state as specified by ion_species.

electron_species (integer)[optional]

Parameter which determines the electron species to be produced along with the ion species, if any. When both species are specified, the particles for each are created with equal weight.

monolayers (real)

Number of monolayers belonging to species which are initially adsorbed onto the surface. A monolayer is defined as a surface number density of

threshold (string & real)[optional]

Breakdown criterion to initiate desorption using either the surface electric field strength or the temperature as the threshold value. The format is:

threshold TYPE VALUE

where `TYPE' is either field-stress or temperature and `VALUE' is the magnitude of the electric field or the temperature in degrees (kelvins). When this parameter is not used, desorption will occur as if the threshold has been exceeded.

binding_energy (real)

Binding energy of the adsorbed species to the surface substrate, in eV.

maximum_desorption_rate (real)

Upper bound on the rate of desorption, in units of monolayers per unit time (see section User Units).

stimulated_cross_section (real)

Cross section (assumed to be constant) for stimulated desorption of species by electrons, in units of area, which is dependent upon the system of units specified by the user (see section User Units).

sampling_rate (real)[optional]

Sampling rate for random selection of events as a unitless fraction. The default value causes every trial which passes the other criteria to produce an event.

Default: 1.0

minimum_charge (real)[optional]

Lower bound on the numerical weight of desorbed particles in units of charge.

Default: 0.0

ionization

Invokes the impact ionization model, usually for a neutral species that is transformed into a singly ionized state. The latter must be listed in the [Particle Species] section of input as a separate species directly following the neutral species (see section Particle Species Input). Cross sections as a function of energy must be supplied for the impacting electron species in a file specified in the [Particle Interaction] section (see section Particle Interaction Input).

The compiler directive IONIZATION_ON must be defined in order to use the ionization model (see section IONIZATION_ON). If there are more than one ionizable species, the compiler directive MUTABLE_SPECIES must be set to an integer greater than or equal to the number of such species (see section MUTABLE_SPECIES=#). The ionization interval is set by the ionization_interval parameter in the [Control] section of input (see section Control Input).

The model-specific parameters

Example:

ionization
from 0.0, 0.0,  2.0
to   1.0, 0.0, 10.0
species 3
movie_tag 0 *
electron_species 5
movie_tag 0 *
ionization_factors *
 1.5 ; primary electrons
 1.0 ; protons
 0.0 ; neutrals
 1.5 ; ions
 1.5 ; secondary electrons
end
production_rates *
 1.0 1.0 1.0 1.0 1.0
end
thermal_energy 500 *
movie_fraction 0.0 *

from to (real)

For the ionization model, these coordinate parameters describe a volume of the simulation space over which the model is applied.

species (integer)

Integer identifying the species to be ionized (usually neutral).

ionization_factors (real)[optional]

The probability of ionization by a particle is calculated every ionization_interval timesteps (see section ionization_interval (integer)). Ionization factors multiply the charge of simulation particles produced in an ionization event. To maintain the correct physical charge, the ionization probability is multiplied by the inverse of these factors. A value of 1 gives simulation particle production at the same rate (relative to the number of impacting particles) as physical particles. Values < 1 give more simulation particles (with less charge) which may be desirable for better statistics.

The number of entries should equal the number of species in the calculation, and are listed in the order that the species appear in the [Particle Species] input section (see section Particle Species Input). The code cannot produce more than one ion per event, so there is a lower limit on the ionization factor below which the production rate is constant. A value of 0 means that the species corresponding to this entry produces no ionization.

production_rates (real)[optional]

The probability of ionization by a particle is calculated every ionization_interval timesteps (see section ionization_interval (integer)). The production rate gives the number of new simulation particles resulting from this calculation, as a fraction of the number of primary particles. The charge represented by the new particles is consistent with the physical ionization probability. For some calculations, using production_rates instead of ionization_factors provides a convenient way of controlling the number of ions and secondary electrons produced. As an example, if one wants the number of ions to equal the number of primary particles inside the from, to volume after N timesteps, the production rate should be set to ionization_interval/N.

The number of entries should equal the number of species in the calculation, and are listed in the order that the species appear in the [Particle Species] input section (see section Particle Species Input). The code cannot produce more than one ion per event, so the production rate must be less than 1 (a value exactly equal to 1 will cause the code to revert to the ionization_factors method above). A value of 0 means that the species corresponding to this entry produces no ionization.

higherstate

This is a specialized model for charge-stripping of ions by ions. The ion species must already exist in a charge-state of 1. The compiler directive NUMBER_DENSITIES must be defined, along with MAX_SPECIES, which must be set equal to an integer greater than 1 (see section NUMBER_DENSITIES, see section MAX_SPECIES=#). The atomic numbers for the species involved must be given in the [Particle Species] input section (see section Particle Species Input).

The model-specific parameters

Example:

higherstate
from 0.0, 0.0, 0.0
to   5.0, 5.0,10.0
interval 10
species 2
movie_tag 0 *
electron_species 4
movie_tag 0 *
ionization_potential 10.0 ; eV
cross_sections
 0.0
 2.0e-16
 function 5
 0.0
end
movie_fraction 0.0 *

Stripping cross sections are given for each species acting on the species being stripped to the next higher charge state. The number of entries must equal the number of species defined in the [Particle Species] input section (see section Particle Species Input).

from to (real)

For the higherstate model, these coordinate parameters describe a volume of the simulation space over which the model is applied.

ionization_potential (real)

Ionization potential of the species atom, in eV. This parameter, when a non-zero value is specified, is used to evaluate a probability for "field" ionization. This is in addition to, or instead of, the stripping due to the presence of species densities as expained below.

cross_sections (real)

Specifies stripping cross sections for each species present which contributes to a total probability for a stripping event on the species being stripped of an electron to the next higher ionization state. When zero values are specified, the effect of that species is not included. This is in addition to, or instead of, the stripping due to the "field" ionization as expained above. Also, note that this list may include an energy-dependent function instead of a value for any of the species.

photoionization

Two models for the photoionization of neutral and ionic species are available. For the first, which is designated EXTERNAL_SOURCE, the radiation source is assumed to be a cylindrical blackbody radiator (Ref.[10]). The radiation field is assumed to be larger than the source radius or length The blackbody temperature may be time-dependent. The user may specify the source radius and centroid position, but the source length is fixed at 1 cm. A cross-section table must be provided for the designated species involved. The second model, designated AMBIENT_FIELD, uses the energy contained in the electric field on a cell-by-cell basis to determine the probability of an ionization event. Any electrons that are produced by these reactions will appear in the designated electron_species. Ions will belong to the species+1 entry in the [Particle Species] input section (see section Particle Species Input), which should therefore contain the next higher charge state.

The model-specific parameters

Example of the EXTERNAL_SOURCE model:

photoionization
model EXTERNAL_SOURCE
from -5.0, -5.0, 0.0
to    5.0,  5.0,20.0
interval 1
species 3
movie_tag 0 *
electron_species 2
movie_tag 0 *
production_factor 0.2 *
reference_point 0.0 0.0 10.0
source_radius 0.5
ionization_potential 13.6 ; eV
temporal_function 3 ; for source temperature
cross_section_file F.NFF
movie_fraction 0.0 *

Example of the AMBIENT_FIELD model:

photoionization
model AMBIENT_FIELD
from -5.0, -5.0, -5.0
to    5.0,  5.0,  5.0
interval 1
species 3
movie_tag 0 *
electron_species 2
movie_tag 0 *
production_factor 1.0 *
movie_fraction 0.0 *

model (string)

Two different models of photoionization are available: EXTERNAL_SOURCE and AMBIENT_FIELD.

from to (real)

For the photoionization model, these coordinate parameters describe a volume of the simulation space over which photoionization is applied.

species (integer)

Integer identifying the species to be photoionized (usually neutral).

production_factor (real)

The probability of photoionization is calculated every interval timesteps. The production_factor multiplies the charge of the simulation particles produced in a photoionization event. To maintain the correct physical charge, the photoionization probability is multiplied by the inverse of this factor. A value of 1 gives simulation particle production at the physical rate (relative to the number of species particles). Values less than 1 generate more simulation particles, which may be desirable for better statistics. The code cannot produce more than one ionized particle per event, so there is a lower bound on the value of production_factor below which the number of simulation particles does not increase.

reference_point (real)

Location of the center of the spherical photon source. This parameter is for the EXTERNAL_SOURCE model only.

source_radius (real)

Radius of the spherical photon source. This parameter is for the EXTERNAL_SOURCE model only.

ionization_potential (real)

Ionization potential of the species atom, in eV. This is used as a cutoff energy and as a threshold for the thermal energy of the resulting ions. This parameter is for the EXTERNAL_SOURCE model only.

temporal_function (integer)

Time-dependence of the blackbody radiator temperature in eV. Time-of-flight effects are calculated as part of the model. This parameter is for the EXTERNAL_SOURCE model only.

cross_section_file (string)

An ASCII text data file containing the photoionization cross section data. Presently, the model calculates the photoionization cross sections from photoabsorption data of Henke et al. (Ref.[7]). The Henke data tables are available from various WEB sites, including `http://xray.uu.se/hypertext/henke.html' or `ftp://grace.lbl.gov/pub/sf/'. This parameter is for the EXTERNAL_SOURCE model only.

cross_section_file F.NFF

plasma

Creates particles inside the simulation space at the start of the simulation. If an electromagnetic field algorithm is used, the fields are zero at the start of a simulation, so that the plasma is by definition neutral. If only one plasma species is defined, then effectively an immobile charge of the opposite sign is present. This is not the case if STATIC_FIELDS or any of its related compiler directives is defined.

The model-specific parameters

Example:

plasma
from -5.0,-5.0,-5.0
to    5.0, 5.0, 5.0
species 1
discrete_numbers 2 2 2 *
density_function 1
momentum_function 0 *
x_dependent_function 0 *
y_dependent_function 0 *
z_dependent_function 0 *
reference_point 0. 0. 0.
density_flags 0 0 0
momentum_flags 0 0 0
drift_momentum 0 0 0 *
rotation off *
thermal_energy 10.0 *
random_energy_function 0 *
movie_tag 0 *
movie_fraction 0.0 *

from to (real)

For the plasma model, these coordinate parameters describe a volume of the simulation space over which plasma is created.

density_function (integer)

Integer identifying the function used to specify the spatial dependence of the particle number density. Used in conjunction with the reference_point and density_flags parameters. This can be a function of multiple variables corresponding to x, y, or z.

momentum_function (integer)[optional]

Integer identifying the function used to specify the spatial dependence of the particle momenta. Used in conjunction with the reference_point and momentum_flags parameters. This can be used, for example, to create an expanding plasma cloud, with the momenta directed away from the defined reference_point. These are added to any drift momenta specified. This function is ignored when the index is set to zero. (See section Functions Input.)

x_dependent_function (integer)[optional]

Integer identifying the function used to specify the spatial dependence of the particle momenta as a function of the x-coordinate, relative to the value in the reference_point parameter. This function is used as a multiplier of any momentum components defined by either the drift_momentum or the momentum_function parameters, and is only required in cases where it is necessary to vary the particle momenta in a direction different from that of the defined momentum component itself. This parameter is set to zero if not required.

y_dependent_function (integer)[optional]

Integer identifying the function used to specify the spatial dependence of the particle momenta as a function of the y-coordinate, relative to the value in the reference_point parameter. This function is used as a multiplier of any momentum components defined by either the drift_momentum or the momentum_function parameters, and is only required in cases where it is necessary to vary the particle momenta in a direction different from that of the defined momentum component itself. This parameter is set to zero if not required.

z_dependent_function (integer)[optional]

Integer identifying the function used to specify the spatial dependence of the particle momenta as a function of the z-coordinate, relative to the value in the reference_point parameter. This function is used as a multiplier of any momentum components defined by either the drift_momentum or the momentum_function parameters, and is only required in cases where it is necessary to vary the particle momenta in a direction different from that of the defined momentum component itself. This parameter is set to zero if not required.

density_flags (flag)

A set of flags for each of the dimensions (X|Y|Z) with ON or OFF values indicating the coordinates on which the density function is dependent. If all three of these are set to ON simultaneously, then the spatial dependence of the density is radial about the reference point. It is not necessary to set any of these on if the density function is simply defined to be a constant.

momentum_flags (flag)

A set of flags for each of the dimensions (X|Y|Z) with ON or OFF values indicating the component direction(s) for which the momentum spatial dependence function is used. If all three of these are set to ON simultaneously, then the spatial dependence of the momenta is radial about the reference point. At least one of these must have an ON value in order for the momentum function to be used.

rotation (flag)

If rotation is ON, indicates rotation of the plasma about the defined reference point. The angular momentum as a function of radius is determined by the combination of the momentum_function and the momentum_flags. Note that two of those flags should be set on, while the third is off.

random_energy_function (integer)[optional]

Integer identifying the function used for sampling of randomly directed energy. Used instead of the thermal_energy parameter. This is usually a tabulated set of data pairs such that the independent variables are energies in eV, and the ordinate values are relative probabilities. Note that the user must set the sampling_function parameter to yes under the appropriate function in the [Functions] section of input (see section Functions Input).

excitation

The excitation model converts electrons from a low energy state to an excited state by laser acceleration.

Example:

excitation
from -1.0, -1.0, 0.0
to    1.0,  1.0, 5.0
interval 10
species 1
excited_species 2
conversion_rate 50.0
temporal_function 3 *
sampling_rate 1.0 *
drift_momentum 0 0 1000.0 *
thermal_energy 300.0 *
movie_tag 0 *
movie_fraction 0.0 *

from to (real)

For the excitation model, these coordinates define a volume of the simulation space over which the particle excitation is applied.

conversion_rate (real)

Conversion rate for the production of excited state particles from the plasma species in fraction per unit time.

temporal_function (integer)[optional]

Integer identifying the function used to specify the time-dependence of the conversion rate, as a multiplier. (See section Functions Input.)

sampling_rate (real)[optional]

Sampling rate for random selection of events as a unitless fraction. The default value causes every test particle to produce an event.

Default: 1.0

fragmentation

The fragmentation model converts heavy molecules into two smaller ones by bond breaking, due to impacting processes of the ambient particles.

Example:

fragmentation
from 0.0, 0.0, 0.0
to   5.0, 5.0, 5.0
interval 20
species 1
first_product_species 2
movie_tag 0 *
second_product_species 3
movie_tag 0 *
cross_sections
 0.0
 0.0
 0.0
 2.5e-15
 2.5e-15
end
movie_fraction 0.0 *

from to (real)

For the fragmentation model, these coordinates define a volume of the simulation space over which the model is applied.

first_product_species (integer)

This is the index of the first species in the resulting pair of product particles involved in this process.

second_product_species (integer)

This is the index of the second species in the resulting pair of product particles involved in this process.

cross_sections (real)

Specifies the cross sections for each species present which contributes to a total probability for a fragmenting event on the target species. When zero values are specified, the effect of that species is not included. There is no effect due to the ambient field stress, at present.

fileread

The fileread model injects particles from a user-supplied data file.

The model-specific parameters

Example:

; Beam fileread
fileread
from -1.0, -1.0, 0.0
to    1.0,  1.0, 0.0
normal Z
interval 1
species 1
particle_data_file slice.dat
temporal_function 1
centroid1_function 0 *
centroid2_function 0 *
reference_point 0. 0. 0.
recycle_time 0.0 *
movie_tag 0 *
movie_fraction 0.0 *

from to (real)

For the fileread model, these coordinates should define a plane and the normal parameter should be set to (+/-) X|Y|Z to give the direction of injection.

particle_data_file (string)

Name of the file containing the explicit particle data to be used for injection. The format of this file is given in section Fileread Particle File.

particle_data_file slice.dat

temporal_function (integer)

Integer identifying the function used to specify the time-dependence of the beam, but only as a way of turning it off or on and does not otherwise affect the beam current (see section Functions Input).

recycle_time (real)

Time on the data file from which data is recycled once the end-of-file has been reached. If this has a value of zero, which is the default, then subsequent particle creation proceeds from the beginning of the file.

fission

The fission model improves particle statistics by periodically splitting particles of a certain species into smaller ones. The resulting particles are separated and located at the surrounding cell nodes (or cell centers when the EXTENDED_PARTICLES compiler directive is defined). Thus the number of particles resulting from this process depends on the number of real dimensions in the simulation setup (2x in 1-D, 4x in 2-D, 8x in 3-D). Use of this model requires the PARTICLE_COLLAPSE compiler option be defined (see section Compiler Directives).

The model-specific parameters

Example:

; Particle splitting
fission
from 0.0, -2.0, 0.0
to   1.0,  2.0, 5.0
interval 100
species 3
maximum_number 20

from to (real)

For the fission model, these coordinate parameters describe a volume of the simulation space over which the particle splitting is applied.

maximum_number (integer)

Number of particles per cell above which the splitting procedure is terminated.

trajectory

Used to introduce tracer particles with a specified charge-weighting. If the charge-weighting is zero, the particles are affected by the electromagnetic fields, but do not generate any; i.e., they behave like "test" particles. Trajectory data (position, momenta, fields) for these particles are written to an ASCII data file for as long as they exist in the simulation. There can be more than one instance of trajectory input to produce trajectories starting from different locations.

The file name is `trMpN.p4', where `M' is an integer identifying which instance of trajectory input that the data is associated with and `N' numbers the trajectories within that particular instance. Currently, `N' is limited to the range 1--63, i.e., no more than 63 traces can be produced per trajectory instance.

The parameters associated with this model

Example:

trajectory
charge_weight 0
at 10.0 20.0
interval 10
species 1
episodes
 time 2.0 to 2.5
 time 3.0 to 3.5
end
drift_momentum 0 0 0 *
select 1 0 1 0 0 0 1 0 1 0 1 0
movie_tag 1 *
movie_fraction 1.0 *

charge_weight (integer)

Electrical charge to be assigned to the tracer particles, in units of charge. If the value is zero, then the particles respond to the electromagnetic fields, but do not create any.

episodes

Defines one or more time-windows during which tracer particles are generated. The units for time are dependent upon which system of units has been specified by the user (see section User Units).

select (integer)

A set of 12 integers with values 0 (=no) or 1 (=yes) indicating which of the orbit quantities in the set {x, y, z, px, py, pz, Ex, Ey, Ez, Bx, By, Bz} are written to the trajectory data file(s).

Particle Collapse Input

The [Particle Collapse] section specifies parameters which control the particle collapse algorithm, which is a means of periodically reducing the global particle number for a selected species. The compiler directive PARTICLE_COLLAPSE must be defined (see section PARTICLE_COLLAPSE).

Example:

[Particle Collapse]
collapse1
interval 500
species 1
threshold 75000
maximum_number 20
tolerance 0.001
lower_cutoff 0.0
upper_cutoff 0.7

interval (integer)

The interval parameter specifies the time step interval between possible attempts to undergo the particle collapse process, depending on whether the threshold criterion is met.

threshold (integer)

The threshold parameter specifies the total number of particles that the species must reach in order to initiate particle collapse.

maximum_number (integer)

This is the number of particles per cell which the collapse algorithm attempts to produce. If the number of particles in a cell is less than this to begin with, then no particles are combined in that cell.

tolerance (real)

In order for two particles to combine, the square of the difference in their velocities divided by their average velocity must be less than the tolerance parameter.

lower_cutoff (real)

Particles with charge weight smaller than this fraction of the largest particle weight in a cell are not eligible for combination.

upper_cutoff (real)

Particles with charge weight larger than this fraction of the largest particle weight in a cell are not eligible for combination.

Particle Migration Input

The [Particle Migration] section specifies parameters which control particle migration between kinetic and fluid electron species (see section fluid_species_flag (flag)[optional]). This is only relevant when a fluid electron plasma is present and requires the compiler directive FLUID_PHYSICS to be defined (see section FLUID_PHYSICS).

Example:

[Particle Species]
species1
charge  -1
mass     1.0
fluid_species_flag off *
migrant_species_flag on *
species2
charge  -1
mass     1.0
fluid_species_flag on *
migrant_species_flag on *

[Particle Migration]
hybrid_kinetic_species 1
hybrid_fluid_species 2
hybrid_kinetic_species_movie_tag 3
hybrid_fluid_species_movie_tag 4
transition_ratio 10.0

hybrid_kinetic_species (integer)

The hybrid_kinetic_species parameter designates a kinetic electron species index to which fluid species (i.e., those with fluid_species_flag on) may migrate. Additionally, only those species designated by migrant_species_flag on may migrate to the hybrid kinetic species. See section Particle Species Input.

hybrid_fluid_species (integer)

The hybrid_fluid_species parameter designates a fluid electron species index to which kinetic species (i.e., those with fluid_species_flag off) may migrate. Additionally, only those species designated by migrant_species_flag on may migrate to the hybrid fluid species. See section Particle Species Input.

hybrid_kinetic_species_movie_tag (integer)

The hybrid_kinetic_species_movie_tag parameter designates a movie tag for the hybrid_kinetic_species to replace any existing tags that individual particles had before migration.

hybrid_fluid_species_movie_tag (integer)

The hybrid_fluid_species_movie_tag parameter designates a movie tag for the hybrid_fluid_species to replace any existing tags that individual particles had before migration.

transition_ratio (real)

The ratio of electron kinetic energy to the electron thermal energy at which migration between fluid and kinetic species occurs. A kinetic electron whose energy falls below this ratio is transformed into a fluid electron, and vice versa.

Default: 10.0

Particle Extraction Input

The [Particle Extraction] section allows the user to dump particles passing through a grid-conformal plane to a file for further processing. Requests for this data are numbered consecutively by appending an integer index to the extract keyword. The format is

extractN
species SP
direction DIR
maximum_number NUMBER
start_time START
stop_time STOP
at X Y Z

where `N' is 1, 2, ..., `SP' is the species index (see section Particle Species Input), `DIR' is the direction of particle motion and can be X|Y|Z, `NUMBER' is the maximum number of particles to accumulate, and `START' and `STOP' are the simulation times at which accumulation starts and stops. The plane passes through the at coordinate and is normal to the `DIR' parameter. The units for time are dependent upon which system of units has been specified by the user (see section User Units).

Example:

[Particle Extraction]
extract1
species 1
direction Z
maximum_number 10000
start_time 10.0
stop_time 11.0
at 0.0 0.0 6.5

The maximum_number of particles extracted is only approximate, as the code will continue the extraction process for that timestep once the number is reached. The data generated by the extractN request are written to a binary file named `extN.dat'. Each record of `extN.dat' gives the following data for a particle:

time q x y z px py pz temperature

where the temperature is added only for fluid species (see section fluid_species_flag (flag)[optional]).

Particle Interaction Input

When the SCATTERING_ON compiler directive is defined, collisions between the species defined in the [Particle Species] section of the input file can be modeled (see section SCATTERING_ON). Coulomb collisions between charged particles are treated using internally computed Spitzer collision rates. Neutral-neutral collisions are treated using a hard-sphere collision rate. For collisions between neutrals and charged particles, the user must specify the momentum-transfer collision frequency, ionization cross section (if applicable), and charge-exchange collision frequency (if applicable) in an external datafile. These files are listed in the [Particle Interaction] section. Ionization cross sections for collisions between charged particles can also be specified using these files. However, values for the momentum-transfer frequency will be ignored, and the Spitzer collision rates will be used. The only charge-exchange collisions currently supported are those in which the products belong to the same species as the colliding particles, i.e., the charge-exchange can be treated as a momentum-transfer event.

The code will issue a warning message for each neutral species--charged species pair for which no interaction table was found, e.g.:

 *** Warning: no interaction table found for species 2,5 combination

To specify these files for use in a simulation, the keyword interaction_files must be entered, followed by one or more filenames. The format of these files is given in section Particle Interaction Data File. These contain the collision cross sections and momentum-transfer frequencies as functions of energy for either ionization or charge-exchange events.

Example:

[Particle Interaction]
interaction_files
 interH2H2+.tab
 interp+H2.tab
 interH2+H2.tab
 interH2p+.tab
 intereH2.tab
end

An alternative method involves use of internally calculated collision frequencies from the so-called LMD model, which can be invoked as follows:

[Particle Interaction]
interaction 1
 species 1 3
 charge_state_model AMBIENT *
 atomic_number 13
 atomic_weight 27
 solid_density 2.7 ; gm/cc
 ionization_energy 6.0 * ; eV
 melt_temperature 990 * ; degrees K
 log_lambda_min 3.8 *
 g0 1.0 *
 g1 1.0 *
 p1 1.0 *
 p2a 0.65 *
 p2b 2.0 *
 p3a 0.33 *
 p3b 0.0 *
 p4a 1.35 *
 p5 0.0 *
interaction 2
 ...

All of the optional parameters have associated default values. The available options for charge_state_model are AMBIENT, which is the default, and THOMAS_FERMI.

Particle Diagnostics Input

This section of input enables the production of diagnostic dumps containing various particle measurements as functions of a spatial coordinate or some other parameter. The spatial measurements are typically useful in electron or particle beam simulations, where knowledge of certain distributions along the axis of the beam is necessary. They are performed on all particles of a given species present at each grid coordinate of the independent variable, in some cases out to a certain radius. Therefore, the spatial resolution of these diagnostics coincides with that of the simulation grid. Other measurements are distribution functions of particle momenta or energies. Because they are different from spatial diagnostics, they require additional input parameters as shown in the examples below. Note that the number_of_bins is needed here, as well as a pair of lower and upper range values. The values entered determine the full extent of the diagnostic; however, the user can susbstitute either value with the literal string `auto', `automatic' or `default', which causes the range to be determined by the data itself. This can be useful when the user does not have a way to anticipate what the data will look like, or when the data changes radically from one dump time to another. Multiple particle species can be included in a given measurement if desired. The only restriction on these diagnostics is that the spatial extent of the independent variable must be contained within a single grid instance (see section Grid Input). Data dumps for these diagnostics are written at intervals given by the diagnostic_dump_interval or its associated parameters (see section dump_interval (integer)).

The available diagnostic types are:

qsum:
Total charge summed through the plane at each grid point.
xbar|ybar|zbar:
Average of particle X|Y|Z coordinates.
xrms|yrms|zrms:
Root-mean-square average of particle X|Y|Z coordinates.
radrms:
Root-mean-square average of particle distance from the axis of measurement.
vxbar|vybar|vzbar:
Average of particle X|Y|Z momenta (gamma-beta).
vxrms|vyrms|vzrms:
Root-mean-square average of X|Y|Z momenta (gamma-beta).
emittance:
Normalized 2D transverse Lapostolle emittance in units of length-radians.
emitx|emity|emitz:
Normalized X|Y|Z 1D transverse Lapostolle emittance in units of length-radians.
gamma:
Average directed energy normalized to
kenergy:
Average kinetic energy in eV.
ieff:
Effective current measurement.
rhalf:
Half-current radius measurement.
vdist:
Distribution of particle momenta (unsigned gamma-beta).
vxdist:
Distribution of particle momenta in the x-direction (signed gamma-beta).
vydist:
Distribution of particle momenta in the y-direction (signed gamma-beta).
vzdist:
Distribution of particle momenta in the z-direction (signed gamma-beta).
kedist:
Distribution of particle energies (eV).

Example:

[Particle Diagnostics]
diagnostic1
qsum species 1
from 0 0 0
to 0 0 5
;
diagnostic2
xbar species 1
from 0 0 0
to 0 0 5
;
diagnostic3
emittance species 1
from 0 0 0
to 0 0 5
;
diagnostic4
ieff species 1
 radius 1.2
from 0 0 0
to 0 0 5
;
diagnostic5
rhalf species 1
 radius 1.2
from 0 0 0
to 0 0 5
;
diagnostic6
vzdist species 1 3 4
from 0 0 0
to 5 5 5
number_of_bins 40
range -4.0e-5 to 4.0e-5
;
diagnostic7
kedist species 2
from 0 0 0
to 5 5 5
number_of_bins 40
range 0.0 to automatic

Particle Targets Input

The [Particle Targets] section allows the user to make 2-D maps of cumulative fluence (number/unit area), energy density, and the divergence of particles passing through a grid-conformal plane ("target"). Six different types of divergence measurments are included - the mean angle from the normal for each transverse component separately plus the total angle, and the divergence about the mean for each transverse component and its total. Requests for this data are numbered consecutively by appending an integer index to the target keyword. The data for these measurements are written at intervals given by the diagnostic_dump_interval parameter (see section dump_interval (integer)). The format is

targetN TYPE
species SP
normal DIR
x-divisions NX
y-divisions NY
z-divisions NZ
from XMIN YMIN ZMIN
to   XMAX YMAX ZMAX
time TMIN to TMAX *
minimum_energy EMIN *
maximum_energy EMAX *

where `N' is 1, 2, ..., `TYPE' is the target type, either SQUARE or RADIAL, `SP' is the species index (see section Particle Species Input), `DIR' is the signed or unsigned direction normal to the plane (X|+X|-X|Y|+Y|-Y|Z|+Z|-Z), `NX', `NY', `NZ' are the number of divisions ("bins") in each direction (zero in the direction specified by `DIR'), and `XMIN', `YMIN', `ZMIN', `XMAX', `YMAX', `ZMAX' are opposite corners of the 2-D target region. The target type SQUARE refers to the fact that the target is a 2-D rectangular region, regardless of whether the simulation grid is cartesian or cylindrical, and RADIAL means that the target is defined in r-theta coordinates and is available only when using cylindrical coordinates for the simulation grid. Obviously, the direction normal `DIR' must be Z for the latter option. The signed values for DIR cause the target to be selective as to particle direction, while unsigned values will accept particles traveling either way. When present, `TMIN' and `TMAX' window the time period over which data is taken. Otherwise, data is accumulated over all time. The `EMIN' and `EMAX' parameters determine the energy range (in eV) of particles accepted. Default values are zero and infinity. In addition, multiple species can be lumped together in the same target measurement simply by listing them in sequence.

Examples:

[Particle Targets]
target1 SQUARE
species 1
normal Z
x-divisions 10
y-divisions 20
z-divisions 0
from 0.0 -0.2 1.5
to   0.2  0.2 1.5
time 0 to 35 ; ns
minimum_energy 1000 ; eV
maximum_energy 5000 ; eV

target2 RADIAL
species 2 3 4 ; three species together
normal Z
x-divisions 10
y-divisions 60
z-divisions 0
from 0.0 0.0   4.0
to   0.5 6.283 4.0
minimum_energy 0.0
maximum_energy 1.0e6

The data for all targets are written to a file named `targN.p4', where `N' is the timestep on which the data are written. The data file may be written in ASCII text format or binary, depending upon the choice of the target_output_format parameter on input (see section Control Input).

Functions Input

Functions of a single variable are useful in specifying temporal and spatial profiles for fields and particles. Several analytic functions are available, in addition to tabulated numerical data. Functions are referred to in other input sections by the integer index which is appended to the keyword function; e.g., the expression temporal_function 3 in the [External Fields] section means use the function3 entry in the [Functions] section. For a temporal function, the independent variable is assumed to be in units of time, while for a spatial function the independent variable is in units of length. These units are dependent upon which system of units has been specified by the user (see section User Units). Also, there is the option to specify functions of two or three independent variables which can be used in certain instances, such as the description of the spatial dependence for the current density of an injected particle beam (see section spatial_function (integer)).

A tabulated (type 0) function definition has the form

function1 ; tabulated function
type 0
data_pairs
 0.0  1.0
 0.125  1.0
 0.1251 0.0
end
sampling_function no *
resolution_number 0 *

where the data values are given between the data_pairs and end keywords: the first column is the independent variable and the second is the function value. Note the optional qualifiers at the end of the sequence. If set to yes, the data is interpreted as a sampling function, which entails integration and inversion, and can be used for energy sampling in some particle creation routines. The resolution_number is the number of sampling bins used. If not specified, the default value will be 1000 bins.

An analytic function definition has the form:

function1
type 5 ; plus-minus exponential
coefficients C0 C1 C2 C3

or, if it uses a power

function1
type 12 ; one minus exponential rise and fall
coefficients C0 C1 C2
power N

where `C0', `C1', ... are coefficients and `N' denotes an integral power. The value of the type parameter is 0 for a tabulated function, 1--18 for analytic functions, 20 for a polynomial, 30 for numerical data on a file, and 40 for a 2-D function.

In the case of function type 20, which is a polynomial, the format is

function1
type 20
coefficients
C0
C1
C2
end

In the case of function type 30, which designates numerical data contained on an independently generated file, the format is

function1
type 30
data_file f1.dat
independent_variable_multiplier 1.0 *
dependent_variable_multiplier 1.0 *

which designates the file containing the numerical data in ASCII format. The data is arranged in pairs, usually in two columns, consisting of floating point values of the independent and dependent variables, respectively. This is similar to the type 0 tabulated function defined above but may be more convenient for containing a large amount of data. The data may be preceded by any number of comment lines beginning with '#'. In addition, two more optional parameters are available which act as multipliers to the data of either variable. This makes it convenient to use data generated in a different system of units, for example.

In the case of function type 40, which is a 2-D function, the format is

function1
type 40
data_file beam.dat
independent_variable_multiplier 1.0 *
dependent_variable_multiplier 1.0 *

which designates the file containing the 2-D data in ASCII format. The multipliers are the same as defined for type 30 above. The data is arranged in the following order, assuming that the data is to be utilized in the x-y plane:

# optional comment lines, beginning with '#'
nx ny (integer number of data-points in x and y directions)
x[1] ... x[nx] (x-coordinate data)
y[1] ... y[ny] (y-coordinate data)
values[1][1] ... values[1][nx]
    |                |        (values of dependent variable in x and y)
values[ny][1] ... values[ny][nx]

The following table lists the analytic functions and their coefficients. The independent variable is denoted by x.

1
constant (1 coefficient):
C0
2
power term (2 coefficients):
C0*x^C1
3
single pulse (2 coefficients):
C0 = magnitude
C1 = pulse duration
4
linear times exponential (2 coefficients):
C0*x*exp(-C1*x)
5
plus-minus exponential (4 coefficients):
C0*exp(-C1*x) - C2*exp(-C3*x)
6
one over exponential (5 coefficients):
C0/(exp((x-C1)*C2)+C3))+C4
7
sine raised to power N plus constant (5 coefficients):
C0*(sin((C1+x*C3*0.5e9)*x+C2))^N+C4
C0 = magnitude
C1 = angular frequency
C2 = offset in radians
C3 = sweep rate in Hz/time-unit (zero for no sweep)
C4 = added constant
8
sine rise to constant (2 coefficients):
for x < C1, C0*sin(x*Pi/(2*C1))
for x >= C1, C0
9
exponential decay from infinity (3 coefficients):
for x < C2, 0.0
for x >= C2, C0/(1.0-exp(-C1*(x-C2)))
10
Bessel function J0 (3 coefficients):
C0*J0(C1*x/C2)
11
Bessel function J1 (3 coefficients):
C0*J1(C1*x/C2)
12
one minus exponential rise and fall raised to power N (3 coefficients):
for x < C2, C0*(1.0-exp(-C1*x))*(1.0-exp(-C1*(C2-x)))^N
for x >= C2, 0.0
13
parabolic rise and fall (2 coefficients):
C0*(1.0-(x-C1)^2/(C1*C1))
for x >= 2*C1, 0.0
14
sine(a)-sine(b) flat spectrum (4 coefficients):
for x < C3, C0*(sin(C2*(x-C3/2))-sin(C1*(x-C3/2)))/((C2-C1)*(x-C3/2))
for x >= C3, 0.0
15
Bennett profile (3 coefficients):
for x < C2, C0/(1.0+(x/C1)^2)^2
for x >= C2, 0.0
16
Gaussian profile (3 coefficients):
for x < C2, C0*exp(-(x/C1)^2)
for x >= C2, 0.0
17
smooth ramp between two constants (4 coefficients):
C0 = magnitude before ramp
C1 = magnitude after ramp
C2 = beginning time of ramp
C3 = ending time of ramp
18
solenoidal magnetic field (4 coefficients):
C0 = magnitude of field at peak
C1 = length of solenoid
C2 = radius of solenoid
C3 = exponential falloff factor to model the presence of an iron core in units of 1/length^2 used as exp(-C3*x^2) (set C3 = 0 for no core)
19
analytic laser function (2 coefficients):
C0 = wavelength
C1 = spot-size (radius)
20
polynomial of degree N (N+1 coefficients):
C0+C1*x+C2*x^2+ ... +CN*x^N

Users may enter their own customized functions of 1, 2, or 3 independent variables by using a script in Python format. The rules for Python syntax can be found in the "Defining Functions" section of the "Python Tutorial" at `http://python.fyxm.net/doc/2.2.3/tut/tut.html'. An example of using a Python function is as follows. Note the use of `script' instead of an integer for this type, followed by the text enclosed in parentheses. The name of the defined function is arbitrary. The compiler directive USE_PYTHON must be defined to use this feature (see section USE_PYTHON). Obviously the Python software must be installed on the platform being used. An example of this format is:

function1; emulate type 2
type script
"def type2(x):
 c0,c1=1.0,0.5
 if(x<0):return 0
 return c0*x**c1"

The function in this example is equivalent to the type 2 "power term" function mentioned above, which would be written as:

function1
type 2 ; power term
coefficients 1.0 0.5

An example of a 3-variable function is as follows:

function4
"def sphere(x,y,z):
 if(sqrt(x*x+y*y+z*z)>5):return 0
 return 1"

Probes Input

The [Probes] section defines the type and location of various diagnostic time histories which are written at intervals given by probe_interval (see section probe_interval (integer)) to the file `history.p4', where the `p4' extension indicates it is readable by the P4 postprocessor. There are probes for grid quantities at single points, spatial integrals of grid quantities, and particle quantities, as described below. Any probe may be given its own label by the user. If not, a descriptive label is assigned by the code to appear on the time history file.

Point Probes

Point probes are used for grid quantities like fields and currents. Fields can be obtained either at their actual staggered grid locations, or at the cell corner positions (which have the averaged field values applied to particles). The latter are usually more convenient, since the staggered location of a field depends on its orientation. (Electric fields and currents are at the half-grid positions in the direction they point and at the cell edges in the plane normal to them. Magnetic fields are at the full-grid positions in the direction they point and at the center of the faces normal to them.)

The format of a point probe is

probe1
label "LABEL" *
point FIELD COMP
at X Y Z

where `LABEL' is an optional user-defined description and `FIELD' is the grid quantity (E|ENODE for electric field, B|BNODE for magnetic field, J for current density, PHI for electric potential, RHO for charge density, RHON for particle number density by species, QDEP for deposited surface charge density, KDEP for deposited surface temperature, WDEP for deposited surface energy density, EDEP for deposited volumetric energy density, TEMP for surface temperature, EDENS for background plasma electron density, NU for momentum transfer frequency, TE for plasma electron temperature in eV, and SIGMA for conductivity). If the quantity is a vector, then the component direction `COMP' must be given (one of X|Y|Z). `X Y Z' is the probe location and the grid quantity nearest to `X Y Z' is used.

The output units are dependent upon which system of units has been specified by the user (see section User Units).

Integrated Probes

These involve line-integrals, loop-integrals, surface fluxes and volume integrals. The available types are:

voltage
Line integral of electric field along the direction of integration. The output is in units of potential (see section User Units) and is multipied by -1 in accordance with the usual definition of potential difference. The from, to parameters define the path of integration, which may be in a negative coordinate direction, and must be conformal to a grid line. Example:
probe2
voltage
from 0.0 0.0 0.0
to   5.0 0.0 0.0
current
This measurement can be a line-integral or a loop-integral of magnetic field, depending on how the from, to parameters are defined. When only one coordinate varies it is a line-integral of magnetic field along the direction of integration, although in 2-D geometries, this direction is assumed to be in the virtual dimension. Output is in units of current (see section User Units). Example of line-integral in 3-D cylindrical geometry:
probe3
current
from 9.0 0.0 0.0
to   9.0 6.283 0.0
A loop-integral of magnetic field is defined when the from, to parameters are specified such that two coordinates vary in 3-D, or one coordinate in 2-D if the virtual coordinate is not specified. However, the path of integration is not assumed to be along the coordinates of this loop, but is measured around any conductors which appear within the loop. The measurement is signed according to whether the conductor is within the loop or is a hollow outer wall, but is always in the positive direction normal to the plane defined by the loop. Example of loop-integral in 3-D cartesian geometry:
probe4
current
potential 2 *
from -0.5 -0.5 1.0
to    0.5  0.5 1.0
where the optional potential parameter isolates the measurement exclusively to conductors which have been assigned that potential index. See section Objects Input. This enables the user to isolate anode current and cathode current selectively. If no potential index is specified then the measurement is made over all conductors within the specified range. It should be noted that this integral is performed as close as possible to conductor surfaces, in order to exclude free particle currents from the measurement. Output is in units of current (see section User Units).
fourier
Integral of a component of E or B times sine or cosine of the spatial coordinate (adjusted by mode number) along the path specified by the from, to parameters. The field component need not be the same as the path direction. This diagnostic may be useful for measuring the growth of expected modes. Example:
probe5
fourier E X
parity SINE
wave_lengths 0.5
from 0.0 0.0 1.0
to   5.0 0.0 1.0
flux J|W
Integral of current density or Poynting flux through a plane. The measurement is always in the positive direction normal to the plane defined by the from, to parameters. Output is in units of current or energy rate (see section User Units). Example:
probe6
flux J
from -0.5 -0.5 1.0
to    0.5  0.5 1.0
volume E|B|RHO|RHON|WDEP|EDEP|DWDT|DEDT
Volume integral to obtain the electric field energy, magnetic field energy, charge, number, accumulated surface energy deposition, volumetric energy deposition, or energy deposition rates for either surface or volumetric energy (see section User Units). Example:
probe7 ; electric field energy
volume E
from 0.0 0.0 0.0
to  10.0 5.0 5.0
Slight variations of this format occur for some of the volume integrals. For RHON the summation is made for a single species, and must be specified as in the following example:
probe8
volume RHON
species 3
from 0.0 0.0 0.0
to  10.0 5.0 5.0
For WDEP, EDEP, DWDT, and DEDT the summation can optionally be made for a specified medium, as given in the example:
probe9
volume WDEP
medium 2 *
from 0.0 0.0 0.0
to  10.0 5.0 5.0
If no medium is specified then the summation is made over all mediums present.

Particle-Measurement Probes

Particle measurement probes compute moments of the particle distribution passing through a specified grid-conformal plane. The format is

particle TYPE species SP direction DIR
 at X Y Z
 x-window 1.5 *
 y-window 1.5 *
 z-window 0.0 *
 r-window 0.0 *

where `TYPE' is one of the types from the table below, `SP' is the species index (see section Particle Species Input), `DIR' is the direction of particle motion (X|+X|-X|Y|+Y|-Y|Z|+Z|-Z), and the plane is normal to the `DIR' direction and passes through the at coordinates. The `DIR' parameter may be signed or unsigned, signed meaning that only particles moving in that direction will contribute to the measurement, and unsigned meaning that particles traveling in either direction will contribute. The measurements may be further restricted by any of the optional windowing parameters shown, limited to either of the two directions transverse to the `DIR' parameter. That is, if `DIR' is Z, then the z-window parameter does not apply. The windowing is done in a cartesian sense for the first three options, whereas the r-window parameter limits the overall radius of the measurement. All quantities are weighted by the numerical magnitude of the particles except dqdt which is weighted by charge. The available types are:

dqdt:
Total current through the plane.
xbar|ybar|zbar:
Average of particle X|Y|Z coordinates relative to the at coordinate.
xrms|yrms|zrms:
Root-mean-square average of particle X|Y|Z coordinates with respect to the at coordinate.
radrms:
Root-mean-square average of particle coordinates transverse to `DIR'.
vxbar|vybar|vzbar:
Average of particle X|Y|Z momenta (gamma-beta).
vxrms|vyrms|vzrms:
Root-mean-square average of X|Y|Z momenta (gamma-beta).
emittance:
Normalized 2D transverse Lapostolle emittance in units of length-radians.
emitx|emity|emitz:
Normalized X|Y|Z 1D transverse Lapostolle emittance in units of length-radians.
gamma:
Average directed energy normalized to
kenergy:
Average kinetic energy in eV.
ieff:
Effective current measurement.
rhalf:
Half-current radius measurement.

Another option includes designation of a slice with some thickness by use of the from, to parameters. This is useful when the particles are not actually moving fast enough through the measurement plane to obtain good statistics. However, in this case the dqdt measurement type is not meaningful. Note that, in most cases, the two pairs of coordinates not matching the `DIR' parameter are treated as a single reference point. The exceptions are the two integrated measurements, ieff and rhalf, which firstly, are confined to having the direction Z and secondly, must have spatial extent in both the axial and radial directions. The latter may either be defined through an additional parameter, radius, or by default in the to parameter. Note that the windowing parameters may still be used. The format is:

particle TYPE species SP direction DIR
 radius RAD *
 from X Y Z
 to   X Y Z
 x-window 0.0 *
 y-window 0.0 *
 z-window 0.0 *

Examples:

probe10 ; dq/dt through a plane at Z=0.7
particle dqdt species 1
 direction Z
 at 0.0 0.0 0.7

probe11 ; dq/dt at Z=0.7 for particles traveling in the + direction
particle dqdt species 1
 direction +Z
 at 0.0 0.0 0.7

probe12 ; average y-position at Z=0.7
particle ybar species 1
 direction Z
 at 0.0 0.0 0.7

probe13 ; rms radius of beam at Z=0.7
particle radrms species 1
 direction Z
 at 0.0 0.0 0.7

probe14 ; emittance of beam at Z=0.7
particle emittance species 1
 direction Z
 at 0.0 0.0 0.7

probe15 ; effective current of beam at Z=0.7 to 0.9
particle ieff species 1
 direction Z
 radius 1.2
 from 0.0 0.0 0.7
 to   0.0 0.0 0.9

probe16 ; half-current radius of beam at Z=0.7 to 0.9
particle rhalf species 1
 direction Z
 radius 1.2
 from 0.0 0.0 0.7
 to   0.0 0.0 0.9

In addition, multiple species can be lumped together in the same measurement simply by listing them in sequence as follows:

particle TYPE species SP1 SP2 ...
 direction DIR
 at X Y Z

Example:

probe17 ; dq/dt for species 1, 2, 4, and 7 together
particle dqdt species 1 2 4 7
 direction Z
 at 0.0 0.0 1.5

Particle-Slice Probes

Particle slice probes compute moments of the particle distribution in a collection of injected particles. These slices are produced by the particle injection model (see section injection) or the particle fileread model (see section fileread) if the slice_times parameter is used to specify a list of times (see section slice_times (integer)[optional]). The format is:

slice NS TYPE species SP direction DIR

where `NS' is the slice index (1 for the first slice-time, etc.), `TYPE' is one of the types from the table given for Particle-Measurement Probes (see section Particle-Measurement Probes), `SP' is the species index (see section Particle Species Input), and `DIR' is the direction of particle motion (X|Y|Z). The dqdt measurement type is not meaningful for particle slice probes.

Global Particle Probes

Global particle probes sum data over all the particles of a selected species. The format is:

global TYPE species SP

where `TYPE' is one of the types from the table below and `SP' is the species index (see section Particle Species Input). The quantities vxtot, vytot, vztot and ketot are weighted by the particle weights. The available types are:

number:
Total number of macro-particles in the simulation.
charge:
Total amount of charge contained in the simulation.
vxtot:
Total normalized momentum (gamma-beta) in the x-direction of the simulation.
vytot:
Total normalized momentum (gamma-beta) in the y-direction of the simulation.
vztot:
Total normalized momentum (gamma-beta) in the z-direction of the simulation.
ketot:
Total kinetic energy contained in the simulation (joules or ergs).
ocmax:
Maximum value of the cyclotron frequency times the time step (unitless).
opmax:
Maximum value of the plasma frequency times the time step (unitless). Note: The NUMBER_DENSITIES compiler directive must be defined in order to use this probe (see section NUMBER_DENSITIES).

Global Energy Probes

Global energy probes take integrated energy measurements over the entire simulation space. The format is simply:

energy TYPE

where `TYPE' is one of the types from the table below. The available types are:

field_flux:
Instantaneous energy flux (rate) into the system through the fields at outlet boundaries.
particle_flux:
Instantaneous energy flux (rate) into the system through particle creation.
dedx_loss:
Instantaneous energy lost from the system through particle absorption.
field_energy:
Total energy in the system contained in the fields.
particle_energy:
Total energy in the system contained in the particles.
total_energy:
Total energy in the system of both kinds.
net_energy:
Amount of energy in the system which is not accounted for, that is, the total energy in the system minus the accumulated measurable energy gained by the system up to the time that this measurement is taken. If there are no other abnormal means of energy entering or leaving the system, this could be a good measurement of energy conservation in the field-particle interactions or the collisional plasma processes.

Global Medium Probes

Global medium probes take integrated measurements over the entire simulation space. The format is simply:

medium M TYPE

where `M' is the medium index and `TYPE' is one of the types from the table below. The only available type is:

radiation_energy:
Cumulative energy radiated by Bremsstrahlung production from a method 4 medium model (see section method 4).

Convergence Probes

Convergence probes are an easy way to gauge how well the simulation is performing in the various iterative solution techniques available. These include the static electric field solution, the magnetostatic solution, and any of the implicit solutions. The format is simply:

convergence TYPE

where `TYPE' is one of the types from the table below. The available types are:

iterations:
The iteration count after either convergence or reaching the maximum.
epsilon:
The final value of the convergence criterion measurement, after either convergence or the maximum iteration count is reached.
residue:
The final value of the residue measurement if the field solution is one of the static potential types, or the convergence "rate" if the field solution is electromagnetic ADI.

Performance Probes

The single performance probe available is a measure of the CPU time used to complete a timestep. The format is simply:

performance cpu_time

Circuit Model Probes

Circuit model probes extract measurements from any circuit model present. The format is:

circuit N element L TYPE

where `N' is the circuit index, `L' is the element number, and `TYPE' is one of the following:

voltage:
voltage at the initial end of a network element or a transmission-line segment.
current:
current in a network element or a transmission-line segment in the direction from the initial end to the opposite end, that is, toward the simulation grid.
liner-radius:
the inner radius of an associated liner model, which is assumed to contract as the liner implodes.
forward-voltage-in:
forward traveling voltage at the initial end of a network element or a transmission-line segment.
forward-voltage-out:
forward traveling voltage at the opposite end of a network element or a transmission-line segment.
backward-voltage-in:
backward traveling voltage at the initial end of a network element or a transmission-line segment.
backward-voltage-out:
backward traveling voltage at the opposite end of a network element or a transmission-line segment.

When the circuit referred to is a transmission-line the word segment can be used instead of element. When the circuit is a static one, the word element and its number is omitted altogether. Also, for static circuits, only the voltage and current measurements are relevant.


Go to the first, previous, next, last section, table of contents.