Base classes#

Base classes for kinetic backgrounds.

class struphy.kinetic_background.base.KineticBackground[source]#

Bases: object

Base class for kinetic background distributions.

Kinetic backgrounds are mainly used for particle weight computation:

they appear as initial conditions in the numerator of particle weights
they are evaluated at particle coordinates in the control-variate method for noise reduction.

Kinetic backgrounds can be defined in arbitrary phase space coordinates. A determinant of the velocity Jacobian must be provided in the subclasses.

abstract property vdim#: Dimension of the velocity space (vdim = n).

abstract property velocity_coords: Literal['cartesian', 'vpara_mu', 'vpara_vperp', 'vpara_energy']#: Velocity coordinates of the background.

abstract velocity_jacobian_det(eta1, eta2, eta3, *v)[source]#: Jacobian determinant of the velocity coordinate transformation (starting from Cartesian velocity coordinates).

abstract property volume_form: bool#: True if the background is represented as a volume form (thus including the velocity Jacobian).

abstract n(*coords)[source]#

Number density (0-form).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A numpy.array with the density evaluated at evaluation points (same shape as coords).

abstract u(*coords)[source]#

Mean velocities (Cartesian components).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A list[float] (background values) or a list[numpy.array] of the evaluated velocities.

property params: dict#: Parameters passed to __init__(), as dictionary.

property axes_transform: dict#

Mapping from logical dimension key to its LaTeX-formatted axis label, used for plot labeling.

Keys are “e1”, “e2”, “e3” (always \(\eta_1, \eta_2, \eta_3\)) and “v1”, “v2”, “v3”, whose labels depend on velocity_coords: “cartesian” (\(v_x, v_y, v_z\)), “vpara_mu” (\(v_\parallel, \mu\)), “vpara_vperp” (\(v_\parallel, v_\perp\)), or “vpara_energy” (\(v_\parallel, E\)). The “v3” entry is None unless velocity_coords is “cartesian”.

Evaluate a “reduced” version of the background, where all but 1 or 2 dimensions have been integrated out. See Particle binning.

Integration is performed via a simple midpoint rule, with the number of integration points specified by integrate_resol. One can set a maximum for the total evaluation points in order to avoid memory issues (default is 1e8, corresponding to ~1 GB for double precision).

Parameters:

dim_1 (LiteralOptions.KineticDimensionsToPlot | int) – The axis (or axes) along which the reduced distribution is evaluated (i.e. the axes that are not integrated out). They refere to logical phase space axes. If dim_2 is not defined the reduced distribution is 1D, otherwise it is 2D.
dim_2 (LiteralOptions.KineticDimensionsToPlot | int) – The axis (or axes) along which the reduced distribution is evaluated (i.e. the axes that are not integrated out). They refere to logical phase space axes. If dim_2 is not defined the reduced distribution is 1D, otherwise it is 2D.
v_lim (float | tuple[float]) – Limit values for the velocity axes (default: 5.0), given as (v_lim_1, v_lim_2) for dim_1 and dim_2 respectively (a single float is broadcast to both entries). v_lim[0] also sets the integration bounds of any velocity axis that is integrated out (i.e. neither dim_1 nor dim_2); v_lim[1] is only used when dim_2 is itself a velocity axis. For a Cartesian velocity coordinate (and v_parallel), the limits are [-v_lim, v_lim]. For a positive velocity coordinate (such as mu or v_perp), the limits are [0, v_lim].
resol (int | tuple[int] | np.ndarray | tuple[np.ndarray]) – Resolution of the evaluation grid along the plotted axis (axes). If a single integer is provided, it is used for both dim_1 and dim_2. If a numpy array is provided, it is used as the evaluation points along the corresponding axis (or axes).
integrate_resol (tuple[int | float] | None) – Number of quadrature points for integration along each phase space axis. If None, is determined as \(max\_points^{1/N}\) where \(N\) is the number of axes to integrate out. If tuple, length must be the dimension of the phase space (3 + vdim), where the plotted axes (dim_1, dim_2) must hold the value None. A float value means evaluation at that point rather than intgration. Example: integrate_resol=(None, 0.5, 20, None, 15, 15) for a 3D integral in (eta_3, vy, vz), evaluated at eta_2=0.5, and dim_1=”e1”, dim_2=”v1” for 2D evaluation. High number of quadrature points can lead to memory issues.
max_points (int = 1e8) – Maximum number of points to evaluate the background on (default is 1e8, corresponding to ~1 GB for double precision).
domain (Domain | None = None) – Mapping to physical space. If given, dim_1 and dim_2 must both be space axes ([“e1”,”e2”,”e3”]) and the returned physical_coords holds the corresponding “x”, “y”, “z” arrays; otherwise physical_coords is None.

