Base classes

Base classes for MHD equilibria.

class struphy.fields_background.base.FluidEquilibrium

Bases: object

Abstract base class for callable fluid equilibria on arbitrary domains.

This class provides a unified interface for representing fluid equilibrium states, including velocity, pressure, and number density fields. It supports coordinate transformations between logical (reference) and physical domains through the Domain object, enabling computations on mapped domains.

Variables:

• params (dict) – Dictionary of parameters passed to the class initialization. Automatically strips ‘self’ and ‘__class__’ entries.

• domain (Domain) – Domain object that characterizes the mapping from the logical cube [0, 1]^3 to the physical domain. Enables coordinate transformations and differential form conversions (0-forms, 1-forms, 2-forms, 3-forms).

• Requirements (Implementation)

• ---------------------------

• pairs (Child classes must provide at least one method from each of these)

• Velocity (*)

• Pressure (*)

• Density (* Number)

• Quantities (Derived)

• ------------------

• fields (The class automatically provides derived fields computed from the basic)

• Temperature (*)

• velocity (* Thermal)

• density (* Entropy)

• Forms (Differential)

• -------------------

• as (Vector fields (velocity) are available)

• uv (*)

• u1 (*)

• u2 (*)

• u_cart (*)

• (densities) (Scalar fields are available as 0-forms (point values) and 3-forms)

• p3 (* p0,)

• n3 (* n0,)

• t3 (* t0,)

• q3 (* q0,)

Notes

The class uses abstract methods to enforce implementation in child classes. Subclasses should override coordinate-appropriate base methods (CartesianFluidEquilibrium or LogicalFluidEquilibrium) to simplify implementation.

property params: dict

Parameters passed to __init__() of the class in equils.py, as dictionary.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

property is_default

u1(*etas, squeeze_out=False)

1-form components of velocity on logical cube [0, 1]^3.

u2(*etas, squeeze_out=False)

2-form components of velocity on logical cube [0, 1]^3.

uv(*etas, squeeze_out=False)

Contra-variant components of velocity on logical cube [0, 1]^3.

u_cart(*etas, squeeze_out=False)

Cartesian components of velocity evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

p0(*etas, squeeze_out=False)

0-form pressure on logical cube [0, 1]^3.

p3(*etas, squeeze_out=False)

3-form pressure on logical cube [0, 1]^3.

n0(*etas, squeeze_out=False)

0-form number density on logical cube [0, 1]^3.

n3(*etas, squeeze_out=False)

3-form number density on logical cube [0, 1]^3.

t0(*etas, squeeze_out=False)

0-form temperature on logical cube [0, 1]^3.

t3(*etas, squeeze_out=False)

3-form temperature on logical cube [0, 1]^3.

vth0(*etas, squeeze_out=False)

0-form thermal velocity on logical cube [0, 1]^3.

vth3(*etas, squeeze_out=False)

3-form thermal velocity on logical cube [0, 1]^3.

q0(*etas, squeeze_out=False)

0-form square root of the pressure on logical cube [0, 1]^3.

q3(*etas, squeeze_out=False)

3-form square root of the pressure on logical cube [0, 1]^3.

s0_monoatomic(*etas, squeeze_out=False)

0-form entropy density on logical cube [0, 1]^3. Hard coded assumption : gamma = 5/3 (monoatomic perfect gaz)

s3_monoatomic(*etas, squeeze_out=False)

3-form entropy density on logical cube [0, 1]^3. Hard coded assumption : gamma = 5/3 (monoatomic perfect gaz)

s0_diatomic(*etas, squeeze_out=False)

0-form entropy density on logical cube [0, 1]^3. Hard coded assumption : gamma = 7/5 (diatomic perfect gaz)

s3_diatomic(*etas, squeeze_out=False)

3-form entropy density on logical cube [0, 1]^3. Hard coded assumption : gamma = 5/3 (monoatomic perfect gaz)

u1_1(*etas, squeeze_out=False)

u1_2(*etas, squeeze_out=False)

u1_3(*etas, squeeze_out=False)

u2_1(*etas, squeeze_out=False)

u2_2(*etas, squeeze_out=False)

u2_3(*etas, squeeze_out=False)

uv_1(*etas, squeeze_out=False)

uv_2(*etas, squeeze_out=False)

uv_3(*etas, squeeze_out=False)

u_cart_1(*etas, squeeze_out=False)

u_cart_2(*etas, squeeze_out=False)

u_cart_3(*etas, squeeze_out=False)

to_dict() → dict

classmethod from_dict(dct: dict | None) → FluidEquilibrium

classmethod get_equil_by_name(equil_name: str) → type[FluidEquilibrium]

class struphy.fields_background.base.CartesianFluidEquilibrium

Bases: FluidEquilibrium

Specialization for equilibria defined in Cartesian coordinates.

Child classes must implement the abstract methods u_xyz, p_xyz, and n_xyz, which return velocity, pressure, and number density in Cartesian physical space (x, y, z). The base class automatically handles coordinate transformations and differential form conversions.

abstract u_xyz(x, y, z)

Cartesian velocity in physical space. Must return the components as a tuple.

abstract p_xyz(x, y, z)

Equilibrium pressure in physical space.

abstract n_xyz(x, y, z)

Equilibrium number density in physical space.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.LogicalFluidEquilibrium

Bases: FluidEquilibrium

Specialization for equilibria defined on the logical cube [0, 1]^3.

Child classes must implement the abstract methods uv, p0, and n0, which return contravariant velocity, 0-form pressure, and 0-form number density on the logical reference domain. Useful for direct implementation when physical coordinates are obtained via coordinate transformation through the domain mapping.

abstract uv(*etas, squeeze_out=False)

Contra-variant (vector field) velocity on logical cube [0, 1]^3. Must return the components as a tuple.

abstract p0(*etas, squeeze_out=False)

0-form pressure on logical cube [0, 1]^3.

abstract n0(*etas, squeeze_out=False)

0-form density on logical cube [0, 1]^3.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.NumericalFluidEquilibrium

Bases: LogicalFluidEquilibrium

Specialization for equilibria with numerically computed domain mappings.

Child classes must provide a numerical_domain property that returns a Domain object representing the mapping from the logical cube [0, 1]^3 to the physical domain. This class overrides the domain property to use the numerically computed mapping.

abstract property numerical_domain

Numerically computed mapping from the logical cube [0, 1]^3 to the physical domain in the form of a Domain object.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.FluidEquilibriumWithB

Bases: FluidEquilibrium

Extension of FluidEquilibrium with magnetic field and its gradient.

Child classes must implement either Cartesian (b_xyz, gradB_xyz) or logical (bv, gradB1) methods for magnetic field and its gradient. Provides methods for 1-form and 2-form transformations of the magnetic field.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

b1(*etas, squeeze_out=False)

1-form components of magnetic field on logical cube [0, 1]^3.

b2(*etas, squeeze_out=False)

2-form components of magnetic field on logical cube [0, 1]^3.

bv(*etas, squeeze_out=False)

Contra-variant components of magnetic field on logical cube [0, 1]^3.

b_cart(*etas, squeeze_out=False)

Cartesian components of magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

unit_b1(*etas, squeeze_out=False)

Unit vector components of magnetic field (1-form) on logical cube [0, 1]^3.

unit_b2(*etas, squeeze_out=False)

Unit vector components of magnetic field (2-form) on logical cube [0, 1]^3.

unit_bv(*etas, squeeze_out=False)

Unit vector components of magnetic field (contra-variant) on logical cube [0, 1]^3.

unit_b_cart(*etas, squeeze_out=False)

Unit vector Cartesian components of magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

gradB1(*etas, squeeze_out=False)

1-form components of gradient of magnetic field strength evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

gradB2(*etas, squeeze_out=False)

