docs: add mathematical formulas to atomic model classes#5257
docs: add mathematical formulas to atomic model classes#5257iProzd merged 5 commits intodeepmodeling:masterfrom
Conversation
Add mathematical formulas to atomic model class docstrings: - DPAtomicModel: descriptor + fitting pipeline - LinearEnergyAtomicModel: linear combination of models - PairTabAtomicModel: pairwise tabulated energy 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? |
|
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:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Repository UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughExpanded and reformatted class docstrings for three atomic-model classes to include mathematical descriptions and notation for descriptor/energy workflows; no code, signatures, or runtime behavior were changed. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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/atomic_model/pairtab_atomic_model.py`:
- Around line 48-55: The docstring formula for per-atom pairwise energy omits
the 1/2 prefactor used in the implementation; update the displayed equation for
E^i to E^i = 1/2 \sum_{j \in \mathcal{N}(i)} E_{t_i,t_j}(r_{ij}) so it matches
the code that multiplies the neighbor sum by 0.5 (the neighbor-sum energy
accumulation in this module). Ensure the LaTeX/formatted text and any
accompanying explanation mention the 1/2 factor to indicate pairwise
double-counting is corrected.
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
🧹 Nitpick comments (1)
deepmd/dpmodel/atomic_model/dp_atomic_model.py (1)
29-41: Formula inputs left undefined in the "where" clauseThe
whereclause on lines 40–41 only explains\mathcal{D}^iand\mathbf{y}^i, but three inputs introduced in the first equation —\mathbf{R}^i,\mathbf{R}_j, and\mathrm{types}— are never described. A reader unfamiliar with the codebase won't know thatjindexes over the neighbours of atomior what\mathrm{types}represents.📝 Suggested clarification
- where :math:`\mathcal{D}^i` is the descriptor for atom :math:`i`, and - :math:`\mathbf{y}^i` is the predicted atomic property (energy, dipole, etc.). + where :math:`\mathbf{R}^i` is the position of atom :math:`i`, + :math:`\mathbf{R}_j` are the positions of its neighbours :math:`j`, + :math:`\mathrm{types}` are the atomic-type indices, + :math:`\mathcal{D}^i` is the resulting descriptor for atom :math:`i`, and + :math:`\mathbf{y}^i` is the predicted atomic property (energy, dipole, etc.).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@deepmd/dpmodel/atomic_model/dp_atomic_model.py` around lines 29 - 41, The docstring's math block defines Descriptor(R^i, R_j, types) but the "where" clause omits explanations for the inputs; update the docstring in dp_atomic_model.py to document that R^i is the position of atom i, R_j denotes positions of neighbor atoms (j indexes neighbors of i), and types denotes atomic species or type identifiers used by Descriptor; also briefly state that Descriptor(...) computes the environment descriptor D^i from those inputs and that Fitting(...) maps D^i to the atomic prediction y^i so readers can map R^i, R_j, and types to Descriptor and Fitting.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@deepmd/dpmodel/atomic_model/dp_atomic_model.py`:
- Around line 29-41: The docstring's math block defines Descriptor(R^i, R_j,
types) but the "where" clause omits explanations for the inputs; update the
docstring in dp_atomic_model.py to document that R^i is the position of atom i,
R_j denotes positions of neighbor atoms (j indexes neighbors of i), and types
denotes atomic species or type identifiers used by Descriptor; also briefly
state that Descriptor(...) computes the environment descriptor D^i from those
inputs and that Fitting(...) maps D^i to the atomic prediction y^i so readers
can map R^i, R_j, and types to Descriptor and Fitting.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #5257 +/- ##
=======================================
Coverage 82.00% 82.00%
=======================================
Files 750 750
Lines 75082 75081 -1
Branches 3615 3615
=======================================
Hits 61572 61572
+ Misses 12347 12346 -1
Partials 1163 1163 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
The implementation applies 0.5 factor to avoid double-counting
pairs. Update formula to E^i = 1/2 * sum E_{t_i,t_j}(r_ij).
There was a problem hiding this comment.
Pull request overview
This PR adds mathematical formulas to the docstrings of three atomic model classes following the numpydoc convention. The additions provide precise mathematical descriptions of how each model computes atomic properties.
Changes:
- Added mathematical notation for the descriptor-fitting pipeline in DPAtomicModel
- Documented the linear combination formula for LinearEnergyAtomicModel with use case examples
- Explained the pairwise energy computation formula for PairTabAtomicModel with table lookup details
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| deepmd/dpmodel/atomic_model/dp_atomic_model.py | Added mathematical formulas describing descriptor extraction and fitting network pipeline |
| deepmd/dpmodel/atomic_model/linear_atomic_model.py | Added weighted sum formula for linear model combinations with practical use cases |
| deepmd/dpmodel/atomic_model/pairtab_atomic_model.py | Added pairwise energy formula with table lookup and double-counting explanation |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fix subject-verb agreement: 'Linear model makes'
|
Fixed:
Commit: da653ad |
- dp_atomic_model: use α_j for atom types, D for descriptor, F for fitting - linear_atomic_model: remove incorrect statement about learnable weights
Summary
Add detailed mathematical formulas to atomic model class docstrings following numpydoc convention.
Changes
Added formulas to the following classes:
DPAtomicModel: Descriptor + fitting pipeline
LinearEnergyAtomicModel: Linear combination of models
PairTabAtomicModel: Pairwise tabulated energy
Convention
Following numpydoc convention, parameters are documented in class docstrings, not in
__init__docstrings.Statistics
Authored by OpenClaw (model: GLM-5)
Summary by CodeRabbit