Normalization#

Struphy models are implemented in normalized variables. In general, any dependent or independent variable \(X\) is expressed as

\[X = X'\,\hat X\,,\]

where \(\hat X\) is the unit and \(X'\) is the numerical value appearing in the code. For example, the same length \(a\) could be either expressed as \(a = 2 \cdot 1\, \textrm{meter}\) or as \(a = 4 \cdot 0.5\, \textrm{meter}\), where in the second case the unit of length was chosen to be 0.5 meter.

The units \(\hat X\) for a Struphy model can be influenced by the user through BaseUnits in the launch file, where the user can set

  • the unit of length \(\hat x\), expressed in Meter,

  • the unit of the magnetic field strength \(\hat B\), expressed in Tesla,

  • the unit of number density \(\hat n\), expressed in \(\mathbf{10^{20}\,m^{-3}}\).

  • optional: the unit of thermal energy \(k_\textnormal{B} \hat T\), expressed in keV.

This immediately gives meaning to the numerical values of these quantities appearing in the parameter file. Additionally,

  • the unit of velocity \(\hat v\), expressed in Meters/Second,

is hard coded for each model under the attribute velocity_scale. There are four possibilities:

  1. speed of light, \(\hat v = c\).

  2. alfvén speed of the bulk species,

\[\hat v = v_\textnormal{A, bulk} := \sqrt{\hat B^2 / (m_\textnormal{bulk} \hat n \mu_0)}\,.\]

  1. cyclotron speed of the bulk species,

\[\hat v = v_\textnormal{c, bulk} := \hat x \Omega_\textnormal{c, bulk}/(2\pi) = \hat x\, q_\textnormal{bulk} \hat B /(m_\textnormal{bulk}2\pi)\,.\]

  1. thermal velocity of the bulk species,

\[\hat v = \sqrt{\frac{k_\textnormal{B} \hat T}{m_\textnormal{bulk}}}\,.\]

Several additional units are derived internally from the above basic units, in the class Units. In particular,

  • the time unit in Seconds:

\[\hat t = \frac{\hat x}{\hat v} \,,\]

  • the pressure unit in Pascal:

\[\hat p = m_\textnormal{bulk} \hat n \hat v^2\,,\]

which is equal to \(\hat B^2/\mu_0\) if the velocity scale is Alfvén,

  • the mass density unit in \(\mathbf{kg/m^3}\):

\[\hat \rho = m_\textnormal{bulk} \hat n\]

  • the current density unit in Ampere\(\boldsymbol{/m^2}\):

\[\hat \jmath = q_\textnormal{bulk} \hat n \hat v\,.\]

We refer to Example: Vlasov-Maxwell-Poisson discretization for an example of how to derive a normalization for a physics model.

Units class#

class struphy.io.options.Units(base: BaseUnits | None = None)[source]#

Colllects base units and derives other units from these. See Normalization.

property x#
property B#
property n#

Unit of particle number density in 1/m^3.

property kBT#
property v#

Unit of velocity in m/s.

property t#

Unit of time in s.

property p#

Unit of pressure in Pa, equal to B^2/mu0 if velocity_scale=’alfvén’.

property rho#

Unit of mass density in kg/m^3.

property j#

Unit of current density in A/m^2.

derive_units(velocity_scale: str = 'light', A_bulk: int | None = None, Z_bulk: int | None = None, verbose=False)[source]#

Derive the remaining units from the base units, velocity scale and bulk species’ A and Z.

Equation parameters#

In Struphy models, the following equation parameters appear:

\[\alpha_\textrm{s} = \frac{\hat \Omega_\textnormal{ps}}{\hat \Omega_\textnormal{cs}}\,,\qquad \varepsilon_\textrm{s} = \frac{1}{\hat \Omega_\textnormal{cs} \hat t} \,,\]

featuring the plasma- and cyclotron frequency of species \(\textrm{s}\), respectively,

\[\hat\Omega_\textnormal{ps} = \sqrt{\frac{\hat n (Z_\textrm{s}e)^2}{\epsilon_0 (A_\textrm{s} m_\textnormal{H})}} \,,\qquad \hat \Omega_{\textnormal{cs}} = \frac{(Z_\textrm{s}e) \hat B}{(A_\textrm{s} m_\textnormal{H})}\,,\]

where \(Z_\textrm{s}\) and \(A_\textrm{s}\) stand for the species’ charge and mass number, respectively. These equation parameters are defined in EquationParameters and can be overridden in the launch file via set_phys_params().

class struphy.models.species.Species.EquationParameters(species, units: Units | None = None, alpha: float | None = None, epsilon: float | None = None, kappa: float | None = None, verbose: bool = False)#

Normalization parameters of one species, appearing in scaled equations.