Geological structure, seismic imaging and hydromechanical petrophysics for Hydrostate.
Mechanicalstate connects Vs, Vp and density images to geological structure and uncertain material priors, then predicts seismic properties from hydraulic states through explicit constitutive models. It is a GAIA Hazlab research alpha, with fixed-grid Hydrostate coupling, prescribed disturbance/recovery, Gaia DataHub interchange, synthetic examples and analytical tests. It does not uniquely invert seismic velocities into porosity/permeability, reproduce a field experiment, or predict mechanical hazards.
The scientific basis includes Shi, Montgomery, Denolle and coauthors, Science (2026), Agroseismology and the impact of farming practices on soil hydrodynamics. The exact implemented depth/rate coefficients are traced to the versioned preprint methods and compared with the public reference implementation. They are kept separate from a general retention/suction-stress model. See the source/version assessment.
| Component | Purpose and limit |
|---|---|
| Structural JSON | Cartesian 3D geology/facies, Vs/Vp/bulk density, porosity and separately specified hydraulic priors, with references, support and uncertainty |
| Hydrostate adapter | Same-grid material export to the actual pinned Richards kernel, with exact grid/reference/mask identity |
| Temporal coupling | Hydrological stepping with prescribed conductivity/retention changes, per-cell water-preserving reconciliation, exact event splits and complete owner restart |
| Disturbance/recovery | Independent elastic damage and hydraulic anomalies with finite exponential recovery modes/permanent changes; amplitudes and timescales are scenario inputs |
| Gaia DataHub | Typed DataTree groups and actual Gaia Zarr I/O for states, materials, interval ledgers, event jumps and checkpoints; a model extension, not an upstream registered dataset |
| Retention and stress | Distinct physical/effective saturation, phase density, VG retention, Bishop/suction-stress and a separate Shi depth/rate closure |
| Elastic response | Hertz–Mindlin with contact-slip parameter, calibrated pressure scaling, stable moduli/velocity transforms |
| Fluid diagnostics | Optional Wood/Gassmann substitution under stated low-frequency homogeneous pressure assumptions |
| Demonstrations/tests | Prescribed wetting/drying history, exact inversion ambiguity, analytical identities and heterogeneous Hydrostate equilibrium/flow checks |
Hydrostate owns pressure, moisture, water storage and flow. Mechanicalstate
supplies structure/material priors, prescribed material evolution and seismic
observation operators. Retention changes conserve
W = theta + Ss max(psi,0) in each unchanged cell; physical saturation and
density use theta, not elastic storage. The separate dynamic-capillary
pressure calculation remains a diagnostic. Feeding non-equilibrium capillary
pressure into flow requires additional constitutive state and verified
conservation/energy equations; prescribed equilibrium-retention changes do
not supply that missing physics.
Python 3.12 or later for the Gaia-enabled workflow:
git clone https://github.com/gaia-hazlab/mechanicalstate.git
cd mechanicalstate
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[plot,dev,integration,datahub]"
python -m unittest discover -s tests -v
mechanicalstate demo --output runs/demo.json --plot runs/demo.png
mechanicalstate hydro-check --structure examples/structure/synthetic_valley.json \
--output runs/hydro_check.json
python scripts/verify_project.py --output runs/verification.json
mechanicalstate couple --days 90 --output runs/coupled
The integration and datahub extras install tested Hydrostate/Gaia revisions
recorded in pyproject.toml. Install just .[plot,dev] for
the constitutive demonstration without the optional hydrological backend.
Core constitutive and hydraulic coupling support Python 3.11+. Gaia persistence
requires Python 3.12+ because the pinned rioxarray>=0.23 requires it; Gaia's
package-level Python minimum alone does not describe this constraint. CI tests
core calculations on 3.11 and the complete Gaia workflow on 3.12.
The coupled example uses the small synthetic valley and a
prescribed event schedule: an
earthquake at a nonhourly timestamp, a preparation-stage material change and
a wildfire. Independent anomalies alter Ks and retention alpha; a
separate elastic-damage field alters the illustrative drained-frame moduli.
Recovery modes can span days, months and years. A disturbance label supplies
no hidden relation from shaking, seismic velocity or burning to material
change.
Hydraulic substeps resolve water evolution, exchange intervals resolve continuous material evolution, and each event cuts an interval at its exact valid time. The driver retains before/after jump fields and complete future event/recovery memory in its checkpoint. Its first-order operator splitting requires coupling-interval refinement even though recovery modes use exact exponential updates.
The compatibility report gives the
equations, API, units, clocks, owner checkpoints and Gaia group layout. It
also explains why gaia align must not transform prognostic/event/restart
groups. Geometry-changing slides are rejected. Root loss and water repellency
are recorded diagnostics; root, surface-flow and fire-heating feedback are
not implemented. The experiment supplies prescribed material scenarios,
not an earthquake, landslide or wildfire dynamics model.
The 90-day check closes the
cumulative water ledger to 5.20e-9 m3 on 70 active cells and verifies actual
Gaia checkpoint/read/continuation equality. A separate
rapid-recovery refinement finds a
0.00777 m final pressure difference between one-hour and 225-second steps.
Hourly coupling is therefore not established as adequate for rapid material
changes; budget closure and format compatibility do not establish accuracy.
For an isotropic elastic interpretation,
G = rho Vs² and K = rho (Vp² − 4Vs²/3).
These determine moduli for that interpretation; hydraulic properties still
depend on mineralogy, contacts, cracks, pore geometry, saturation and stress.
Facies/boreholes/laboratory data provide uncertain retention/permeability
priors. Imaging resolution is distinct from voxel spacing.
Use physical Sw = theta/phi for liquid volume and density. Retention uses
Se = (theta − theta_r)/(theta_s − theta_r); these are different when residual
water is present. A saturated water-content measurement alone cannot determine
positive pore pressure. Intrinsic permeability is converted through
Ks = k rho_water g / viscosity, with all constituent assumptions declared.
The demonstration includes distinct porosity/saturation/contact-pressure sets with identical Vs, Vp and density in its stated drained-frame model. This exposes a real inverse ambiguity rather than hiding it behind one fitted parameter vector. Geological/hydrological information and calibration are needed to resolve it.
The revised integration decision proposes using the existing GAIA soil twin as the regional observation/analysis/orchestration host. Mechanicalstate supplies material/petrophysical/recovery capabilities and Hydrostate supplies selectable hydraulic engines/reference tests. The common protocol must preserve native support, member identity, physical ownership and hazard-specific requirements. This is a proposed integration; posterior cycling and actual hazard consumers remain separate implementation and validation tasks. See the pinned review and independent prompts for Fable / Antigravity.
- Structural contract and Hydrostate bridge.
- Petrophysical equations, assumptions and limits.
- Agroseismology source/version and code-license assessment.
- Hydrostate/Gaia compatibility and temporal coupling.
- Prescribed disturbance, recovery and source evidence.
- Demonstrations and measured verification.
Next scientific stages are independent site/laboratory calibration, imaging support and covariance operators, material ensembles, temporal seismic-data assimilation and a verified dynamic-capillarity feedback model. Nonlinear strength, failure, shaking and deformation belong in separate hazard models; small-strain seismic stiffness is not geotechnical resistance.
src/mechanicalstate/ Constitutive laws, structure, recovery, coupler and demos
examples/structure/ Small synthetic 3D structural/material input
examples/coupling/ Prescribed synthetic event/recovery schedule
docs/technical/ Equations, source assessment and compact evidence
tests/ Analytical, metadata and real-backend integration tests
.github/workflows/ Linux Python 3.11/3.12 tests and generated artifacts
Read AGENTS.md and CONTRIBUTING.md. Our independent code is MIT licensed; cite CITATION.cff and the methods used. FarmDAS reference code is CC BY-NC 4.0 and is linked, not bundled or relicensed. No paper PDFs or observational datasets are bundled.