_models

Physical property metadata for PSI’s model quantities and scales.

This module provides the Props dataclass and three read-only mapping objects that fully describe every quantity PSI’s modeling codes write to HDF files:

• The filename/lookup identifier (e.g., 'br')

• Human-readable description (e.g., 'MAS Magnetic Field (Radial Component)')

• Native code Unit (e.g., Unit("2.20689 G") or Unit("MAS_b"))

• Dimensionality (e.g., 3 for 3-D output fields)

• Scalar or vector classification

• Mesh staggering code (e.g., 0b011)

For metadata access, one should use the provided getter functions rather than the mapping objects directly.

Mapping	Model	Contents
get_mas_quantity_properties()	MAS (Magnetohydrodynamic Algorithm outside a Sphere)	19 3-D output fields: velocity, magnetic field, current density, temperature, density, pressure, wave energy, Elsässer amplitudes, heating
get_pot3d_quantity_properties()	POT3D (High Performance Potential Field Solver)	3 magnetic field components (br, bt, bp)
get_psi_scale_properties()	PSI coordinate grids (shared by MAS, POT3D, and related codes)	3 1-D coordinate scale arrays (r, t, p)

Coordinate scales

Every PSI HDF file stores three 1-D coordinate arrays alongside its data. These arrays define the spherical grid on which model output is sampled and are standard across MAS, POT3D, and most other PSI codes:

Key	Symbol	Physical quantity	Units	Range
'r'	\(r\)	Radial distance	solar radii (PSI_rsun)	\(r \geq 1\,R_\odot\)
't'	\(\theta\)	Co-latitude (pole = 0)	radians (PSI_angle)	\([0,\,\pi]\)
'p'	\(\varphi\)	Longitude	radians (PSI_angle)	\([0,\,2\pi]\)

PSI HDF files are written in Fortran order (column-major), so the first Fortran dimension varies fastest in memory. When read into NumPy (row-major), the axis order is reversed: a 3-D array has shape \((N_\varphi, N_\theta, N_r)\) and the three scale arrays map to axes as follows:

Key	Fortran dimension	NumPy axis	arr.shape index
'r'	1st (fastest-varying)	last	-1
't'	2nd	middle	-2
'p'	3rd (slowest-varying)	first	0

MAS Model Quantities

MAS outputs 19 3-D fields in spherical coordinates. Code-unit values are converted to physical (CGS/SI) unit by multiplying by the normalization constants defined in psi_io._units. Approximate physical scales are given in parentheses.

Key	Symbol	Physical quantity	Physical unit (CGS)	Type	Mesh code
vr	\(v_r\)	Radial velocity	km s⁻¹ (FN_V ≈ 481 km s⁻¹)	vector	0b011
vt	\(v_\theta\)	Co-latitude velocity	km s⁻¹	vector	0b101
vp	\(v_\varphi\)	Longitude velocity	km s⁻¹	vector	0b110
br	\(B_r\)	Radial magnetic field	G (FN_B ≈ 2.2 G)	vector	0b100
bt	\(B_\theta\)	Co-latitude magnetic field	G	vector	0b010
bp	\(B_\varphi\)	Longitude magnetic field	G	vector	0b001
jr	\(J_r\)	Radial current density	A m⁻² (FN_J)	vector	0b011
jt	\(J_\theta\)	Co-latitude current density	A m⁻²	vector	0b101
jp	\(J_\varphi\)	Longitude current density	A m⁻²	vector	0b110
t	\(T\)	Single-fluid temperature	MK (FN_T ≈ 28 MK)	scalar	0b111
te	\(T_e\)	Electron temperature	MK	scalar	0b111
tp	\(T_p\)	Proton temperature	MK	scalar	0b111
rho	\(\rho\)	Plasma density	cm⁻³ (FN_N = 10⁸ cm⁻³)	scalar	0b111
p	\(p\)	Plasma pressure	erg cm⁻³ (FN_P)	scalar	0b111
ep	\(e^+\)	Forward Alfvén wave energy density	erg cm⁻³	scalar	0b111
em	\(e^-\)	Backward Alfvén wave energy density	erg cm⁻³	scalar	0b111
zp	\(z^+\)	Outward Elsässer amplitude	km s⁻¹	scalar	0b111
zm	\(z^-\)	Inward Elsässer amplitude	km s⁻¹	scalar	0b111
heat	\(Q\)	Volumetric heating rate	erg cm⁻³ s⁻¹ (FN_HEAT)	scalar	0b111

