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

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

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python, pytorch, tensorflow
Domain
documentation, machine-learning

Research direction

Start with the loss section in doc/model/train-energy.md, then read deepmd/utils/argcheck.py and the loss implementations in deepmd/dpmodel/loss/ener.py and deepmd/pt/loss/ener.py. Document loss_func, f_use_norm, and scalar or three-value huber_delta with verified defaults and backend restrictions, add the requested JSON examples, and confirm grep finds all three keys.

Written by the indexing model from the issue text.

Description

Docs

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

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.