docs(model): document charge-spin config, so3_readout, distinguish_types; fix population toctree

Open
  • Is something wrong?
#5,924 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python
Domain
documentation

Research direction

Start with the DPA-3 schema block and related spin documentation in deepmd/utils/argcheck.py and doc/model/train-energy-spin.md; inspect dataloader handling for charge_spin and verify backend annotations before writing claims. Update doc/model/train-energy-spin.md, dpa3.md, dpa4.md, train-fitting-property.md, and index.rst, then run the four grep checks in the issue to confirm each option and the population page are documented.

Written by the indexing model from the issue text.

Description

Docs

Parent issue: #5917 (checklist items 9, 11, 15, 17)

Scope

Four independent fixes to the doc/model/ pages:

  1. Charge-spin conditioning training config (e3fda4537 C++ runtime, f39a08128 dpa3 decoupled from fparam, 6984e4c63 paddle): the training-side options add_chg_spin_ebd and default_chg_spin (see deepmd/utils/argcheck.py:694-703 and :2097-2108 — verify which descriptor each block belongs to, DPA-4/SeZM vs DPA-3) are undocumented. (dim_chg_spin is an internal serialized dimension exposed via get_dim_chg_spin(), not a config key.) The LAMMPS inference keyword charge_spin is already documented at doc/third-party/lammps-command.md:66 — cross-link it.
  2. so3_readout DPA-4/SeZM option (4b6506db4): "none" / "glu" / "mlp" read-out FFN mode for the final l=0 descriptor (deepmd/utils/argcheck.py:626-634); no prose in doc/model/dpa4.md.
  3. distinguish_types in property fitting (7cd0d191b): element type-wise bias; schema entry at deepmd/utils/argcheck.py:2827-2829,2872-2877 (default True); no prose in doc/model/train-fitting-property.md.
  4. Orphaned page: doc/model/train-fitting-population.md exists but is missing from the doc/model/index.rst toctree.

Implementation plan

1. Charge-spin training config — doc/model/train-energy-spin.md (+ pointer in doc/model/dpa3.md)

Read the DPA-3 schema block (argcheck.py ~line 2090–2150) and the spin training docs first.

  • In doc/model/train-energy-spin.md, document:
    • model/descriptor/add_chg_spin_ebd: embed per-frame charge and spin conditions into the descriptor type embedding;
    • the charge_spin input data (shape [nframes, 2], [charge, spin]) and how to provide it in training data (verify data key handling/charge_spin real-data support in the dataloader code);
    • default_chg_spin: fallback [charge, spin] used when charge_spin data is absent (including at inference time);
  • In doc/model/dpa3.md, add a short subsection pointing to the above (and note backend support per the argcheck doc_only_pt_supported annotations — verify whether the DPA3 variant is also supported by Paddle after 6984e4c63 before writing backend claims).
  • Cross-reference the LAMMPS charge_spin keyword (doc/third-party/lammps-command.md) for inference.
2. so3_readout — doc/model/dpa4.md

Add prose describing the option with the three modes, following the argcheck docstring semantics: none applies a degree-0 scalar FFN to the l=0 slice only (l>0 coefficients discarded); glu/mlp apply a full equivariant FFN on the SO(3) Wigner-D grid so l>0 geometry is folded into l=0 before the scalar read-out; the read-out degree equals the node degree of the last interaction block and the Wigner-D frame order follows kmax. Note backend support annotation (doc_only_pt_supported — verify against current argcheck).

3. distinguish_types — doc/model/train-fitting-property.md

Add a short paragraph: when enabled (default True), per-element-type output statistics/biases are computed for the property fitting net (element type-wise bias), improving accuracy for heteroatom systems; set to False to share one bias across types (verify behavior from deepmd/utils/argcheck.py and the property fitting implementation before writing).

4. Toctree — doc/model/index.rst

Add train-fitting-population to the toctree, placed with the other train-fitting-* entries (after train-fitting-property).

Constraints

  • Confirm which descriptor schema block (argcheck.py:694 vs :2097) corresponds to which descriptor page before documenting; keep backend-support statements consistent with the doc_only_pt_supported / paddle annotations in the code.
  • Match surrounding prose style; use {ref} links for schema cross-references like neighboring pages do.

Verification

  • grep -n "chg_spin" doc/model/train-energy-spin.md doc/model/dpa3.md shows new prose.
  • grep -n "so3_readout" doc/model/dpa4.md shows the option.
  • grep -n "distinguish_types" doc/model/train-fitting-property.md shows the option.
  • grep -n "train-fitting-population" doc/model/index.rst shows the toctree entry.

Parent issue: #5917

Coding agent: opencode
opencode version: 1.18.9
Model: ustc/k3
Reasoning effort: max

Dominant language
Python
Stars
2.1k
Forks
663
Avg merge
3d 11h
Merged PRs (30d)
25

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from deepmodeling/deepmd-kit

All issues in deepmodeling/deepmd-kit

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.