@ParticleGenerator¶

The particle generator is in charge of sampling particles from the phase space. Thus, the particle generator must know which type of particle to sample (i.e. electron, proton or some other charged particle?) as well as the bounds of the phase space from which to pick the particle properties (energy, initial pitch angle and initial position).

Summary of options¶

Option	Description
`@ParticleGenerator charge`	Charge of particle (in units of elementary charge).
`@ParticleGenerator driftshifttol`	Relative tolerance when computing the drift orbit shift.
`@ParticleGenerator mass`	Rest mass of particle (in units of the electron rest mass).
`@ParticleGenerator mpi_distribute_mode`	Specifies which parameter to split among MPI processes.
`@ParticleGenerator position`	Whether specified position refers to particle or guiding-center.
`@ParticleGenerator progress`	Instructs SOFT to output info on the simulation progress.
`@ParticleGenerator nzeta`	The number of points to use for the gyro phase integral.

In addition to these options, the following phase space parameters can also be specified. Exactly one spatial and two momentum parameters must be specified, and the two momentum parameters chosen must span all of momentum space together.

Parameter	Type	Description
`@ParticleGenerator a`	Spatial	Normalized minor radius (0 on magnetic axis; 1 on last closed flux surface).
`@ParticleGenerator r`	Spatial	Minor radius (meters).
`@ParticleGenerator rho`	Spatial	Major radius (meters).
`@ParticleGenerator gamma`	Momentum	Particle energy, normalized to the particle rest mass (= Lorentz factor).
`@ParticleGenerator p`	Momentum	Particle momentum, normalized to the particle rest mass.
`@ParticleGenerator ppar`	Momentum	Particle momentum parallel to magnetic field, normalized to the particle rest mass.
`@ParticleGenerator pperp`	Momentum	Particle momentum perpendicular to magnetic field, normalized to the particle rest mass.
`@ParticleGenerator thetap`	Momentum	Particle pitch angle \(\theta_{\rm p}\) (in radians).
`@ParticleGenerator ithetap`	Momentum	Pi-complement of particle pitch angle, \(\theta_{\rm p}' = \pi - \theta_{\rm p}\) (in radians).
`@ParticleGenerator xi`	Momentum	Cosine of particle pitch angle, \(\xi = \cos\theta_{\rm p}\).

Example configuration¶

Electron — The following example sets up a phase-space for an electron with 100 points on the grid in each dimension. The mass and charge default to those of an electron, and so do not have to be specified. We also instruct SOFT to output a total of 100 progress messages during the run. Since we do not set the meaning of the position explicitly, SOFT assumes that we specify the position of the guiding-center:

@ParticleGenerator PGen_electron {
    r        = 0, 0.30, 100;    # Minor radius (m)
    gamma    = 1.1, 3.0, 100;   # Energy       (mc^2)
    thetap   = 0.02, 0.8, 100;  # Pitch angle  (rad)
    progress = 100;             # Output 100 progress messages
}

Deuterium — The following example sets up a phase-space for a deuterium ion with 100 points on the grid in each dimension. The proton-electron mass ratio is approximately \(m_{\rm p} / m_{\rm e}\approx 1836\), and hence the deuterium-electron mass ratio is approximately \(m_{\rm D} / m_{\rm e}\approx 3672\). We explicitly state that we specify the particle position using the position option:

@ParticleGenerator PGen_deuterium {
    mass   = 3672;            # Electron masses
    charge = 2;               # Elementary charges
    a      = 0, 1, 100;       # Normalized minor radius
    p      = 1e-3, 1e-1, 100; # Momentum (mc)
    thetap = 0.1, 0.3, 100;   # Pitch angle (rad)
}

With MPI — The following example is near-identical to the electron example above, but explicitly instructs SOFT to split the gamma (energy) parameter among the MPI processes:

@ParticleGenerator PGen_electron {
    r                   = 0, 0.30, 100;    # Minor radius (m)
    gamma               = 1.1, 3.0, 100;   # Energy       (mc^2)
    thetap              = 0.02, 0.8, 100;  # Pitch angle  (rad)
    progress            = 100;             # Output 100 progress messages
    mpi_distribute_mode = gamma;           # Divide the energy parameter among MPI processes
}

Options¶

charge¶

Default value:	`-1`
Allowed values:	Any non-zero real number.

Charge of particle to simulate. The charge is given in units of the elementary charge so that a value of 1 corresponds to the proton charge and -1 to the electron charge.

driftshifttol¶

Default value:	`1e-4`
Allowed values:	\(\epsilon < \text{tolerance} < 1\)

Tolerance for determining the guiding-center drift orbit shift (which is used to determine where to launch particles and where to sample the distribution function). In general, this parameter does not need to be changed.

mass¶

Default value:	`1`
Allowed values:	Any positive real number.

Rest mass of particle to simulate. The mass is given in units of the electron rest mass. In these units, the proton mass is \(m_{\rm p}\approx 1836.15267389\) [1].

mpi_distribute_mode¶

Default value:	`auto`.
Allowed values:	`1`, `2`, `auto`, `radius` and all of the phase-space parameters listed under Phase space parameters.

When running in MPI mode (MPI = Message Passing Interface; distributed memory parallelization), this parameter can be used to specify how the phase space should be divided among the MPI processes. In contrast to regular OpenMP parallelization, which builds a queue of points in phase space, MPI requires one phase space parameter to be divided evenly among the processes.

Which parameter to divide is specified by giving the name of the parameter, as listed under Phase space parameters, or by giving one of 1, 2 and radius. The former two cause SOFT to divide the first and second momentum parameter respectively (i.e. the alphabetically first and second momentum parameter), while the latter divides the radial parameter, whichever it may be.

If auto is specified, SOFT2 chooses the phase space parameter with the largest number of grid points. This is the default setting.

position¶

Default value:	`guiding-center`
Allowed values:	`gc`, `guiding-center` and `particle`.

Specifies whether the guiding-center or particle is given as input. If, for example, the particle position is specified, but guiding-center orbits are simulated, then the guiding-centers are offset from the given position by one Larmor radius, and vice versa for the opposite case.

progress¶

Default value:	`no`
Allowed values:	`yes`, `no` or a positive integer.

If yes or a positive integer n, outputs a message reporting the progress of the simulation a total of n times during the run. The reports are split evenly accross the phase space, meaning that if the phase space consists of N total grid points, then SOFT reports progress roughly when the number of processed grid points is a multiple of N / n.

nzeta¶

Default value:	`1`
Allowed values:	Any positive integer.

Determines how many points to use for the integral over gyro angle. For guiding-center calculations, this value should always be set to 1 (the only effect of setting it to some other value for guiding-center calculations is that the simulation becomes slower by the factor specified). This value only makes sense for full-orbit simulations.

[1]	https://en.wikipedia.org/wiki/Proton-to-electron_mass_ratio

Phase space parameters¶

a¶: Normalized minor radius — The initial minor radial location of the particle/guiding-center, normalized to the minor radial value of the last closed flux surface. Thus, \(a = 0\) corresponds to the magnetic axis and \(a = 1\) to the maximum radius of the last closed flux surface.

r¶: Minor radius — The initial minor radial location of the particle/guiding-center, given in meters.

rho¶: Major radius — The initial major radial location of the particle/guiding-center, given in meters.

gamma¶: Energy — The energy of the particle/guiding-center, normalized to the particle rest mass \(mc^2\), where \(c\) denotes the speed of light in vacuum. This quantity is also known as the Lorentz factor or relativistic factor, and can also be written \(\gamma = \left( 1 - v^2/c^2 \right)^{-1/2}\), where \(v\) is the speed of the particle.

p¶: Momentum — The momentum of the particle/guiding-center, normalized to the particle rest mass \(mc\), where \(c\) denotes the speed of light in vacuum. This quantity is related to the particle energy/relativistic factor through \(\gamma^2 = 1 + p^2\).

ppar¶: Parallel momentum — Momentum of the particle parallel to the magnetic field, normalized to the particle rest mass \(mc\), where \(c\) denotes the speed of light in vacuum.

pperp¶: Perpendicular momentum — Momentum of the particle perpendicular to the magnetic field, normalized to the particle rest mass \(mc\), where \(c\) denotes the speed of light in vacuum.

thetap¶: Pitch angle — Angle between the particle velocity vector and the magnetic field vector. Given in radians. The pitch angle ranges between \(0\) and \(\pi\). A value greater than \(\pi/2\) means that the particle is moving antiparallel to the magnetic field.

ithetap¶: Complementary pitch angle — Same as @ParticleGenerator thetap, except that it is defined as “pi minus @ParticleGenerator thetap”, i.e. \(\theta_{\rm p}' = \pi - \theta_{\rm p}\). This is useful when simulating particles with negative parallel momentum (moving in the antiaparallel direction of the magnetic field), since instead of specifying \(\theta_{\rm p} = 3.14159265359\) we can then set \(\theta_{\rm p}' = 0\).

xi¶: Cosine of pitch angle — Cosine of the pitch angle \(\theta_{\rm p}\), i.e. \(\xi = \cos\theta_{\rm p}\).

Jacobians¶

The following is a list of all the Jacobian determinants for transformations from a Cartesian coordinate system \((p_x, p_y, p_z)\) to other coordinate systems \((p_1, p_2, \zeta)\), where \(\zeta\) is the gyro angle.

gamma / ppar — \((\gamma, p_{\parallel})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \gamma\mathrm{d}\gamma\mathrm{d}p_{\parallel}\mathrm{d}\zeta\]

gamma / pperp — Does not contain sufficient information to determine if the guiding-center is travelling in the parallel or anti-parallel direction of the magnetic field.

gamma / thetap — \((\gamma, \theta_{\rm p})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \gamma\sin\theta_{\rm p}\sqrt{\gamma^2-1}\,\mathrm{d}\gamma\mathrm{d}\theta_{\rm p}\mathrm{d}\zeta\]

gamma / xi — \((\gamma, \xi)\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \gamma\sqrt{\gamma^2-1}\,\mathrm{d}\gamma\mathrm{d}\xi\mathrm{d}\zeta\]

p / ppar — \((p, p_{\parallel})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = p\,\mathrm{d}p\mathrm{d}p_{\parallel}\mathrm{d}\zeta\]

p / pperp — Does not contain sufficient information to determine if the guiding-center is travelling in the parallel or anti-parallel direction of the magnetic field.

p / thetap — \((p, \theta_{\rm p})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = p^2\sin\theta_{\rm p}\,\mathrm{d}p\mathrm{d}\theta_{\rm p}\mathrm{d}\zeta\]

p / xi — \((p, \xi)\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = p^2\,\mathrm{d}p\mathrm{d}\theta_{\rm p}\mathrm{d}\zeta\]

ppar / pperp — \((p_{\parallel}, p_{\perp})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = p_\perp\,\mathrm{d}p_{\parallel}\mathrm{d}p_{\perp}\mathrm{d}\zeta\]

ppar / thetap — \((p_{\parallel}, \theta_{\rm p})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \frac{p_\parallel^2\sin\theta_{\rm p}}{\cos^3\theta_{\rm p}}\,\mathrm{d}p_{\parallel}\mathrm{d}\theta_{\rm p}\mathrm{d}\zeta\]

ppar / xi — \((p_{\parallel}, \xi)\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \frac{p_\parallel^2}{\xi^3}\,\mathrm{d}p_{\parallel}\mathrm{d}\xi\mathrm{d}\zeta\]

pperp / thetap — \((p_{\parallel}, \theta_{\rm p})\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \frac{p_\perp^2}{\sin^2\theta_{\rm p}}\,\mathrm{d}p_{\perp}\mathrm{d}\theta_{\rm p}\mathrm{d}\zeta\]

pperp / xi — \((p_\perp, \xi)\)

\[\mathrm{d}p_x\mathrm{d}p_y\mathrm{d}p_z = \frac{p_\perp^2}{\left( 1 - \xi^2 \right)^{3/2}}\,\mathrm{d}p_{\perp}\mathrm{d}\xi\mathrm{d}\zeta\]