doc: update DPA3 doc and example #4655
Conversation
📝 WalkthroughWalkthroughThis pull request updates documentation and examples to incorporate the new DPA-3 descriptor. It revises a reference path in the DPA-2 document and adds comprehensive new documentation for DPA-3, including its capabilities, training examples, and configuration details. The toctree in the model index is updated, and the list of supported descriptors in the PyTorch/DP section now includes DPA-3. Additionally, new example files and a test input path for DPA-3 have been added, along with a minor comment update in an existing example file. Changes
Suggested reviewers
Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms (27)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
doc/model/dpa3.md (1)
14-16: Consider adding a placeholder for the upcoming reference.The reference is marked as "will be released soon." This is acceptable for now, but it would be helpful to add a TODO comment or issue reference to track when this should be updated with the actual citation once published.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
doc/model/dpa2.md(1 hunks)doc/model/dpa3.md(1 hunks)doc/model/index.rst(1 hunks)doc/model/train-energy-spin.md(1 hunks)examples/water/dpa3/README.md(1 hunks)examples/water/dpa3/input_torch.json(1 hunks)examples/water/lmp/jax_dpa.lammps(1 hunks)source/tests/common/test_examples.py(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (29)
- GitHub Check: Test Python (6, 3.12)
- GitHub Check: Test Python (6, 3.9)
- GitHub Check: Test Python (5, 3.12)
- GitHub Check: Test Python (5, 3.9)
- GitHub Check: Test Python (4, 3.12)
- GitHub Check: Test Python (4, 3.9)
- GitHub Check: Test Python (3, 3.12)
- GitHub Check: Build wheels for cp310-manylinux_aarch64
- GitHub Check: Test Python (3, 3.9)
- GitHub Check: Build wheels for cp311-win_amd64
- GitHub Check: Build C++ (clang, clang)
- GitHub Check: Test Python (2, 3.12)
- GitHub Check: Build wheels for cp311-macosx_arm64
- GitHub Check: Build C++ (rocm, rocm)
- GitHub Check: Build wheels for cp311-macosx_x86_64
- GitHub Check: Test Python (2, 3.9)
- GitHub Check: Build C++ (cuda120, cuda)
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Analyze (python)
- GitHub Check: Test Python (1, 3.12)
- GitHub Check: Test C++ (false)
- GitHub Check: Build C library (2.14, >=2.5.0rc0,<2.15, libdeepmd_c_cu11.tar.gz)
- GitHub Check: Build C++ (cuda, cuda)
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Test Python (1, 3.9)
- GitHub Check: Build C library (2.18, libdeepmd_c.tar.gz)
- GitHub Check: Test C++ (true)
- GitHub Check: Build C++ (cpu, cpu)
- GitHub Check: Analyze (c-cpp)
🔇 Additional comments (12)
doc/model/index.rst (1)
13-13: Newdpa3Entry in Toctree
The newdpa3entry has been correctly added to the toctree. Please verify that its indentation and ordering are consistent with the other entries so that the navigation renders as expected.examples/water/dpa3/README.md (1)
1-5: README for DPA-3 Model Input Documentation
This new README clearly outlines the purpose and input configuration for the 6-layer DPA-3 model. Please double-check that the relative link to the DPA-3 documentation correctly resolves in the built documentation.examples/water/lmp/jax_dpa.lammps (1)
8-8: Updated LAMMPS Comment for DPA-2/3
The updated comment now indicates that the configuration applies to both DPA-2 and DPA-3 when using the JAX backend. This added clarity is beneficial.doc/model/dpa2.md (1)
29-29: Reference File Path Update
The reference toexamples/water/lmp/jax_dpa.lammpsnow reflects the updated example for both DPA-2 and DPA-3. Please confirm that this change is coordinated with all relevant documentation and examples.doc/model/train-energy-spin.md (1)
51-55: Extension of Supported Descriptors withdpa3
Adding thedpa3descriptor to the list of supported descriptors in the PyTorch/DP section is a good update. Ensure that any further references to DPA-3 in the training examples or configuration details are updated accordingly for clarity and consistency.source/tests/common/test_examples.py (1)
61-61: Addition of DPA3 example input file path looks good.The new path correctly follows the established pattern of adding example input files to the test suite. This ensures that the DPA3 example configuration will be tested for argument validity.
examples/water/dpa3/input_torch.json (1)
1-94: Well-structured configuration for the DPA3 descriptor.The JSON configuration is properly formatted and contains all necessary components for the DPA3 model:
- Type mapping for water molecules (O, H)
- Descriptor configuration with repflow settings
- Appropriate fitting network parameters
- Learning rate and loss configurations
- Training and validation data paths
The hyperparameters align with the recommendations documented in the DPA3 documentation.
doc/model/dpa3.md (5)
1-13: Clear introduction to the DPA3 descriptor with proper formatting.The document starts with appropriate heading and backend support icons. The introduction effectively explains the purpose and strengths of the DPA3 model as a large atomic model (LAM) designed for diverse chemical and materials systems.
18-44: Comprehensive hyperparameter test results.The table of hyperparameter tests provides valuable guidance for users. It includes:
- A systematic comparison across various configurations
- Clear metrics (RMSE for energy, force, and virial)
- Training time information
- Comparison with DPA-2 as a baseline
This information will help users select appropriate hyperparameters based on their specific needs.
47-59: Installation requirements clearly documented.The section properly explains the requirements for source code installation, including:
- Custom OP library requirements
- MPI compatibility considerations
- CUDA-Aware MPI recommendations
This provides users with the necessary information for successful installation and optimization.
60-68: Important JAX backend limitations highlighted.The section clearly documents the limitation regarding MPI ranks when using the JAX backend with LAMMPS, and provides the necessary command to ensure proper operation. The reference to the example file is helpful.
70-80: Concise information on data format, type embedding, and model compression.These final sections provide important details about:
- Supported data formats
- Type embedding implementation
- Model compression limitations
This completes the documentation with all necessary technical details for users.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## devel #4655 +/- ##
==========================================
- Coverage 84.80% 84.80% -0.01%
==========================================
Files 692 692
Lines 66396 66396
Branches 3539 3540 +1
==========================================
- Hits 56306 56305 -1
Misses 8949 8949
- Partials 1141 1142 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
examples/water/dpa3/input_torch.json (1)
67-93: Training Configuration and Potential TypoThe training block is comprehensive, specifying file paths for statistics, training, and validation data, as well as key hyperparameters such as
batch_size,gradient_max_norm, and logging intervals. One minor note: the key"numb_steps"(line 85) might be a typographical error—consider renaming it to"num_steps"to enhance clarity and align with common naming conventions.- "numb_steps": 1000000, + "num_steps": 1000000,Please verify whether this key is intended as a custom identifier or if a change is warranted.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
examples/water/dpa3/input_torch.json(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (29)
- GitHub Check: Build wheels for cp310-manylinux_aarch64
- GitHub Check: Build wheels for cp311-win_amd64
- GitHub Check: Build wheels for cp311-macosx_arm64
- GitHub Check: Build C++ (clang, clang)
- GitHub Check: Build wheels for cp311-macosx_x86_64
- GitHub Check: Build C++ (rocm, rocm)
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Build C++ (cuda120, cuda)
- GitHub Check: Build C++ (cuda, cuda)
- GitHub Check: Build C++ (cpu, cpu)
- GitHub Check: Test Python (6, 3.12)
- GitHub Check: Test Python (6, 3.9)
- GitHub Check: Test Python (5, 3.12)
- GitHub Check: Test Python (5, 3.9)
- GitHub Check: Test Python (4, 3.12)
- GitHub Check: Build C library (2.14, >=2.5.0rc0,<2.15, libdeepmd_c_cu11.tar.gz)
- GitHub Check: Test Python (4, 3.9)
- GitHub Check: Build C library (2.18, libdeepmd_c.tar.gz)
- GitHub Check: Test Python (3, 3.12)
- GitHub Check: Test Python (3, 3.9)
- GitHub Check: Test Python (2, 3.12)
- GitHub Check: Test Python (2, 3.9)
- GitHub Check: Test Python (1, 3.12)
- GitHub Check: Test Python (1, 3.9)
- GitHub Check: Test C++ (false)
- GitHub Check: Test C++ (true)
- GitHub Check: Analyze (python)
- GitHub Check: Analyze (c-cpp)
🔇 Additional comments (5)
examples/water/dpa3/input_torch.json (5)
1-7: Overall JSON Structure and Formatting is CorrectThe file follows valid JSON syntax and the overall layout is clear. However, the simple "_comment" entries (e.g., "that's all") could be enriched with more descriptive text to aid future maintainers.
8-35: Detailed Descriptor Section for DPA-3The "descriptor" section is thorough and includes all the necessary parameters for configuring DPA-3. The numerical values (e.g., for "n_dim", "e_dim", "a_dim", etc.) appear reasonable. Please verify that parameter names like
"update_residual_init"(set to"const") and the activation function"silut:10.0"exactly match what the downstream processing expects.
36-49: Consistent Fitting Network SettingsThe "fitting_net" configuration is consistent with the descriptor. The neuron layers, activation function, and seed are clearly specified. Consider adding more detailed comments if these values have specific implications on the network design.
50-56: Clear Learning Rate ConfigurationThe exponential decay learning rate setup is clear with explicit parameters for decay steps, start, and stop rates. Make sure that the chosen decay schedule aligns with the experimental setup and training dynamics.
57-66: Well-Defined Loss Function ParametersThe loss configuration appropriately defines the types and preference limits for energy, force, and volume. Confirm that these values meet the intended training criteria and that
"ener"is the right type specifier.
Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu> Signed-off-by: Duo <50307526+iProzd@users.noreply.github.com>
Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu> Signed-off-by: Duo <50307526+iProzd@users.noreply.github.com>
Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu> Signed-off-by: Duo <50307526+iProzd@users.noreply.github.com>
Summary by CodeRabbit
Documentation
New Features
Tests