2-form components of gradient of magnetic field strength evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

gradBv(*etas, squeeze_out=False)

Contra-variant components of gradient of magnetic field strength evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

gradB_cart(*etas, squeeze_out=False)

Cartesian components of gradient of magnetic field strength evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

a1(*etas, squeeze_out=False)

1-form components of vector potential on logical cube [0, 1]^3.

a2(*etas, squeeze_out=False)

2-form components of vector potential on logical cube [0, 1]^3.

av(*etas, squeeze_out=False)

Contra-variant components of vector potneital on logical cube [0, 1]^3.

absB0(*etas, squeeze_out=False)

0-form absolute value of magnetic field on logical cube [0, 1]^3.

absB3(*etas, squeeze_out=False)

3-form absolute value of magnetic field on logical cube [0, 1]^3.

u_para0(*etas, squeeze_out=False)

0-form parallel velocity on logical cube [0, 1]^3.

u_para3(*etas, squeeze_out=False)

3-form parallel velocity on logical cube [0, 1]^3.

b1_1(*etas, squeeze_out=False)

b1_2(*etas, squeeze_out=False)

b1_3(*etas, squeeze_out=False)

b2_1(*etas, squeeze_out=False)

b2_2(*etas, squeeze_out=False)

b2_3(*etas, squeeze_out=False)

bv_1(*etas, squeeze_out=False)

bv_2(*etas, squeeze_out=False)

bv_3(*etas, squeeze_out=False)

unit_b1_1(*etas, squeeze_out=False)

unit_b1_2(*etas, squeeze_out=False)

unit_b1_3(*etas, squeeze_out=False)

unit_b2_1(*etas, squeeze_out=False)

unit_b2_2(*etas, squeeze_out=False)

unit_b2_3(*etas, squeeze_out=False)

unit_bv_1(*etas, squeeze_out=False)

unit_bv_2(*etas, squeeze_out=False)

unit_bv_3(*etas, squeeze_out=False)

gradB1_1(*etas, squeeze_out=False)

gradB1_2(*etas, squeeze_out=False)

gradB1_3(*etas, squeeze_out=False)

gradB2_1(*etas, squeeze_out=False)

gradB2_2(*etas, squeeze_out=False)

gradB2_3(*etas, squeeze_out=False)

gradBv_1(*etas, squeeze_out=False)

gradBv_2(*etas, squeeze_out=False)

gradBv_3(*etas, squeeze_out=False)

a1_1(*etas, squeeze_out=False)

a1_2(*etas, squeeze_out=False)

a1_3(*etas, squeeze_out=False)

a2_1(*etas, squeeze_out=False)

a2_2(*etas, squeeze_out=False)

a2_3(*etas, squeeze_out=False)

av_1(*etas, squeeze_out=False)

av_2(*etas, squeeze_out=False)

av_3(*etas, squeeze_out=False)

class struphy.fields_background.base.CartesianFluidEquilibriumWithB

Bases: CartesianFluidEquilibrium

Specialization for fluid equilibria with magnetic field in Cartesian coordinates.

Child classes must implement the abstract methods b_xyz and gradB_xyz, which return magnetic field and its gradient strength in Cartesian physical space.

abstract b_xyz(x, y, z)

Cartesian magnetic field in physical space. Must return the components as a tuple.

abstract gradB_xyz(x, y, z)

Cartesian gradient of magnetic field strength in physical space. Must return the components as a tuple.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.LogicalFluidEquilibriumWithB

Bases: LogicalFluidEquilibrium

Specialization for fluid equilibria with magnetic field on the logical cube [0, 1]^3.

Child classes must implement the abstract methods bv (contravariant magnetic field) and gradB1 (1-form gradient of magnetic field strength) on the logical domain.

abstract bv(*etas, squeeze_out=False)

Contra-variant (vector field) magnetic field on logical cube [0, 1]^3. Must return the components as a tuple.

abstract gradB1(*etas, squeeze_out=False)

Co-variant (1-from) gradient of magnetic field strength on logical cube [0, 1]^3. Must return the components as a tuple.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.NumericalFluidEquilibriumWithB

Bases: LogicalFluidEquilibriumWithB

Specialization for fluid equilibria with magnetic field and numerically computed domain mappings.

Child classes must provide a numerical_domain property that returns a Domain object. This class overrides the domain property to use the numerically computed mapping.

abstract property numerical_domain

Numerically computed mapping from the logical cube [0, 1]^3 to the physical domain in the form of a Domain object.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.MHDequilibrium

Bases: FluidEquilibriumWithB

Extension of FluidEquilibriumWithB with current density field.

Child classes must implement either Cartesian (j_xyz) or logical (jv) methods for current density. The velocity field is derived from current density as j/n, overriding the base FluidEquilibrium. Provides methods for 1-form and 2-form transformations of the current density.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

j1(*etas, squeeze_out=False)

1-form components of current on logical cube [0, 1]^3.

j2(*etas, squeeze_out=False)

2-form components of current on logical cube [0, 1]^3.

jv(*etas, squeeze_out=False)

Contra-variant components of current on logical cube [0, 1]^3.

j_cart(*etas, squeeze_out=False)

Cartesian components of current evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

u1(*etas, squeeze_out=False)

1-form components of mean velocity evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

u2(*etas, squeeze_out=False)

2-form components of mean velocity evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

uv(*etas, squeeze_out=False)

Contra-variant components of mean velocity evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

u_cart(*etas, squeeze_out=False)

Cartesian components of mean velocity evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

curl_unit_b1(*etas, squeeze_out=False)

1-form components of curl of unit magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

curl_unit_b2(*etas, squeeze_out=False)

2-form components of curl of unit magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

curl_unit_bv(*etas, squeeze_out=False)

Contra-variant components of curl of unit magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

curl_unit_b_cart(*etas, squeeze_out=False)

Cartesian components of curl of unit magnetic field evaluated on logical cube [0, 1]^3. Returns also (x,y,z).

curl_unit_b_dot_b0(*etas, squeeze_out=False)

0-form of \((\nabla \times \mathbf b_0) \times \mathbf b_0\) evaluated on logical cube [0, 1]^3.

j1_1(*etas, squeeze_out=False)

j1_2(*etas, squeeze_out=False)

j1_3(*etas, squeeze_out=False)

j2_1(*etas, squeeze_out=False)

j2_2(*etas, squeeze_out=False)

j2_3(*etas, squeeze_out=False)

jv_1(*etas, squeeze_out=False)

jv_2(*etas, squeeze_out=False)

jv_3(*etas, squeeze_out=False)

curl_unit_b1_1(*etas, squeeze_out=False)

curl_unit_b1_2(*etas, squeeze_out=False)

curl_unit_b1_3(*etas, squeeze_out=False)

curl_unit_b2_1(*etas, squeeze_out=False)

curl_unit_b2_2(*etas, squeeze_out=False)

curl_unit_b2_3(*etas, squeeze_out=False)

curl_unit_bv_1(*etas, squeeze_out=False)

curl_unit_bv_2(*etas, squeeze_out=False)

curl_unit_bv_3(*etas, squeeze_out=False)

show(n1=16, n2=33, n3=21, n_planes=5)

Generate vtk files of equilibirum and do some 2d plots with matplotlib.

Parameters:

• n1 (int) – Evaluation points of mapping in each direcion.

• n2 (int) – Evaluation points of mapping in each direcion.

• n3 (int) – Evaluation points of mapping in each direcion.

• n_planes (int) – Number of planes to show perpendicular to eta3.

class struphy.fields_background.base.CartesianMHDequilibrium

Bases: MHDequilibrium

Specialization for MHD equilibria in Cartesian coordinates.

