Physicsnemo Discover

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.

Evaluation Report

Evaluation of the physicsnemo-discover skill before publication through NVSkills-Eval.

This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.

Evaluation Summary

• Skill: physicsnemo-discover
• Evaluation date: 2026-05-29
• NVSkills-Eval profile: external
• Environment: local
• Dataset: 4 evaluation tasks
• Attempts per task: 2
• Pass threshold: 50%
• Overall verdict: PASS

Agents Used

• claude-code
• codex

Metrics Used

Reported benchmark dimensions:

• Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
• Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
• Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
• Effectiveness: checks whether the agent performs measurably better with the skill than without it.
• Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.

Underlying evaluation signals used in this run:

• security (Security): checks for unsafe operations, secret leakage, and unauthorized access.
• skill_execution (Skill Execution): verifies that the agent loaded the expected skill and workflow.
• skill_efficiency (Efficiency): checks routing quality, decoy avoidance, and redundant tool usage.
• accuracy (Accuracy): grades final-answer correctness against the reference answer.
• goal_accuracy (Goal Accuracy): checks whether the overall user task completed successfully.
• behavior_check (Behavior Check): verifies expected behavior steps, including safety expectations.
• token_efficiency (Token Efficiency): compares token usage with and without the skill.

Test Tasks

The benchmark dataset contained 4 evaluation tasks:

• Positive tasks: 2 tasks where the skill was expected to activate.
• Negative tasks: 2 tasks where no skill was expected.
• Unlabeled tasks: 0 tasks where positive/negative intent could not be inferred.

Task composition is derived from the evaluation dataset when possible. Entries with expected_skill set are treated as positive skill-activation cases, while entries with expected_skill: null are treated as negative activation cases.

Results

Score values show skill-assisted performance. Values in parentheses show uplift versus the no-skill baseline when baseline data is available.

Tier 1: Static Validation Summary

Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 10 total findings.

Top findings:

