This section guides you through the anatomy of an input file for LTP-PIC. The page is broken up into discussing an example 2D input file and an example 3D input file, although the 3D file is a straightforward extension of the 2D file. The final section describes how the user can set a custom analytical magnetic field via the source code. Quick links to the sections can be found here:

2D Input file example

3D Input file example

Setting the magnetic field

General input file rules

LTP-PIC requires only one input file to specify the setup for the entire simulation (with the exception being the dimensionality and order of interpolation which are set at compile time, see here for more details).

Some general important properties and rules for using the input file include:

• The file name must end with the .dat suffix.
• The file can be located anywhere within memory accessible to the runtime processors. Although it must be appropriately referenced at runtime (see here for more details).
• Certain input file paramters are required and must be set in the input file. If they are not LTP-PIC will detect this, warn the user, and then exit the run. See below for details on which parameters are required.
• Other input file parameters are optional and if they are not specified they will be set to a specific default value which will be specified to the user in the printed output. See below for details on which parameters are optional and their default values.
• The # symbol is used for commenting. Within a given line, anything written after the # will be ignored by the code.
• Empty lines within the file will not be read
• Non-empty lines must begin with the string defining the given parameter (i.e no spaces before the string). Following the string the user defines the value of the parameter. Any number of spaces can occur between the string and the value, or after the value.
• The value can take most syntax formats, including integers, decimal values and scientific notation such as 1.2e-4 or 1.2E-4
• Unless specified below all parameters can be set in any order (with respect to their row). Exceptions include input blocks which specify:
  • block
  • species
  • Creation types such as: plasma, source, beam
  • Collision types such as: elastic, excitation, ionization, cxchange
  • Diagnostic types such as: phase, probe

2D Input file example

Top

This section discusses each component of the 2D example input file located at Examples/example2d.dat.

Each section of the input file will be discussed in turn, with comments added to each line describing what the parameter does, the units of the quantity (if defined), whether it is essential or optional, and if it is optional, what the default value will be.

Reminder: When running a simulation in 2D, ensure that the -DTWO_DIM compiler flag is set before compiling LTP-PIC.

Time stepping control

These settings control the time step and total simulation time of the simulation as well as set the frequency for outputting data and checkpoints to enable restarts.

time_step_size 1.0e-10    #Length of each time step in (s), required input
number_steps 80           #Number of time steps in the simulation, require input
print_interval 10         #Number of time steps between printing of output data, optional, default of 0 (no printing)
checkpoint_interval 50    #Number of time steps between printing of checkpointing data, optional, default of 0 (no checkpoints)

Numerical settings

These settings relate to the numerical methods used in the code.

The solver_id sets the algorithm used to solve the Poisson equation at each time step. The default (31), which uses Hypre's PFMG Geometric Multigrid algorithm as a preconditioner for a GMRES solve. We have run extensive tests and determined that for almost all cases this is the ideal algorithm which offers the highest performance, see the page on field solver performance for more details. Other field solver options can be explored by interrogating the field.c file, determining which integer corresponds to the preferred solver type and then setting this in the input file.

The hypre_gpu flag sets whether Hypre will solve the Poisson equation on the CPU (0) or the GPU (1). Specifically this tells OpenACC to either pass the data from the GPU to the CPU, or to keep it on the GPU. If set to 1 you must ensure that the HYPRE_DIR environment variable points to a build of Hypre which runs on the GPU. For CPU only simulations this should be set to 0.

The random_seed flag sets the seed used to initialise the Pseudo Random Number Generator (PRNG) for each MPI task. This should only be used if reproducability is required for debugging purposes. Do not use for production runs. The default behaviour (i.e. when not set, or commented out) is to draw a different random seed from /dev/urandom for each MPI task.

solver_id 31      #Set the linear algebra solver agorithm for the Poisson equation, optional, default of 31
hypre_gpu 0       #Flag for whether Hypre runs on the CPU (0) or GPU (1), optional, default of 0 (runs on the CPU)
random_seed 1     #ONLY FOR DEBUGGING. Initial seed set for the PRNG on each MPI process, optional, default is to draw from /dev/urandom

Physical models