Child classes must implement the abstract methods b_xyz, j_xyz, p_xyz, n_xyz, and gradB_xyz in Cartesian physical space.

abstract b_xyz(x, y, z)

Cartesian magnetic field in physical space. Must return the components as a tuple.

abstract j_xyz(x, y, z)

Cartesian current (curl of magnetic field) in physical space. Must return the components as a tuple.

abstract p_xyz(x, y, z)

Equilibrium pressure in physical space.

abstract n_xyz(x, y, z)

Equilibrium number density in physical space.

abstract gradB_xyz(x, y, z)

Cartesian gradient of magnetic field strength in physical space. Must return the components as a tuple.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.AxisymmMHDequilibrium

Bases: CartesianMHDequilibrium

Base class for ideal axisymmetric MHD equilibria based on a poloidal flux function \(\psi(R, Z)\) and a toroidal field function \(g_{tor}(R, Z)\) in a cylindrical coordinate system \((R, \phi, Z)\).

The magnetic field and current density are then given by

\[\mathbf B = \nabla \psi \times \nabla \phi + g_{tor} \nabla \phi\,,\qquad \mathbf j = \nabla \times \mathbf B\,.\]

The pressure and density profiles need to be implemented by child classes.

abstract psi(R, Z, dR=0, dZ=0)

Poloidal flux function per radian. First AND second derivatives dR=0,1,2 and dZ=0,1,2 must be implemented.

abstract g_tor(R, Z, dR=0, dZ=0)

Toroidal field function. First derivatives dR=0,1 and dZ=0,1 must be implemented.

abstract property psi_range

Psi on-axis and at plasma boundary returned as list [psi_axis, psi_boundary].

abstract property psi_axis_RZ

Location of magnetic axis in R-Z-coordinates returned as list [psi_axis_R, psi_axis_Z].

abstract p_xyz(x, y, z)

Equilibrium pressure in physical space.

abstract n_xyz(x, y, z)

Equilibrium number density in physical space.

b_xyz(x, y, z)

Cartesian B-field components calculated as BR = -(dpsi/dZ)/R, BPhi = g_tor/R, BZ = (dpsi/dR)/R.

j_xyz(x, y, z)

Cartesian current density components calculated as curl(B).

gradB_xyz(x, y, z)

Cartesian gradient |B| components calculated as grad(sqrt(BR**2 + BPhi**2 + BZ**2)).

static inverse_map(x, y, z)

Inverse cylindrical mapping.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.LogicalMHDequilibrium

Bases: MHDequilibrium

Specialization for MHD equilibria on the logical cube [0, 1]^3.

Child classes must implement the abstract methods bv, jv, p0, n0, and gradB1 on the logical reference domain.

abstract bv(*etas, squeeze_out=False)

Contra-variant (vector field) magnetic field on logical cube [0, 1]^3. Must return the components as a tuple.

abstract jv(*etas, squeeze_out=False)

Contra-variant (vector field) current density (=curl B) on logical cube [0, 1]^3. Must return the components as a tuple.

abstract p0(*etas, squeeze_out=False)

0-form pressure on logical cube [0, 1]^3. Must return the components as a tuple.

abstract n0(*etas, squeeze_out=False)

0-form density on logical cube [0, 1]^3.

abstract gradB1(*etas, squeeze_out=False)

1-form gradient of magnetic field strength strength on logical cube [0, 1]^3. Must return the components as a tuple.

property domain

Domain object that characterizes the mapping from the logical to the physical domain.

class struphy.fields_background.base.NumericalMHDequilibrium

Bases: LogicalMHDequilibrium

Specialization for MHD equilibria with numerically computed domain mappings.

Child classes must provide a numerical_domain property that returns a Domain object. This class overrides the domain property to use the numerically computed mapping.

abstract property numerical_domain

Numerically computed mapping from the logical cube [0, 1]^3 to the physical domain in the form of a Domain object.

property domain: Domain

Domain object that characterizes the mapping from the logical to the physical domain.