mhd_io#

Lazy, unit-aware HDF readers for PSI MAS and POT3D magnetohydrodynamic output.

This module reads three-dimensional field variables from Predictive Science Inc.’s MAS and POT3D solvers through a single interface that spans both HDF4 (.hdf) and HDF5 (.h5) files. Readers are lazy: metadata is resolved at construction from the filename and HDF attributes, while array data is transferred from disk only on access, and full-dataset reads are cached on the reader.

Entry point

PsiData() is the sole public symbol and the intended way to use this module. It is a factory that inspects the file extension and model argument and returns the matching concrete reader; the underlying _Hdf* classes should never be instantiated directly.

from psi_io.mhd_io import PsiData

PsiData('br001001.hdf', model='mas')                                    # MAS HDF4
PsiData('br001.h5', model='pot3d', unit='Gauss')                        # POT3D HDF5 (unit declared)
PsiData('emission.h5', mesh='MMM', scales='X,Y,Z', order='C', ...)      # Custom reader

Reader interface

The object returned by PsiData() is an _HdfData instance. Refer to the following classes for the complete reference:

_HdfData — the main field reader. _HdfData.read() slices by index and _HdfData.vslice() slices by physical coordinate value with linear interpolation. Both return Quantity data in physical (r, θ, φ) order, with optional unit conversion and mesh remapping.
_HdfArray — the array interface inherited by every reader, defining the metadata properties (name, desc, unit, mesh, shape, dtype, data_cached, interp_cached …) and the base _HdfArray.read().
reader.scales — a named tuple of per-axis coordinate readers (r, t, p) that expose the same _HdfArray interface as the main reader.

Note

PSI HDF files are stored in Fortran column-major order, so reader.shape and the on-disk layout are (Nφ, Nθ, Nr) with the radial axis last. All slicing arguments and returned coordinate scales are nevertheless given in physical (r, θ, φ) order.

Supported quantities

MAS provides 19 field variables — magnetic field, velocity, and current-density components, temperatures, density, pressure, Alfvén/Elsässer wave energy, and coronal heating — while POT3D provides the three magnetic-field components. Each quantity’s canonical unit and mesh stagger are defined in psi_io.models, and the corresponding normalization constants in psi_io.units. POT3D output is unnormalized; see the PsiData() warning on declaring its unit.

Classes

`_HdfArray`(*args[, cache])	Abstract base class for a single HDF dataset with optional caching.
`_HdfData`(ifile[, dataset_id])	Abstract base class for a PSI MAS or POT3D HDF data reader.

Functions

PsiData(ifile, /, *args, **kwargs)

Open a PSI MAS or POT3D HDF file and return the appropriate data reader.

Attributes

CacheType

Type alias for the three valid cache modes.

Exceptions

`CacheWarning`	Warning raised when a cache operation is ignored or conflicts with the cache mode.
`MetaDataWarning`	Warning raised when HDF metadata is missing, ambiguous, or inconsistent.