docs: add DPA3 cyclohexane distillation tutorial

[njzjz-bot]

Summary

• add a getting-started notebook for distilling a cyclohexane Student potential from the DPA3 pretrained Teacher model
• add an Open in Bohrium badge for https://ustc.bohrium.com/notebooks/99176325231/
• add the notebook to the getting-started toctree and use internal documentation links for ASE and dpdata references

Checks

• Parsed the notebook JSON successfully
• Verified there are no CJK characters in the notebook
• Verified source markdown no longer uses external DeePMD documentation URLs for the ASE/dpdata references
• Parsed all plain Python code cells with ast.parse
• Ran git diff --check

Authored by OpenClaw (model: custom-chat-jinzhezeng-group/gpt-5.5)

Summary by CodeRabbit

• Documentation
  • Added a new cyclohexane distillation page to the getting-started guide, expanding the DeePMD-kit “typical procedure” quick-start options with an additional tutorial.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

💤 Files selected but had no reviewable changes (1)

• doc/getting-started/dpa3_cyclohexane_distillation.ipynb

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 31d9e89a-ea1c-42a1-a598-417ec61e6369

📥 Commits

Reviewing files that changed from the base of the PR and between ddceacf and 4b0296c.

📒 Files selected for processing (1)

• doc/getting-started/dpa3_cyclohexane_distillation.ipynb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a comprehensive knowledge distillation tutorial notebook (dpa3_cyclohexane_distillation.ipynb) to the getting-started documentation, demonstrating end-to-end DPA-3 model distillation for cyclohexane. The notebook covers teacher model preparation, dataset generation via MD sampling, student model training, model freezing/compression, student inference, and visualization. A corresponding toctree entry in the getting-started index makes the notebook navigable.

Changes

Knowledge distillation tutorial notebook and documentation navigation

Layer / File(s)	Summary
Notebook setup and dependencies doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Adds notebook introduction, dependency installation instructions, and imports of core libraries (pathlib, numpy, dpdata).
Teacher model preparation doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Downloads DPA-3.2-5M teacher weights and inspects model structure via branch and type map inspection.
Distillation dataset generation doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Generates initial cyclohexane 3D structure from SMILES using Open Babel, runs teacher MD with ASE DP calculator, previews trajectory frames, and writes DeePMD-format training dataset.
Student model training and analysis doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Creates student training configuration with se_atten_v2 descriptor, trains the model via dp --pt train, and plots training RMSE curves from lcurve.out.
Student model freeze, compression, and testing doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Exports frozen student model, compresses it, and evaluates the compressed model on the distillation dataset.
Student MD inference and visualization doc/getting-started/dpa3_cyclohexane_distillation.ipynb	Runs MD with the compressed student model, records energies, plots energy trace, and renders 3D structures of representative frames.
Add dpa3_cyclohexane_distillation toctree entry doc/getting-started/index.rst	Registers the new distillation tutorial notebook as a navigable page in the getting-started documentation index.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'docs: add DPA3 cyclohexane distillation tutorial' accurately and clearly summarizes the main change: adding a new documentation tutorial notebook for DPA3 cyclohexane distillation.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.14%. Comparing base (4b6506d) to head (4b0296c).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5564      +/-   ##
==========================================
- Coverage   82.17%   82.14%   -0.03%     
==========================================
  Files         898      900       +2     
  Lines      103576   104138     +562     
  Branches     4432     4473      +41     
==========================================
+ Hits        85117    85548     +431     
- Misses      17063    17181     +118     
- Partials     1396     1409      +13     

☔ 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.

[iProzd]

A few issues should be fixed before merging:

1. The text repeatedly says the workflow extracts/trains on energy, force, and virial labels, but the generated dataset contains only energy/force and the training config sets the virial loss weights to 0. Please update the wording to avoid implying that virials are used in this case.

2. Some saved notebook outputs show “3Dmol.js failed to load” with large inline JavaScript blocks. These should be cleared or replaced with static outputs before adding the notebook to the official docs.

3. The text says the Teacher MD uses 5,000 steps, but the code sets MD_STEPS = 500. Please make these consistent.

[njzjz]

I'll let the agent fix 1 and 3. Regarding 2,

• Some saved notebook outputs show “3Dmol.js failed to load” with large inline JavaScript blocks. These should be cleared or replaced with static outputs before adding the notebook to the official docs.

3Dmol is rendered correctly on the web page. https://deepmodeling--5564.org.readthedocs.build/projects/deepmd/en/5564/getting-started/dpa3_cyclohexane_distillation.html

[wanghan-iapcm]

The notebook is committed with all executed outputs, which should be stripped before merge (the reference quick_start.ipynb has clean outputs). Concretely: this pip install cell carries a ~53KB log full of ANSI progress bars and Tsinghua-mirror URLs (pypi.tuna.tsinghua.edu.cn), plus /opt/mamba/... paths and pinned versions; the outputs also include Bohrium/Kaggle kernel-protocol fields (parent_header, id, meta) and doubly-nested stream outputs that are not valid nbformat; and the notebook metadata retains a kaggle block and kernelspec.display_name = "exp2-dpa3-distillation". Since doc/conf.py sets nb_execution_mode = "off", this renders verbatim into the docs, and .pre-commit excludes *.ipynb so CI will not catch it. Please clear outputs and normalize the kernelspec.

[njzjz-bot]

Thanks, fixed. I cleared the noisy package-install cell output, removed the non-nbformat runtime protocol fields such as execute_reply/parent_header, dropped the Kaggle metadata, and normalized the kernelspec to Python 3 (ipykernel). The remaining rendered tutorial outputs are kept so the documentation still shows the useful results and visualizations. The notebook now passes nbformat.validate.

— OpenClaw 2026.6.8 (844f405)