Returns:

reduced_density (xp.ndarray) – The background integrated over all axes except dim_1 (and dim_2, if given); 1D if dim_2 is None, else 2D.
plot_pts1, plot_pts2 (xp.ndarray | None) – Evaluation points along dim_1 and dim_2. plot_pts2 is None if dim_2 is not given.
physical_coords (dict | None) – Dictionary with keys “x”, “y”, “z” holding the domain-mapped position arrays (broadcast to the shape of reduced_density), or None if no domain was given.

plot(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 | tuple[int] = 100, integrate_resol: tuple[int | float] | None = None, max_points: int = 10000000.0, domain: Domain | None = None, proj_axis: tuple[str] = ('x', 'y'), plot_3D: bool = False)[source]#

Plots the density profile (slice) of the phase space background distribution. The slice can be 1D or 2D, in logical coordinates. If a domain is given, the 2D slice is also plotted in physical (Cartesian) coordinates, and optionally as a 3D surface.

See reduced_eval() for how the profile is computed.

Parameters:

dim_1 (LiteralOptions.KineticDimensionsToPlot = ["e1","e2","e3","v1","v2","v3"]) – The axes used in the projection, they refere to logical phase 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 phase 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 (broadcast to dim_1 and dim_2, see reduced_eval()).
resol (int | tuple[int] = 100) – Resolution of the plot along each plotted axis. If a single integer is provided, it is used for both dim_1 and dim_2.
integrate_resol (tuple[int | float] | None = None) – Number of quadrature points for integration along each phase space axis that is not plotted. See reduced_eval() for details; if None it is chosen automatically from max_points. A float value means evaluation at that point rather than intgration.
max_points (int = 1e7) – Maximum number of points to evaluate the background on, to avoid memory issues.
domain (Domain | None = None) – Domain used to map the plot to physical (Cartesian) space, producing an additional 2D plot (and, if plot_3D=True, a 3D surface plot) alongside the logical-space plot. If given, dim_1 and dim_2 must both be space axes ([“e1”, “e2”, “e3”]).
proj_axis (tuple[str] = ("x", "y")) – The two Cartesian axes (“x”, “y”, “z”) used for the 2D physical-space plot (only used if domain is given). If you do not see the density profile in 2D, you may change these axes.
plot_3D (bool = False) – Also plot the density as a colored surface in 3D physical space. Requires domain to be given.

class struphy.kinetic_background.base.SumKineticBackground(f1, f2)[source]#

Bases: KineticBackground

property vdim#: Dimension of the velocity space (vdim = n).

property velocity_coords#: 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)[source]#: Jacobian determinant of the velocity coordinate transformation.

n(*coords)[source]#

Number density (0-form).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A numpy.array with the density evaluated at evaluation points (same shape as coords).

u(*coords)[source]#

Mean velocities (Cartesian components).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A list[float] (background values) or a list[numpy.array] of the evaluated velocities.

class struphy.kinetic_background.base.ScalarMultiplyKineticBackground(f0, a)[source]#

Bases: KineticBackground

property vdim#: Dimension of the velocity space (vdim = n).

property velocity_coords#: Velocity coordinates of the background.

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

velocity_jacobian_det(eta1, eta2, eta3, *v)[source]#: Jacobian determinant of the velocity coordinate transformation.

n(*coords)[source]#

Number density (0-form).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A numpy.array with the density evaluated at evaluation points (same shape as coords).

u(*coords)[source]#

