[Code scan] Freeze Paddle DPA3 parameters with stop_gradient

[njzjz]

This issue comes from a Codex global scan of deepmodeling/deepmd-kit at commit 73de44b1f94471b2e3bdb6b11f57b34d7bc791bb.

Problem

The Paddle DPA3 descriptor tries to honor trainable=False by setting param.requires_grad = trainable:

deepmd-kit/deepmd/pd/model/descriptor/dpa3.py

Lines 251 to 253 in 73de44b

	# set trainable
	for param in self.parameters():
	param.requires_grad = trainable

Other Paddle descriptors freeze parameters with stop_gradient, which is the Paddle parameter flag used by autograd:

deepmd-kit/deepmd/pd/model/descriptor/se_a.py

Lines 528 to 531 in 73de44b

	# set trainable
	self.trainable = trainable
	for param in self.parameters():
	param.stop_gradient = not trainable

deepmd-kit/deepmd/pd/model/descriptor/dpa2.py

Lines 331 to 333 in 73de44b

	# set trainable
	for param in self.parameters():
	param.stop_gradient = not trainable

Impact

Users configuring a non-trainable Paddle DPA3 descriptor can still update descriptor parameters during training because the freeze pass writes a PyTorch-style attribute instead of Paddle's stop_gradient flag. DPA3's RepFlow/MLP parameters rely on this outer descriptor freeze pass, so the requested freeze does not take effect.

Suggested fix

Use the same Paddle pattern as the neighboring descriptors:

for param in self.parameters():
    param.stop_gradient = not trainable

If Paddle exposes any additional trainable-state APIs in the supported versions, keep this consistent across all Paddle descriptor wrappers.

[wanghan-iapcm]

On checking against the installed Paddle, the DPA3 freeze is not actually broken, so I'm deferring a fix.

Paddle's Tensor provides requires_grad as a working property that aliases stop_gradient (setting param.requires_grad = value sets param.stop_gradient = not value). Verified with a bare import paddle (no deepmd):

import paddle
x = paddle.create_parameter([2], dtype="float32")
x.requires_grad = False
assert x.stop_gradient is True   # holds

So for param in self.parameters(): param.requires_grad = trainable in deepmd/pd/model/descriptor/dpa3.py does correctly freeze the parameters when trainable=False, and a test asserting all(p.stop_gradient for p in dd.parameters()) passes on the current code. There is no failing case to demonstrate.

That said, DPA3 is the only Paddle descriptor using requires_grad; the siblings (se_a, dpa2, …) use param.stop_gradient = not trainable. Switching DPA3 to match would be a consistency/robustness cleanup (not relying on the requires_grad compat alias), but it is not a functional bug fix, so I'm leaving it unless you'd like the consistency change made. If a supported Paddle version is known to not provide the requires_grad alias, please point to it and I'll ship the stop_gradient change with a regression test.