geoprior.models.subsidence.debugs

Debug helpers for GeoPriorSubsNet.

Keep all verbosity + shape/unit printing here so _geoprior_subnet.py stays clean.

All functions are safe to call inside tf.function: they use tf.print and TensorFlow assertions. - Compare in-memory vs loaded inference model on the same batch. - Report prediction diffs + weight name/shape diffs + key attribute digests.

Functions

dbg_assert_data_layout(*, verbose, ...[, level])
dbg_call_nonfinite(*, verbose[, level])	Debug non-finite checks for call() internal tensors.
dbg_call_nonfinite_diag(*, verbose, ...[, level])	Print non-finite diagnostics inside call().
dbg_chk_core_finite(*, verbose, cons_res, ...)
dbg_chk_finite(tag, x)	Assert finite, return x (small helper).
dbg_chk_scales(*, verbose, scales[, level])
dbg_cons_units_rms(*, verbose, sk, cons_res)
dbg_done_apply_gradients(*[, debug_grads, ...])
dbg_dt_debug(*, verbose[, level])	Debug dt conversion and t-grid sanity.
dbg_dt_diag(*, verbose, time_units, dt_units, t)	Print dt consistency checks in time_units and seconds.
dbg_gw_grad_flux_rms(*, verbose, dh_dx_raw, ...)	Print RMS diagnostics for spatial head gradients and Darcy-like flux terms K*∂h/∂x, K*∂h/∂y (raw coord units).
dbg_gw_units_and_sec_scale(*, verbose, ...)	Print GW residual diagnostics before/after applying sec_u scaling.
dbg_mae(tag, y, yhat)	Print batch MAE for y vs yhat.
dbg_on(verbose, level)	Return True if verbose is strictly above level.
dbg_pde_divergence_maxabs(*, verbose, ...[, ...])	Print max-abs diagnostics for the divergence terms, before and optionally after normalization/chain-rule correction.
dbg_run_first_iter(*, verbose, level, ...)	Run fn() only at optimizer.iterations == 0.
dbg_select_q(y, quantiles, *[, q])	Select a quantile slice if y is (B,H,Q,1)/(B,H,Q).
dbg_stats(tag, x)	Print min/max/mean (graph-safe).
dbg_step0_inputs_targets(*, verbose, inputs, ...)
dbg_step10_grads(*, verbose, trainable_vars, ...)
dbg_step1_thickness(*, verbose, H_field, H_si)
dbg_step2_coords_checks(*, verbose, coords, ...)
dbg_step31_forward_outputs(*, verbose, ...)
dbg_step33_physics_fields(*, verbose, ...[, ...])
dbg_step33_physics_logits(*, verbose, ...[, ...])
dbg_step3_mean_head(*, verbose, ...[, level])
dbg_step3_residual_scales(*, verbose, ...[, ...])	Print raw residual stats + scaling factors.
dbg_step41_si_grads(*, verbose, dh_dt, ...)
dbg_step4_ad_raw(*, verbose, dh_dcoords, ...)
dbg_step5_q(*, verbose, Q_si, dh_dt[, level])	Print Q source term block.
dbg_step5_q_source(*, verbose, Q_si, dh_dt)
dbg_step6_consolidation(*, verbose, ...)
dbg_step7_residuals(*, verbose, gw_res, ...)
dbg_step8_residual_scale_stats(*, verbose[, ...])	Debug block for residuals + scaling stats.
dbg_step8_scaling(*, verbose, cons_res_raw, ...)
dbg_step9_losses(*, verbose[, data_loss, ...])	Debug-print loss scalars (only those provided).
dbg_term_grads_finite(*, verbose, ...[, level])
dbg_units_once(*, verbose, iterations, ...)
debug_model_reload(mem_model, load_model, ...)	Run a compact reload debug on one batch and return a dict report.
model_scaling_digest(model)	Stable digest of model.scaling_kwargs to verify the same config survived reload.
weight_diff_report(m1, m2, *[, top, ...])	Compare weights between two models using stable keys.

geoprior.models.subsidence.debugs.weight_diff_report(m1, m2, *, top=30, include_ok=False, include_extra=False)

Compare weights between two models using stable keys.

Each row is:

(max_abs_diff or inf, tag, weight_id, shape_info)

Where tag in:

{“OK”, “MISSING”, “SHAPE”, “EXTRA”}

Notes

• Uses w.path when available (best).

• Otherwise uses name + occurrence index.

• Set top<=0 to return all rows.

Parameters:

• m1 (Any)

• m2 (Any)

• top (int)

• include_ok (bool)

• include_extra (bool)

Return type:

list[tuple[float, str, str, Any]]

geoprior.models.subsidence.debugs.model_scaling_digest(model)

Stable digest of model.scaling_kwargs to verify the same config survived reload.

Parameters:

