Available Maxwellians

Maxwellian (Gaussian) distributions in velocity space.

class struphy.kinetic_background.maxwellians.Maxwellian3D(n: tuple[float | Callable, Perturbation] = (1.0, None), u1: tuple[float | Callable, Perturbation] = (0.0, None), u2: tuple[float | Callable, Perturbation] = (0.0, None), u3: tuple[float | Callable, Perturbation] = (0.0, None), vth1: tuple[float | Callable, Perturbation] = (1.0, None), vth2: tuple[float | Callable, Perturbation] = (1.0, None), vth3: tuple[float | Callable, Perturbation] = (1.0, None), uniform_on_disc: bool = False)

Bases: Maxwellian

A Maxwellian depending \((\eta_1, \eta_2, \eta_3)\) and on three (\(n=3\)) Cartesian velocities.

Parameters:

• n (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• ui (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vthi (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• uniform_on_disc (bool) – Whether the density n is uniform on the disc.

property vdim

Dimension of the velocity space.

property velocity_coords: Literal['cartesian', 'vpara_mu', 'vpara_vperp', 'vpara_energy']

Velocity coordinates of the background.

velocity_jacobian_det(eta1, eta2, eta3, vx, vy, vz)

Jacobian determinant is 1 (Cartesian velocity coordinates).

Input parameters should be slice of 2d numpy marker array. (i.e. *self.phasespace_coords)

Parameters:

• eta1 (array_like) – Logical evaluation points.

• eta2 (array_like) – Logical evaluation points.

• eta3 (array_like) – Logical evaluation points.

• vx (array_like) – Velocity evaluation points.

• vy (array_like) – Velocity evaluation points.

• vz (array_like) – Velocity evaluation points.

Returns:

• out (array-like) – The Jacobian determinant evaluated at given logical coordinates.

• ——-

property volume_form

Boolean. True if the background is represented as a volume form (thus including the velocity Jacobian).

property moment_factors

Collection of factors multiplied onto the defined moments n, u, and vth.

n(eta1, eta2, eta3)

Zero-th moment (density).

u(eta1, eta2, eta3)

Mean velocities.

vth(eta1, eta2, eta3)

Thermal velocities.

class struphy.kinetic_background.maxwellians.GyroMaxwellian2D(n: tuple[float | Callable, Perturbation] = (1.0, None), u_para: tuple[float | Callable, Perturbation] = (0.0, None), u_perp: tuple[float | Callable, Perturbation] = (0.0, None), vth_para: tuple[float | Callable, Perturbation] = (1.0, None), vth_perp: tuple[float | Callable, Perturbation] = (1.0, None), volume_form: bool = True, B0: float | Callable | Literal['equil'] = 'equil', uniform_on_disc: bool = False)

Bases: Maxwellian

A gyrotropic Maxwellian depending on two velocities \((v_\parallel, \mu)\), \(n=2\), where \(v_\parallel = \mathbf v \cdot \mathbf b_0\) and \(\mu = v_\perp^2/(2B_0)\) is the magnetic moment, with \(B_0\) the background magnetic field strength.

Parameters:

• n (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• u_para (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• u_perp (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vth_para (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vth_perp (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• volume_form (bool) – Whether to represent the Maxwellian as a volume form; if True it is multiplied by the Jacobian determinant |v_perp| of the polar coordinate transofrmation (default = False).

• B0 (float | Callable | "equil") – Background magnetic field strength \(B_0\) in \(\mu = v_\perp^2/(2B_0)\), see eval_B0(): a constant, a callable of the stacked logical positions etas of shape (3, N) returning shape (N,), or "equil" (default) for the local field strength \(|\mathbf B_0|(\boldsymbol \eta)\) of the equilibrium attached with attach_equil() (done automatically for the background and initial condition of a Particles5D species).

• uniform_on_disc (bool) – Whether the density n is uniform on the disc.

property vdim

Dimension of the velocity space.

property velocity_coords: Literal['cartesian', 'vpara_mu', 'vpara_vperp', 'vpara_energy']

Velocity coordinates of the background.

velocity_jacobian_det(eta1, eta2, eta3, v_para, mu)

Jacobian determinant of the velocity coordinate transformation to \((v_\parallel, mu)\), is \(B_0\).

Input parameters should be slice of 2d numpy marker array. (i.e. *self.phasespace_coords)

Parameters:

• eta1 (array_like) – Logical evaluation points.

• eta2 (array_like) – Logical evaluation points.

• eta3 (array_like) – Logical evaluation points.

• v_para (array_like) – Parallel velocity and magnetic moment evaluation points.

• mu (array_like) – Parallel velocity and magnetic moment evaluation points.

Returns:

• out (array-like) – The Jacobian determinant evaluated at given logical coordinates.

• ——-

attach_equil(equil: FluidEquilibriumWithB)

Attach the equilibrium whose field strength \(|\mathbf B_0|\) is used for B0="equil" (replacing an equilibrium attached before). Does nothing for a constant or callable B0.

The background object itself is changed: if it is shared by particles with different equilibria (e.g. two simulations set up in one script before running), the last equilibrium attached is used by all of them, and a warning is logged.

eval_B0(etas)

Evaluate the magnetic field strength \(B_0\) in \(\mu = v_\perp^2/(2B_0)\) at flat positions.

Parameters:

etas (array_like) – Stacked logical positions of shape (3, N).

Returns:

out – \(B_0\) at the positions, shape (N,).

Return type:

array-like

eval_B0_on_args(etas)

eval_B0() at the positions eta1, eta2, eta3 of a Maxwellian evaluation, flat (1d arrays) or on a phase-space meshgrid (3 + vdim dimensions, positions on the first 3 axes): there it is evaluated on the spatial points only and broadcast to the velocity axes. A constant B0 is returned as float.

property volume_form: bool

Boolean. True if the background is represented as a volume form (thus including the velocity Jacobian |v_perp|).

property moment_factors

Collection of factors multiplied onto the defined moments n, u, and vth.

n(eta1, eta2, eta3)

Zero-th moment (density).

u(eta1, eta2, eta3)

Mean velocities.

vth(eta1, eta2, eta3)

Thermal velocities.

class struphy.kinetic_background.maxwellians.GyroMaxwellian2Dvperp(n: tuple[float | Callable, Perturbation] = (1.0, None), u_para: tuple[float | Callable, Perturbation] = (0.0, None), u_perp: tuple[float | Callable, Perturbation] = (0.0, None), vth_para: tuple[float | Callable, Perturbation] = (1.0, None), vth_perp: tuple[float | Callable, Perturbation] = (1.0, None), equil: FluidEquilibriumWithB | None = None, volume_form: bool = True, uniform_on_disc: bool = False)

Bases: Maxwellian

A gyrotropic Maxwellian depending on two velocities \((v_\parallel, v_\perp)\), \(n=2\), where \(v_\parallel = \mathbf v \cdot \mathbf b_0\) and \(v_\perp\) is the radial component of a polar coordinate system perpendicular to the magentic direction \(\mathbf b_0\).

Parameters:

• n (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• u_para (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• u_perp (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vth_para (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vth_perp (tuple) – Moments of the Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• equil (FluidEquilibriumWithB) – Fluid background.

• volume_form (bool) – Whether to represent the Maxwellian as a volume form; if True it is multiplied by the Jacobian determinant |v_perp| of the polar coordinate transofrmation (default = False).

• uniform_on_disc (bool) – Whether the density n is uniform on the disc (default = False).

property vdim

Dimension of the velocity space.

property velocity_coords: Literal['cartesian', 'vpara_mu', 'vpara_vperp', 'vpara_energy']

Velocity coordinates of the background.

velocity_jacobian_det(eta1, eta2, eta3, v_para, v_perp)

Jacobian determinant of the velocity coordinate transformation to \((v_\parallel, v_\perp)\), is \(v_\perp\).

Input parameters should be slice of 2d numpy marker array. (i.e. *self.phasespace_coords)

Parameters:

• eta1 (array_like) – Logical evaluation points.

• eta2 (array_like) – Logical evaluation points.

• eta3 (array_like) – Logical evaluation points.

• v_para (array_like) – Parallel and perpendicular velocity evaluation points.

• v_perp (array_like) – Parallel and perpendicular velocity evaluation points.

Returns:

• out (array-like) – The Jacobian determinant evaluated at given logical coordinates.

• ——-

property volume_form: bool

Boolean. True if the background is represented as a volume form (thus including the velocity Jacobian |v_perp|).

property equil: FluidEquilibriumWithB

Fluid background with B-field.

property moment_factors

Collection of factors multiplied onto the defined moments n, u, and vth.

n(eta1, eta2, eta3)

Zero-th moment (density).

u(eta1, eta2, eta3)

Mean velocities.

vth(eta1, eta2, eta3)

Thermal velocities.

class struphy.kinetic_background.maxwellians.CanonicalMaxwellian2D(n: tuple[float | Callable, Perturbation] = (1.0, None), vth: tuple[float | Callable, Perturbation] = (1.0, None), volume_form: bool = True, uniform_on_disc: bool = False, equil: AxisymmMHDequilibrium | None = None, epsilon: float = 1.0, cache_size: int | None = None, shift: str | None = 'Bmax', shifted: bool | None = None)

Bases: GyroMaxwellian2D

Canonical Maxwellian distribution function in \((\eta_1, \eta_2, \eta_3, v_\parallel, \mu)\) coordinates. Uses caching for evaluation of the canonical toroidal momentum in these coordinates.

The distribution is parameterized by the density and thermal speed as functions of the (shifted) canonical toroidal momentum \(\psi_c\):

\[\psi_c = P_\phi - \text{sign}(v_\parallel)\sqrt{2(\epsilon - \mu B_\text{ref})}\frac{m_sF}{q_sB_\text{ref}} \mathcal{H}(\epsilon - \mu B_\text{ref})\,,\qquad P_\phi = \psi + \frac{m_s F}{q_s B}v_\parallel\,,\]

where \(P_\phi\) is the canonical toroidal momentum and the reference field \(B_\text{ref}\) is set by shift (see below). The shift (Angelino et al., Phys. Plasmas 13, 052304 (2006)) makes \(\psi_c = \psi\) where \(|\mathbf B| = B_\text{ref}\) on the orbit of a passing particle, such that the profiles in \(\psi_c\) are close to the profiles in the flux label of the position.

• Energy

\[\epsilon = \frac{1}{2}m_sv_\parallel² + \mu B,\]

• Magnetic moment

\[\mu = \frac{m_s v_\perp²}{2B},\]

where \(\psi\) is the poloidal magnetic flux function, \(F=F(\psi)\) is the poloidal current function and \(\mathcal{H}\) is the Heaviside function.

With the three constants of motion, a canonical Maxwellian distribution function is defined as

\[F(\psi_c, \epsilon, \mu) = \frac{n(\psi_c)}{(2\pi)^{3/2}v_\text{th}³(\psi_c)} \text{exp}\left[ - \frac{\epsilon}{v_\text{th}²(\psi_c)}\right].\]

Parameters:

• n (tuple) – Moments of the canonical Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• vth (tuple[float | Callable, Perturbation]) – Moments of the canonical Maxwellian as tuples. The first entry defines the background (float for constant background or callable), the second entry defines a Perturbation (can be None).

• maxw_params (dict) – Parameters for the kinetic background.

• vth – Thermal-speed background and optional perturbation.

• equil (AxisymmMHDequilibrium, optional) – Fluid equilibrium used to evaluate background profiles in the magnetic geometry.

• volume_form (bool, default=True) – If True, represent the distribution as a volume form and include the appropriate velocity-space Jacobian when evaluating it.

• cache_size (int, optional) – Number of rows in the cache buffer for \(\psi_c\) evaluation. If None, no caching is used. Must be able to accomodate all markers on the current process.

• shift (str | None, default="Bmax") –

  Reference field \(B_\text{ref}\) of the shift of the canonical toroidal momentum:

  • "Bmax": the maximum of \(|\mathbf B|\) on the flux surface \(\psi = P_\phi\), see absB_max(). A particle can only bounce (\(v_\parallel = 0\)) on this surface, hence the shift vanishes for all particles that can bounce, \(\psi_c\) is a function of the constants of motion \(P_\phi, \epsilon, \mu\) and the distribution is an exact equilibrium of the guiding-center motion (with the constant poloidal current function \(F = -B_0 R_0\) assumed in \(P_\phi\), as in AdhocTorus). It has a net parallel flow.

  • "B0": the on-axis field (Angelino et al.). The shift jumps at the bounce points of the trapped particles with \(\epsilon > \mu B_0\) (the sign of \(v_\parallel\) changes there), so the distribution is not an exact equilibrium (default up to Struphy 3.6).

  • None: no shift, \(\psi_c = P_\phi\) (exact equilibrium, but the profiles are shifted by the drift-orbit width with respect to the position).

• shifted (bool, optional) – Deprecated, use shift: True is shift="B0", False is shift=None.

shift_modes = {'B0': 1, 'Bmax': 2, None: 0}

Integer codes of the values of shift, as passed to the compiled kernels.

property equil: AxisymmMHDequilibrium

One of equils in case that moments are to be set in that way, None otherwise.

property epsilon: float

Epsilon parameter in the canonical toroidal momentum.

property shift: str | None

Reference field of the shift of the canonical toroidal momentum ("Bmax", "B0" or None).

property moment_factors

Collection of factors multiplied onto the defined moments n, u, and vth.

eval_psic(*coords, use_cbufs: bool = True)

Shifted canonical toroidal momentum evaluated at given particle positions and velocities.

If use_cbufs is False, the cache buffers are not used (and not overwritten) for marker evaluation. Otherwise the result for markers is a view of the buffer cbufs["psic"], which the next evaluation overwrites: copy it to keep it.

shift_kernel_args()

Arguments (shift_mode, psi_axis, psi_edge, bmax_table) of the compiled kernels that evaluate the shifted canonical toroidal momentum of markers, see shift_modes and absB_max_table.

classmethod shift_kernel_args_for(equil: AxisymmMHDequilibrium, shift: str | None)

Kernel arguments of shift_kernel_args() for a given equilibrium and shift.

eval_rc(eta1, eta2, eta3, vparallel, mu)

Square root of radially normalized canonical toroidal momentum.

\[\begin{split}\begin{aligned} r_c^2 &= \frac{\psi_c - \psi_\text{axis}}{\psi_\text{edge} - \psi_\text{axis}} \,, \\[3mm] r_c &= \begin{cases} \sqrt{\frac{\psi_c - \psi_\text{axis}}{\psi_\text{edge} - \psi_\text{axis}}} & \text{if} \quad \frac{\psi_c - \psi_\text{axis}}{\psi_\text{edge} - \psi_\text{axis}} \geq 0 \,, \\ -\sqrt{\frac{\psi_c - \psi_\text{axis}}{\psi_\text{edge} - \psi_\text{axis}}} & \text{if} \quad \frac{\psi_c - \psi_\text{axis}}{\psi_\text{edge} - \psi_\text{axis}} < 0 \,, \end{cases} \end{aligned}\end{split}\]

where \(\psi_\text{axis}\) and \(\psi_\text{edge}\) are poloidal magnetic flux function at the center and edge of poloidal plane respectively.

n(eta1, eta2, eta3, vparallel, mu)

Zero-th moment (density).

u(eta1, eta2, eta3, vparallel, mu)

Mean velocities (zero for the canonical Maxwellian).

vth(eta1, eta2, eta3, vparallel, mu)

Thermal velocities.

class struphy.kinetic_background.maxwellians.ColdPlasma(n: tuple[float | Callable, Perturbation] = (1.0, None), u1: tuple[float | Callable, Perturbation] = (0.0, None), u2: tuple[float | Callable, Perturbation] = (0.0, None), u3: tuple[float | Callable, Perturbation] = (0.0, None), equil: FluidEquilibriumWithB | None = None, uniform_on_disc: bool = False)

Bases: Maxwellian

Base class for a distribution as a Dirac-delta in velocity (vth = 0). The __call__ method returns the density evaluation.

classmethod default_maxw_params()

Default parameters dictionary defining the constant value of the constant background.

property vdim

Dimension of the velocity space (vdim = 0).

property velocity_coords: Literal['cartesian', 'vpara_mu', 'vpara_vperp', 'vpara_energy']

Velocity coordinates of the background.

property volume_form

Boolean. True if the background is represented as a volume form (thus including the velocity Jacobian).

property equil: FluidEquilibriumWithB

Fluid background with B-field.

velocity_jacobian_det(eta1, eta2, eta3, *v)

Jacobian determinant of the velocity coordinate transformation.

n(eta1, eta2, eta3)

Zero-th moment (density).

u(eta1, eta2, eta3)

Mean velocities.

vth(eta1, eta2, eta3)

Thermal velocities (are zero here, see __init__).