docs: expand DPA4 water README with Mini/Neo/Air variant comparison

[SchrodingersCattt]

Summary

Expand examples/water/dpa4/README.md with detailed comparison of the three DPA4 model variants (Mini, Neo, Air) from the DPA4-MatPES-v20260628 release.

Changes

• Architecture comparison table: channels, lmax, n_blocks, so2_layers, n_focus for all three variants
• Training hyperparameter comparison: start_lr, batch_size, num_epochs
• Step-by-step guide: how to modify input.json descriptor, learning_rate, and training sections to switch between Mini/Neo/Air
• Validation metrics: Energy MAE, Force MAE, model parameter counts
• Usage instructions: download, test, freeze, and fine-tune pretrained checkpoints
• References: DPA4 paper (arXiv:2606.02419), DeePMD-kit docs, MatPES dataset

All data sourced from the official AIS Square model page and the released training config files.

-- Co-authored by: https://matmaster.bohrium.com/matmaster/

Summary by CodeRabbit

• New Features
  • Added ready-to-use example training configurations for three DPA4 water model variants: Air, Neo, and Mini.
  • Expanded the documentation with a clear comparison of the available model variants and how to switch between them.
  • Reorganized the example input-file guidance into a more readable format with updated pointers to the variant configs.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR documents DPA4 model architecture variants (Air, Neo, Mini) in the water example README, adding a comparison table of descriptor keys and reorganizing the Input files section. It also adds three new example JSON training configuration files under arc_variants/ for these variants.

Changes

DPA4 architecture variants

Layer / File(s)	Summary
README variant documentation examples/water/dpa4/README.md	Adds a "Model architecture variants" section with a descriptor key comparison table (channels, lmax, n_blocks, so2_layers, n_focus), reworks the Input files section into a bulleted list referencing arc_variants/, and relocates the Run heading.
Example input configuration files examples/water/dpa4/arc_variants/input-air.json, examples/water/dpa4/arc_variants/input-neo.json, examples/water/dpa4/arc_variants/input-mini.json	Introduces three new JSON configs defining model descriptor/fitting-net hyperparameters, learning-rate schedule, energy loss settings, HybridMuon optimizer, and training/data/checkpoint/logging parameters for each architecture variant.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the README documentation update comparing the Mini, Neo, and Air DPA4 variants.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

examples/water/dpa4/README.md (1)

23-36: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify how to invoke the arc_variants/ files given relative dataset paths.

The variant JSON files (e.g. arc_variants/input-air.json) use "../data/data_0" for training_data.systems, same as the baseline input.json. DeepMD resolves these paths relative to the current working directory at invocation time, not relative to the JSON file's location. The "Run" section (Line 37+) only documents cd examples/water/dpa4 && dp --pt train input.json; it doesn't show how to run a variant (e.g., dp --pt train arc_variants/input-air.json from the same examples/water/dpa4 directory). If a user instead cds into arc_variants/ before running, the relative path would resolve one level too shallow and fail to find the dataset.

Consider adding an explicit example invocation for the variants next to this bullet to avoid path-resolution confusion.

📝 Suggested addition

 - `arc_variants/`: input files for DPA4-Air, DPA4-Neo, and DPA4-Mini
   architectures.
+
+  Run a variant from `examples/water/dpa4` (do not `cd` into `arc_variants/`),
+  e.g.:
+  ```bash
+  dp --pt train arc_variants/input-neo.json
+  ```

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/water/dpa4/README.md` around lines 23 - 36, The arc_variants/
entries need an explicit usage example because their training_data.systems paths
are resolved from the current working directory, not the JSON location. Update
the README’s input-files section by adding a clear invocation example for one of
the arc_variants JSONs using the same examples/water/dpa4 working directory, and
reference arc_variants/input-air.json or arc_variants/input-neo.json so users
know not to run it from inside arc_variants/.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/water/dpa4/README.md`:
- Around line 23-36: The arc_variants/ entries need an explicit usage example
because their training_data.systems paths are resolved from the current working
directory, not the JSON location. Update the README’s input-files section by
adding a clear invocation example for one of the arc_variants JSONs using the
same examples/water/dpa4 working directory, and reference
arc_variants/input-air.json or arc_variants/input-neo.json so users know not to
run it from inside arc_variants/.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7074b342-13cc-430a-ae7e-95b283d60198

📥 Commits

Reviewing files that changed from the base of the PR and between 0f19772 and 5adc1b8.

📒 Files selected for processing (4)

• examples/water/dpa4/README.md
• examples/water/dpa4/arc_variants/input-air.json
• examples/water/dpa4/arc_variants/input-mini.json
• examples/water/dpa4/arc_variants/input-neo.json

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.09%. Comparing base (0f19772) to head (181fc04).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5711      +/-   ##
==========================================
- Coverage   81.22%   81.09%   -0.13%     
==========================================
  Files         980      980              
  Lines      109356   109355       -1     
  Branches     4206     4205       -1     
==========================================
- Hits        88821    88679     -142     
- Misses      19013    19152     +139     
- Partials     1522     1524       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.