GeoPrior-v3 is an open, reproducible research codebase for physics-guided machine learning in geohazard forecasting and risk assessment. Today, it focuses on land subsidence via GeoPriorSubsNet; next, it expands toward landslides and broader geohazard regimes.
GeoPrior is built to answer practical scientific questions:
- Physics-consistent forecasting — Can predictions respect governing constraints (e.g., consolidation / groundwater dynamics)?
- Generalization across cities/regions — Can one workflow adapt to different regimes with a consistent packaging strategy?
- Uncertainty that supports decisions — How reliable are forecast intervals, and where do risks concentrate?
- Reproducibility — Can reviewers and researchers re-run results end-to-end (GitHub + Code Ocean)?
Current focus
- Land subsidence forecasting with GeoPriorSubsNet v3.2
- Physics residual monitoring + learned closures (e.g., effective parameters)
Planned
- Landslide forecasting modules (susceptibility + triggers + dynamics)
- Multi-hazard risk analytics (composable workflows and diagnostics)
pip install geoprior-v3This installs GeoPrior and the scientific Python stack it depends on. Python 3.10+ is supported.
git clone https://github.com/earthai-tech/geoprior-v3.git
cd geoprior-v3
pip install -e .[dev]The [dev] extra installs testing and tooling dependencies
(e.g., pytest, coverage, black, ruff).
import geoprior as gp
from geoprior.logging import get_logger, initialize_logging
initialize_logging(verbose=False)
log = get_logger(__name__)
log.info("GeoPrior logging is ready.")GeoPrior now exposes a family-based CLI.
The root entry point is geoprior, and dedicated shortcuts are also
available for the run, build, and plot families.
geoprior-init --help
geoprior --help
geoprior-run --help
geoprior-build --helpTo create nat.com/config.py interactively:
geoprior-initThe canonical root form is:
geoprior run <command> [args]
geoprior build <command> [args]
geoprior plot <command> [args]Family-specific entry points avoid repeating the family name:
geoprior-run <command> [args]
geoprior-build <command> [args]
geoprior-plot <command> [args]Examples:
geoprior run stage1-preprocess
geoprior-run stage2-train --help
geoprior build full-inputs-npz --help
geoprior-build physics-payload-npz --help
geoprior-run sm3-suite --preset tau50 --help| Family | Command | Purpose |
|---|---|---|
run |
stage1-preprocess |
Stage-1 preprocessing and artifact export. |
run |
stage2-train |
Train the main GeoPrior model. |
run |
stage3-tune |
Hyperparameter tuning workflow. |
run |
stage4-infer |
Inference, evaluation, and export from trained runs. |
run |
stage5-transfer |
Cross-city transfer evaluation. |
run |
sensitivity |
Run physics or lambda sensitivity workflows. |
run |
sm3-identifiability |
Run one SM3 synthetic identifiability experiment. |
run |
sm3-suite |
Launch preset SM3 regime suites such as tau50 or both50. |
run |
offset-diagnostics |
Run SM3 log-offset diagnostics. |
build |
full-inputs-npz |
Merge Stage-1 split input NPZ files into one union NPZ. |
build |
physics-payload-npz |
Export a physics payload NPZ from a trained model and inputs. |
build |
external-validation-metrics |
Compute borehole or external validation metrics. |
build |
external-validation-fullcity |
Build the full-city validation workflow end to end. |
build |
assign-boreholes |
Assign validation boreholes to the nearest city cloud. |
build |
add-zsurf-from-coords |
Merge elevation lookup tables and add z_surf to tabular data. |
build |
sm3-collect-summaries |
Combine per-regime SM3 summary CSV files into one table. |
Typical usage:
geoprior run stage1-preprocess
geoprior run stage2-train
geoprior build full-inputs-npz
geoprior-build external-validation-metrics --help
geoprior-run sm3-suite --preset tau50A typical end-to-end workflow is organized as:
- Stage-1 preprocessing
- Stage-2 training
- Stage-3 tuning
- Stage-4 inference
- Stage-5 transfer evaluation
- supplementary build and diagnostic commands
Example:
geoprior run stage1-preprocess
geoprior run stage2-train
geoprior run stage4-infer --help
geoprior build external-validation-metrics --help
geoprior build sm3-collect-summaries --helpGeoPrior-v3 is designed for end-to-end reproducible science.
- Stable configs via
nat.com/config.pyand CLI overrides - Deterministic pipeline stages exposed through
geoprior run ... - Reusable artifact builders exposed through
geoprior build ... - Capsule-friendly execution via
codeocean/
If you publish results, please pin:
- the GeoPrior version (tag / release)
- config files used
- CLI commands invoked
- environment definition (e.g.,
environment.yml)
For detailed usage, API reference, workflow guides, and example galleries, please visit the official documentation:
The GeoPrior research core is openly available to support reproducible scientific research.
In addition, GeoPrior includes the GeoPrior 3.0 Forecaster App, which offers a complete GUI-based application workflow built on top of the research framework. This application version is maintained separately from the public repository, which focuses on the core scientific and reproducible modules.
For access to the GeoPrior 3.0 Forecaster App, please contact the author directly.
- App tutorial: https://youtu.be/JtOpX5lv4iw
- Example simulation run: https://youtu.be/nCouLQQFpQg
Contributions are welcome.
- Check the Issues tracker for bugs or ideas.
- Fork the repository.
- Create a new branch for your feature/fix.
- Add tests when applicable.
- Open a Pull Request.
Please see CONTRIBUTING.md for details.
GeoPrior-v3 is distributed under the Apache License 2.0.
See LICENSE and NOTICE for details.
- Bug reports & feature requests: GitHub Issues
- Author: Laurent Kouadio — https://lkouadio.com/
- Email: etanoyau@gmail.com