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))[source]#

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 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)[source]#

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)[source]#

Zero-th moment (density).

u(eta1, eta2, eta3)[source]#

Mean velocities.

vth(eta1, eta2, eta3)[source]#

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)[source]#

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

  • 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 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)[source]#

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)[source]#

Zero-th moment (density).

u(eta1, eta2, eta3)[source]#

Mean velocities.

vth(eta1, eta2, eta3)[source]#

Thermal velocities.

plot_density_profile(dim_1: Literal['e1', 'e2', 'e3', 'v1', 'v2', 'v3'] = 'e1', dim_2: Literal['e1', 'e2', 'e3', 'v1', 'v2', 'v3'] | None = None, v_lim: float = 5.0, resol: int = 100, integrate_resol: int = 10, logical_coord: tuple[float] = (0.5, 0.5, 0.5), in_physical: bool = False, domain: Domain | None = None, proj_axis: tuple[float] = (0, 1), plot_3D: bool = False, title: str | None = None, use_mu: bool = False, equil: FluidEquilibriumWithB | None = None)[source]#

Plots the density profile (slices) of the phase space background distribution. The slice can either be 1D or 2D, in logical or in Cartesian coordinates.

Parameters:

  • dim_1 (LiteralOptions.KineticDimensionsToPlot = ["e1","e2","e3","v1","v2","v3"]) – The axes used in the projection, they refere to logical space axes. If dim_2 is not defined the projection is 1D, it is 2D if dim_2 is attributed.

  • dim_2 (LiteralOptions.KineticDimensionsToPlot = ["e1","e2","e3","v1","v2","v3"]) – The axes used in the projection, they refere to logical space axes. If dim_2 is not defined the projection is 1D, it is 2D if dim_2 is attributed.

  • v_lim (float = 5.0) – Limit value of the velocity axes.

  • resol (int = 100) – Resolution along each axes

  • integrate_resol (int = 10) – Resolution along not used velocity axes. The density is reduced (with a maximum function) over these axes before being plotted. High values (>50) may require much memory.

  • logical_coord (tuple[float] = (0.5, 0.5, 0.5)) – Refere to the default coordinate (in logical space) attributed to each axe which is not used in the projection.

  • in_physical (bool = False) – Specify if the result is plotted in logical coordinates or in Cartesian coordinates, has a effect in 2D plotting. If True, you must specify a domain.

  • domain (Domain | None = None) – Domain used to plot the density if in_physical=True.

  • proj_axis (tuple[float] = (0,1)) – Axes of the Cartesian coordinates used to plot the density: 0->x, 1->y, 2->z. I you do not see the density profile in 2D, you may change these axes.

  • plot_3D (bool = False) – Plots a surface in a 3D environment. Only for physical projection.

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)[source]#

Bases: object

Canonical Maxwellian distribution function in constants-of-motion 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[float | Callable, Perturbation]) – Density background and optional perturbation.

  • vth (tuple[float | Callable, Perturbation]) – Thermal-speed background and optional perturbation.

  • equil (FluidEquilibriumWithB, 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.

property coords#

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

property equil: FluidEquilibriumWithB#

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

check_maxw_params()[source]#
velocity_jacobian_det(eta1, eta2, eta3, energy)[source]#

TODO

gaussian(e, vth=1.0)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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()[source]#

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

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)[source]#

Jacobian determinant of the velocity coordinate transformation.

n(eta1, eta2, eta3)[source]#

Zero-th moment (density).

u(eta1, eta2, eta3)[source]#

Mean velocities.

vth(eta1, eta2, eta3)[source]#

Thermal velocities (are zero here, see __init__).