model (Any)

Return type:

str

geoprior.models.subsidence.debugs.debug_model_reload(mem_model, load_model, dataset, *, pred_key='subs_pred', also_check=None, top_weights=30, atol=1e-06, rtol=1e-06, log_fn=None)

Run a compact reload debug on one batch and return a dict report.

• Compares predictions (max/mean abs diff) for pred_key (+ optional keys).

• Compares weights by name (MISSING/SHAPE/OK).

• Compares scaling_kwargs digest + time_units attribute.

Parameters:

• mem_model (Any)

• load_model (Any)

• dataset (Iterable)

• pred_key (str)

• also_check (list[str] | None)

• top_weights (int)

• atol (float)

• rtol (float)

• log_fn (Callable[[str], None] | None)

Return type:

dict[str, Any]

geoprior.models.subsidence.debugs.dbg_on(verbose, level)

Return True if verbose is strictly above level.

Parameters:

• verbose (int)

• level (int)

Return type:

bool

geoprior.models.subsidence.debugs.dbg_run_first_iter(*, verbose, level, iterations, fn)

Run fn() only at optimizer.iterations == 0.

Graph-safe: uses tf.cond and returns a dummy scalar.

Parameters:

• verbose (int)

• level (int)

• iterations (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_stats(tag, x)

Print min/max/mean (graph-safe).

Parameters:

• tag (str)

• x (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_pde_divergence_maxabs(*, verbose, raw_dKdhx_dcoords, raw_d_K_dh_dx_dx, raw_d_K_dh_dy_dy, d_K_dh_dx_dx=None, d_K_dh_dy_dy=None, level=7, prefix='pde/div')

Print max-abs diagnostics for the divergence terms, before and optionally after normalization/chain-rule correction.

Parameters:

• verbose (int)

• raw_dKdhx_dcoords (Tensor)

• raw_d_K_dh_dx_dx (Tensor)

• raw_d_K_dh_dy_dy (Tensor)

• d_K_dh_dx_dx (Any | None)

• d_K_dh_dy_dy (Any | None)

• level (int)

• prefix (str)

Return type:

None

geoprior.models.subsidence.debugs.dbg_gw_units_and_sec_scale(*, verbose, gw_units, gw_res_before, gw_res_after, level=7, prefix='gw/units')

Print GW residual diagnostics before/after applying sec_u scaling.

Call this right after you do:

gw_res_before = gw_res gw_res = gw_res * sec_u gw_res_after = gw_res

Parameters:

• gw_units (Any) – Usually resolve_gw_units(sk). Keep it as Any so callers can pass python strings without TF ops.

• verbose (int)

• gw_res_before (Tensor)

• gw_res_after (Tensor)

• level (int)

• prefix (str)

Return type:

None

Notes

We print RMS to catch accidental unit explosions.

geoprior.models.subsidence.debugs.dbg_mae(tag, y, yhat)

Print batch MAE for y vs yhat.

Parameters:

• tag (str)

• y (Tensor)

• yhat (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_chk_finite(tag, x)

Assert finite, return x (small helper).

Parameters:

• tag (str)

• x (Tensor)

Return type:

Tensor

geoprior.models.subsidence.debugs.dbg_step0_inputs_targets(*, verbose, inputs, targets, level=12)

Parameters:

• verbose (int)

• inputs (dict[str, Any])

• targets (Any)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step1_thickness(*, verbose, H_field, H_si, level=12)

Parameters:

• verbose (int)

• H_field (Tensor)

• H_si (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step2_coords_checks(*, verbose, coords, inputs, level=12)

Parameters:

• verbose (int)

• coords (Tensor)

• inputs (dict[str, Any])

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_units_once(*, verbose, iterations, targets, gwl_pred_final, s_pred_final, quantiles, level=7)

Parameters:

• verbose (int)

• iterations (Tensor)

• targets (dict[str, Tensor])

• gwl_pred_final (Tensor)

• s_pred_final (Tensor)

• quantiles (Sequence[float] | None)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_assert_data_layout(*, verbose, data_final, data_mean_raw, quantiles, level=12)

Parameters:

• verbose (int)

• data_final (Tensor)

• data_mean_raw (Any | None)

• quantiles (Sequence[float] | None)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step3_mean_head(*, verbose, gwl_mean_raw, gwl_si, h_si, level=12)

Parameters:

• verbose (int)

• gwl_mean_raw (Tensor)

• gwl_si (Tensor)

• h_si (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step31_forward_outputs(*, verbose, data_final, s_pred_final, gwl_pred_final, data_mean_raw, phys_mean_raw, level=12)

Parameters:

• verbose (int)

• data_final (Tensor)

• s_pred_final (Tensor)

• gwl_pred_final (Tensor)

• data_mean_raw (Any | None)

• phys_mean_raw (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step33_physics_logits(*, verbose, K_logits, Ss_logits, dlogtau_logits, Q_logits, K_base, Ss_base, dlogtau_base, level=12)

Parameters:

• verbose (int)

• K_logits (Tensor)

• Ss_logits (Tensor)

• dlogtau_logits (Tensor)

• Q_logits (Any | None)

• K_base (Tensor)

• Ss_base (Tensor)

• dlogtau_base (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step33_physics_fields(*, verbose, K_field, Ss_field, tau_field, tau_phys, Hd_eff, delta_log_tau, logK, logSs, log_tau, log_tau_phys, level=12)

Parameters:

• verbose (int)

• K_field (Tensor)

• Ss_field (Tensor)

• tau_field (Tensor)

• tau_phys (Tensor)

• Hd_eff (Tensor)

• delta_log_tau (Tensor)

• logK (Tensor)

• logSs (Tensor)

• log_tau (Tensor)

• log_tau_phys (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step4_ad_raw(*, verbose, dh_dcoords, dh_dt_raw, dh_dx_raw, dh_dy_raw, K_dh_dx, K_dh_dy, dKdhx_dcoords, dKdhy_dcoords, d_K_dh_dx_dx_raw, d_K_dh_dy_dy_raw, dK_dcoords, dSs_dcoords, dK_dx_raw, dK_dy_raw, dSs_dx_raw, dSs_dy_raw, level=12)

Parameters:

• verbose (int)

• dh_dcoords (Tensor)

• dh_dt_raw (Tensor)

• dh_dx_raw (Tensor)

• dh_dy_raw (Tensor)

• K_dh_dx (Tensor)

• K_dh_dy (Tensor)

• dKdhx_dcoords (Tensor)

• dKdhy_dcoords (Tensor)

• d_K_dh_dx_dx_raw (Tensor)

• d_K_dh_dy_dy_raw (Tensor)

• dK_dcoords (Tensor)

• dSs_dcoords (Tensor)

• dK_dx_raw (Tensor)

• dK_dy_raw (Tensor)

• dSs_dx_raw (Tensor)

• dSs_dy_raw (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step41_si_grads(*, verbose, dh_dt, d_K_dh_dx_dx, d_K_dh_dy_dy, dK_dx, dK_dy, dSs_dx, dSs_dy, level=12)

Parameters:

• verbose (int)

• dh_dt (Tensor)

• d_K_dh_dx_dx (Tensor)

• d_K_dh_dy_dy (Tensor)

• dK_dx (Tensor)

• dK_dy (Tensor)

• dSs_dx (Tensor)

• dSs_dy (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step5_q_source(*, verbose, Q_si, dh_dt, level=12)

Parameters:

• verbose (int)

• Q_si (Tensor)

• dh_dt (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_cons_units_rms(*, verbose, sk, cons_res, level=7)

Parameters:

• verbose (int)

• sk (dict[str, Any])

• cons_res (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step6_consolidation(*, verbose, allow_resid, cons_active, s_mean_raw, s_pred_si, dt_units, s0_cum_11, s_inc_pred, s_state, h_ref_si_11, h_state, cons_step_m, cons_res)

Parameters:

• verbose (int)

• allow_resid (bool)

• cons_active (bool)

• s_mean_raw (Tensor)

• s_pred_si (Tensor)

• dt_units (Tensor)

• s0_cum_11 (Tensor)

• s_inc_pred (Tensor)

• s_state (Tensor)

• h_ref_si_11 (Tensor)

• h_state (Tensor)

• cons_step_m (Tensor)

• cons_res (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step7_residuals(*, verbose, gw_res, prior_res, smooth_res, loss_mv, bounds_res, loss_bounds, level=12)

Parameters:

• verbose (int)

• gw_res (Tensor)

• prior_res (Tensor)

• smooth_res (Tensor)

• loss_mv (Tensor)

• bounds_res (Tensor)

• loss_bounds (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step8_scaling(*, verbose, cons_res_raw, gw_res_raw, cons_res, gw_res, level=7)

Parameters:

• verbose (int)

• cons_res_raw (Tensor)

• gw_res_raw (Tensor)

• cons_res (Tensor)

• gw_res (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_chk_scales(*, verbose, scales, level=2)

Parameters:

• verbose (int)

• scales (dict[str, Tensor])

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_chk_core_finite(*, verbose, cons_res, gw_res, tau_field, K_field, Ss_field, level=2)

Parameters:

• verbose (int)

• cons_res (Tensor)

• gw_res (Tensor)

• tau_field (Tensor)

• K_field (Tensor)

• Ss_field (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step9_losses(*, verbose, data_loss=None, loss_cons=None, loss_gw=None, loss_prior=None, loss_smooth=None, physics_loss_raw=None, physics_loss_scaled=None, total_loss=None, level=7)

Debug-print loss scalars (only those provided).

Parameters:

• verbose (int)

• data_loss (Any | None)

• loss_cons (Any | None)

• loss_gw (Any | None)

• loss_prior (Any | None)

• loss_smooth (Any | None)

• physics_loss_raw (Any | None)

• physics_loss_scaled (Any | None)

• total_loss (Any | None)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step10_grads(*, verbose, trainable_vars, grads, level=9)

Parameters:

• verbose (int)

• trainable_vars (Sequence[Tensor])

• grads (Sequence[Any | None])

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_term_grads_finite(*, verbose, debug_grads, trainable_vars, data_loss, terms_scaled, tape, level=1)

Parameters:

• verbose (int)

• debug_grads (bool)

• trainable_vars (Sequence[Tensor])

• data_loss (Tensor)

• terms_scaled (dict[str, Tensor])

• tape (Any)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_done_apply_gradients(*, debug_grads=False, verbose=1)

Parameters:

• debug_grads (bool)

• verbose (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_select_q(y, quantiles, *, q=0.5)

Select a quantile slice if y is (B,H,Q,1)/(B,H,Q).

If quantiles is None, returns y as-is.

Parameters:

• y (Tensor)

• quantiles (Sequence[float] | None)

• q (float)

Return type:

Tensor

geoprior.models.subsidence.debugs.dbg_step5_q(*, verbose, Q_si, dh_dt, level=12)

Print Q source term block.

Parameters:

• verbose (int)

• Q_si (Tensor)

• dh_dt (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step8_residual_scale_stats(*, verbose, level=3, cons_res_raw, cons_scale, gw_res_raw, gw_scale)

Debug block for residuals + scaling stats.

Replaces:

_stats(“cons_res_raw”, cons_res) _stats(“cons_scale”, scales[“cons_scale”]) _stats(“gw_res_raw”, gw_res) _stats(“gw_scale”, scales[“gw_scale”])

Parameters:

• verbose (int)

• level (int)

• cons_res_raw (Tensor)

• cons_scale (Tensor)

• gw_res_raw (Tensor)

• gw_scale (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_dt_debug(*, verbose, level=3, time_units, dt_units, t)

Debug dt conversion and t-grid sanity.

Replaces the “dt debug” block.

Parameters:

• verbose (int)

• level (int)

• time_units (str)

• dt_units (Tensor)

• t (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_call_nonfinite(*, verbose, level=9, coords_for_decoder, H_si, K_base, Ss_base, dlogtau_base, tau_field)

Debug non-finite checks for call() internal tensors.

Replaces:

tf_print_nonfinite(“call/coords_for_decoder”, coords_for_decoder) …

Parameters:

• verbose (int)

• level (int)

• coords_for_decoder (Tensor)

• H_si (Tensor)

• K_base (Tensor)

• Ss_base (Tensor)

• dlogtau_base (Tensor)

• tau_field (Tensor)

Return type:

None

geoprior.models.subsidence.debugs.dbg_step3_residual_scales(*, verbose, cons_res, gw_res, scales, level=3)

Print raw residual stats + scaling factors.

Parameters:

• verbose (int)

• cons_res (Tensor)

• gw_res (Tensor)

• scales (dict)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_dt_diag(*, verbose, time_units, dt_units, t, level=3)

Print dt consistency checks in time_units and seconds.

Parameters:

• verbose (int)

• time_units (str)

• dt_units (Tensor)

• t (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_call_nonfinite_diag(*, verbose, coords_for_decoder, H_si, K_base, Ss_base, dlogtau_base, tau_field, level=9)

Print non-finite diagnostics inside call().

Parameters:

• verbose (int)

• coords_for_decoder (Tensor)

• H_si (Tensor)

• K_base (Tensor)

• Ss_base (Tensor)

• dlogtau_base (Tensor)

• tau_field (Tensor)

• level (int)

Return type:

None

geoprior.models.subsidence.debugs.dbg_gw_grad_flux_rms(*, verbose, dh_dx_raw, dh_dy_raw, K_field, level=3, prefix='gw/gradflux')

Print RMS diagnostics for spatial head gradients and Darcy-like flux terms K*∂h/∂x, K*∂h/∂y (raw coord units).

Replaces:

tf_print(“to_rms(dh_dx)=”, to_rms(dh_dx_raw)) tf_print(“to_rms(dh_dy)=”, to_rms(dh_dy_raw)) tf_print(“to_rms(K_field * dh_dx)=”, to_rms(K_field * dh_dx_raw)) tf_print(“to_rms(K_field * dh_dy)=”, to_rms(K_field * dh_dy_raw))

Parameters:

• verbose (int)

• dh_dx_raw (Tensor)

• dh_dy_raw (Tensor)

• K_field (Tensor)

• level (int)

• prefix (str)

Return type:

None