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

Đang mở
  • Có gì không ổn?
#5,926 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 3 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
72/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
python, pytorch, tensorflow
Lĩnh vực
documentation, machine-learning

Hướng nghiên cứu

Bắt đầu với phần loss trong doc/model/train-energy.md, sau đó đọc deepmd/utils/argcheck.py và các triển khai loss trong deepmd/dpmodel/loss/ener.py và deepmd/pt/loss/ener.py. Ghi lại loss_func, f_use_norm và huber_delta dạng vô hướng hoặc ba giá trị cùng với các giá trị mặc định đã được xác minh và các hạn chế của backend, thêm các ví dụ JSON được yêu cầu và xác nhận rằng grep tìm thấy cả ba khóa.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
Python
Star
2.1k
Fork
663
Merge trung bình
3 ngày 11 giờ
Pull request đã merge (30 ngày)
25

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của deepmodeling/deepmd-kit

Tất cả issue của deepmodeling/deepmd-kit

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.