deepmodeling / deepmodeling/deepmd-kit

docs(loss): document loss_func/f_use_norm and three-value huber_delta

Open
#5,926 0 comments 0 reactions 0 assignees View on GitHub
Docs
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.