pycsamt.inversion.regularization#

Regularization controls for inversion workflows.

Functions

`pygimli_lambda`(cfg, *[, default])	Return the pyGIMLi lambda value using shared option names.
`regularization_from_config`(cfg)	Build backend-neutral controls from a config object.
`regularization_residual`(values, *[, ...])	Return unweighted residual terms for smooth/damped/blocky penalties.
`regularization_weight`(cfg, *[, default])	Return the scalar penalty weight for least-squares backends.

Classes

Regularization([kind, alpha_s, alpha_x, ...])

Backend-neutral regularization settings.

class pycsamt.inversion.regularization.Regularization(kind='smooth', alpha_s=1.0, alpha_x=1.0, alpha_z=1.0, reference_weight=0.0, metadata=<factory>)[source]#

Bases: PyCSAMTObject, MetadataMixin

Backend-neutral regularization settings.

Regularization stores the model-structure penalty vocabulary shared by built-in, SimPEG, and pyGIMLi inversion paths. The residual helpers operate on model-parameter arrays, usually log-domain resistivity values, and return unweighted structure residuals that can be multiplied by a global scalar such as \(\sqrt{\lambda}\).

For a smooth model \(m\), the penalty contains finite differences such as

\[\phi_m = \alpha_x \|\nabla_x m\|_2^2 + \alpha_z \|\nabla_z m\|_2^2 .\]

For damped/reference regularization, a smallness term \(\alpha_s\|m-m_{ref}\|_2^2\) is added. For "blocky" models, the finite differences are normalized by \(\sqrt{(\Delta m)^2 + \epsilon^2}\) to reduce sensitivity to sharp edges.

Parameters:

kind ({"none", "smooth", "damped", "blocky"}, default "smooth") – Regularization family. "none" disables the penalty, "smooth" penalizes model roughness, "damped" combines smallness/reference and roughness terms, and "blocky" applies an edge-preserving normalized gradient penalty.
alpha_s (float, default 1.0) – Smallness or reference-model weight. This controls residual terms of the form \(m - m_{ref}\) when damping/reference regularization is active.
alpha_x (float, default 1.0) – Lateral roughness weight applied along the profile or X axis.
alpha_z (float, default 1.0) – Vertical roughness weight applied along the depth or Z axis.
reference_weight (float, default 0.0) – Extra multiplier for the reference-model term. When a reference model is provided, values below one are promoted to one for damped/smallness terms.
metadata (dict, optional) – Free-form provenance metadata attached to the regularization settings.

Notes

This class stores relative penalty settings only. The scalar objective weight is read separately by regularization_weight(), while pyGIMLi-specific lambda handling is read by pygimli_lambda().

Examples

Build a smoothness penalty for a 2-D log-resistivity model:

>>> import numpy as np
>>> from pycsamt.inversion.regularization import Regularization
>>> from pycsamt.inversion.regularization import regularization_residual
>>> reg = Regularization(kind="smooth", alpha_x=2.0, alpha_z=1.0)
>>> residual = regularization_residual(np.ones((3, 4)), regularization=reg)
>>> residual.size
17

Read shared settings from an inversion config:

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.regularization import regularization_from_config
>>> cfg = InversionConfig(regularization="damped",
...     backend_options={"alpha_s": 0.5, "regularization_weight": 2.0})
>>> regularization_from_config(cfg).alpha_s
0.5

References

kind: str = 'smooth'#

alpha_s: float = 1.0#

alpha_x: float = 1.0#

alpha_z: float = 1.0#

reference_weight: float = 0.0#

metadata: dict[str, Any]#

validate()[source]#

Validate regularization kind and non-negative weights.

Raises:: ValueError – If kind is not one of "none", "smooth", "damped", or "blocky", or if any alpha/reference weight is negative.
Return type:: None

Examples

>>> from pycsamt.inversion.regularization import Regularization
>>> Regularization(kind="smooth", alpha_x=1.0).validate() is None
True

pycsamt.inversion.regularization.regularization_from_config(cfg)[source]#

Build backend-neutral controls from a config object.

Parameters:: cfg (object) – Inversion config-like object exposing regularization and optional backend_options. Recognized backend options include alpha_s, alpha_model, alpha_x, alpha_lateral, alpha_z, alpha_vertical, reference_weight, and regularization_metadata.
Returns:: Parsed regularization settings.
Return type:: Regularization

Examples

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.regularization import regularization_from_config
>>> cfg = InversionConfig(regularization="blocky",
...     backend_options={"alpha_x": 2.0, "alpha_z": 0.5})
>>> reg = regularization_from_config(cfg)
>>> (reg.kind, reg.alpha_x, reg.alpha_z)
('blocky', 2.0, 0.5)

pycsamt.inversion.regularization.regularization_residual(values, *, reference=None, regularization=None, blocky_eps=0.01, axes=None)[source]#

Return unweighted residual terms for smooth/damped/blocky penalties.

values are normally log-domain model parameters. The returned vector already contains the square-root alpha factors; callers can multiply by a global scalar such as sqrt(regularization_weight).

Parameters:

values (array-like) – Model parameter array. One-dimensional arrays are treated as depth profiles. Two-dimensional arrays are treated as (z, x) sections.
reference (array-like, optional) – Reference model with the same shape as values or broadcastable to that shape.
regularization (Regularization, optional) – Regularization settings. If omitted, Regularization() is used.
blocky_eps (float, default 1e-2) – Stabilization value in the blocky normalized-gradient penalty.
axes (tuple of {"x", "z"}, optional) – Axes on which to compute roughness. Defaults to ("z",) for 1-D arrays and ("x", "z") for 2-D or higher arrays.

Returns:

Concatenated residual vector. Empty when kind="none" or all active penalty terms have zero weight.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from pycsamt.inversion.regularization import Regularization
>>> from pycsamt.inversion.regularization import regularization_residual
>>> reg = Regularization(kind="damped", alpha_s=1.0, alpha_z=1.0)
>>> residual = regularization_residual(np.array([1.0, 2.0, 4.0]),
...     reference=np.ones(3), regularization=reg)
>>> residual.size
5

References

pycsamt.inversion.regularization.regularization_weight(cfg, *, default=0.0)[source]#

Return the scalar penalty weight for least-squares backends.

Parameters:

cfg (object) – Inversion config-like object with optional backend_options.
default (float, default 0.0) – Value returned when no shared weight is configured.

Returns:

Value from backend_options["regularization_weight"] or backend_options["reg_weight"].

Return type:

float

Examples

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.regularization import regularization_weight
>>> cfg = InversionConfig(backend_options={"regularization_weight": 3.0})
>>> regularization_weight(cfg)
3.0

pycsamt.inversion.regularization.pygimli_lambda(cfg, *, default=20.0)[source]#

Return the pyGIMLi lambda value using shared option names.

Parameters:

cfg (object) – Inversion config-like object with optional backend_options.
default (float, default 20.0) – Fallback value when no lambda-like option is configured.

Returns:

Value from lam, lambda, or regularization_weight in that priority order.

Return type:

float

Examples

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.regularization import pygimli_lambda
>>> cfg = InversionConfig(backend_options={"lam": 7.0})
>>> pygimli_lambda(cfg)
7.0