• MEDIUM QUALITY/quality_discoverability: Description contains vague words (skills/physicsnemo-discover/SKILL.md)
• MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (skills/physicsnemo-discover/SKILL.md)
• MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (skills/physicsnemo-discover/SKILL.md)
• MEDIUM SECURITY/Unknown (SDI-2): The skill instructs an agent to shallow-clone an external Git repository (https://github.com/NVIDIA/physicsnemo) into a (SKILL.md:37)
• LOW QUALITY/quality_discoverability: Description very long (504 chars, recommend 50-150) (skills/physicsnemo-discover/SKILL.md)

Tier 2: Deduplication Summary

Tier 2 validation passed. NVSkills-Eval ran 2 checks and found 0 total findings.

Notable observations:

• Context Deduplication: Collected 3 file(s)
• Inter-Skill Deduplication: Parsed skill 'physicsnemo-discover': 504 char description

Publication Recommendation

The skill is suitable to proceed toward NVSkills-Eval publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

Search Recipes — How to discover PhysicsNeMo artifacts live

Concrete Glob / Grep / Read patterns the skill should use to discover what's actually in the repo, instead of relying on a static inventory. All paths are relative to the resolved repo root.

Guiding rule

If you are about to name a class, file, or example, run at least one search below first to confirm it exists and capture its current description.

---

1. Confirm the repo root

Read <root>/pyproject.toml                  # check name == "nvidia-physicsnemo"
Glob <root>/physicsnemo/__init__.py         # must exist
Glob <root>/examples/README.md              # usually exists

If any of these fail, ask the user to confirm the path.

---

2. Find examples for a domain

# 2a. Enumerate examples in the target domain
Glob examples/<domain>/**/README.md

# 2b. Read each README's top (title + first paragraph) to match user intent
Read examples/<domain>/<candidate>/README.md   # limit=30

# 2c. When READMEs are ambiguous, inspect the training script imports to see
#     which models / datapipes the example actually uses
Grep "from physicsnemo" examples/<domain>/<candidate>/ --type py -n --head_limit 20

If the user's domain keyword doesn't map cleanly to a folder name:

# 2d. Broad search for concept across all examples
Grep -l "<concept keyword>" examples/ --type md
Grep -l "<concept keyword>" examples/ --type py

---

3. List currently-exported models across ALL families matching a data shape

The skill's output surfaces a menu of candidate families, not a single pick. Enumerate every family the taxonomy's data-shape row lists — not just the first one that looks plausible.

# 3a. Top-level model registry exports — the full top-level menu
Read physicsnemo/models/__init__.py

# 3b. Per-family loop — for EACH candidate family from the taxonomy data-shape row,
#     confirm the subdir exists and read its exports. Do not stop after one match.
Glob physicsnemo/models/<family>/__init__.py
Read physicsnemo/models/<family>/__init__.py
# repeat for every candidate family in the data-shape row

# 3c. Extract purpose from a specific model's docstring (after 3b has surfaced the family)
Grep -n "^class " physicsnemo/models/<family>/<file>.py
Read physicsnemo/models/<family>/<file>.py     # limit ~80 lines around the class

# 3d. Cross-reuse: find which examples instantiate each candidate family.
#     This feeds the "Instantiated by: <example>" annotation in the output skeleton.
Grep -rn "from physicsnemo.models.<family>" examples/ --type py -l

For experimental models:

Glob physicsnemo/experimental/models/**/__init__.py
Read physicsnemo/experimental/models/<family>/__init__.py

Always flag experimental matches as "API may change".

---

4. List currently-exported datapipes for a format

# 4a. Top-level datapipes exports
Read physicsnemo/datapipes/__init__.py

# 4b. Subpackage exports — enumerate live rather than assuming names
Glob physicsnemo/datapipes/*/__init__.py
Read physicsnemo/datapipes/<subpackage>/__init__.py

# 4c. Base classes for custom data
#     See TAXONOMY.md § Data format → how to find a datapipe for the
#     full file paths + confirmation steps. Commands below are quick
#     reference.
Grep -n "^class " physicsnemo/datapipes/readers/base.py
Grep -n "^class " physicsnemo/datapipes/datapipe.py
Grep -n "^class " physicsnemo/datapipes/transforms/base.py

For format-specific discovery:

Grep -l "<format name, e.g. HDF5, Zarr, VTK>" physicsnemo/datapipes/ --type py

---

5. List currently-exported core utilities

# 5a. For a known module (distributed, utils, metrics, mesh, diffusion, etc.)
Read physicsnemo/<module>/__init__.py

# 5b. If the init is thin, list the files and sample headers
Glob physicsnemo/<module>/*.py
Grep -n "^(class|def) " physicsnemo/<module>/<file>.py --head_limit 20

For submodules (e.g. utils/logging/, utils/profiling/, metrics/climate/):

Glob physicsnemo/<module>/*/__init__.py
Read physicsnemo/<module>/<submodule>/__init__.py

---

6. Find documentation pages

# 6a. Top-level doc indexes
Read docs/index.rst
Read docs/api_index.rst
Read docs/examples_index.rst

# 6b. Domain example indexes
Glob docs/examples_*.rst
Read docs/examples_<domain>.rst

# 6c. API doc for a specific module
Glob docs/api/**/*.rst
Read docs/api/<path>.rst

# 6d. Broad search
Grep -l "<concept>" docs/ --glob "*.rst"

---

7. Confirm a specific class / function exists

# 7a. Search by class name across physicsnemo
Grep -n "^class <ClassName>" physicsnemo/ --type py

# 7b. Search by function name
Grep -n "^def <func_name>" physicsnemo/ --type py

# 7c. If not found where expected — check compat layer for renames
Read physicsnemo/compat/__init__.py

If a name isn't found anywhere, it may have been renamed. Do not emit it.

---

8. Check scale / distribution patterns used in an example

# Does this example use DDP, FSDP, domain parallelism?
Grep -n "DistributedManager\|FSDP\|ShardTensor\|torch.distributed" examples/<domain>/<example>/ -l
Grep -n "DistributedManager\|FSDP\|ShardTensor\|torch.distributed" examples/<domain>/<example>/ --type py

---

9. Decide between similar examples

When the user's description matches multiple examples, compare by:

# 9a. README purpose statements (first 20 lines)
Read examples/<domain>/<cand_a>/README.md   # limit 20
Read examples/<domain>/<cand_b>/README.md   # limit 20

# 9b. Data format used (training script imports + file globs)
Grep -n "h5py\|zarr\|xarray\|pyvista\|tfrecord\|numpy.load" examples/<domain>/<cand>/ --type py
Glob examples/<domain>/<cand>/**/*.yaml      # Hydra configs often hint at scale + data

Pick the example whose README purpose statement and data format match the user's situation most closely.

---

10. Fallback: pure keyword search

If the user's phrasing doesn't map to any taxonomy entry:

Grep -l "<user keyword>" examples/ --type md
Grep -l "<user keyword>" physicsnemo/ --type py
Grep -l "<user keyword>" docs/ --glob "*.rst"

---

11. Check shared datapipe across examples

See TAXONOMY.md § Cross-example reuse patterns for the rationale and known reuse cases (Darcy2D, ERA5, VTK). The recipe below is the mechanical step: grep the datapipe class across examples/ and surface confirmed reuse in the output.

# 11a. Which examples import a given datapipe class?
Grep -rn "<DatapipeClass>" examples/ --type py -l

# 11b. Which models do those examples pair the datapipe with?
#      Run for each example surfaced by 11a.
Grep -n "from physicsnemo.models" examples/<domain>/<example>/ --type py

Use the result to annotate the "Datapipe(s) for your data format" section with "Reused by: <examples>" and to pick reference examples that span ≥2 model families on the same data.

---

Output discipline

Every pointer you emit must be traceable to a tool result in the current turn. If you cannot show where you just read it, don't emit it. This is how the skill stays honest as the repo evolves.

PhysicsNeMo Taxonomy — Navigation Hints

This file is a navigation scaffold, not an inventory. It tells you which top-level folder(s) to search given the user's problem shape. The actual class and file names come from the live repo via Glob/Grep/Read — never cite from this file.

All paths are relative to the repo root (resolve per SKILL.md).

---

Top-level package map (high-stability)

These package directories change only at major releases. Use them as entry points; search inside for current contents.

Folders may be added, graduated out of experimental/, or removed between releases. Glob physicsnemo/*/ at the start of discovery and trust that over this table.

---

Data shape → candidate model families (primary routing axis)

The data shape is the primary routing axis. Multiple model families typically apply to a given shape — this table lists the subdirectories worth searching. Exact class names come from __init__.py at search time.

Enumerate ALL candidate families listed for the row that matches the user's data shape — not just the first. When translating to concrete classes, read every relevant physicsnemo/models/<family>/__init__.py. The output skeleton in SKILL.md expects a menu, not a single recommendation.

Cross-example reuse patterns

Datapipes and problems are often shared across model families — that shared structure is what makes the framework composable. Worth checking whether the same datapipe is used by multiple families:

• Darcy-style 2D regression data typically feeds multiple model families (e.g. spectral operators and attention-based operators on the same Darcy2D).
• ERA5 climate data underlies several weather architectures simultaneously.
• VTK / point-cloud geometry inputs are consumed by more than one geometry-aware operator family.

These are hints to verify live, not ground truth: grep the candidate datapipe class across examples/ to confirm current reuse, then surface that reuse in the output so the user sees model ↔ datapipe decoupling explicitly.

---

Example domain map (secondary navigation)

Domains are a secondary navigation layer — useful for finding concrete reference instantiations once the model-family and datapipe menus are known. Subfolder names inside these may change — always Glob the current contents.

If the user's domain isn't listed, Glob examples/*/ and read top-level READMEs to find the closest.

---

Data format → how to find a datapipe

Do not hardcode format-to-subfolder mappings here — the datapipes layout changes. Instead:

1. Glob physicsnemo/datapipes/*/__init__.py to enumerate current subpackages. 2. Read each __init__.py to see what it exports and what formats its docstrings mention. 3. If no subpackage looks right, grep by format keyword across physicsnemo/datapipes/: Grep -l "<format>" physicsnemo/datapipes/ --type py (e.g. "HDF5", "zarr", "xarray", "pyvista", "tfrecord", "healpix"). 4. For custom / unsupported formats, point users at the contractual base classes: physicsnemo/datapipes/readers/base.py, physicsnemo/datapipes/datapipe.py, physicsnemo/datapipes/transforms/base.py. Confirm these files still exist before citing them.

---

Task type → relevant concepts to search

---

Documentation map

Always Glob docs/ before citing — the RST layout evolves.

---

External resources and companion packages

URLs for hosted docs, the dev blog, the pretrained-model catalog, the Jupyter collection, the forum, and companion repos (CFD inference, Curator, Symbolic, Earth-2 Studio) rot and should not be hardcoded here. Look them up from the canonical sources in the repo itself:

• Root README.md — links section and companion-package mentions.
• Root FAQ.md — hosts current URLs for forum, NGC catalog, and related repos.

Grep these two files for https:// when you need a URL, and cite what you find — don't recite from memory.

---

Decision hints (axes of choice, not class names)

Use these to ask the right disambiguating question. Do not emit a concrete class or family name from this section — resolve current names via live discovery in physicsnemo/models/ and the relevant examples/<domain>/.

• Super-resolution / downscaling: deterministic vs stochastic (diffusion-based). Ask which.
• Surrogate for a CFD sim on a geometry: surface-only vs surface+volume input. Ask which, then search physicsnemo/models/ for operators that take the right input shape.
• Global weather forecasting: multiple architecture families coexist (spectral, mesh-graph, 3D transformer). Read examples/weather/ and physicsnemo/models/ __init__.py files to see the current options.
• Regional km-scale weather: typically different from global — confirm scope, then discover candidates in examples/weather/.
• PDE with arbitrary geometry: point-cloud / transformer operators; some may still live in experimental/.
• Molecular / particle dynamics: graph networks with nearest-neighbor or radius-based connectivity.
• Learn a solution operator for a PDE: regular-grid vs irregular-geometry is the splitting axis; the current operator families differ on each side.

These hints are deliberately vague on class names — the skill must confirm against the live repo before emitting any.

---

Common axis-collapse traps to flag

Axes of choice users frequently collapse. Surface the distinction; let live discovery name the current candidates — do not hardcode family names.

• Grid vs mesh conflation. Cartesian grid and triangulated mesh need different model families.
• Weather scope. Global vs regional km-scale forecasting typically route to different architectures.
• CFD with geometry + fields. Surface-only vs surface+volume is the splitting axis.
• Super-resolution / downscaling. Deterministic vs stochastic (diffusion-based) is the user's call.
• Physics-informed ≠ PINN. Physics loss on a neural operator, coordinate MLP + PDE residuals, or hybrid map to different parts of the repo.
• GNN backend migration. PhysicsNeMo is moving from DGL to PyG. Locate the migration doc by globbing — Glob examples/**/*pyg*.md or Glob examples/**/*migration*.md. Do not cite a path from memory.
• modulus → physicsnemo rename. If snippets import modulus, point at the migration guide by globbing *MIGRATION*.

Stability of what you cite

• High stability: top-level folders directly under physicsnemo/, the examples/<domain>/ split, the docs/ Sphinx layout. Use as navigation anchors; Glob current contents at the start of discovery.
• Medium stability: subdirectories inside top-level folders, example folder names.
• Low stability: specific class names, specific file paths inside subdirectories, anything under experimental/.

When citing from a medium- or low-stability area, confirm it exists now before returning it.

Description: <br>

Official NVIDIA-authored guidance for navigating PhysicsNeMo — pick the model, datapipe, or example for a SciML/AI4Science task (surrogates, forecasting, downscaling, physics-informed, inverse, generative). <br>

This skill is ready for commercial/non-commercial use. <br>

Owner

NVIDIA <br>

License/Terms of Use: <br>

Apache-2.0 <br>

Use Case: <br>

Developers and engineers navigating the PhysicsNeMo repository to identify which model families, datapipes, examples, and documentation apply to their scientific machine learning or AI4Science problem. <br>

Deployment Geography for Use: <br>

Global <br>

Known Risks and Mitigations: <br>

Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br> Mitigation: Review and scan skill before deployment. <br>

Reference(s): <br>

• TAXONOMY.md <br>
• RECIPES.md <br>
• PhysicsNeMo GitHub Repository <br>

Skill Output: <br>

Output Type(s): [Analysis, File path citations] <br> Output Format: [Markdown] <br> Output Parameters: [1D] <br> Other Properties Related to Output: [None] <br>

Evaluation Agents Used: <br>

• Claude Code (claude-code) <br>
• Codex (codex) <br>

Evaluation Tasks: <br>

Evaluated against 4 internal evaluation tasks (2 positive skill-activation, 2 negative) with 2 attempts per task via NVSkills-Eval. <br>

Evaluation Metrics Used: <br>

Reported benchmark dimensions: <br>

• Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
• Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
• Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
• Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
• Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>

Underlying evaluation signals used in this run: <br>

• security: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
• skill_execution: Verifies that the agent loaded the expected skill and workflow. <br>
• skill_efficiency: Checks routing quality, decoy avoidance, and redundant tool usage. <br>
• accuracy: Grades final-answer correctness against the reference answer. <br>
• goal_accuracy: Checks whether the overall user task completed successfully. <br>
• behavior_check: Verifies expected behavior steps, including safety expectations. <br>
• token_efficiency: Compares token usage with and without the skill. <br>

Evaluation Results: <br>

Skill Version(s): <br>

0.1.0 (source: pyproject.toml) <br>

Ethical Considerations: <br>

NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br> Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns here. <br>