[pull] master from deepmodeling:master - #317
Merged
Merged
Conversation
## Summary
This PR introduces DPA4C, the compact and compressible degree-wise
member of
the DPA4 family, as a PyTorch Exportable (`pt_expt`) descriptor. DPA4C
is a
strictly local, one-hop model intended for high-throughput molecular
dynamics:
it reads each directed neighbor edge once, performs one destination
reduction,
and converts the resulting degree-wise moments into a fixed invariant
vector
without cross-atom message passing.
The PR includes the complete path from training to deployment:
- a backend-neutral DPA4C descriptor and a native `pt_expt`
implementation;
- graph-native training, serialization, export, compression, and
calibration;
- fused CUDA descriptor, fitting, force, virial, and magnetic-force
paths;
- native-spin conditioning from the descriptor through Python, C, C++,
and
LAMMPS/Kokkos interfaces;
- frame-level charge and spin-multiplicity conditioning, including
runtime
re-specialization of compressed artifacts;
- function-preserving fine-tuning from a spin-free checkpoint;
- ragged mixed-size training batches without exposing phantom atoms to
the
network; and
- user documentation plus non-spin and native-spin examples.
## Why DPA4C
DPA4/SeZM uses equivariant message passing to target the accuracy
frontier.
DPA4C targets a different operating point: a compact local student whose
radial dependence can be tabulated and whose angular computation can be
fused
into bounded per-edge and per-node CUDA kernels.
The descriptor consumes a carry-all cutoff graph rather than a
fixed-capacity
neighbor list. It therefore has no `sel` parameter, no capacity derived
from
the densest training frame, and no neighbor truncation. Its persistent
per-atom state is determined by `channels` and `lmax`, not by the number
of
neighbors.
## Descriptor architecture
### Edge representation
For every directed edge `j -> i`, DPA4C combines:
- the DPA4 Bessel or Gaussian radial basis;
- a bias-free one-hidden-layer SwiGLU radial network;
- ordered PairFiLM scale and shift terms for `(type_i, type_j)`;
- optional pair-conditioned shared radial modes; and
- a C3 cutoff envelope whose value and first three radial derivatives
join
continuously to zero at `rcut`.
`radial_modes` increases chemical/radial resolution without widening the
per-atom moment state. The portable implementation accepts any
non-negative
mode count; the compressed CUDA path specializes the production profiles
listed below.
### One-reduction degree-wise moments
The edge direction is expanded in real Cartesian harmonics through
`lmax`.
All scalar masses and all angular moments are packed into one edge
payload and
accumulated with one destination segment reduction. Two smooth
neighborhood
masses normalize the scalar and non-scalar blocks and are also emitted
as
descriptor coordinates so the fitting network retains effective
coordination
information.
The channel schedule keeps degree 0 wide, retains several channels for
degrees
1 and 2, and uses one channel for degrees 3 and 4. This bounds the node
state
while preserving the low-degree angular information that dominates the
model.
### Fixed invariant readout
The node-local readout combines:
- exact aligned Gram matrices within each degree;
- normalized low-rank bispectrum contractions across allowed degree
triples;
- the projected `Qv` quartic; and
- the two neighborhood-mass coordinates.
Only O(3)-even invariant scalars reach the standard energy fitting
network.
Energy is therefore invariant under rotations, reflections, and neighbor
permutations, while force and virial remain conservative derivatives of
the
same total energy.
The public structural controls are:
- `channels` in `{8, 16, 32, 64, 128}`;
- `lmax` in `{2, 3, 4}`;
- `basis_type` in `{bessel, gaussian}`;
- `n_radial`;
- `radial_modes`; and
- `use_amp`, which applies bf16 autocast only to the edge-dominated
stage and
restores descriptor precision before reduction and invariant
contraction.
## Frame charge-state conditioning
When `add_chg_spin_ebd` is enabled, DPA4C accepts one frame-level
`[charge, multiplicity]` condition. This condition is independent of the
per-atom native-spin vector. It enters at two finite locations:
1. a shift of the center type embedding; and
2. a bias of the ordered-pair encoder hidden state.
The portable graph path keeps the condition per frame, so one batch may
contain
different charge states. `default_chg_spin` supplies the fallback state
when an
input does not provide one.
Compression folds a single state into the finite type table and
ordered-pair
caches, leaving the radial table, angular equations, and CUDA kernel
layout
unchanged. The exported artifact carries a charge-state fold that
rebuilds only
the affected constants when the evaluator, C/C++ API, or LAMMPS pair
style
selects another state. This keeps the compact canonical inference ABI
free of a
per-edge runtime condition while avoiding a permanently baked-in charge
state.
## Compression and deployment
Compression tabulates the distance-only radial network with quintic
Hermite
splines on `[0, rcut]` and snapshots the finite ordered-type-pair
tables. The
compiled descriptor supports:
```text
channels in {8, 16, 32, 64, 128}
lmax in {2, 3, 4}
radial_modes in {0, 2, 4, 8}
precision = float32
```
The fused implementation includes forward and backward descriptor
operators,
compact canonical graph operators, fitting-network kernels, and
force/virial
assembly. The backward saves the minimum node moment state and
recomputes the
edge-local radial and angular terms, avoiding a persistent per-edge
moment
tensor. Evaluation is tiled so temporary memory stays bounded for large
edge
sets.
`DP_CUDA_INFER=1` enables the fused descriptor/fitting path with
autograd force
assembly. `DP_CUDA_INFER=2` additionally uses the compact canonical
fused
energy/force/virial composition. The export metadata records the graph
ABI and
dtype contract used by the C++ and LAMMPS loaders.
Graph folding now fails explicitly when a topology requests local-owner
folding
but does not provide a valid owner for every ghost. This prevents a
malformed
standalone C++ call from silently dropping halo-edge contributions.
Extended
multi-rank paths keep ghosts as distinct nodes and use reverse
communication as
their force-folding contract.
## Integration surface
- Registers `descriptor.type: dpa4c` for the PyTorch Exportable backend
and
documents its arguments in `argcheck`.
- Adds model serialization, graph export, compression routing, inference
metadata, and evaluation inputs for both charge state and native spin.
- Extends C and C++ energy/spin interfaces with charge-state dimensions,
setters, and per-call inputs.
- Adds non-spin water and native-spin NiO examples and a full user
guide.
- Adds backend-neutral, PyTorch, CUDA, graph-lower, export, fine-tuning,
symmetry, derivative, serialization, compression, and deployment tests.
- Adapts the DPA1 shared graph-kernel helpers without changing DPA1's
public
descriptor contract.
The final integration commit also replaces the removed
`doc_only_pt_expt_supported` symbol with the current
`supported_backends("pt_expt")` registry introduced on `master` by
#5929.
This is the only modification made after cherry-picking the four DPA4C
commits.
## Current scope and limitations
- DPA4C is implemented for `pt_expt`; other backends are not added here.
- Compressed inference is float32-only and restricted to the structural
profiles listed above. Unsupported profiles continue to use the portable
path or are rejected by explicit compression validation.
- Descriptor-level excluded type pairs are not supported by the fused
compact
kernel.
- Native spin requires `scheme: native`; the virtual-atom `deepspin`
scheme is
not used by DPA4C.
- The symmetric spin invariant basis does not represent the
antisymmetric
Dzyaloshinskii-Moriya interaction.
- The provided LAMMPS example covers evaluation and spin minimization.
Spin
dynamics through stock `fix nve/spin` additionally depends on that fix
recognizing the new pair style.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added the DPA4C descriptor with native-spin, charge-state
conditioning, compressed CUDA inference, and canonical graph support.
* Added native-spin LAMMPS pair styles and expanded C/C++ APIs for spin,
charge-state configuration, and GPU graph inference.
* Added compression capability detection and support for analytically
bounded compression domains.
* **Bug Fixes**
* Improved force, virial, magnetic-force, charge-state, and loss
handling consistency.
* **Documentation**
* Added DPA4C guides, training configurations, and spin-enabled LAMMPS
examples.
* **Tests**
* Expanded coverage for DPA4C, CUDA compression, export, validation,
spin, and charge-state behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
## Summary - Recommend DPA4 when accuracy is the priority and DPA4C when throughput or system scale is the binding constraint. - Update the pretrained and fine-tuning quick start to use a built-in DPA4 OMat24 single-task checkpoint, and remove the experimental DPA4-only LoRA workflow from the project landing page. - Replace the DPA-3 and DeepPot-SE default examples with DPA4 and DPA4C examples, and refresh both Pareto figures from the latest results. ## Validation - All pre-commit hooks passed during commit. - `git diff --check upstream/master...HEAD` - `dp pretrained download -h` lists the documented DPA4 checkpoint. - Verified the DPA4, DPA4C, and DPA4 OMat24 links return HTTP 200. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the README to feature DPA4 and DPA4C as the primary model families. - Refreshed pretrained-model and fine-tuning guidance with DPA4 OMat24 checkpoints. - Added training examples for accuracy-focused DPA4 and throughput-focused DPA4C workflows. - Removed outdated LoRA and legacy branch-selection instructions. - Updated references and links for DPA4, DPA4 OMat24, and DPA4C. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary - add the `deepmd-install` Agent Skill with concise routes for pip, conda, dp1s, offline packages, Docker, source builds, C/C++, and LAMMPS - fetch version-matched official documentation before rendering version-sensitive commands, using exact-ref raw Markdown from GitHub or the official Gitee mirror - treat dynamic command values as literal process arguments rather than shell source - pin pip and Conda installations to the selected release and fail verification on a normalized version mismatch - make source runtime and compiled-backend selection explicit, including the documented backend-neutral C/C++ route - keep a compact failure-mode reference for environment identity, backend and accelerator selection, source builds, native loader checks, Docker, and LAMMPS - document skill installation in the README and installation docs, using the official Gitee mirror as the network fallback ## Design The skill provides route selection, safety boundaries, and verification criteria without duplicating the installation manual. It assumes no local source checkout. The agent opens the direct official page first, resolves a release to its tag, and falls back to the corresponding Markdown at that exact tag or commit when versioned web documentation is unavailable. Source installation remains the recommended path when a compiler is available and build time is acceptable. TensorFlow, PyTorch, JAX, Paddle, and backend-neutral C/C++ libraries are represented, while version-specific package, accelerator, and build commands remain owned by the official documentation. ## Validation - official `quick_validate.py skills/deepmd-install` - repository pre-commit hooks for all changed files - shell-free argv round-trip with spaces, command-substitution syntax, backticks, semicolons, and option-looking values - PEP 440 release normalization and exact pip requirement parsing - Conda exact-version MatchSpec parsing, including rejection of the fuzzy single-equals form - direct GitHub and official Gitee raw-documentation fetch at an exact upstream commit - official Gitee and upstream `master` commit identity check - source build environment-assignment shell check - local Git checkout checks for both a normal ref and an option-looking ref - `git diff --check`
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )