gwexpy.interop.emg3d_

Interoperate with emg3d electromagnetic modelling fields.

---

Interoperability with emg3d electromagnetic modelling fields.

emg3d.fields.Field stores electric or magnetic field components on a staggered grid (Yee grid). Each Cartesian component has a slightly different shape because it lives on edges (E-field) or faces (H-field).

GWexpy’s ScalarField requires all spatial components to share the same shape, so this module interpolates each component to the cell centres of the TensorMesh before packing them into a VectorField. The original staggered layout is recorded in the ScalarField metadata.

Only the emg3d Python package is required; no external C dependencies beyond those already installed with emg3d.

References

https://emg3d.emsig.xyz/

Functions

from_emg3d_field(cls, field, *[, component, ...])	Convert an emg3d.fields.Field to a GWexpy VectorField.
from_emg3d_h5(cls, filepath, *[, name, ...])	Load an emg3d field saved via emg3d.save() and convert it.
to_emg3d_field(vf, *[, frequency, electric])	Convert a GWexpy VectorField back to an emg3d.fields.Field.

gwexpy.interop.emg3d_.from_emg3d_field(cls: type, field: Any, *, component: str | None = None, interpolate_to_cell_center: bool = True) → ScalarField | VectorField

Convert an emg3d.fields.Field to a GWexpy VectorField.

The emg3d Field stores each Cartesian component (fx, fy, fz) on a staggered (Yee) grid where component shapes may differ. When interpolate_to_cell_center is True (default), each component is averaged to the common cell-centre grid so that all three ScalarField objects share the same spatial shape.

Parameters:

• cls (type) – VectorField (default) or ScalarField class.

• field (emg3d.fields.Field) – emg3d field object. Must have attributes fx, fy, fz, grid, and electric (bool).

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

• interpolate_to_cell_center (bool, default True) – Interpolate staggered-grid components to cell centres. Setting this to False raises ValueError if the shapes differ.

Returns:

• ScalarField – When component is specified or cls is ScalarField.

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

Raises:

ValueError – If interpolate_to_cell_center=False and component shapes differ.

Examples

>>> from gwexpy.fields import VectorField
>>> vf = VectorField.from_emg3d_field(field)

>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField.from_emg3d_field(field, component="z")

gwexpy.interop.emg3d_.from_emg3d_h5(cls: type, filepath: str | Path, *, name: str = 'field', component: str | None = None, interpolate_to_cell_center: bool = True) → ScalarField | VectorField

Load an emg3d field saved via emg3d.save() and convert it.

Parameters:

• cls (type) – VectorField or ScalarField.

• filepath (str or Path) – Path to the HDF5 / npz / json file written by emg3d.save().

• name (str, default "field") – Key under which the field was saved (kwarg name passed to emg3d.save(**{name: field})).

• component ({"x", "y", "z"}, optional) – Extract a single component.

• interpolate_to_cell_center (bool, default True) – See from_emg3d_field().

Return type:

ScalarField or VectorField

gwexpy.interop.emg3d_.to_emg3d_field(vf: VectorField | ScalarField, *, frequency: float | None = None, electric: bool = True) → Any

Convert a GWexpy VectorField back to an emg3d.fields.Field.

Parameters:

• vf (VectorField or ScalarField) – Source field. For VectorField, components "x", "y", "z" are expected. For ScalarField the single component is broadcast as the x-component.

• frequency (float, optional) – Field frequency in Hz. Overrides vf’s axis0 value when given.

• electric (bool, default True) – Whether the field is an E-field (True) or H-field (False).

Returns:

Reconstructed field object.

Return type:

emg3d.fields.Field

Raises:

• ImportError – If emg3d is not installed.

• ValueError – If the VectorField does not contain exactly 3 components.