pycsamt.inversion.objective#

Objective-function helpers for inversion backends.

Functions

`component_errors`(values, cfg, *, component)	Return errors for one data component using config settings.
`component_mask`(values, cfg, *, component)	Return a boolean mask for one component using config mask settings.
`error_model_from_config`(cfg)	Build an `ErrorModel` from inversion config options.
`relative_errors`(values[, floor])	Return absolute errors from a relative floor.
`weighted_rms`(observed, predicted[, errors])	Return normalized weighted RMS misfit.

Classes

ErrorModel([rho_relative, rho_absolute, ...])

Component-aware data-error settings for inversion backends.

class pycsamt.inversion.objective.ErrorModel(rho_relative=0.05, rho_absolute=1e-12, phase_absolute=3.0, phase_relative=0.0, tdem_relative=0.05, tdem_absolute=1e-30, impedance_relative=0.05, impedance_absolute=1e-12, min_error=1e-12, masks=<factory>)[source]#

Bases: object

Component-aware data-error settings for inversion backends.

ErrorModel centralizes the floors used when packing objective functions for the built-in, SimPEG, pyGIMLi, Occam2D, and ModEM adapters. It supports component-specific relative/absolute floors and boolean masks used to exclude stations, frequencies, time gates, or individual samples.

Parameters:

rho_relative (float, default 0.05) – Relative apparent-resistivity error floor.
rho_absolute (float, default 1e-12) – Absolute apparent-resistivity error floor in ohm metres.
phase_absolute (float, default 3.0) – Absolute phase error floor in degrees.
phase_relative (float, default 0.0) – Optional relative phase error floor.
tdem_relative (float, default 0.05) – Relative TDEM decay-value error floor.
tdem_absolute (float, default 1e-30) – Absolute TDEM decay-value error floor.
impedance_relative (float, default 0.05) – Relative impedance-component error floor.
impedance_absolute (float, default 1e-12) – Absolute impedance-component error floor.
min_error (float, default 1e-12) – Global lower bound applied to all returned errors.
masks (dict, optional) – Component or station masks. Supported keys include component names such as "rho", "phase", "tdem", and station-level keys "station"/"station_mask".

Notes

Configuration helpers read overrides from backend_options and nested backend_options["error_model"] dictionaries. Explicit observed-data errors can still be passed to errors() or component_errors().

Examples

Build an error model directly:

>>> from pycsamt.inversion.objective import ErrorModel
>>> model = ErrorModel(rho_relative=0.05, phase_absolute=2.0)
>>> model.errors([100.0, 200.0], component="rho").tolist()
[5.0, 10.0]

Use component masks to down-weight stations or samples:

>>> from pycsamt.inversion.objective import ErrorModel
>>> model = ErrorModel(masks={"station": [True, False]})
>>> model.mask([[1.0, 2.0], [3.0, 4.0]], component="rho").tolist()
[[True, True], [False, False]]

References

rho_relative: float = 0.05#

rho_absolute: float = 1e-12#

phase_absolute: float = 3.0#

phase_relative: float = 0.0#

tdem_relative: float = 0.05#

tdem_absolute: float = 1e-30#

impedance_relative: float = 0.05#

impedance_absolute: float = 1e-12#

min_error: float = 1e-12#

masks: dict[str, Any]#

errors(values, *, component, explicit=None, relative=False)[source]#

Return data errors for one observed component.

Parameters:

values (array-like) – Observed or predicted values used to scale relative error floors.
component (str) – Component name. Common aliases include "rho", "rho_a", "phase", "tdem", "dbdt", and "impedance".
explicit (array-like, optional) – Explicit absolute errors. When provided, component floor settings are bypassed except for the global min_error lower bound.
relative (bool, default False) – If True, return relative errors by dividing absolute errors by abs(values) with min_error protection.

Returns:

Error array with the same shape as values.

Return type:

ndarray

Examples

>>> from pycsamt.inversion.objective import ErrorModel
>>> model = ErrorModel(rho_relative=0.1, rho_absolute=1.0)
>>> model.errors([5.0, 100.0], component="rho").tolist()
[1.0, 10.0]
>>> model.errors([45.0], component="phase").tolist()
[3.0]