Currently the only model allows you to change the relative permittivity of the physics in the simulation, this can allow for larger cell sizes and time steps at the potential cost of physical accuracy.

relative_permittivity 1.0     #Relative permittivity of vacuum, optional, default of 1.0 (true vacuum)

Grid properties

Properties for setting up the grid.

There are a few important rules required which must be adhered to when preparing the grid:

1. The cells must be square. That is, (xmax - xmin)/nx must equal (ymax - ymin)/ny otherwise the code will exit.
2. The num_process_* parameters define the processor grid over which the numerical grid is split for field solving purposes. Therefore when executing the code the number of MPI tasks called must be equal to num_process_x * num_process_y otherwise the code will fail. Note that the number of cells in each direction does not need to be perfectly divisible by the number of processors in that direction.
3. The num_process_* value must be perfectly divisible by the respective num_regions_* value in the same direction.

Each Region defines an area of the grid over which particles for each MPI process can evolve. In other words, if there are multiple MPI tasks per region, these can share the load of handling the particles in that Region. This can improve load balancing when there are strong density gradients, but has the disadvantage of requiring an MPI_Allreduce() at each time step between Region tasks.

Another way to think about it is if num_regions_* = 1 then there is purely particle decomposition across the whole grid in that given direction. Or if num_regions_* = num_process_*, where * is the same direction, this corresponds to purely domain decomposition across the grid in that given direction.

nx 64             #Number of cells in the x-direction, required
ny 50             #Number of cells in the y-direction, required
xmin -3.2e2       #Minimum of the grid in the x-direction (m), required
xmax 3.2e2        #Maximum of the grid in the x-direction (m), required
ymin 0.0          #Minimum of the grid in the y-direction (m), required
ymax 0.05         #Maximum of the grid in the y-direction (m), required
num_process_x 2   #Number of processors in the x-direction, required
num_process_y 2   #Number of processors in the y-direction, required
num_regions_x 2   #Number of Regions in the x-direction, required
num_regions_y 2   #Number of Regions in the y-direction, required

Boundary conditions

The flags for the possible boundary conditions are defined as follows:

• 0 - periodic boundary. The opposite boundary must be the same otherwise the code exits.
• 1 - Conducting (Dirichlet) boundary. The corresponding *_min/max_val must be set to a fixed potential. Optional parameters allow the user to input a sinusoidally varying potential, these include: *_min/max_amp, *_min/max_freq, *_min/max_phase Particles are absorbed at this boundary.
• 2 - Neumann boundary condition. Sets the gradient of the electric potential normal to the wall to 0.0. Particles are lost through this boundary.

xbound_min 0             #Boundary condition setting at x = xmin edge, required
xbound_max 0             #Boundary condition setting at x = xmax edge, required
ybound_min 1             #Boundary condition setting at y = ymin edge, required
ybound_max 1             #Boundary condition setting at y = ymax edge, required
xbound_min_val 0.0       #Potential (V) on the left edge for Dirichlet BC, required if xbound_min is 1
xbound_max_val 0.0       #Potential (V) on the right edge for Dirichlet BC, required if xbound_max is 1
ybound_min_val 0.0       #Potential (V) on the bottom edge for Dirichlet BC, required if ybound_min is 1
ybound_max_val 20.0      #Potential (V) on the top edge for Dirichlet BC, required if ybound_max is 1
ybound_max_amp 5.0       #Potential sinusoidal amplitude (V) on the top edge for Dirichlet BC, optional, default is 0.0
ybound_max_freq 13.56e6  #Potential sinusoidal frequency (Hz) on the top edge for Dirichlet BC, optional, default is 0.0
ybound_max_phase 0.0     #Potential sinusoidal phase on the top edge for Dirichlet BC, optional, default is 0.0

In the above example, the potential at the Dirichlet boundary ybound_max is given by:

ybound_max_phi = ybound_max_val + ybound_max_amp*sin(2*PI*(ybound_max_freq*time + ybound_max_phase))

Only ybound_max_val is required and all others are set to 0.0 if not specified.

Magnetic Field

