docs(model): document charge-spin config, so3_readout, distinguish_types; fix population toctree

Đang mở
  • Có gì không ổn?
#5,924 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ó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
68/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
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với khối lược đồ DPA-3 và tài liệu spin liên quan trong deepmd/utils/argcheck.py và doc/model/train-energy-spin.md; kiểm tra cách dataloader xử lý charge_spin và xác minh các chú thích backend trước khi đưa ra nhận định. Cập nhật doc/model/train-energy-spin.md, dpa3.md, dpa4.md, train-fitting-property.md và index.rst, sau đó chạy bốn bước kiểm tra grep trong issue để xác nhận rằng từng tùy chọn và trang population đã được ghi trong tài liệu.

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 9, 11, 15, 17)

Scope

Four independent fixes to the doc/model/ pages:

  1. Charge-spin conditioning training config (e3fda4537 C++ runtime, f39a08128 dpa3 decoupled from fparam, 6984e4c63 paddle): the training-side options add_chg_spin_ebd and default_chg_spin (see deepmd/utils/argcheck.py:694-703 and :2097-2108 — verify which descriptor each block belongs to, DPA-4/SeZM vs DPA-3) are undocumented. (dim_chg_spin is an internal serialized dimension exposed via get_dim_chg_spin(), not a config key.) The LAMMPS inference keyword charge_spin is already documented at doc/third-party/lammps-command.md:66 — cross-link it.
  2. so3_readout DPA-4/SeZM option (4b6506db4): "none" / "glu" / "mlp" read-out FFN mode for the final l=0 descriptor (deepmd/utils/argcheck.py:626-634); no prose in doc/model/dpa4.md.
  3. distinguish_types in property fitting (7cd0d191b): element type-wise bias; schema entry at deepmd/utils/argcheck.py:2827-2829,2872-2877 (default True); no prose in doc/model/train-fitting-property.md.
  4. Orphaned page: doc/model/train-fitting-population.md exists but is missing from the doc/model/index.rst toctree.

Implementation plan

1. Charge-spin training config — doc/model/train-energy-spin.md (+ pointer in doc/model/dpa3.md)

Read the DPA-3 schema block (argcheck.py ~line 2090–2150) and the spin training docs first.

  • In doc/model/train-energy-spin.md, document:
    • model/descriptor/add_chg_spin_ebd: embed per-frame charge and spin conditions into the descriptor type embedding;
    • the charge_spin input data (shape [nframes, 2], [charge, spin]) and how to provide it in training data (verify data key handling/charge_spin real-data support in the dataloader code);
    • default_chg_spin: fallback [charge, spin] used when charge_spin data is absent (including at inference time);
  • In doc/model/dpa3.md, add a short subsection pointing to the above (and note backend support per the argcheck doc_only_pt_supported annotations — verify whether the DPA3 variant is also supported by Paddle after 6984e4c63 before writing backend claims).
  • Cross-reference the LAMMPS charge_spin keyword (doc/third-party/lammps-command.md) for inference.
2. so3_readout — doc/model/dpa4.md

Add prose describing the option with the three modes, following the argcheck docstring semantics: none applies a degree-0 scalar FFN to the l=0 slice only (l>0 coefficients discarded); glu/mlp apply a full equivariant FFN on the SO(3) Wigner-D grid so l>0 geometry is folded into l=0 before the scalar read-out; the read-out degree equals the node degree of the last interaction block and the Wigner-D frame order follows kmax. Note backend support annotation (doc_only_pt_supported — verify against current argcheck).

3. distinguish_types — doc/model/train-fitting-property.md

Add a short paragraph: when enabled (default True), per-element-type output statistics/biases are computed for the property fitting net (element type-wise bias), improving accuracy for heteroatom systems; set to False to share one bias across types (verify behavior from deepmd/utils/argcheck.py and the property fitting implementation before writing).

4. Toctree — doc/model/index.rst

Add train-fitting-population to the toctree, placed with the other train-fitting-* entries (after train-fitting-property).

Constraints

  • Confirm which descriptor schema block (argcheck.py:694 vs :2097) corresponds to which descriptor page before documenting; keep backend-support statements consistent with the doc_only_pt_supported / paddle annotations in the code.
  • Match surrounding prose style; use {ref} links for schema cross-references like neighboring pages do.

Verification

  • grep -n "chg_spin" doc/model/train-energy-spin.md doc/model/dpa3.md shows new prose.
  • grep -n "so3_readout" doc/model/dpa4.md shows the option.
  • grep -n "distinguish_types" doc/model/train-fitting-property.md shows the option.
  • grep -n "train-fitting-population" doc/model/index.rst shows the toctree entry.

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.