docs: add mathematical formulas to model classes#5258
docs: add mathematical formulas to model classes#5258iProzd merged 7 commits intodeepmodeling:masterfrom
Conversation
Add mathematical formulas to model class docstrings: - DPModelCommon: descriptor + fitting pipeline - SpinModel: virtual atom positions and torque conversion Follow numpydoc convention: parameters in class docstring.
|
Related Documentation Checked 0 published document(s) in 1 knowledge base(s). No updates required. How did I do? Any feedback? |
for more information, see https://pre-commit.ci
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded and expanded class-level docstrings in the deepmd model package for DPModelCommon, SpinModel, and EnergyModel describing responsibilities, data flows, neighbor selection, fitting-network access, model prediction pipeline, spin preprocessing, virtual/ghost-atom handling, and conversion of virtual-atom forces into magnetic torques. No code logic, behavior, or public API changes. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@deepmd/dpmodel/model/spin_model.py`:
- Around line 32-49: The module docstring in spin_model.py contains LaTeX
backslashes (e.g., \boldsymbol, \tau, \times, \cdot) which are being interpreted
as Python escape sequences; update the triple-quoted docstring to a raw string
by adding the r prefix (i.e., change """...""" to r"""...""") at the top of
spin_model.py (the docstring for the Spin model wrapper) so the backslashes are
preserved literally.
There was a problem hiding this comment.
Pull request overview
Adds numpydoc-style mathematical formulas to key model class docstrings to clarify the prediction pipeline and spin/virtual-atom mechanics.
Changes:
- Expanded
SpinModeldocstring with virtual-atom position and torque equations. - Added an
r"""..."""class docstring toDPModelCommondescribing the descriptor→fitting pipeline.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| deepmd/dpmodel/model/spin_model.py | Documents spin preprocessing, virtual-atom construction, and torque conversion with LaTeX math. |
| deepmd/dpmodel/model/dp_model.py | Documents the common DP model prediction pipeline using numpydoc + LaTeX math. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
D301: Use r""" if any backslashes in a docstring
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #5258 +/- ##
=======================================
Coverage 82.00% 82.00%
=======================================
Files 750 750
Lines 75082 75080 -2
Branches 3615 3615
=======================================
Hits 61572 61572
+ Misses 12347 12345 -2
Partials 1163 1163 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…ntiation Model layer sums atomic energies and computes forces/virials by differentiation, not descriptor+fitting pipeline.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@deepmd/dpmodel/model/dp_model.py`:
- Around line 37-41: The virial formula in the docstring uses per-atom energy
E^i but should use the total potential energy E to match the force definition;
update the math to Xi = - sum_i (partial E / partial r_i) ⊗ r_i (or equivalently
Xi = - sum_i r_i ⊗ F_i) so it references total energy E instead of E^i, and then
reconcile/remove the workaround in transform_output.py that "pops atomic virial"
(or update that code to compute the virial from the total E via dp_model.py's
Xi) to ensure the implementation and documentation use the same
total-energy-based virial.
DPModelCommon is a generic base class. The energy-specific formulas for reduction (E = sum E^i) and differentiation (forces, virials) belong in EnergyModel.
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- spin_model: use single backslashes in raw string for LaTeX - ener_model: virial formula uses total energy E, not per-atom E^i
Summary
Add detailed mathematical formulas to model class docstrings following numpydoc convention.
Changes
Added formulas to the following classes:
DPModelCommon: Descriptor + fitting pipeline
SpinModel: Virtual atom positions and torque conversion
Convention
Following numpydoc convention, parameters are documented in class docstrings, not in
__init__docstrings.Statistics
Authored by OpenClaw (model: GLM-5)
Summary by CodeRabbit