🚀[FEA]: Add hydrology example — attribute-conditioned physics-UDE across a 61-well aquifer (already-working PhysicsNeMo port)

Is this a new feature, an improvement, or a change to existing functionality?

Improvement (new example)

How would you describe the priority of this feature request

Medium — donates a working PhysicsNeMo port + real observational benchmark to the examples set.

Please provide a clear description of problem you would like to solve.

PhysicsNeMo currently ships three Darcy examples (examples/cfd/darcy_physics_informed, darcy_nested_fnos, darcy_transolver). All three solve steady, saturated, linear Darcy on synthetic square domains with random K fields. Great for showing the ML pipelines; nothing yet for transient subsurface flow with real observational data, which is what practicing hydrogeologists and physical-science reviewers want to see.

There's also no example in the repo that shows how to use physicsnemo.Module + .mdlus checkpointing to wrap a domain-specific inductive-bias model (mass-balance ODE + attribute-conditioned hypernetwork) — a natural pattern for physics-ML across many similar systems (many wells, many turbines, many patients, many reactors).

What I'd like to donate

I maintain HydroPhysicsAI — a MIT-licensed physics-informed neural operator for groundwater, trained across all 61 monitoring wells of the Zhuoshui alluvial fan (Taiwan, 2012–2022, out-of-sample validation from 2019). It already includes a working PhysicsNeMo port (hydrophysics/models/ude_physicsnemo.py, class PhysicsNeMoUDE, invoked via --model ude_nemo) that reproduces the PyTorch reference at KGE 0.591 with .mdlus native checkpointing.

I'd like to strip this down to physicsnemo example conventions and contribute it as a first-class example.

What the example would demonstrate:

• A physicsnemo.Module subclass whose forward computes an attribute → ODE-parameter hypernetwork.
• A semi-implicit ODE rollout with a physics-residual collocation loss (mass balance + recession + rainfall recharge memory + ET + upstream coupling).
• One shared operator across 61 wells, not per-well calibration — plus leave-one-well-out generalization to wells never seen at training time.
• Native PhysicsNeMo checkpointing via .mdlus (save architecture + weights + metadata in one versioned file).
• Benchmark against a per-well gray-box ODE and climatology, on real observational aquifer data.

Reported skill (already reproduced in HydroPhysicsAI):

Model	Median KGE	Notes
Climatology	0.446	seasonal-mean baseline
Per-well gray-box ODE	0.736	61 hand-calibrated ODEs
Shared physics-UDE (PhysicsNeMo, ude_nemo)	0.591–0.754	one operator, all wells
Leave-one-well-out generalization	0.565	wells never seen at training

How this differs from the existing Darcy examples

Existing (×3)	Proposed
Steady linear Darcy	Transient nonlinear mass-balance ODE
Synthetic K field	Real 61-well observational time-series
Per-realization pipeline	One shared operator across many systems (attribute-conditioned)
Manufactured validation	Real out-of-sample benchmark vs gray-box + climatology
Standard PyTorch container	physicsnemo.Module with .mdlus checkpointing

Alignment with recent example PRs

The cadence of merged community example PRs (radiation transport #1647, GLOBE DrivAerML #1610, Inverse PINN #1627, GLOBE + AirFRANS #1401) shows appetite for self-contained physical-science examples. This proposal follows the same shape.

Dataset packaging plan

To keep the example directory small, I'd propose the same pattern used for large weather datasets in this repo (examples/weather/dataset_download):

• Ship a small curated 2-well demo subset (a few MB) inside the example directory for the CI-friendly smoke run.
• Provide a dataset_download.py that fetches the full 61-well Zhuoshui dataset from HydroPhysicsAI for anyone reproducing the reported KGE numbers.

Happy to adjust if the maintainers prefer a purely synthetic subset that reproduces the pipeline without the observational headline.

Describe any alternatives you have considered

• Do nothing, point users at HydroPhysicsAI externally — loses the physicsnemo showcase and the .mdlus pattern example.
• Contribute only the model class, no data — reproducibility suffers; reviewers can't run the benchmark.
• Wait until a paper is out — the working PhysicsNeMo port already exists and reproduces the reference score; happy to update the README with the paper citation once available.

Questions for maintainers (blockers before I open a PR)

1. Location: examples/cfd/ (aligns with existing Darcy siblings) or a new examples/hydrology/ / examples/subsurface/ group?
2. Dataset packaging: the "small demo subset + external-fetch script for full data" plan above — acceptable, or is there a preferred pattern I should follow?
3. Scope: happy to trim the first PR (single well, single loss term) or keep the full multi-well hypernetwork + recharge-memory + ET treatment. Preference?

Reference material for the review

• Repo: https://github.com/Rekin226/HydroPhysicsAI (MIT)
• Working PhysicsNeMo port: hydrophysics/models/ude_physicsnemo.py
• Model card: MODEL_CARD.md
• Technical writeup: docs/TECHNICAL_WRITEUP.md
• Live HF demo: https://huggingface.co/spaces/Rekin226/HydroPhysicsAI-demo

Willingness to contribute

Yes — I'll open the WIP PR as soon as directions 1–3 are pinned. DCO signoff on file (via NVIDIA/NeMo-Agent-Toolkit PR #2107).

Start by reviewing hydrophysics/models/ude_physicsnemo.py in the linked HydroPhysicsAI repository and the existing Darcy examples under examples/cfd/. Then inspect the examples/weather/dataset_download pattern for dataset handling. The work is complete when a self-contained hydrology example demonstrates the shared 61-well model, smoke-test data, full-data download path, benchmark evaluation, and .mdlus checkpointing.