Mean velocities (Cartesian components).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A list[float] (background values) or a list[numpy.array] of the evaluated velocities.

class struphy.kinetic_background.base.Maxwellian[source]#

Bases: KineticBackground

Base class for a Maxwellian distribution function. It is defined on \([0, 1]^3 \times \mathbb R^n, n \geq 1,\) with logical position coordinates \(\boldsymbol{\eta} \in [0, 1]^3\):

\[f(\boldsymbol{\eta}, v_1,\ldots,v_n) = n(\boldsymbol{\eta}) \prod_{i=1}^n \frac{1}{\sqrt{2\pi}\,v_{\mathrm{th},i}(\boldsymbol{\eta})} \exp\left[-\frac{(v_i-u_i(\boldsymbol{\eta}))^2}{2\,v_{\mathrm{th},i}(\boldsymbol{\eta})^2}\right],\]

defined by its velocity moments: the density \(n(\boldsymbol{\eta})\), the mean-velocities \(u_i(\boldsymbol{\eta})\), and the thermal velocities \(v_{\mathrm{th},i}(\boldsymbol{\eta})\).

abstract vth(*coords)[source]#

Thermal velocities (0-forms).

Parameters:: coords (numpy.arrays) – Evaluation points. All arrays must be of same shape (can be 1d for flat evaluation).
Return type:: A list[float] (background values) or a list[numpy.array] of the evaluated thermal velocities.

check_maxw_params()[source]#

property gauss_types: tuple[Literal['cartesian', 'polar', 'mu', 'energy']]#: Velocity coordinate types of the Maxwellian (one per velocity dimension).

classmethod gaussian(v, u=0.0, vth=1.0, B0=2.0, type: Literal['cartesian', 'polar', 'mu', 'energy'] = 'cartesian', volume_form=False)[source]#

1-dim. normal distribution, to which array-valued mean- and thermal velocities can be passed.

The type selects the velocity coordinate of the Maxwellian:

"cartesian": standard Gaussian,

\[G(v) = \frac{1}{\sqrt{2\pi}\,v_{\mathrm{th}}}\exp\left[-\frac{(v-u)^2}{2\,v_{\mathrm{th}}^2}\right]\,.\]
"polar": \(v \geq 0\) is the radial coordinate of a polar representation \((v, \theta)\) of a 2d isotropic Gaussian velocity space (e.g. \(v_\perp\) in gyro-/drift-kinetic Maxwellians, gyro-angle already integrated out), requires \(u=0\),

\[G_{\mathrm{polar}}(v) = \frac{1}{v_{\mathrm{th}}^2}\exp\left[-\frac{v^2}{2\,v_{\mathrm{th}}^2}\right]\,.\]
"energy": \(v \geq 0\) is an energy-like coordinate such as \(\mu|\mathbf B| = m v_\perp^2/2\),

requires \(u=0\), volume_form must be False (its Jacobian depends on \(B^*\)),

\[G_{\mathrm{energy}}(v) = \frac{1}{v_{\mathrm{th}}^2}\exp\left[-\frac{v}{v_{\mathrm{th}}^2}\right]\,.\]

For "polar", volume_form=True multiplies by the polar velocity Jacobian \(|v|\) (needed to integrate to 1 over \(v \in [0,\infty)\); for \(u=0\) this reduces to the Rayleigh distribution); volume_form=False leaves the Jacobian out, corresponding to the 0-form (density) representation used elsewhere in the discretization.

Parameters:

v (float | array-like) – Velocity coordinate; must be non-negative if type is "polar" or "energy".
u (float | array-like) – Mean velocity evaluated at position array, same shape as v. Must be 0 unless type == "cartesian".
vth (float | array-like) – Thermal velocity evaluated at position array, same shape as v.
B0 (float | array-like) – Background magnetic field evaluated at position array, same shape as v. Only used for type == "mu".
type (str) – Velocity coordinate type, one of "cartesian", "polar", "mu", "energy".
volume_form (bool) – If True, multiply by the polar velocity Jacobian |v|. Only valid for type == "polar".

Return type:

An array of size(v).

property add_perturbation: bool#

Table of Contents

Previous topic

Next topic

Base classes#