geoprior.models.subsidence.step_core#

Core step computations for subsidence physics evaluation.

Functions

physics_core(model, inputs, training[, ...])

Compute GeoPrior physics residuals and losses for a batch.
geoprior.models.subsidence.step_core.physics_core(model, inputs, training, return_maps=False, *, for_train=False)[source]#

Compute GeoPrior physics residuals and losses for a batch.

This function implements the shared physics pathway used by both training and evaluation for GeoPrior-style PINN models. It is designed to keep the physics logic consistent across:

  • train_step() (when physics losses are added to the total loss)

  • evaluation routines (when physics diagnostics are reported)

At a high level, the function performs:

  1. Input preparation and SI conversions (thickness, head, coords).

  2. Forward pass through the model to obtain data predictions and physics logits.

  3. Mapping of physics logits to bounded physical fields (\(K\), \(S_s\), \(tau\)) and the closure prior \(tau_{phys}\).

  4. Automatic differentiation to obtain PDE derivatives with respect to the model coords.

  5. Chain-rule scaling to SI-consistent derivatives.

  6. Construction of residual maps for: * consolidation relaxation residual, * groundwater flow residual, * time-scale prior residual, * smoothness prior residual, * bounds residual.

  7. Optional nondimensionalization / residual scaling.

  8. Assembly of physics losses, gating schedules, and diagnostic epsilon metrics.

The returned dictionary contains predictions, auxiliary forward outputs, packed physics values (for logging), and optionally the full residual maps and fields.

Parameters:

  • model (object) –

    Model instance providing GeoPrior-style methods and attributes.

    The function expects the model to expose (at minimum):

    • scaling_kwargsdict

      Resolved scaling and convention payload.

    • time_unitsstr or None

      Dataset time unit (for per-second conversions).

    • forecast_horizonint

      Horizon length used to tile coords when needed.

    • _forward_all(inputs, training=...)callable

      Forward pass returning (y_pred, aux).

    • split_data_predictions(x)callable

      Split concatenated data head into subsidence and GWL.

    • split_physics_predictions(x)callable

      Split concatenated physics head into (K_logits, Ss_logits, dlogtau_logits, Q_logits).

    • pde_modes_activeiterable of str

      Active PDE modes (e.g., {‘consolidation’, ‘gw_flow’}).

    • Optional gates: _q_gate(), _subs_resid_gate().

    • Optional physics switch: _physics_off().

    The function is tolerant to partial capabilities and will short-circuit when physics is disabled, but missing mandatory signals (e.g., thickness) raise errors.

  • inputs (dict[str, Any | None]) – Dict input batch following the GeoPrior batch API.

  • training (bool)

  • return_maps (bool)

  • for_train (bool)

Return type:

dict[str, Any]