Species block

Species block#

This block contains information about the species of particles which are used in the code. Also details of how these are initialised. See EPOC++ input deck for more information on the input deck.

Basics#

The next section of the input deck describes the particle species used in the code. An example species block for any EPOC++ code is given below.

begin:species
   # Rightwards travelling electrons
   name = Right
   charge = -1
   mass = 1.0
   temperature = 273
   drift_x = 2.5e-24
   number_density = if(abs(x) lt 1e-6, 10, 0.0)
   number_density = if((x gt -1e-6) and (abs(y) gt 2e-6), \
                        0.0, number_density(Right))
   nparticles_per_cell = 128
end:species

begin:species
   # Leftwards travelling electrons
   name = Left
   charge = -1
   mass = 1.0
   temperature = 273
   drift_x = -2.5e-24
   number_density = 10
   nparticles_per_cell = 128
end:species

Each species block accepts the following parameters:

  • name - This specifies the name of the particle species defined in the current block. This name can include any alphanumeric characters in the basic ASCII set. The name is used to identify the species in any consequent input block and is also used for labelling species data in any output dumps. It is a mandatory parameter. NOTE: IT IS IMPOSSIBLE TO SET TWO SPECIES WITH THE SAME NAME!

  • charge - This sets the charge of the species in multiples of the electron charge. Negative numbers are used for negatively charged particles. This is a mandatory parameter.

  • mass - This sets the mass of the species in multiples of the electron mass. Cannot be negative. This is a mandatory parameter.

  • nparticles - This specifies the number of pseudoparticles which should be loaded into the simulation domain for this species block. Using this parameter is the most convenient way of loading particles for simulations which contain multiple species with different number densities. If nparticles is specified in a species block then any value given for nparticles in the control block is ignored. nparticles should not be specified at the same time as fraction within a species block.

  • fraction - This specifies what fraction of nparticles (the global number of particles specified in the control block) should be assigned to the species. NOTE: fraction should not be specified at the same time as nparticles for a given species.

  • nparticles_per_cell - Integer parameter which specifies the number of particles per cell to use for the initial particle loading.

To avoid confusion, there is no globally used nparticles_per_cell. If you want to have a single value to change in the input deck then this can be achieved using a constant block.

The species blocks are also used for specifying initial conditions for the particle species. The initial conditions in EPOC++ can be specified in various ways, but the easiest way is to specify the initial conditions in the input deck file. This allows any initial condition which can be specified everywhere in space by a number density and a drifting Maxwellian distribution function. These are built up using the normal maths expressions, by setting the density and temperature for each species which is then used by the autoloader to actually position the particles.

The elements of the species block used for setting initial conditions are:

  • number_density - Particle number density in \(m^{-3}\). As soon as a number_density= line has been read, the values are calculated for the whole domain and are available for reuse on the right hand side of an expression. This is seen in the above example in the first two lines for the Electron species, where the number density is first set and then corrected. If you wish to specify the number density in parts per cubic centimetre then you can divide by the “cc” constant (see here). This parameter is mandatory.

  • number_density_min - Minimum particle number density in \(m^{-3}\). When the number density in a cell falls below number_density_min the autoloader does not load any pseudoparticles into that cell to minimise the number of low weight, unimportant particles. If set to 0 then all cells are loaded with particles. This is the default.

  • number_density_max - Maximum particle number density in \(m^{-3}\). When the number density in a cell rises above number_density_max the autoloader clips the number_density to number_density_max allowing easy implementation of exponential rises to plateaus. If it is a negative value then no clipping is performed. This is the default.

  • mass_density - Particle mass density in \(kg\,m^{-3}\). The same as “number_density” but multiplied by the particle mass. If you wish to use units of \(g\,cm^{-3}\) then append the appropriate multiplication factor. For example: “mass_density = 2 * 1e3 / cc”.

  • temperature_{x,y,z} - The temperature in each direction for a thermal distribution in Kelvin. Can be a function of space.

  • temperature - Sets an isotropic temperature distribution in Kelvin. Can be a function of space. If both temperature and a specific temperature_x, temperature_y, temperature_z parameter is specified then the last to appear in the deck has precedence. If neither are given then the species will have a default temperature of zero Kelvin.

  • temperature_{x,y,z}_ev, temperature_ev - These are the same as the temperature parameters described above except the units are given in electronvolts rather than Kelvin, i.e. using 1ev = 11604.5K .

  • drift_{x,y,z} - Specifies a momentum space offset in \(kg\ ms^{-1}\) to the distribution function for this species. By default, the drift is zero.

For momentum initialisation, by default the code will initialise momenta using a Maxwellian:

