deepmodeling / deepmodeling/deepmd-kit
docs(cli): document dp test stress output and dp show serialization-tree
- Dominant language
- Python
- Stars
- 2k
- Forks
- 649
- Avg merge
- 6d 18h
- Merged PRs (30d)
- 15
Description
Parent issue: #5917 (checklist items 4–5)
## Scope
1. **`dp test` stress output** (`330fa7558`, `feat: dp test stress`): when the tested data contains stress labels and the model predicts virial/stress, `dp test` writes per-frame stress details to a `.s.out` file and prints Stress MAE/RMSE in eV/ų. Nothing about stress appears in `doc/test/test.md`.
2. **`dp show serialization-tree`** (`e19bd188b`): `deepmd/main.py:1049` adds a `serialization-tree` choice, implemented in `deepmd/entrypoints/show.py:153` via `DeepEval.serialize()`. `doc/model/show-model-info.md` does not list it.
## Implementation plan
### 1. `doc/test/test.md` — new "Evaluate stress" section
Read `deepmd/entrypoints/test.py` first, in particular:
- lines ~500–560: where the stress detail file `.s.out` is written and the requirement "Stress detail output requires both reference and prediction stresses";
- lines ~815–840 and ~895–910, ~970–980: Stress MAE/RMSE printing.
Then document:
- When stress labels are present in the test data, `dp test` additionally reports `Stress MAE` and `Stress RMSE` in eV/ų in the summary output (and averaged over systems).
- The per-frame stress detail is written to `.s.out` (analogous to `.e.out`/`.f.out`/`.v.out`); list its columns as implemented (verify ordering in code).
- Convention: stress sigma = −virial / volume, tensile-positive, in eV/ų (verify against `test.py:825`).
### 2. `doc/model/show-model-info.md` — add `serialization-tree`
Read `deepmd/entrypoints/show.py:140-170` and the `DeepEval.serialize` implementation to determine which backends/model kinds support it.
- Add `serialization-tree` to the `` bullet list (after `observed-type`): shows the model's serialization tree (the structure of the data serialized into the model file).
- Add a matching **serialization-tree** entry under "Output Description".
- Note backend support explicitly only if it is restricted (verify; `DeepEval.serialize` suggests all backends exposing `DeepEval`).
## Constraints
- Verify file naming (`.s.out`) and column layout directly from `deepmd/entrypoints/test.py`; do not guess.
- Match the existing documentation style of both pages.
## Verification
- `grep -n -i "stress" doc/test/test.md` shows the new section.
- `grep -n "serialization-tree" doc/model/show-model-info.md` shows the attribute listed.
---
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.