feat(loss): support three-value huber delta

[OutisLi]

Allow huber_delta to accept either one shared float or a three-value list for energy, force and virial.

Summary by CodeRabbit

• New Features

  • Enhanced Huber loss configuration: accept either a single delta or a 3-element list to set separate thresholds for energy, force, and virial (backward compatible).
  • Added automatic resolution of per-term deltas so each loss component uses its own threshold.

• Documentation

  • Updated argument validation and docs to describe the new 3-element ordering and usage.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4410696d-dd11-47e7-bf9b-6b28964e661f

📥 Commits

Reviewing files that changed from the base of the PR and between 4894c6d and a7a1edd.

📒 Files selected for processing (6)

• deepmd/dpmodel/loss/ener.py
• deepmd/pd/loss/ener.py
• deepmd/pt/loss/ener.py
• deepmd/tf/loss/ener.py
• deepmd/utils/argcheck.py
• deepmd/utils/loss.py

🚧 Files skipped from review as they are similar to previous changes (3)

• deepmd/pt/loss/ener.py
• deepmd/utils/argcheck.py
• deepmd/dpmodel/loss/ener.py

---

📝 Walkthrough

Walkthrough

Energy-loss modules now accept either a single float or a 3-element list for huber_delta; inputs are resolved into per-term deltas (energy, force, virial) via a new resolver and per-term thresholds are used in Huber-loss computations across DP/PT/PD/TF implementations. Argument docs and validation were updated accordingly.

Changes

Cohort / File(s)	Summary
Loss implementations (runtime/backends) deepmd/dpmodel/loss/ener.py, deepmd/pt/loss/ener.py, deepmd/pd/loss/ener.py, deepmd/tf/loss/ener.py	Constructor/signature updated to accept `huber_delta: float
Utilities (validation & helpers) deepmd/utils/loss.py, deepmd/utils/argcheck.py	Added resolve_huber_deltas(huber_delta) to normalize/validate single vs 3-element inputs (expects [energy, force, virial] for list). Updated loss_ener() arg documentation/type to accept float or list[float] and reflect the 3-element ordering.
Serialization/Backward compatibility note (implicit) ...	self.huber_delta assignment/serialize() unchanged (may now hold a list); behavior preserved but Huber computations use resolved per-term fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(dpmodel): fix natoms[0] bug, einsum, and return type in EnergyLoss #5325: Touches deepmd/dpmodel/loss/ener.py and modifies EnergyLoss.call() internals and reshaping logic — directly related to DP loss changes here.
• feat: add huber loss #4684: Introduced Huber-loss support in loss modules; this change extends that work to accept per-term (3-value) deltas.
• feat: dpmodel energy loss & consistent tests #4531: Also modifies EnergyLoss implementations and is relevant to overlapping loss computation changes.

Suggested reviewers

• njzjz
• iProzd
• wanghan-iapcm

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(loss): support three-value huber delta' clearly and concisely summarizes the main change: extending the huber_delta parameter to accept three separate values instead of just one.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds support for specifying separate Huber-loss deltas for energy/force/virial in the PyTorch and dpmodel energy losses, and updates the config arg schema/docs to allow either a scalar or 3-value list.

Changes:

• Extend huber_delta to accept float | list[float] and resolve it into per-term deltas in PyTorch and dpmodel energy losses.
• Update argcheck documentation and schema type for huber_delta to allow a 3-value list [energy, force, virial].

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
deepmd/utils/argcheck.py	Updates huber_delta documentation and schema type to allow either a float or 3-value list.
deepmd/pt/loss/ener.py	Resolves huber_delta into per-term deltas and applies them in Huber loss branches.
deepmd/dpmodel/loss/ener.py	Mirrors the per-term delta resolution and usage for the array-API/dpmodel implementation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 76.47059% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.30%. Comparing base (3f52fa9) to head (a7a1edd).

Files with missing lines	Patch %	Lines
deepmd/utils/loss.py	57.14%	3 Missing ⚠️
deepmd/dpmodel/loss/ener.py	66.66%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #5329   +/-   ##
=======================================
  Coverage   82.30%   82.30%           
=======================================
  Files         777      778    +1     
  Lines       77938    77953   +15     
  Branches     3675     3676    +1     
=======================================
+ Hits        64150    64163   +13     
- Misses      12614    12617    +3     
+ Partials     1174     1173    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.