mask(values, *, component)[source]#

Return a boolean inclusion mask for one component.

Parameters:

values (array-like) – Data array whose shape defines the returned mask shape.
component (str) – Component name. Component-specific masks are checked first, then station-level masks under "station" or "station_mask".

Returns:

Boolean mask broadcast to the shape of values.

Return type:

ndarray of bool

Examples

>>> from pycsamt.inversion.objective import ErrorModel
>>> model = ErrorModel(masks={"station": [True, False]})
>>> model.mask([[1.0, 2.0], [3.0, 4.0]], component="rho").tolist()
[[True, True], [False, False]]

pycsamt.inversion.objective.component_errors(values, cfg, *, component, explicit=None, relative=False)[source]#

Return errors for one data component using config settings.

Parameters:

values (array-like) – Data values used for scaling.
cfg (object) – Inversion config-like object accepted by error_model_from_config().
component (str) – Component name or alias.
explicit (array-like, optional) – Explicit data errors.
relative (bool, default False) – Return relative errors instead of absolute errors.

Returns:

Component error array.

Return type:

ndarray

Examples

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.objective import component_errors
>>> cfg = InversionConfig(error_floor=0.05, phase_error=2.0)
>>> component_errors([100.0, 200.0], cfg, component="rho").tolist()
[5.0, 10.0]
>>> component_errors([45.0], cfg, component="phase").tolist()
[2.0]

pycsamt.inversion.objective.component_mask(values, cfg, *, component)[source]#

Return a boolean mask for one component using config mask settings.

Parameters:

values (array-like) – Data array whose shape defines the returned mask shape.
cfg (object) – Inversion config-like object accepted by error_model_from_config().
component (str) – Component name or alias.

Returns:

Boolean inclusion mask.

Return type:

ndarray of bool

Examples

>>> import numpy as np
>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.objective import component_mask
>>> cfg = InversionConfig(backend_options={"masks": {"station": [True, False]}})
>>> component_mask(np.ones((2, 2)), cfg, component="rho").tolist()
[[True, True], [False, False]]

pycsamt.inversion.objective.error_model_from_config(cfg)[source]#

Build an ErrorModel from inversion config options.

Parameters:: cfg (object) – Inversion config-like object exposing error_floor, phase_error, and optional backend_options. Overrides may be placed directly in backend_options or inside backend_options["error_model"].
Returns:: Component-aware error model.
Return type:: ErrorModel

Examples

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.objective import error_model_from_config
>>> cfg = InversionConfig(error_floor=0.1, phase_error=2.0)
>>> model = error_model_from_config(cfg)
>>> model.rho_relative
0.1
>>> model.phase_absolute
2.0

pycsamt.inversion.objective.relative_errors(values, floor=0.05)[source]#

Return absolute errors from a relative floor.

Parameters:

values (array-like) – Data values used for relative scaling.
floor (float, default 0.05) – Relative floor as a fraction of absolute value.

Returns:

max(abs(values) * floor, 1e-12).

Return type:

ndarray

Examples

>>> from pycsamt.inversion.objective import relative_errors
>>> relative_errors([10.0, 100.0], floor=0.1).tolist()
[1.0, 10.0]

pycsamt.inversion.objective.weighted_rms(observed, predicted, errors=None)[source]#

Return normalized weighted RMS misfit.

Parameters:

observed (array-like) – Observed and predicted data arrays. They must be broadcast-compatible through NumPy conversion.
predicted (array-like) – Observed and predicted data arrays. They must be broadcast-compatible through NumPy conversion.
errors (array-like, optional) – Absolute data errors. If omitted, unit errors are used.

Returns:

Root-mean-square of (predicted - observed) / errors over finite, positive-error samples. Returns nan when no valid samples exist.

Return type:

float

Examples

>>> from pycsamt.inversion.objective import weighted_rms
>>> round(weighted_rms([10.0, 20.0], [11.0, 18.0], [1.0, 2.0]), 6)
1.0

References