\(f (p_x,p_y,p_z) \propto \exp\left(-\frac{p_x^2 }{ 2mkT_x}\right) \exp\left(-\frac{p_y^2 }{ 2mkT_y}\right) \exp\left(-\frac{p_z^2 }{ 2mkT_z}\right)\)

\(T_x\), \(T_y\), \(T_z\) are tracked separately, and if the user sets temperature, all 3 directions are updated.

Maxwell Juttner distributions#

EPOC++ allows the user to request a Maxwell-Jüttner distribution rather than a Maxwellian distribution when sampling the particle momentum for a species.

  • use_maxwell_juttner - Logical flag determining whether to sample from the Maxwell-Jüttner distribution when loading the particle species. If “T” then Maxwell-Jüttner is used and if “F” Maxwellian is used. The default value is “F”.

  • fractional_tail_cutoff - The sampling is carried out using a rejection method with an arbitrary cut-off. This parameter takes a floating-point argument which specifies the fraction of maximum value at which the sampling should be cut off. Smaller values lead to distortion nearer the peak of the distribution but are faster to sample. Larger values lead to a better approximation of the distribution function but are slower to sample. The default value is 0.0001.

If the user sets use_maxwell_juttner = T, then the code will use relatvistic Maxwell-Juttner distribution:

\(f (p_x, p_y, p_z) \propto \exp\left(\frac{mc^2}{k\langle T\rangle} \left(\sqrt{1 + \frac{p_x^2}{m^2c^2}\frac{\langle T \rangle}{T_x} + \frac{p_y^2}{m^2c^2}\frac{\langle T \rangle}{T_y} + \frac{p_z^2}{m^2c^2}\frac{\langle T \rangle}{T_z}} - 1 \right)\right)\)

\(\langle T \rangle\) is the average temperature across all 3 dimensions.

This form of 3-temperature Maxwell-Juttner was chosen as it reduces to our 3-temperature Maxwellian in the non-relativistic limit. The constant factor introduced by the \(-1\) acts to normalise \(f\), as Maxwell-Juttner values are obtained through rejection sampling, where \(f(p_x,p_y,p_z)\) is calculated and compared to a random number for acceptance.

An additional fractional_tail_cutoff is provided, which is used to find the maximum magnitude to sample for a given momentum component. For example, when \((p_x,p_y,p_z) = (|p_x|_\text{max}, 0, 0)\), then \(f\) = fractional_tail_cutoff.

If drifts are specified with the Maxwell-Jüttner distribution then the distribution is calculated in the rest frame and then Lorentz transformed to the specified drifting frame.

Arbitrary Distribution functions#

EPOC++ also allows the user to request an arbitrary non-Maxwellian distribution function to use when sampling the particle momentum for a species. If combined with a specified drift then the distribution function is calculated first and the drift is applied to the resulting particles by Lorentz transform.

  • dist_fn - Specifies the functional form of the distribution function, normalised to have a maximum value of 1. The variables “px”, “py” and “pz” should be used to parameterise the x, y and z components of momentum. This may freely vary in space but temporal variation will be ignored since this is only evaluated at the start of the simulation.

  • dist_fn_p{x,y,z}_range - Comma separated pair of numbers to specify the range of momentum for p_{x,y,z} in SI units. Should be of the form “<lower_range>, <upper_range>”

If a range for a momentum direction is not specified then that momentum is assumed to be zero. It is up to the user to ensure that the range is large enough to correctly capture their desired distribution function. Sampling is by a simple rejection sampling and may be much slower than the existing Maxwellian sampler. EPOC++ will print a warning if a large number of samples are needed to complete the sampling. If this occurs then you might need to reduce the range of momentum over which sampling is considered.

If the “dist_fn” key is supplied then any supplied temperature keys are ignored. An example of setting up a truncated power law distribution in px would be

begin:constant
  dens = 10
  v0 = 0.05 * c
  vmax = 0.5 * c
  p0 = v0 * me * (1.0 + 4.0 * x/x_max)
  pmax = vmax * me
  alpha = -2.0
end:constant

begin:species
  name = Electron_pl
  charge = -1
  mass = 1.0
  frac = 0.5
  number_density = dens
  #Truncated power law distribution in px
  dist_fn = exp(-p0/px) * (px/p0)^(alpha)
  dist_fn_px_range = (0, pmax)
end:species

Species Boundary Conditions#

  • bc_{x,y,z}_min - Boundary condition to be applied to this species only on the lower x boundary. Can be any normal boundary condition apart from periodic. If not specified then the global boundary condition is applied.

  • bc_{x,y,z}_max - Boundary condition to be applied to this species only on the upper x boundary. Can be any normal boundary condition apart from periodic. If not specified then the global boundary condition is applied.