If the user would like to use an empirical magnetic field they can do so by specifying *.dat file with the grid data. If not field is specified the simulation will use the analytical magnetic field internal to the code. For details on how to input an analytical magnetic field see Setting the magnetic field

The input file is as follows:

bfield_file bfield2d.dat    #Specification of an empirical magnetic field file. Optional.

For details on how to prepare the empirical magnetic field file see Setting the magnetic field below.

Block input

Creates a material block consisting of two types:

• block_type 1 defines a conducting area which absorbs particles. The must specifiy a fixed potential, but can also set values to define a sinusoidally varying potential.
• block_type 2 defines a dielectric area which absorbs particles and stores their charge on its surface. The user can specify the dielectric constant of the block.

Some rules to keep in mind are:

• Blocks can overlap, however the block which is defined earlier in the input file will apply its potential to the overlapping area.
• Blocks can extend out of the grid area, however the part of the block outside the area will not affect the simulation
• Blocks will "snap-to-grid", that is, when the blocks are loaded into the simulation their geometry may be slightly altered to fix to the nearest nodes defined by the grid. In other words the blocks are grid-conforming and there are no cut-cells.
• All blocks absorb particles.
• There is no limit to the number of blocks you can define.

Note: Block parameters must be defined after the block * parameter is set and before the next block * parameter is listed. For example, in the below input section the properties of the block must be written in the lines after block 1 is written but before where block 2 is written.

An example of a conducting block is:

block 1                     #Block reference number, required
block_type 1                #Type of block, where (1) is conducting and (2) is dielectric, required
block_xmin -0.024           #Minimum extent of the block in the x-direction (m), required
block_xmax -0.008           #Maximum extent of the block in the x-direction (m), required
block_ymin 0.017            #Minimum extent of the block in the y-direction (m), required
block_ymax 0.033            #Maximum extent of the block in the y-direction (m), required
block_potential 10.0        #Potential (V) of the block, required
block_potential_amp 1.0     #Potential sinusoidal amplitude (V) of the block, optional, default is 0.0
block_potential_freq 1.0e5  #Potential sinusoidal frequency (Hz) of the block, optional, default is 0.0
block_potential_phase 0.0   #Potential sinusoidal phase of the block, optional, default is 0.0

The functional form of the sinusoidal wave is identical to that defined in the Boundary Conditions input.

An example of a dielectric block is:

block 1                           #Block reference number, required
block_type 2                      #Type of block, where (1) is conducting and (2) is dielectric, required
block_xmin 0.01                   #Minimum extent of the block in the x-direction (m), required
block_xmax 0.024                  #Maximum extent of the block in the x-direction (m), required
block_ymin 8.0e-3                 #Minimum extent of the block in the y-direction (m), required
block_ymax 0.015                  #Maximum extent of the block in the y-direction (m), required
block_relative_permittivity 4.0   #Relative permittivity of the area inside the block.

Species definition

Here you set the properties of the various species within the simulation (ions, electrons etc.) You can define as many as you like. With reference to the creation routines (plasma, source and beam) described below, the user can set the "clumping" parameter (particle weight) of each species to ensure there are sufficient (or not too many) particles-per-cell. Particle weights are fixed for all particles throughout the simulation.

The print_frac parameter sets the fraction of particle, among all particles of a given Species, to be printed in the phase space output at each print_interval. This operates by specifying a print flag for each particles at the time of creation. In other words, particles which are printed at one time step, will continue to be printed for all other time steps until they leave the domain. Care must be taken to keep the print_frac low enough not to cause excessive data output.

Note: Species parameters must be defined after the species parameter is set and before the next species parameter is listed. For example, in the below input chunk the properties of the species must be written in the lines after species 1 is written and before a potential species 2 is defined.

species 1              #Species reference number, required
clumping 5.53125e5     #Species clumping parameter, required
charge -1.0            #Species charge (units of fundamental charge), required
mass 1.0               #Species mass (units of electron mass), required
magnetized 1           #Magnetized species (1), unmagnetized species (0), optional, default value is 1 (magnetized)

Creation setup

There are three ways to create species particles within the simulation:

