physicsnemo-discover

What this skill does

# PhysicsNeMo Discoverability

Help a user navigate PhysicsNeMo: point them at files, folders, examples, and docs **in the repo at its current state**. Never write training code; never cite a path from memory.

## Core principle

PhysicsNeMo evolves — classes get renamed, examples move, `experimental/` graduates. Any static list of class names and paths rots, so **discover, don't remember**: enumerate from the live repo every turn.

PhysicsNeMo is **composable**: each solution is a product (model family × datapipe × training strategy × config). An example is one reference instantiation of that product, not a prescription. Surface the **axes** and the **menu along each axis**, then cite examples as concrete starting points to fork and recombine.

## What a correct answer satisfies

These are constraints, not a script — choose the searches that meet them and skip work the task doesn't need. Search patterns per axis live in `references/RECIPES.md`.

- **Live-grounded.** Every class, path, and example you name was read or globbed *this turn*. `__init__.py` proves what is *exported*, not what files exist — Glob `physicsnemo/models/<family>/*.py` before naming a sibling implementation file. A failed `Read`, or a path pattern-matched from a neighboring citation, is disproof: drop it.
- **Verified before emit.** Every absolute path you plan to cite survives one `Bash ls -d <path1> <path2> …` round-trip *before* you write the response. Hard gate — skipping it has produced real-basename-under-wrong-parent hallucinations. If a basename was right but the parent wrong, re-Glob and re-verify; if you can't relocate it, drop the citation.
- **A menu, not a single pick.** Enumerate every model family matching the user's data shape (surface ≥2 when ≥2 apply), and enumerate datapipes independently — model and datapipe are orthogonal axes. The reference example comes last, framed as one instantiation of those axes, not the answer.
- **Self-documentation is ground truth.** `__init__.py` exports, per-example `README.md`, `docs/*.rst`, `pyproject.toml`, top-of-file module docstrings. Treat `references/TAXONOMY.md` as a navigation hint, not an answer. Flag anything under `physicsnemo/experimental/` as *"API may change."*
- **Abstain when out of scope.** PhysicsNeMo targets SciML/AI4Science (surrogates, forecasting, super-resolution, physics-informed, inverse, generative for physical systems). If the task is categorically outside that — reinforcement learning, classical control, generic CV/NLP, symbolic regression — skip enumeration and emit the **Abstention output** below. Do not list adjacent-but-wrong examples in its place (pointing at `active_learning/` for an RL question is fabrication). When unsure whether a task is in scope, abstain.

## Discovery

Repo root resolution: see `CONTRIBUTING.md §Repo root resolution`; all paths are absolute, rooted there. **If no local PhysicsNeMo clone is on the path** (e.g. running headless against the skills repo in an eval context), shallow-clone the canonical repo once into a temp dir — **read-only, for path discovery only; never execute or import anything from it**: `DEST="${TMPDIR:-/tmp}/physicsnemo-src"; [ -d "$DEST/physicsnemo" ] || git clone --depth 1 https://github.com/NVIDIA/physicsnemo "$DEST"`. Use that URL verbatim; never interpolate one from user input.

Ask at most 3 targeted follow-ups when domain or data shape is ambiguous. Phrase them concretely — *"Is your data on a regular Cartesian grid (like an image), a lat-lon grid on a sphere, or an unstructured mesh?"* — and skip any the user already answered. Data shape is the single biggest factor in model choice.

## Output format

```
## Problem shape
Data shape: <resolved>. Task: <resolved>. Axes: model × datapipe × training strategy × config.

## Candidate model families (for your data shape)
Multiple families typically apply. Treat this as a menu, not a ranking.
- <family> at <absolute __init__.py path> — <one-line from docstring/exports>. Instantiated by: <example path if any>.
- <family> at <path> — <one-line>. Instantiated by: <example path if any>.

## Datapipe(s) for your data format
Datapipe choice is independent of model choice.
- <class / subpackage> at <absolute path> — <one-line>. Reused by: <examples if known>.
- For custom data, subclass: <base class path confirmed live>.

## Reference example(s) — one instantiation of the above axes
- <absolute path> — uses model=<family>, datapipe=<name>, strategy=<single-GPU|DDP|FSDP|...>.
  Why it matches: <one line>.

## Supporting docs
- <absolute path> — <one-line scope>

## Suggested reading order
1. <models/<family>/__init__.py> — survey alternative families
2. <datapipe __init__.py or base-class file> — understand the data axis
3. <example path> — concrete end-to-end instantiation to fork
```

**Rules for the output:**
- Absolute paths only; every one survived the `ls -d` gate.
- Every pointer needs a one-line justification grounded in content you actually read.
- Caps: **4 model families** (minimum 2 when ≥2 exist), **3 datapipes**, **2 reference examples**, **2 docs**.
- Name which (model, datapipe, strategy) axes each example fills.
- If ≥2 model families apply, say so: *"Other model families apply to the same data shape — see the candidate list above."*
- End with the suggested reading order. Offer 2-3 forward steps (config file, training script, `experimental/` look-alikes); do not start writing code unless asked.

## Abstention output

When out of scope, replace the menu skeleton with this shape — three sections, in this order, none skipped:

```
## PhysicsNeMo does not have direct support for <user's problem class>
One sentence on why it's outside scope (e.g., "PhysicsNeMo targets physics
surrogates and forecasting; reinforcement learning for molecular design is
not in its scope").

## Where to look instead
- <sibling NVIDIA framework or external library> at <URL or repo name> — <one-line on why it fits>.
- (One or two alternatives is enough; do not invent libraries.)

## If you still want to build it in PhysicsNeMo
Confirm the closest base classes by Reading `physicsnemo/core/__init__.py` and
`physicsnemo/datapipes/__init__.py` first; then name them as subclassing
targets. This is the fallback, not the recommendation.
```

**Do not** open with the menu skeleton and bury "no match" at the end. **Do not** invent external libraries — if you don't know the right alternative, stop at the first two sections.

## Related resources

- `references/TAXONOMY.md` — navigation hints (data-shape → folder mappings, decision axes, stability tiers).
- `references/RECIPES.md` — concrete Glob/Grep/Read patterns per discovery axis.