pycsamt.ai.losses.boundary#

Boundary-condition losses on predicted resistivity grids.

Boundary constraints anchor prediction cells that the training data has no sensitivity to, e.g. air cells above topography or the outer mesh padding, to an explicit required value instead of letting the network hallucinate structure there. A boundary constraint is therefore a masked data-fit loss between the prediction and a required target, restricted to a caller-supplied boundary_mask. There is no implicit default target: callers must state the physically motivated value explicitly, e.g. a fixed air resistivity, matching the plan’s requirement that agents contain no hidden physics.

A common boundary_mask source is air_mask().

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

Functions

boundary_condition_loss(y_pred, *, ...[, ...])

Penalize predicted values that violate a boundary constraint.

Classes

BoundaryLoss([kind, delta, reduction])

Configurable, callable boundary-condition penalty.
pycsamt.ai.losses.boundary.boundary_condition_loss(y_pred, *, boundary_mask, target, kind='l2', delta=1.0, valid=None, weights=None, reduction='mean')[source]

Penalize predicted values that violate a boundary constraint.

Parameters:

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

  • boundary_mask (array-like of bool, same shape as y_pred) – Cells subject to the boundary constraint, e.g. air cells above topography or the outer mesh padding. At least one cell must be selected.

  • target (float or array-like) – Required value on boundary_mask cells, e.g. a fixed air resistivity. A scalar is broadcast to the grid shape.

  • kind ({"l1", "l2", "huber"}, default="l2") – Elementwise penalty, as in model_l2_loss().

  • delta (float, default=1.0) – Huber transition point. Ignored unless kind="huber".

  • valid (array-like of bool or None, optional) – Additional cell mask combined with boundary_mask and with finite-value masking of y_pred.

  • weights (array-like or None, optional) – Non-negative per-cell weights broadcastable to the grid shape.

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

Returns:

Reduced boundary-condition penalty.

Return type:

ModelLossResult

Examples

>>> import numpy as np
>>> grid = np.array([[1.0, 1.0], [3.0, 3.0]])
>>> air = np.array([[True, True], [False, False]])
>>> boundary_condition_loss(
...     grid, boundary_mask=air, target=0.0, kind="l1"
... ).value
1.0
class pycsamt.ai.losses.boundary.BoundaryLoss(kind='l2', delta=1.0, reduction='mean')[source]

Bases: object

Configurable, callable boundary-condition penalty.

Parameters:

  • kind ({"l1", "l2", "huber"}, default="l2") – Elementwise penalty applied to each boundary-cell residual.

  • delta (float, default=1.0) – Huber transition point. Ignored unless kind="huber".

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

Examples

>>> import numpy as np
>>> loss = BoundaryLoss(kind="l1")
>>> grid = np.array([[1.0, 1.0], [3.0, 3.0]])
>>> air = np.array([[True, True], [False, False]])
>>> loss(grid, boundary_mask=air, target=0.0).value
1.0
kind: str = 'l2'
delta: float = 1.0
reduction: str = 'mean'