PsiData

Contents

PsiData#

PsiData(ifile, /, *args, **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 object is an _HdfData instance; see _HdfData and the inherited _HdfArray interface for the full set of metadata properties (name, desc, unit, mesh, scales, shape, dtype …) and reader methods. In brief, use read() to load a slice by index and vslice() to slice by physical coordinate value with linear interpolation; both return Quantity data in physical (r, θ, φ) order, and the object supports the context-manager protocol.

By default the reader is lazy (cache='lazy'): array data is transferred from disk only on access, and a full-array read is then cached on the reader. Pass cache='eager' to load the data immediately at construction, or cache=None to disable caching entirely.

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()

Metadata resolution

Every metadata field is drawn from up to three sources, in decreasing priority:

  1. Keyword arguments passed to this function, named after the ModelProps fields (name, desc, unit, scalar, mesh, order, sequence, scales).

  2. The HDF dataset attribute dictionary (reader.attrs), for any of those same field names stored on the file.

  3. The model-mapping defaults in psi_io.models, consulted only when model names a recognized PSI model.

A value supplied at a higher level overrides the levels beneath it: an explicit keyword argument always wins over a file attribute, which in turn overrides the model default. This is how the keyword arguments below can correct or complete metadata that is missing, wrong, or absent from the file.

When model is 'mas' or 'pot3d', the quantity name and sequence additionally fall back to the values parsed from the filename stem (e.g. br001001 → name='br', sequence=1001), and the resolved name selects the ModelProps entry that provides the default unit, mesh, scalar, order, scales, and desc.

When model is the default 'custom', no defaults are inferred — every field must be given as a keyword argument or be present in the file attribute dictionary. name, mesh, scalar, order, and scales are required; unit (defaults to dimensionless), sequence (defaults to 0), and desc (defaults to '') are optional. If a required field cannot be resolved, ValueError (“Missing or incompatible metadata”) is raised.

Parameters:
ifilePathLike

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

modelModelType, optional

PSI model type. Defaults to 'custom'. When 'mas' or 'pot3d' is given, the reader resolves the quantity name, unit, mesh stagger, and other metadata from the corresponding mapping in psi_io.models. With the default 'custom', no metadata is inferred and the required fields (name, mesh, scalar, order, scales) must be supplied as keyword arguments.

dataset_idstr, optional

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

namestr, optional

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

sequenceint, optional

Override the time-step sequence number.

unitUnitLike, optional

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

meshMeshCodeType, optional

Override the mesh stagger from the quantity’s ModelProps entry. Required when model is 'custom' and no mesh attribute is stored on the file.

scalarbool, optional

Whether the quantity is a scalar (rather than a component of a vector) field. Required when model is 'custom'.

orderArrayOrdering, optional

Memory layout of the stored array — 'F' (Fortran / column-major, the PSI default) or 'C' (row-major). Determines whether shape and the slicing axes are reversed relative to the on-disk layout. Required when model is 'custom'.

scalesSequence, optional

Names of the coordinate axes, in physical order (e.g. ('r', 't', 'p')). The argument does three things:

  • Names the axes — the strings become the fields of the reader.scales named tuple and the name of each coordinate scale reader.

  • Orders them — the names are zipped positionally with the file’s stored dimension arrays, so the i-th name labels the i-th dimension; the ordering must therefore match the physical axis order.

  • Fixes the dimensionality — len(scales) sets the expected dataset rank; validate_metadata() emits a MetaDataWarning if it disagrees with ndim (or with the length of mesh / shape), or if any named axis does not match the size of its corresponding data dimension.

Required when model is 'custom'.

descstr, optional

Override the human-readable description. Optional; defaults to ''.

cacheCacheType, optional

Cache mode. 'lazy' (default) caches the array on the first full read, 'eager' loads it immediately, and None disables caching.

Returns:
outH5Data | H4Data

Open reader implementing the full _HdfData 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().

_HdfData

Base data reader interface.

_HdfArray

Base data array interface.

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.name          # 'rho'
>>> reader.unit          # MAS_n
>>> reader.mesh          # Mesh(HALF, HALF, HALF)
>>> reader.data_cached   # False
Contents