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

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 = 2.0, 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).

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

• B0 (float | Callable) – Constant or callable background magnetic field strength (default = 2.0).

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

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.

• ——-

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

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)

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 canonical toroidal momentum \(\psi_c\):

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

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

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.

eval_psic(*coords)

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

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