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

Bases: Maxwellian

A Maxwellian depending 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).

property maxw_params

Parameters dictionary defining moments of the Maxwellian.

property coords

Coordinates of the Maxwellian6D, \((v_1, v_2, v_3)\).

property vdim

Dimension of the velocity space.

property is_polar

List of booleans of length vdim. True for a velocity coordinate that is a radial polar coordinate (v_perp).

velocity_jacobian_det(eta1, eta2, eta3, *v)

Jacobian determinant of the velocity coordinate transformation from Maxwellian6D(‘cartesian’) to Particles6D(‘cartesian’).

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 (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), equil: FluidEquilibriumWithB | None = None, volume_form: bool = True)

Bases: Maxwellian

A gyrotropic Maxwellian depending on two velocities \((v_\parallel, v_\perp)\), \(n=2\), where \(v_\parallel = \matbf 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).

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

• pert_params (dict) – Parameters for the kinetic perturbation added to the background.

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

property maxw_params

Parameters dictionary defining moments of the Maxwellian.

property coords

Coordinates of the Maxwellian5D, \((v_\parallel, v_\perp)\).

property vdim

Dimension of the velocity space.

property is_polar

List of booleans of length vdim. True for a velocity coordinate that is a radial polar coordinate (v_perp).

velocity_jacobian_det(eta1, eta2, eta3, *v)

Jacobian determinant of the velocity coordinate transformation from Maxwellian5D(‘vpara_vperp’) to Particles5D(‘vpara_mu’).

\[\begin{split}\begin{aligned} F &: (v_\parallel, v_\perp) \to (v_\parallel, \mu) \,, \\[3mm] DF &= \begin{bmatrix} \frac{\partial v_\parallel}{\partial v_\parallel} & \frac{\partial v_\parallel}{\partial v_\perp} \\ \frac{\partial \mu}{\partial v_\parallel} & \frac{\partial \mu}{\partial v_\perp} \end{bmatrix} = \begin{bmatrix} 1 & 0 \\ 0 & \frac{v_\perp}{B} \end{bmatrix} \,, \\[3mm] J_F &= \frac{v_\perp}{B} \,, \end{aligned}\end{split}\]

where \(\mu = \frac{v_\perp^2}{2B}\).

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 (array_like) – 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.CanonicalMaxwellian(n: tuple[float | Callable, Perturbation] = (1.0, None), vth: tuple[float | Callable, Perturbation] = (1.0, None), equil: FluidEquilibriumWithB | None = None, volume_form: bool = True)

Bases: object

canonical Maxwellian distribution function. It is defined by three constants of motion in the axissymmetric toroidal system:

• Shifted canonical toroidal momentum

\[\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:

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

• pert_params (dict) – Parameters for the kinetic perturbation added to the background.

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

property coords

Coordinates of the CanonicalMaxwellian, \((\epsilon, \mu, \psi_c)\).

property maxw_params

Parameters dictionary defining constant moments of the Maxwellian.

property equil: FluidEquilibriumWithB

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

check_maxw_params()

velocity_jacobian_det(eta1, eta2, eta3, energy)

TODO

gaussian(e, vth=1.0)

3-dim. normal distribution, to which array-valued thermal velocities can be passed.

Parameters:

• e (float | array-like) – Energy.

• vth (float | array-like) – Thermal velocity evaluated at psic.

Return type:

An array of size(e).

property volume_form

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.

rc(psic)

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.

Parameters:

psic (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).

Return type:

A numpy.array of the evaluated \(r_c\).

n(psic, add_perturbation: bool | None = None)

Density as background + perturbation.

Parameters:

psic (numpy.array) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).

Return type:

A float (background value) or a numpy.array of the evaluated density.

vth(psic)

Thermal velocities as background + perturbation.

Parameters:

psic (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).

Return type:

A list[float] (background value) or a list[numpy.array] of the evaluated thermal velocities.

property add_perturbation: bool

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)

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 maxw_params

Parameters dictionary defining moments of the Maxwellian.

property coords

Coordinates of the constant background.

property vdim

Dimension of the velocity space (vdim = 0).

property is_polar

List of booleans of length vdim. True for a velocity coordinate that is a radial polar coordinate (v_perp).

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