• Plasma: This creates a uniform block of particles at the start of the simulation.
• Source: This creates a continuous "source" of particles within a given area at a specified creation rate. Think of it like artificial ionization.
• Beam: Continuous injection of a beam of particles with set density, energy, beam width and direction.

You can set up as many creation sections as you like, you can create as many creation sections for a single species as you like (i.e. an initial electron density and a beam of electrons).

Note: Creation parameters must be defined after the plasma, source or 'beam' parameter is set and before the next plasma, source and beam parameter is listed. For example, in the below input chunk the properties of the Plasma creation must be written in the lines after plasma 1 is written and before a source 1 is written.

Plasma creation

The user can specify the area over which the plasma is created, as well as the density, temperature and initial drift velocity. The drift velocity is specified in terms of directed kinetic energy, in units of eV, while counterintuitive the "directed" kinetic energy can be positive or negative to specify which direction the flow is occuring.

plasma 1                            #Plasma creation reference number
plasma_species 1                    #Reference number of the species to be created, required, must match a defined species
plasma_density 5.53125e14           #Plasma density (1/m^3), required
plasma_xmin -0.032                  #Minimum extent of the plasma creation in the x-direction (m), required
plasma_xmax 0.032                   #Maximum extent of the plasma creation in the x-direction (m), required
plasma_ymin 0.0                     #Minimum extent of the plasma creation in the y-direction (m), required
plasma_ymax 0.05                    #Maximum extent of the plasma creation in the y-direction (m), required
plasma_temperature 10.0             #Temperature of the created species (eV), optional, default is 0.0
plasma_kinetic_x 0.0                #Directed kinetic energy in the x-direction of the created species (eV), optional, default is 0.0. Can be + or -
plasma_kinetic_y 0.0                #Directed kinetic energy in the y-direction of the created species (eV), optional, default is 0.0. Can be + or -
plasma_kinetic_z 0.0                #Directed kinetic energy in the z-direction of the created species (eV), optional, default is 0.0. Can be + or -

Source creation

Source creation offers a lot of flexibility for creating particle sources within the simulation area.

By setting the source_creation_rate the user specifies the rate of change of particle density within the area defined by the limits of the source area. From this information the code will work out how many particles to inject within this area for each time step. This is an ideal setup for artificial "ionization" sources. The user can also specify the directed kinetic energy of these created particles to form, for example, a beam.

source 1                       #Source creation reference number, required
source_species 1                  #Reference number of the species to be created, required, must match a defined species
source_xmin 0.008                 #Minimum extent of the source creation in the x-direction (m), required
source_xmax 0.024                 #Maximum extent of the source creation in the x-direction (m), required
source_ymin 0.017                 #Minimum extent of the source creation in the y-direction (m), required
source_ymax 0.033                 #Maximum extent of the source creation in the y-direction (m), required
source_temperature 10.0           #Temperature of the created species (eV), optional, default is 0.0
source_creation_rate 5.0e23       #Plasma density creation rage (1/m^3/s), optional, default is 0.0 (no injection)
source_kinetic_x 0.0              #Directed kinetic energy in the x-direction of the created species (eV), optional, default is 0.0. Can be + or -
source_kinetic_y 0.0              #Directed kinetic energy in the y-direction of the created species (eV), optional, default is 0.0. Can be + or -
source_kinetic_z 0.0              #Directed kinetic energy in the z-direction of the created species (eV), optional, default is 0.0. Can be + or -

Beam creation

Beam creation is actually a subset of the Source creation routine (i.e. it calls the Source creation routine in the code), however the input parameters are more suitably defined for creating a beam of charged particles. The beam, with set width, is injected from the beam origin coordinates along the chosen beam_direction with defined species density and velocity (set by the beam energy).

beam 1                  #Beam creation reference number, required
beam_species 2          #Reference number of the species to be injected, required, must match a defined species
beam_origin_x 0.0       #Center point in the x-direction of the beam origin (m), required
beam_origin_y 0.03      #Center point in the y-direction of the beam origin (m), required
beam_direction -y       #Direction of the beam velocity. Can be +x, -x, +y, -y, required
beam_width 0.008        #Width of the beam in the direction perpendicular to the beam_direction (m), required
beam_temperature 5.0    #Temperature of the beam (eV), optional, default is 0.0
beam_density 1.0e15     #Density of the beam (1/m^3), required
beam_energy 2.0e6       #Beam energy (eV), required

