Base classes

Base classes for kinetic backgrounds.

class struphy.kinetic_background.base.KineticBackground

Bases: object

Base class for kinetic background distributions defined on \([0, 1]^3 \times \mathbb R^n, n \geq 1,\) with logical position coordinates \(\boldsymbol{\eta} \in [0, 1]^3\).

Explicit expressions for the following number density \(n\) and mean velocity \(\mathbf u\) must be implemented:

\[ \begin{align}\begin{aligned}n &= \int f \,\mathrm{d} \mathbf v\\\mathbf u &= \frac 1n \int \mathbf v f \,\mathrm{d} \mathbf v\,.\end{aligned}\end{align} \]

abstract property coords

Coordinates of the distribution.

abstract property vdim

Dimension of the velocity space (vdim = n).

abstract property is_polar

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

abstract property volume_form: bool

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

abstract velocity_jacobian_det(eta1, eta2, eta3, *v)

Jacobian determinant of the velocity coordinate transformation.

abstract n(*etas)

Number density (0-form).

Parameters:

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

abstract u(*etas)

Mean velocities (Cartesian components evaluated at x = F(eta)).

Parameters:

etas (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.

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 = 50, 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=False, equil=None)

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.base.SumKineticBackground(f1, f2)

Bases: KineticBackground

property coords

Coordinates of the distribution.

property vdim

Dimension of the velocity space (vdim = n).

property is_polar

List of booleans. True if the velocity coordinates are polar coordinates.

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(*etas)

Number density (0-form).

Parameters:

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

u(*etas)

Mean velocities (Cartesian components evaluated at x = F(eta)).

Parameters:

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

Bases: KineticBackground

property coords

Coordinates of the distribution.

property vdim

Dimension of the velocity space (vdim = n).

property is_polar

List of booleans. True if the velocity coordinates are polar coordinates.

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)

Jacobian determinant of the velocity coordinate transformation.

n(*etas)

Number density (0-form).

Parameters:

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

u(*etas)

Mean velocities (Cartesian components evaluated at x = F(eta)).

Parameters:

etas (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

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(*etas)

Thermal velocities (0-forms).

Parameters:

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

classmethod gaussian(v, u=0.0, vth=1.0, polar=False, volume_form=False)

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

Parameters:

• v (float | array-like) – Velocity coordinate(s).

• u (float | array-like) – Mean velocity evaluated at position array.

• vth (float | array-like) – Thermal velocity evaluated at position array, same shape as u.

• polar (bool) – True if the velocity coordinate is the radial one of polar coordinates (v >= 0).

• volume_form (bool) – If True, the polar Gaussian is multiplied by the polar velocity Jacobian |v|.

Return type:

An array of size(v).

property add_perturbation: bool