POT3D Model Quantities

POT3D solves for the potential magnetic field \(\mathbf{B} = -\nabla\Psi\) driven by a photospheric radial-field boundary condition. It outputs three spherical magnetic field components:

Key	Symbol	Physical quantity	Physical unit	Mesh code
br	\(B_r\)	Radial magnetic field	input magnetogram unit (typically G)	0b011
bt	\(B_\theta\)	Co-latitude magnetic field	input magnetogram unit	0b101
bp	\(B_\varphi\)	Longitude magnetic field	input magnetogram unit	0b110

Note

POT3D mesh codes are the bitwise complement of the corresponding MAS magnetic field codes: POT3D_mesh = 0b111 ^ MAS_mesh. Where MAS places each component on the face through which it is the outward normal (face-centred), POT3D places the same component on the opposite pair of edges (edge-centred).

Warning

POT3D does not apply a normalization: values are in whatever physical unit the input boundary magnetogram was provided in (typically Gauss, but run-dependent). The code unit POT3D_b has a scale factor of 1 (dimensionless-unscaled). Always supply the correct unit explicitly when converting; read(unit='physical') without a unit override will return dimensionless values.

Staggered Grid Overview

MAS and POT3D solve their equations on a three-dimensional staggered (Yee-type) spherical grid \((r, \theta, \varphi)\). Different physical quantities are located at different positions within each grid cell so that discrete differential operators (curl, divergence) are exactly satisfied.

With the convention used in this module, numpy arrays loaded from PSI HDF files have shape \((N_{\phi}, N_{\theta}, N_r)\) — longitude index varies slowest, radial index fastest. Mesh codes therefore assign bits as follows:

Bit position	Numpy axis	Coordinate
Most-significant bit (MSB)	axis = -1 (last)	\(r\) (radial)
Middle bit	axis = -2	\(\theta\) (co-latitude)
Least-significant bit (LSB)	axis = -3 (first)	\(\varphi\) (longitude)

A bit value of 1 means the quantity is on the half mesh along that axis (displaced half a grid spacing), while 0 means it is on the main mesh.

The resulting grid positions for MAS vector components are:

Quantity type	Mesh code	\(r\)	\(\theta\)	\(\varphi\)	Grid position
br	0b100	half	main	main	\(r\)-face center
bt	0b010	main	half	main	\(\theta\)-face center
bp	0b001	main	main	half	\(\varphi\)-face center
vr, jr	0b011	main	half	half	\(r\)-edge center
vt, jt	0b101	half	main	half	\(\theta\)-edge center
vp, jp	0b110	half	half	main	\(\varphi\)-edge center
Scalars (t, rho, p, …)	0b111	half	half	half	Cell corner

This Yee-type arrangement ensures that \(\nabla \cdot \mathbf{B} = 0\) is satisfied exactly at the discrete level: each \(B\) component lives on the face through which it is the outward normal. The current density components \(\mathbf{J} = \nabla \times \mathbf{B}\) then live on the corresponding cell edges. Scalar thermodynamic quantities (density, temperature, pressure) occupy the cell corners, which are equivalent to cell centers on the dual grid.

See Also

psi_io._mesh :

Defines Mesh and the mesh normalization helpers.

psi_io._units :

Provides the custom astropy unit referenced by each Props.

psi_io.mhd_io :

Uses these mappings to auto-configure lazy HDF readers.

Classes

Props(name, desc, unit, ndim, scalar[, _mesh])

Immutable property bundle for a single PSI model quantity.

Functions

extract_quantity_from_filepath(ifile[, default])	Extract the MAS/POT3D quantity name from a filename stem.
extract_sequence_from_filepath(ifile[, default])	Extract the sequence number from a filename stem.
get_mas_quantity_properties(variable)	Return the Props descriptor for a MAS quantity.
get_model_prop_caller(model)	Return the Props getter function for the given model type.
get_pot3d_quantity_properties(variable)	Return the Props descriptor for a POT3D quantity.
get_psi_scale_properties(variable)	Return the Props descriptor for a PSI coordinate scale.
parse_psi_filename_schema(ifile)	Parse a PSI HDF filename that follows the strict <quantity><sequence> schema.

Attributes

MasQuantities	Literal type alias for the 19 named MAS output quantities.
ModelType	Literal type alias for the two recognized PSI model types.
Pot3dQuantities	Literal type alias for the 3 POT3D magnetic field output quantities.
PsiScales	Literal type alias for the three PSI coordinate scale identifiers.