deepmodeling / deepmodeling/deepmd-kit
docs(model): document charge-spin config, so3_readout, distinguish_types; fix population toctree
- Dominant language
- Python
- Stars
- 2k
- Forks
- 649
- Avg merge
- 6d 18h
- Merged PRs (30d)
- 15
Description
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
Contributor guide
Assessment
This issue has not been assessed yet.