geoprior.models.subsidence.payloads#

Physics diagnostics payloads.

This module centralizes data collection from a trained model for physics sanity plots (e.g., Fig.4) and provides robust persistence to disk with simple provenance metadata.

Functions

compute_identifiability_summary(eff_params, ...)

Compute identifiability diagnostics for Supp.

default_meta_from_model(model)

Build lightweight, JSON-serializable provenance from a model.

gather_physics_payload(model, dataset[, ...])

Collect a flat physics payload from a batched dataset for diagnostics.

identifiability_diagnostics_from_payload(...)

Compute synthetic identifiability diagnostics from a physics payload.

load_physics_payload(path)

Load a previously saved physics payload and its metadata.

save_physics_payload(payload, meta[, path, ...])

Save payload + sidecar metadata to disk.

summarise_effective_params(payload)

Collapse 1D arrays to scalar effective parameters.
geoprior.models.subsidence.payloads.default_meta_from_model(model)[source]#

Build lightweight, JSON-serializable provenance from a model.

Notes

  • time_units describes the time coordinate units in the dataset (for example, "year"), meaning what t represents before conversion.

  • Physics diagnostics such as tau, tau_prior, K, and cons_res_vals are exported in SI time units after the model’s internal conversions. In practice, K is in m/s, tau is in s, and cons_res_vals is in m/s.

Return type:

dict

geoprior.models.subsidence.payloads.identifiability_diagnostics_from_payload(payload, tau_true, K_true, Ss_true, Hd_true, K_prior, Ss_prior, Hd_prior, quantiles=(0.5, 0.75, 0.9, 0.95), eps=1e-12)[source]#

Compute synthetic identifiability diagnostics from a physics payload.

This implements the three diagnostics described in Supplementary Methods 3:

  1. Relative error in the effective relaxation time tau.

  2. Discrepancy between the composite timescale closure H_d^2 S_s / (kappa K) (stored as tau_prior) and the true effective timescale tau_eff,true, via a log-timescale residual.

  3. Marginal log-offsets of K, S_s and H_d relative to their true effective values and lithology-based priors.

Parameters:
payloaddict

Physics payload returned by gather_physics_payload() or GeoPriorSubsNet.export_physics_payload(). Must contain 1D arrays with keys: “tau”, “tau_prior”, “K”, “Ss”, “Hd”.

tau_truefloat

True effective relaxation time :math:` au_{mathrm{eff,true}}` from the 1D consolidation column.

K_true, Ss_true, Hd_truefloat

True effective closures \(K_{\mathrm{eff}}\), \(S_{s,\mathrm{eff}}\), and \(H_{d,\mathrm{eff}}\) at the column scale.

K_prior, Ss_prior, Hd_priorfloat

Lithology-based priors used to construct the GeoPrior head for this synthetic column.

quantilestuple of float, default (0.5, 0.75, 0.9, 0.95)

Quantile levels used for summary statistics of the distributions.

epsfloat, default 1e-12

Lower bound used to clip strictly positive quantities before taking logarithms.

Returns:
dict

A dictionary with three blocks:

  • "tau_rel_error": statistics of the relative error :math:`

rac{| au - au_{true}|}{ au_{true}}`.

  • "closure_log_resid": statistics of the log-timescale residual log(tau_prior) - log(tau_true).

  • "offsets": nested dict with "vs_true" and "vs_prior", each containing summary stats for the log-offsets delta_K, delta_Ss, and delta_Hd.

Parameters:
Return type:

dict[str, Any]

geoprior.models.subsidence.payloads.summarise_effective_params(payload)[source]#

Collapse 1D arrays to scalar effective parameters.

Intended for 1D synthetic-column experiments where model outputs are spatially constant and we only need a single representative value per run.

Parameters:

payload (dict[str, ndarray])

Return type:

dict[str, float]

geoprior.models.subsidence.payloads.compute_identifiability_summary(eff_params, true_params, prior_params, kappa_b=1.0, eps=1e-12)[source]#

Compute identifiability diagnostics for Supp. Methods 3.

See Supplementary Methods 3 for definitions of the quantities returned.

Parameters:
Return type:

dict[str, float]

geoprior.models.subsidence.payloads.gather_physics_payload(model, dataset, max_batches=None, float_dtype=<class 'numpy.float32'>, log_fn=None, eps=1e-12, **tqdm_kws)[source]#

Collect a flat physics payload from a batched dataset for diagnostics.

This function iterates over a tf.data.Dataset (or any iterable) and calls model.evaluate_physics(inputs, return_maps=True) on each batch. The returned per-batch tensors are flattened and concatenated into 1D arrays suitable for scatter plots, histograms, and summary stats.

Important

No unit conversion is performed here. The payload is exported in whatever units evaluate_physics(…) returns. Unit consistency is therefore a responsibility of the model’s physics implementation (and its scaling_kwargs), not this I/O layer.

Parameters:
Return type:

dict[str, ndarray]

geoprior.models.subsidence.payloads.save_physics_payload(payload, meta, path=None, format='npz', overwrite=False, log_fn=None)[source]#

Save payload + sidecar metadata to disk.

Parameters:

  • payload (dict) – Output of gather_physics_payload.

  • meta (dict) – Provenance dictionary. Will be JSON-serialized.

  • path (str or Nonr) – File path. If extension missing, inferred from format. If not provided, then get the current directory instead.

  • format ({"npz","csv","parquet"}) – Storage format. “npz” is compact and dependency-free.

  • overwrite (bool) – If False, raise if the file already exists.

Returns:

The resolved data file path that was written.

Return type:

str

geoprior.models.subsidence.payloads.load_physics_payload(path)[source]#

Load a previously saved physics payload and its metadata.

Parameters:

path (str) – Data file path. Supports .npz, .csv, .parquet.

Returns:

(payload, meta) – Payload dict with arrays and metadata dict (if found).

Return type:

(dict, dict)