pycsamt.ai.losses.spatial#

Spatial regularization losses on predicted resistivity grids.

These losses implement the L_grad_x, L_grad_z, and L_TV terms of the staged inversion objective in the AI-inversion plan:

L = w_m * L_model + lambda_x * L_grad_x + lambda_z * L_grad_z
    + lambda_tv * L_TV + lambda_d * L_response

Inputs are predicted model arrays on a canonical geological grid, e.g. (z, x) or (z, y, x) from GeologyGrid. Only forward-difference pairs where both endpoints are finite, user-valid, and non-zero weight are included.

All functions operate on plain NumPy arrays so the module stays importable without an optional deep-learning backend.

Functions

gradient_smoothness_loss(y_pred, *, axis[, ...])

Penalize first-difference magnitude along one grid axis.

total_variation_loss(y_pred, *[, kind, ...])

Penalize anisotropic total variation over every spatial axis.

Classes

SpatialLoss([lambda_x, lambda_z, lambda_tv, ...])

Configurable combination of gradient and TV regularizers.

SpatialLossResult(value, kind, label, ...)

Immutable scalar result of a spatial regularization loss.
class pycsamt.ai.losses.spatial.SpatialLossResult(value, kind, label, reduction, n_valid, weight_sum)[source]

Bases: object

Immutable scalar result of a spatial regularization loss.

Parameters:

  • value (float) – Reduced penalty value. nan when no difference was included and reduction="mean".

  • kind ({"l1", "l2"}) – Elementwise penalty applied to each spatial difference.

  • label (str) – Loss identity, e.g. "grad_axis0" or "tv".

  • reduction ({"mean", "sum"}) – Reduction applied over valid, weighted differences.

  • n_valid (int) – Number of differences included after masking.

  • weight_sum (float) – Sum of weights over included differences.

Examples

>>> import numpy as np
>>> grid = np.array([[0.0, 1.0, 3.0], [0.0, 0.0, 0.0]])
>>> result = gradient_smoothness_loss(grid, axis=1)
>>> result.label
'grad_axis1'
value: float
kind: str
label: str
reduction: str
n_valid: int
weight_sum: float
pycsamt.ai.losses.spatial.gradient_smoothness_loss(y_pred, *, axis, kind='l2', valid=None, weights=None, reduction='mean')[source]

Penalize first-difference magnitude along one grid axis.

Parameters:

  • y_pred (array-like) – Predicted model values on a canonical geological grid.

  • axis (int) – Grid axis along which to difference, e.g. 0 for depth or -1 for the horizontal direction. Negative axes are supported.

  • kind ({"l1", "l2"}, default="l2") – Elementwise penalty applied to each difference.

  • valid (array-like of bool or None, optional) – Cell mask applied before differencing. A difference is kept only if both of its endpoint cells are valid and finite.

  • weights (array-like or None, optional) – Non-negative per-cell weights broadcastable to y_pred. A difference is weighted by the minimum of its two endpoint weights.

  • reduction ({"mean", "sum"}, default="mean") – Reduction applied over included differences.

Returns:

Reduced smoothness penalty, e.g. L_grad_x or L_grad_z.

Return type:

SpatialLossResult

Examples

>>> import numpy as np
>>> grid = np.array([[0.0, 1.0, 3.0], [0.0, 0.0, 0.0]])
>>> gradient_smoothness_loss(grid, axis=1, kind="l1").value
0.75
pycsamt.ai.losses.spatial.total_variation_loss(y_pred, *, kind='l1', valid=None, weights=None, reduction='mean')[source]

Penalize anisotropic total variation over every spatial axis.

Computes gradient_smoothness_loss() along each axis of y_pred and combines them, matching the standard anisotropic total-variation definition (a per-axis sum of directional gradients, as opposed to an isotropic pointwise gradient norm).

Parameters:

  • y_pred (array-like) – Predicted model values on a canonical geological grid.

  • kind ({"l1", "l2"}, default="l1") – Elementwise penalty applied to each difference.

  • valid (array-like of bool or None, optional) – Cell mask shared by every axis.

  • weights (array-like or None, optional) – Non-negative per-cell weights shared by every axis.

  • reduction ({"mean", "sum"}, default="mean") – Reduction applied over all included differences from every axis combined.

Returns:

Reduced total-variation penalty, L_TV, labeled "tv".

Return type:

SpatialLossResult

Examples

>>> import numpy as np
>>> grid = np.array([[0.0, 1.0], [0.0, 3.0]])
>>> total_variation_loss(grid).value
1.5
class pycsamt.ai.losses.spatial.SpatialLoss(lambda_x=1.0, lambda_z=1.0, lambda_tv=0.0, kind='l2', reduction='mean')[source]

Bases: object

Configurable combination of gradient and TV regularizers.

Combines the lambda_x * L_grad_x + lambda_z * L_grad_z + lambda_tv * L_TV terms of the staged inversion objective for a canonical 2-D (z, x) grid, where depth is axis 0 and the horizontal direction is axis 1.

Parameters:

  • lambda_x (float, default=1.0) – Weight applied to the horizontal-gradient term.

  • lambda_z (float, default=1.0) – Weight applied to the depth-gradient term.

  • lambda_tv (float, default=0.0) – Weight applied to the total-variation term.

  • kind ({"l1", "l2"}, default="l2") – Elementwise penalty shared by the two gradient terms. The total-variation term always uses "l1", matching its standard definition.

  • reduction ({"mean", "sum"}, default="mean") – Reduction applied within each enabled term.

Examples

>>> import numpy as np
>>> grid = np.array([[0.0, 1.0], [0.0, 3.0]])
>>> loss = SpatialLoss(
...     lambda_x=1.0, lambda_z=0.0, lambda_tv=0.0, kind="l1"
... )
>>> loss(grid)
2.0
lambda_x: float = 1.0
lambda_z: float = 1.0
lambda_tv: float = 0.0
kind: str = 'l2'
reduction: str = 'mean'