PsiData

Contents

PsiData#

PsiData(ifile, /, model='mas', **kwargs)[source]#

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

Inspects the file extension and model argument, selects the correct concrete reader (HDF5 or HDF4 backend), and returns it. No data are read from disk at construction time — metadata is resolved from the filename and HDF file attributes, and data transfer happens only inside read() or vslice(). Full-array reads are cached automatically; partial reads are not.

The returned reader exposes the following attributes:

  • quantity — canonical lower-case quantity identifier (e.g. 'br').

  • sequence — integer time-step sequence number.

  • unit — Unit for code → physical conversion; normalization constants are defined in psi_io._units.

  • mesh — per-axis Yee-grid stagger as a tuple of Mesh members; see psi_io._mesh.

  • props — full Props descriptor (name, description, unit, mesh code); see psi_io._models.

  • description — human-readable quantity description.

  • scales — Scales(r, t, p) named tuple of coordinate scale readers, each supporting the same read() interface as the main reader.

  • shape, ndim, size, nbytes, dtype, attrs — array metadata; shape is in HDF storage order (Nφ, Nθ, Nr).

  • is_cached — True after a full-array read has been cached.

Use read() to load a slice by index and vslice() to slice by physical coordinate value with linear interpolation. Both return data as Quantity objects in physical (r, θ, φ) order. The object also supports the context-manager protocol.

Warning

POT3D unit convention

POT3D applies no normalization to its output. The stored values are in whatever physical unit the input photospheric magnetogram used — most commonly Gauss, but this is not encoded in the file. The default unit for POT3D is dimensionless_unscaled (scale factor 1), so read(unit='physical') will not perform a meaningful conversion unless the correct unit is supplied at construction:

reader = PsiData('br001.h5', model='pot3d', unit='Gauss')
data, r, t, p = reader.read()
Parameters:
ifilePathLike

Path to the HDF4 (.hdf) or HDF5 (.h5) file.

model{‘mas’, ‘pot3d’}, optional

PSI model type. Defaults to 'mas'.

dataset_idstr, optional

Dataset name within the HDF file. Defaults to the PSI standard identifier for the given format.

quantitystr, optional

Override the quantity name inferred from the filename or file attributes.

sequenceint, optional

Override the time-step sequence number.

unitstr or u.Unit, optional

Override the code-to-physical unit from the quantity’s Props entry. Accepts any string parseable by Unit or a Unit instance.

meshMeshCodeType, optional

Override the mesh stagger from the quantity’s Props entry.

Returns:
outH5Data or H4Data

Open reader implementing the full _HdfInterface API. Concrete type depends on the file extension.

Raises:
ValueError

If the file extension / model combination is unsupported or required metadata cannot be resolved.

FileNotFoundError

If ifile does not exist.

See also

astropy.units.Unit

Unit constructor — accepts strings, compound expressions, and Unit instances.

astropy.units.Quantity.to

Unit conversion used internally when a unit string is supplied to read().

Examples

Read a MAS radial field — full array with coordinate scales, then convert:

>>> from psi_io.mhd_io import PsiData
>>> reader = PsiData('br001001.h5')
>>> data, r, t, p = reader.read()                      # code units (MAS_b)
>>> data, r, t, p = reader.read(unit='Gauss')          # convert to Gauss

Use as a context manager:

>>> with PsiData('vr001001.h5') as reader:
...     data, r, t, p = reader.read(unit='km/s')

Inspect metadata without loading data:

>>> reader = PsiData('rho001001.h5')
>>> reader.quantity    # 'rho'
>>> reader.unit        # MAS_n
>>> reader.mesh        # (Mesh.HALF, Mesh.HALF, Mesh.HALF)
>>> reader.is_cached   # False
Contents