##Collisions

LTP-PIC implements a grid-based Monte-Carlo collision algorithm for interactions between electrons and neutrals as well as ions and neutrals. These charged particles interact with a fixed (non-evolving) background of neutral gas. Currently the following collision algorithms are implemented:

• Elastic collisions between electrons and neutrals or between ions and neutrals (elastic - same module)
• Excitation collisions between electrons and neutrals (excite)
• Ionization collisions between electrons and neutrals, resulting in the producting of an additional electron and ion (ionize - double or higher ionization is not possible)
• Charge-exchange collisions between ions and neutrals (cxchange)

Similar to the Block, Species and Creation sections, each collision interaction is defined by a section of the input file such that the elastic, excite, 'ionize' or cxchange parameter is set and before the next elastic, excite, 'ionize' or cxchange.

Details of these algorithms can be found in the following references:

Elastic Collisions

Elastic collisions between either ions or electrons and a designated neutral species. If the species mass is greater than 1.0 (i.e. not an electron) the appropriate algorithm for ion-neutral collisions is used.

elastic 1                       #Elastic collision reference number, required
species_in 1                    #Species which will undergo the collision, required
neutral_density 9.64e20         #Neutral gas density (1/m^3), required
neutral_temperature 0.02585198  #Neutral gas temperature (eV), required only if the species mass is > 1.0
neutral_mass 7352.9411764706    #Neutral gas mass (units of electron mass), required
xsection_file e_he_elastic.dat  #Collision cross-section data file, required

Excitation Collisions

Excitation collisions between electrons and a designated neutral species. Effectively this causes scattering of the particle and a loss in energy.

excitation 1                       #Excitation collision reference number, required
species_in 1                       #Species which will undergo the collision, required
neutral_density 9.64e20            #Neutral gas density (1/m^3), required
neutral_temperature 0.02585198     #Neutral gas temperature (eV), required
neutral_mass 7352.9411764706       #Neutral gas mass (units of electron mass), required
neutral_excitation_energy 19.82    #Energy lost from the electron during the collision, required
xsection_file e_he_excite1.dat     #Collision cross-section data file, required

Ionization Collisions

Ionization collisions take in one electron, scatter that electron and also produce an additional electron and ion. The produced electron is automatically of the same species as the impacting electron.

ionization 1                        #Ionization collision reference number, required
electron_in 1                       #Electron species which will undergo the collision, required
ion_out 2                           #Ion species which will be produced by the collision, required
neutral_density 9.64e20             #Neutral gas density (1/m^3), required
neutral_mass 7352.9411764706        #Neutral gas mass (units of electron mass), required
neutral_ionization_energy 24.587    #Energy lost during ionization, required
ionization_b_value 10.0             #Relevant parameter for determining the anisotropy of the collision, 10.0 is a reasonable value, required
xsection_file e_he_ionize.dat       #Collision cross-section data file, required

Charge-exchange Collisions

Charge exchange collisions take a single ion and replace it with a randomly sampled ion from a thermal distribution. The algorithm assumes that the neutral is of the same mass, therefore the mass does not need to be specified.

cxchange 1                               #Charge-exchange collision reference number, required
ion_in 1                                 #Ion which will undergo the collision, required
neutral_density 9.64e20                  #Neutral gas density (1/m^3), required
neutral_temperature 0.02585198           #Neutral gas temperature (eV), required
xsection_file he+_he_elastic_back.dat    #Collision cross-section data file, required

Preparing collision input files

Collision input files must consist as a single file with a *.dat suffix with two columns:

• Column 1: Energy in (eV)
• Column 2: Cross-sectional area (m^2)

An example of the beginning of a cross-section file for an elastic electron-Helium collision:

#ELASTIC
#He
# 1.3600e-4
#PROCESS: e + He => e + He
#COMMENT: m/M = 0.000136
#COLUMN1: Energy in eV
#COLUMN2: Elastic in m2
#UPDATED: 2010-11-19 14:00:06
#--------------------------------
   0.00000e+0	  4.90350e-20
   1.00000e-4	  4.90350e-20
   3.51400e-2	  5.50114e-20
   7.15200e-2	  5.74760e-20
   1.09170e-1	  5.89670e-20
   1.48150e-1	  6.03385e-20
   1.88500e-1	  6.13700e-20
   2.30270e-1	  6.22659e-20
   ...            ...

Above the two columns the user can include any comments using the # symbol. See examples in the `XSections/' directory within the repository.

Output settings

There are three ways that data can be output from LTP-PIC for later post-processing. These include:

• Global grid quantity output
• Point probe output
• Species phase space output

Grid Output

This output mechanism relies on simple flags to select which grid based quantities will be output at the species print_interval (see the section on Time Stepping Control. Data from the entire grid is output as a single file for each quantity at each time step.

print_densities 1              #Print species densities on the grid (1), do not print (0), option, default is 0
print_charge_density 1         #Print charge density on the grid, print (1), do not print (0), option, default is 0
print_potential 1              #Print electric potential on the grid, print (1), do not print (0), option, default is 0
print_fields 1                 #Print electric fields on the grid, print (1), do not print (0), option, default is 0
print_current_densities 1      #Print total current densities on the grid, print (1), do not print (0), option, default is 0
print_temperatures 1           #Print species temperatures on the grid, print (1), do not print (0), option, default is 0
print_velocity_moments 1       #Print velocity moments on the grid, print (1), do not print (0), option, default is 0

There are two additional flags which will output into a single file the total number of particles, momentum and energy for each species (as well as potential energy).

These can be set using

print_total_particles 1
print_total_momentum 1
print_total_energy 1

Point probes

Point probes can output certain grid based quantities at a single point within the simulation domain at a user specified interval. Currently the only paramters which can be interrogated are:

• density
• chargedensity
• potential
• electricfieldx, electricfieldy, electricfieldz (in 3D only)

For each probe, the user specifies the paramter, time interval and probe location.

Note: Probe parameters must be defined after the probe parameter is set and before the next probe parameter is listed.

probe 1                     #Probe reference number, required
probe_variable density      #Probe variable (see possibilities above), required
probe_species 1             #Probe species, required only for density
probe_interval 2            #Number of steps between output of probe data
probe_x 11.0e-3             #Probe location in the x-direction (m)
probe_y 0.023               #Probe location in the y-direction (m)

Data for each probe is saved into a single human readable *.dat output file which includes the timestap of each output and the name of the parameter.

Phase Space sampling

The Phase Space diagnostic can be used to output data of particle Lagrangian coordinates, this data can be used to create plots of phase space or species distribution functions.

For each probe, the user specifies the species to interrogate, the interval for printing and the area over which to sample the species particles. All particles within this specified area are saved.

Note: The Phase parameters must be defined after the phase parameter is set and before the next phase parameter is listed.

phase 1                    #Phase diagnostic reference number, required
phase_species 1            #Phase species, required
phase_interval 8           #Number of steps between output of phase data
phase_xmin 2.0e-3          #Lower bound in the x-direction of the area over which to sample particles
phase_xmax 12.0e-3         #Upper bound in the x-direction of the area over which to sample particles
phase_ymin 2.0e-3          #Lower bound in the y-direction of the area over which to sample particles
phase_ymax 12.0e-3         #Upper bound in the y-direction of the area over which to sample particles

Data is saves as a single output file for each phase space diagnostic at each time step.

Note: The code can produce a very very large number of sample particles, therefore we do not recommend using a Phase Space diagnostic which spans the entire simulation area.

3D Input file example

Top

This section discusses select components of the 3D example input file located at Examples/example3d.dat.

We will only discuss the sections which require modification from the 2D input file for 3D. For a full description of each section, see above.

Reminder: When running a simulation in 3D, ensure that the -DTHREE_DIM compiler flag is set before compiling LTP-PIC.

Grid properties in 3D

The same rules apply as in 2D, but are of course extended to 3D:

• The cells must be perfect cubes.
• The number of processes in each direction must be perfectly divisible by the number of Regions in each direction.

nx 64
ny 50
nz 32                 #Number of cells in the z-direction
xmin -3.2e-2
xmax 3.2e-2
ymin 0.0
ymax 0.05
zmin 0.0              #Minimum of the grid in the z-direction (m), required
zmax 3.2e-2           #Maximum of the grid in the z-direction (m), required
num_process_x 2
num_process_y 2
num_process_z 1       #Number of processors in the z-direction, required
num_regions_x 2
num_regions_y 2
num_regions_z 1       #Number of Regions in the z-direction, required

Boundary conditions in 3D

Similar rules apply to the boundary conditions in 3D as in 2D, however each BC now represents a face of the simulation volume instead of an edge.

xbound_min 0             #Boundary condition setting at the face x = xmin, required
xbound_max 0             #Boundary condition setting at the face x = xmax, required
ybound_min 1             #Boundary condition setting at the face y = ymin, required
ybound_max 1             #Boundary condition setting at the face y = ymax, required
zbound_min 2             #Boundary condition setting at the face z = zmax, required
zbound_max 2             #Boundary condition setting at the face z = zmax, required
xbound_min_val 0.0       #Potential on the face x = xmin for Dirichlet BC, required if xbound_min is 1
xbound_max_val 0.0       #Potential on the face x = xmax for Dirichlet BC, required if xbound_max is 1
ybound_min_val 0.0       #Potential on the face y = ymin for Dirichlet BC, required if ybound_min is 1
ybound_max_val 20.0      #Potential (V) on the top edge for Dirichlet BC, required if ybound_max is 1
ybound_max_amp 5.0       #Potential sinusoidal amplitude (V) on the top edge for Dirichlet BC, optional, default is 0.0
ybound_max_freq 13.56e6  #Potential sinusoidal frequency (Hz) on the top edge for Dirichlet BC, optional, default is 0.0
ybound_max_phase 0.0     #Potential sinusoidal phase on the top edge for Dirichlet BC, optional, default is 0.0

Block input in 3D

There are added dimensions to specify the 3D extent of the block. For example, a conducting block can be prepared as:

block 1
block_type 1
block_xmin -0.024
block_xmax -0.008
block_ymin 0.017
block_ymax 0.033
block_zmin 0.002            #Minimum extent of the block in the z-direction (m), required
block_zmax 0.016            #Maximum extent of the block in the z-direction (m), required
block_potential 10.0
block_potential_amp 1.0
block_potential_freq 1.0e5
block_potential_phase 0.0

Creation setup in 3D

There are added dimensions to specify the volume of the Plasma and Source creation method in the z-direction. Additionally the Beam creation method must specify a z-coordinate for the beam origin and a beam "height" (see below for further details).

Plasma creation

plasma 1
plasma_species 1
plasma_density 5.53125e14
plasma_xmin -0.032
plasma_xmax 0.032
plasma_ymin 0.0
plasma_ymax 0.05
plasma_zmin 0.0              #Minimum extent of the plasma creation in the z-direction (m), required
plasma_zmax 0.032            #Maximum extent of the plasma creation in the z-direction (m), required
plasma_temperature 10.0
plasma_kinetic_x 0.0
plasma_kinetic_y 0.0
plasma_kinetic_z 0.0

Source creation

source 1
source_species 1
source_xmin 0.008
source_xmax 0.024
source_ymin 0.017
source_ymax 0.033
source_zmin 0.01               #Minimum extent of the injection creation in the z-direction (m), required
source_zmax 0.016              #Maximum extent of the injection creation in the z-direction (m), required
source_temperature 10.0
source_creation_rate 5.0e23
source_kinetic_x 0.0
source_kinetic_y 1.0
source_kinetic_z 0.0

Beam creation

In 3D a Beam is injected perpendicular to a given area defined by the beam_width and beam_height parameters. If the beam direction is in +/- x or +/y the beam height is in the z-direction and the width is in the other available direction. If the beam direction is in +/- z then the beam height is in the y-direction and the width is in the x-direction.

beam 2
beam_species 2
beam_origin_x 0.0
beam_origin_y 0.03         #Center point in the x-direction of the beam origin (m), required
beam_origin_z 0.02
beam_direction -y          #Direction of the beam velocity. Can be +x, -x, +y, -y, +z, -z, required
beam_width 0.008           #Width of the beam in the direction perpendicular to the beam_direction (m), required
beam_height 0.008          #Height of the beam in the direction perpendicular to the beam_direction (m), required
beam_temperature 0.0
beam_density 1.0e15
beam_energy 2.0e6

##Output Settings

Point probes require the specification of an additional coordinate for the probe location.

probe 1
probe_variable density
probe_species 1
probe_interval 2
probe_x 11.0e-3
probe_y 0.023
probe_z 0.008               #Probe location in the z-direction (m)

Phase space diagnostics require specification of a volume over which particles will be sampled.

phase 1
phase_species 1
phase_interval 8
phase_xmin 2.0e-3
phase_xmax 12.0e-3
phase_ymin 2.0e-3
phase_ymax 12.0e-3
phase_zmin 12.0e-3        #Lower bound in the z-direction of the area over which to sample particles
phase_zmax 22.0e-3        #Upper bound in the z-direction of the area over which to sample particles

Setting the magnetic field

Top

This section includes details on how to "hardcode" an external (i.e. applied) stationary analytical magnetic field profile as well as how to prepare a data file to load as an empirical magnetic field.

Hardcoding an Analytical Magnetic Field

To set the magnetic field you must directly edit the field2d.c or field3d.c source code within the top directory. Specifically, for 2D simulations (when the -DTWO_DIM compiler flag is set) you should edit the functions within the field2d.c file with headers:

ptype BX(ptype x, ptype y)
ptype BY(ptype x, ptype y)
ptype BZ(ptype x, ptype y)

For 3D simulations (when the -DTHREE_DIM compiler flag is set) you should edit the functions within the field3d.c file with the headers:

ptype BX(ptype x, ptype y, ptype z)
ptype BY(ptype x, ptype y, ptype z)
ptype BZ(ptype x, ptype y, ptype z)

REMEMBER TO RE-COMPILE THE CODE AFTER EDITING THESE FUNCTIONS.

Note: These functions are called deep within the particle update routine, and therefore should be optimised for vectorization. Avoid calling other functions, and avoid logical branching (such as IF statements) where possible. If logical statements are required, consider using logical operators.

For example, if you want bz = -1.0 for y < yref and bz = 1.0 for y >= yref, you could write this as:

bz = (y < yref)*-1.0 + (y >= yref)*1.0

This gives the same output as the equivalent IF statement, but avoids code branching, improving parallel performance.

Preparing an Empirical Magnetic Field file

Section Magnetic Field Input above shows how to input a file for an empirical magnetic field for the particles. This file must have the *.dat suffix.

The data must be laid out in 5 columns in 2D with format (x, y, Bx, By, Bz) and 6 columns in 3D with format (x, y ,z, Bx, By, Bz). Bx, By, Bz correspond to the magnetic field vector components at locaton (x, y, z). The location coordinates must define a uniform mesh with square/cubic cells. Coordinates must be cycled in the following order:

• x: fastest iterating
• y: intermediate interations
• z: slowest iterating

Note that the limits of the magnetic field grid and the cell sizes do not have to match that of the simulation grid. Any particle outside the defined magnetic field domain will experience no magnetic field.

For example, in 3D, for a 3x3x2 grid an appropriate structure of the location data is as follows:

x0  y0  z0
x1  y0  z0
x2  y0  z0
x0  y1  z0
x1  y1  z0
x2  y1  z0
x0  y2  z0
x1  y2  z0
x2  y2  z0
x0  y0  z1
x1  y0  z1
x2  y0  z1
x0  y1  z1
x1  y1  z1
x2  y1  z1
x0  y2  z1
x1  y2  z1
x2  y2  z1

LTP-PIC will automatically detect if these rules are satisfied and will notify you and end the simulation if they are not.

Two simple tools for preparing an appropriate empirical magnetic field file can be found in the Utilities/ directory (see Utilities/create_bfield2d.py and Utilities/create_bfield3d.py).

Benchmark input files

Landmark 2a input file

Penning discharge input file