gwexpy.interop.openems_

Interoperate with openEMS field dump HDF5 files.

Interoperability with openEMS field dump HDF5 files.

openEMS writes electromagnetic field data via CSPropDumpBox. The HDF5 layout is:

/Mesh/
    x   # 1-D node coordinates along x
    y
    z
/FieldData/
    TD/          # time-domain dumps
        <step_0> # 4-D array (Nx, Ny, Nz, 3)  — 3 = x/y/z components
        <step_1>
        ...
    FD/          # frequency-domain dumps
        f0_real  # 4-D (Nx, Ny, Nz, 3)
        f0_imag
        f1_real
        ...

The DumpType value (set in the CSXCAD AddDump call) controls which physical quantity is stored and in which domain. Only h5py is required; the openEMS Python bindings are not needed.

HDF5 dataset attributes

If time-domain datasets carry a "Time" attribute (float, seconds), the returned axis0 uses those physical time values. If frequency-domain datasets carry a "frequency" attribute (float, Hz), axis0 uses those physical frequency values. Both fall back to integer indices when the attribute is absent.

References

https://openems.de/index.php/HDF5_Field_Dumps.html

Functions

from_openems_hdf5(cls, filepath, *[, ...])

Read an openEMS field dump HDF5 file into a ScalarField or VectorField.
gwexpy.interop.openems_.from_openems_hdf5(cls: type, filepath: str | Path, *, dump_type: int = 0, timestep: int | None = None, frequency_index: int | None = None, component: Literal['x', 'y', 'z'] | None = None, unit: Any | None = None) → ScalarField | VectorField[source]

Read an openEMS field dump HDF5 file into a ScalarField or VectorField.

openEMS dumps field data as HDF5 files containing mesh coordinates under /Mesh/x, /Mesh/y, /Mesh/z and field values under /FieldData/TD (time domain) or /FieldData/FD (frequency domain). Each time step or frequency bin stores a 4-D array of shape (Nx, Ny, Nz, 3) where the last axis holds the x, y, z components.

Parameters:

  • cls (type) – ScalarField or VectorField class.

  • filepath (str or Path) – Path to the HDF5 dump file.

  • dump_type (int, default 0) –

    openEMS DumpType value used when the dump was configured. Determines the physical quantity and domain:

    • 0 → E-field, time domain

    • 1 → H-field, time domain

    • 10 → E-field, frequency domain

    • 11 → H-field, frequency domain

    • 20-22 → SAR (scalar, frequency domain)

  • timestep (int, optional) – For time-domain dumps: which step index to extract. None loads all steps along axis 0.

  • frequency_index (int, optional) – For frequency-domain dumps: which frequency index to extract. None loads all frequencies along axis 0.

  • component ({"x", "y", "z"}, optional) – Return a single vector component as ScalarField. None returns all three components as VectorField.

  • unit (str or astropy.units.Unit, optional) – Override the physical unit. Defaults to the unit implied by dump_type (see DUMP_TYPE_MAP).

Returns:

  • ScalarField – When component is given, dump type is SAR, or cls is ScalarField.

  • VectorField – When component is None and cls is VectorField.

Raises:

  • ValueError – If the required field group is absent, or if a requested time step / frequency index does not exist.

  • ImportError – If h5py is not installed.

Examples

Read all components of a time-domain E-field dump:

>>> from gwexpy.fields import VectorField
>>> vf = VectorField.from_openems_hdf5("e_dump.h5", dump_type=0)

Read only the z-component:

>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField.from_openems_hdf5("e_dump.h5", component="z")