pycsamt.core.base#

Foundational objects and transfer-function containers for pyCSAMT.

Functions

ensure_station(name, station_id, *[, policy])

Return a valid station name using policy rules.

pick_adapter_key(obj, *[, hint])

Infer an adapter key ('avg', 'j', 'edi') from an object.

to_edi(source, *[, key])

Dispatch source to a registered adapter and return EDI.

Classes

CoreObject()

Minimal base class for PyCSAMT objects and mixins.

MTBase()

Common electromagnetic and MT utilities.

SupportsFromBundle(*args, **kwargs)

Protocol for classes that can be built from a TFBundle.

SupportsToBundle(*args, **kwargs)

Protocol for objects that can export a TFBundle.

TFBundle([freq, z, z_err, tipper, ...])

Lightweight, neutral payload for transfer functions.
class pycsamt.core.base.TFBundle(freq=None, z=None, z_err=None, tipper=None, tipper_err=None, rho=None, phase=None, station=None, station_id=None, lat=None, lon=None, elev=None, azimuth=None, attrs=<factory>)[source]#

Bases: CoreObject

Lightweight, neutral payload for transfer functions.

The bundle holds frequency-indexed arrays and optional site metadata. It is intentionally permissive about array types (e.g., lists or NumPy arrays) so that backends can populate and consume it without hard dependencies.

Parameters:

  • freq (array_like or None) – Frequency vector, length n.

  • z (array_like or None) – Impedance tensor, shape (n, 2, 2) (complex).

  • z_err (array_like or None) – Errors for z, shape (n, 2, 2) (float).

  • tipper (array_like or None) – Magnetic tipper. Common shapes are (n, 2) or (n, 1, 2); callers may normalize as needed.

  • tipper_err (array_like or None) – Errors for the tipper, shape like tipper.

  • rho (array_like or None) – Apparent resistivity, length n (float).

  • phase (array_like or None) – Phase, length n. Units are backend-specific; the Zonge path often stores milliradians.

  • station (str or None) – Preferred station/site name.

  • station_id (str, int or None) – Identifier used to synthesize a name when missing.

  • lat (float or None) – Optional geographic location and elevation.

  • lon (float or None) – Optional geographic location and elevation.

  • elev (float or None) – Optional geographic location and elevation.

  • azimuth (float or None) – Sensor azimuth or site orientation (degrees).

  • attrs (dict) – Free-form attributes that accompany the data.

Notes

Only one of z or (rho, phase) is required for most workflows. Transformers may fill the missing part using package settings (see pycsamt.core.config).

Examples

>>> from pycsamt.core.base import TFBundle
>>> TFBundle(freq=[1.0], z=[[ [0+1j, 0], [0, 0+1j] ]],
...          station=\"S001\")
TFBundle(...)
freq: Any | None = None#
z: Any | None = None#
z_err: Any | None = None#
tipper: Any | None = None#
tipper_err: Any | None = None#
rho: Any | None = None#
phase: Any | None = None#
station: str | None = None#
station_id: str | int | None = None#
lat: float | None = None#
lon: float | None = None#
elev: float | None = None#
azimuth: float | None = None#
attrs: dict[str, Any]#
is_empty()[source]#

Return True if there is no usable TF content.

A bundle is considered empty when neither z nor the pair (rho, phase) is present.

Returns:

True if empty, False otherwise.

Return type:

bool

Examples

>>> TFBundle().is_empty()
True
>>> TFBundle(rho=[100], phase=[45]).is_empty()
False
class pycsamt.core.base.SupportsToBundle(*args, **kwargs)[source]#

Bases: Protocol

Protocol for objects that can export a TFBundle.

Any class implementing:

to_bundle(self) -> TFBundle

is considered compatible. This keeps interop light while avoiding a hard dependency on specific backends.

to_bundle()[source]#
Return type:

TFBundle

class pycsamt.core.base.SupportsFromBundle(*args, **kwargs)[source]#

Bases: Protocol

Protocol for classes that can be built from a TFBundle.

Any class implementing the classmethod:

from_bundle(cls, bundle: TFBundle) -> Any

is considered compatible. This is commonly used by test doubles or thin wrappers in frontends.

classmethod from_bundle(bundle)[source]#
Parameters:

bundle (TFBundle)

pycsamt.core.base.ensure_station(name, station_id, *, policy=None)[source]#

Return a valid station name using policy rules.

Validation is performed by the active StationNamePolicy. If the given name is invalid or missing, a synthetic one is derived from station_id.

Parameters:

  • name (str or None) – Preferred station/site name.

  • station_id (str, int or None) – Identifier used to synthesize a fallback name.

  • policy (StationNamePolicy, optional) – Custom policy. Defaults to the global policy from get_config().

Returns:

Validated or synthesized station name.

Return type:

str

See also

pycsamt.core.config.StationNamePolicy

Normalization, synthesis and limits.

Examples

>>> ensure_station(None, 7)
'S007'
pycsamt.core.base.pick_adapter_key(obj, *, hint=None)[source]#

Infer an adapter key ('avg', 'j', 'edi') from an object.

Heuristics look at the object’s module and class name. If a hint is provided, it is returned verbatim (lower-cased).

Parameters:

  • obj (Any) – Source object whose kind should be inferred.

  • hint (str, optional) – Explicit override for the key.

Returns:

Inferred key or None if it cannot be decided.

Return type:

str or None

Notes

This function does not validate that an adapter exists for the returned key. Use to_edi() to dispatch safely.

Examples

>>> class X: pass
>>> X.__module__ = 'pycsamt.zonge.avg'
>>> pick_adapter_key(X())  # zonge path
'avg'
pycsamt.core.base.to_edi(source, *, key=None, **kwargs)[source]#

Dispatch source to a registered adapter and return EDI.

This function consults the adapter registry managed by pycsamt.core.config. It attempts to infer the adapter key when not provided and calls the associated factory.

Parameters:

  • source (Any) – The object to convert (AVG, Jones, etc.).

  • key (str, optional) – Adapter key (e.g., 'avg', 'j', 'edi'). If omitted, pick_adapter_key() is used.

  • **kwargs (Any) – Extra keyword arguments forwarded to the adapter.

Returns:

An EDI object or an EDI collection, depending on the adapter.

Return type:

Any

Raises:

RuntimeError – If the key cannot be inferred or no adapter is registered for it.

See also

pycsamt.core.config.register_adapter

Register new adapters at runtime.

pick_adapter_key

Lightweight key inference from object metadata.

Examples

Register a trivial adapter and convert an object:

>>> from pycsamt.core.config import register_adapter
>>> class Dummy: pass
>>> Dummy.__module__ = 'pycsamt.zonge.avg'
>>> register_adapter('avg', lambda src, **k: {'edi': True})
>>> to_edi(Dummy())
{'edi': True}