Scientific foundations#
This section presents the scientific and mathematical scaffolding behind GeoPrior-v3, with particular emphasis on the subsidence model family centered on GeoPriorSubsNet. It is intended for readers who want to understand not only what the package does, but also why the model is structured the way it is, how the physical assumptions are expressed, and where the main loss, scaling, stability, and identifiability choices come from.
Rather than serving as a purely theoretical appendix, this part of the documentation connects the underlying scientific ideas to the practical forecasting workflow implemented throughout the package. The pages collected here move from broad model positioning to increasingly specific technical components. Together, they explain:
how the model family is positioned within the broader GeoPrior project,
which poroelastic and consolidation ideas are used as scientific scaffolding,
how residuals, losses, and scaling choices are assembled,
how constraints and identifiability shape the training problem,
how quantities, units, and transformations should be interpreted in practice.
This section complements the Applications pages, which show how these ideas are used in complete workflows, and the Subsidence API reference reference, which documents the concrete module interfaces that implement much of this logic.
Note
Use this section when you need scientific interpretability rather than only usage instructions. It is especially useful for research writing, method comparison, debugging of physics-informed behavior, and contributor work that touches the model formulation directly.
Begin with the overall positioning of the GeoPrior model family, including how the flagship subsidence workflow fits into the broader project roadmap.
Study the main subsidence model page and its role in linking data, learned fields, physics residuals, and uncertainty-aware outputs.
Examine how the governing scientific assumptions are translated into the physics-guided structure used by the model.
Review the background concepts that motivate the consolidation and groundwater components of the formulation.
Understand how the main residual terms are constructed and how their different roles interact during model training.
Follow the relationship between data-fit terms, physics penalties, priors, and optimization strategy.
Clarify the interpretation of variables, sign conventions, unit handling, and data-side assumptions used throughout the workflow.
See how nondimensionalization, normalization, and scale-aware choices stabilize training and interpretability.
Explore the mathematical utilities and conceptual formulas that support the model implementation and its diagnostics.
Review how parameter coupling, prior structure, and closure logic affect what can realistically be inferred from the data.
Understand the safeguards that help keep the learned fields, residual terms, and optimization process physically credible.
How to read this section#
There are two good ways to use these pages.
The first is as a guided conceptual path. Readers who are new to the scientific material should usually begin with Models overview and GeoPriorSubsNet, then continue to Physics formulation and Poroelastic background. That order provides the main modeling picture before moving into residual details, loss construction, and training controls.
The second is as a targeted technical reference. For debugging, comparison, or manuscript preparation, it is often more useful to read Residual assembly, Losses and training, Scaling and conventions (scaling_kwargs), Identifiability, and Stability and constraints together. Those pages capture many of the design choices that matter most for interpretation, justification, and reproducible scientific discussion.
Tip
If you are reading GeoPrior primarily as a scientific contribution, start with the model and physics pages first. If you are already familiar with the general formulation and want to understand training behavior in detail, move directly to the residual, loss, scaling, and identifiability pages.