pycsamt.z.base#

Classes

`BaseEM`
`EMBase`([name, meta, verbose])	Minimal, mixin-style base class for EM containers.

class pycsamt.z.base.EMBase(name=None, meta=<factory>, verbose=0)[source]#

Bases: object

Minimal, mixin-style base class for EM containers.

EMBase provides a small set of uniform behaviors used by higher-level containers such as Z, ResPhase, and Tipper. It centralizes frequency handling, safe slicing along the frequency axis, shape checks, light verbosity control, and compact summaries.

The class is deliberately conservative: it makes as few assumptions as possible about attribute names and shapes, while still enabling useful defaults for common containers.

Parameters:

name (str, optional) – Human-friendly display name. Used by summary() and representations.
meta (dict, optional) – Arbitrary metadata attached to the instance. Not used by core logic.
verbose (int, default 0) – Controls the object logger level. 0 → WARNING, 1 → INFO, >=2 → DEBUG. See set_verbose().

Variables:

name (str or None) – Display name.
meta (dict) – User metadata stored verbatim.
verbose (int) – Current verbosity level. See set_verbose().
log (logging.Logger) – Per-class logger created via get_logger().
freq (ndarray or None) – One-dimensional frequency vector in Hz. The property enforces finite, strictly positive values. Stored internally as _freq when set.
n_freq (int) – Inferred number of frequencies. If _freq exists, its length is returned. Otherwise, the first dimension of any known array attribute (e.g., _z, _tipper, _resistivity, _phase) is used. Returns 0 if unknown.

Notes

Design. The class aims to be a small, composable layer. It avoids imposing a strict attribute schema so that existing containers can adopt it without refactors. Uniform frequency handling is offered through the :pyattr:`freq` property.

Slicing. subset() returns a deep-copied view where every attribute whose first dimension equals :pyattr:`n_freq` is sliced along axis-0. This covers typical arrays like _z, _tipper, _phase, and their error fields. Subclasses can override _sliceable_predicate() for fine-grained control.

Validation. validate_shapes() checks that all frequency-aligned arrays share the same leading dimension (:pyattr:`n_freq`). It raises ZError on mismatches.

Verbosity. set_verbose() updates the instance logger level only. It does not alter global logging configuration.

Back-compat. BaseEM remains available as an alias to EMBase for compatibility with older imports.

Examples

Minimal subclass that stores a frequency vector and a tensor:

>>> import numpy as np
>>> from pycsamt.z.base import BaseEM
>>> class Dummy(BaseEM):
...     def __init__(self, f, z, *, name=None, verbose=0):
...         super().__init__(name=name, verbose=verbose)
...         self.freq = f
...         self._z = np.asarray(z, complex)
...
>>> f = np.array([10.0, 1.0])
>>> z = np.zeros((2, 2, 2), complex)
>>> d = Dummy(f, z, name="site-A", verbose=1)
>>> d.n_freq
2
>>> print(d.summary())
EMBase: site-A
n_freq: 2
f[Hz]: min=1, max=10
errors: no
arrays:
  - _z: (2, 2, 2)@complex128

Frequency-axis subsetting with a boolean mask:

>>> m = np.array([True, False])
>>> d2 = d.subset(m)
>>> d2.n_freq
1

Validating shapes (raises on mismatch):

>>> d._phase = np.zeros((1, 2, 2))
>>> from pycsamt.exceptions import ZError
>>> _ = d.validate_shapes()
Traceback (most recent call last):
    ...
ZError: freq-aligned arrays mismatch n_freq. ...