deepmodeling / deepmodeling/deepmd-kit
docs(loss): document loss_func/f_use_norm and three-value huber_delta
- Dominant language
- Python
- Stars
- 2k
- Forks
- 649
- Avg merge
- 6d 18h
- Merged PRs (30d)
- 15
Description
Parent issue: #5917 (checklist items 13–14)
## Scope
Two energy-loss options exist only as schema entries:
1. **Force L2-norm / MAE loss** (`3f52fa95a`, `feat(dp, pt): add force l2 norm loss & mae loss`, PR #5294). NOTE: the shipped config keys are **`loss_func`** (`"mse"` / `"mae"`) and **`f_use_norm`**, not `force_l2_norm` — the original checklist item title used a pre-merge name. Schema: `deepmd/utils/argcheck.py:4319-4331` (`doc_loss_func`, `doc_f_use_norm`), arguments at `:4468-4479`. Semantics: `loss_func` selects MSE vs MAE for energy/force/virial/atom losses; `f_use_norm` uses the L2 norm of force vectors in the loss and is only valid when `loss_func="mae"` or `use_huber=True` (validation enforced).
2. **Three-value Huber delta** (`14c349b42`): `huber_delta` accepts a single float or a list of three values (schema at `argcheck.py:4481-4487`, `[float, list[float]]`, default `0.01`). Verify from the loss implementation which three losses the three values correspond to (likely energy/force/virial — confirm in `deepmd/dpmodel/loss/ener.py` and `deepmd/pt/loss/ener.py`).
Neither appears in `doc/model/train-energy.md`; `grep huber doc/` returns nothing.
## Implementation plan
### `doc/model/train-energy.md`
Read the loss section of the page plus `argcheck.py` entries and the DP/PT `ener` loss implementations first. Extend the loss prose (near the `use_huber` / `pref` documentation):
- `loss_func`: `"mse"` (verify default) vs `"mae"`, which loss terms it applies to, backend support (DP & PyTorch per the commit title — verify TF support is absent before claiming);
- `f_use_norm`: what it changes for force loss (norm of the force vector instead of per-component), and the validity constraint (`loss_func="mae"` or `use_huber=True`);
- `use_huber` + `huber_delta`: Huber loss threshold; document scalar vs three-value forms and their meaning, with default `0.01` (verify per-backend support from code);
- A minimal JSON example showing `loss_func: "mae"` with `f_use_norm: true`, and one with a three-value `huber_delta`.
## Constraints
- Use the shipped key names (`loss_func`, `f_use_norm`); the checklist's `force_l2_norm` was a working title.
- Verify defaults and backend support in `argcheck.py` and the loss classes; state backend restrictions explicitly.
- Keep math/style consistent with the surrounding loss documentation.
## Verification
- `grep -n "loss_func\|f_use_norm\|huber_delta" doc/model/train-energy.md` shows the new prose.
---
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.