fix(paddle): freeze DPA3 descriptor parameters

[njzjz]

Closes #5686.

Summary

• freeze Paddle DPA3 parameters with Paddle's stop_gradient flag instead of assigning a PyTorch-style requires_grad attribute;
• centralize descriptor-level trainability in _apply_trainable();
• reapply the setting after deserialization replaces type, charge/spin, MLP, edge/angle, and RepFlow child layers;
• add a regression covering both direct construction and serialize/deserialize round-trip with charge/spin embeddings enabled.

Root cause

Paddle's autograd contract is parameter.stop_gradient. On the project's minimum supported Paddle 3.0.0, assigning parameter.requires_grad merely adds an unrelated Python attribute and leaves stop_gradient=False, so optimizers can still update a descriptor configured with trainable=False.

Construction was not the only affected path. DescrptDPA3.deserialize() constructs a descriptor and then replaces several registered child layers with freshly deserialized parameters. The descriptor-level freeze therefore needs to run again after all replacements are complete.

Why existing tests missed this

Existing DPA3 consistency tests compare numerical outputs and serialization behavior, but do not inspect Paddle autograd flags. A model can produce identical inference values while its supposedly frozen parameters remain trainable.

The regression temporarily masks newer Paddle's requires_grad compatibility alias, retaining the minimum-version semantics even in nightly CI. It then requires every named parameter to have stop_gradient=True both immediately after construction and after a round-trip. Enabling add_chg_spin_ebd=True ensures the optional replacement paths are included.

Old-fail / new-pass validation

• original implementation, Paddle 3.0.0: failed with 17 parameters still requiring gradients;
• original implementation, Paddle 3.4.0.dev20260310: failed with the same 17 parameters under the minimum-version compatibility seam;
• constructor-only intermediate fix, Paddle 3.0.0: construction passed but round-trip failed with 22 unfrozen parameters;
• constructor-only intermediate fix, Paddle 3.4.0.dev20260310: round-trip failed with 28 unfrozen parameters;
• complete fix, Paddle 3.0.0: regression passed, including both subtests;
• complete fix, Paddle 3.4.0.dev20260310: regression plus existing DPA3 consistency test passed (2 passed).

Additional checks:

• ruff format .;
• ruff check .;
• git diff --check;
• independent final review: no findings.

Coding agent: Codex
Codex version: codex-cli 0.144.1
Model: gpt-5.6-sol
Reasoning effort: xhigh

Summary by CodeRabbit

• Bug Fixes

  • Fixed non-trainable DPA3 descriptor parameters becoming trainable after deserialization.
  • Ensured the non-trainable setting consistently prevents gradient updates before and after model loading.

• Tests

  • Added coverage verifying parameter gradient settings during initialization and serialization/deserialization.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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: af66fdd4-f3fb-4e5f-b165-75024522a1c6

📥 Commits

Reviewing files that changed from the base of the PR and between 3122138 and d71bb3d.

📒 Files selected for processing (2)

• deepmd/pd/model/descriptor/dpa3.py
• source/tests/pd/model/test_dpa3.py

---

📝 Walkthrough

Walkthrough

DPA3 now applies Paddle’s stop_gradient flag through a shared helper during construction and deserialization. Tests verify that non-trainable parameters remain frozen after serialization and deserialization.

Changes

DPA3 trainability lifecycle

Layer / File(s)	Summary
Apply and verify parameter freezing deepmd/pd/model/descriptor/dpa3.py, source/tests/pd/model/test_dpa3.py	DescrptDPA3 applies stop_gradient through _apply_trainable() during construction and after deserialized sublayers are registered. Tests verify frozen parameters before and after a serialization round trip.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: copilot, hydrogensulfate

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the main change: freezing Paddle DPA3 descriptor parameters.
Linked Issues check	✅ Passed	The PR addresses #5686 by switching DPA3 freezing to stop_gradient and reapplying it after deserialization.
Out of Scope Changes check	✅ Passed	The changes stay focused on DPA3 trainability and regression coverage, with no obvious unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[njzjz]

Possible reviewers based on changed lines, exact file history, and exact-file review history:

• @iProzd — 8 reviews on exact changed files (deepmd/pd/model/descriptor/dpa3.py, source/tests/pd/model/test_dpa3.py).

No review request was made automatically.

Coding agent: Codex
Codex version: codex-cli 0.144.4
Model: gpt-5.6-sol
Reasoning effort: xhigh