Skip to content

openPMD backend§

Available file types§

At the moment, ozzy can read openPMD files in HDF5 format, whether with group-, file- or variable-based iteration encoding.

Default metadata§

The metadata from openPMD files is mostly converted into xarray attrs, while unit-related metadata is also used to rescale the actual data.

The backend reads metadata from two places:

  • openpmd_viewer.OpenPMDTimeSeries, especially fields_metadata and the metadata returned by get_field(...).
  • Raw HDF5 attributes via h5py

For field data, unitSI is used to rescale field values, timeOffset to shift t, and gridUnitSI / gridUnitSIPerDimension to rescale spatial coordinates. Then each data variable, or DataArray, gets a TeX label, compact display units derived from unitDimension, and selected attributes like geometry, type, geometryParameters, fieldSmoothing, gridGlobalOffset, plus theta_mode for geometries with azimuthal mode decomposition.

For particle data, metadata is collected from the attributes both at particle and species level. These attributes are used for weighting correction, unitSI conversion, labels and units. The dataset for each species will contain two additional attributes: species_name and unique_pids. Particle id, when present, is renamed to pid.

Entry-point read function§

read §

read(
    files,
    records=None,
    separate_theta_modes=False,
    **kwargs
)

Read selected records from openPMD files into a Dataset.

Parameters:

Name Type Description Default

files §

 list[str]

Paths to the openPMD files to read.

 required

records §

 str, list[str], or None

Records to read from the files. Accepted values are:

  • 'fields', 'grid', 'mesh', or 'meshes' to read all grid-based variables
  • the name of one grid-based variable
  • a list of grid-based variable names
  • 'particles' or 'part' to read particle data when exactly one particle species is present
  • the name of one particle species

If None, an error is raised listing the available records.

 None

separate_theta_modes §

 bool

Whether to keep each azimuthal mode separate for each data variable when reading grid-based data in geometries with azimuthal mode decomposition. If True, returns each data variable reconstructed from all azimuthal modes.

 False

Returns:

Type Description
Dataset

Dataset containing the requested openPMD records. If no files are provided, or the files cannot be opened, an empty dataset is returned.

Raises:

Type Description
NotImplementedError

If the files appear to be in ADIOS2 format, identified by the .bp suffix.
ValueError

If records is None, if the requested record is unavailable, if multiple particle species are requested, or if the records list mixes unsupported or ambiguous record names.

Examples:

Read all grid-based variables 
ds = ozzy.open("openpmd", files, records="fields")

# ds is an xarray.Dataset containing all available grid-based variables.
Read one particle species 
ds_electrons = ozzy.open("openpmd", files, records="electrons")

# ds_electrons is an xarray.Dataset containing particle data for the
# `electrons` species, if that species exists in the files.