fix(dpmodel): preserve model dictionaries during serialization (#5788)

## Summary

- preserve the caller-owned model dictionary while save_dp_model()
rewrites variables into YAML or HDF5 references;
- copy only the nested dict and list containers that traversal mutates,
so large arrays are not duplicated;
- retain support for non-copyable variable objects such as h5py.Dataset;
- add regressions for nested YAML/native serialization and an
HDF5-backed variable.

## Why existing tests missed this

The existing save/load tests pass deepcopy(self.model_dict) into
save_dp_model() and then validate only the serialized round trip. That
disposable copy hides mutations of the object supplied by a real caller,
so the shallow-copy bug was never observed.

The new tests pass a caller-owned nested structure directly, assert that
its containers and variables remain unchanged, and cover both
serialization implementations. The HDF5 dataset case also prevents a
memory-heavy full deepcopy from becoming the fix.

## Validation

- targeted serialization tests and existing save/load tests: 6 passed;
- ruff format .;
- ruff check .;
- git diff --check.

Closes #5639.

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


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
  * Saving models no longer alters the original nested data structures.
* Preserves shared and non-copyable objects, including HDF5-backed
datasets, during serialization.
* Ensures saved models retain expected data when loaded across supported
formats.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: njzjz-bot <njzjz-bot@users.noreply.github.com>

Author: njzjz

deepmd/dpmodel/utils/serialization.py

@@ -63,6 +63,22 @@ def traverse_model_dict(
     return model_obj
 
 
+def _copy_model_containers(model_obj: Any) -> Any:
+    """Copy only containers that :func:`traverse_model_dict` mutates.
+
+    Arrays and other variable objects can be large or may not support ``deepcopy``.
+    They remain shared because traversal replaces their entries in parent containers
+    without modifying the variable objects themselves.
+    """
+    if isinstance(model_obj, dict):
+        if model_obj.get("@is_variable", False):
+            return model_obj
+        return {key: _copy_model_containers(value) for key, value in model_obj.items()}
+    if isinstance(model_obj, list):
+        return [_copy_model_containers(value) for value in model_obj]
+    return model_obj
+
+
 class Counter:
     """A callable counter.
 
@@ -91,9 +107,12 @@ def save_dp_model(filename: str, model_dict: dict) -> None:
     filename : str
         The filename to save to.
     model_dict : dict
-        The model dict to save.
+        The model dict to save. The caller retains ownership, and this function does
+        not modify it.
     """
-    model_dict = model_dict.copy()
+    # Give traversal an independent container tree while retaining references to
+    # potentially large or non-copyable variable objects.
+    model_dict = _copy_model_containers(model_dict)
     filename_extension = Path(filename).suffix
     extra_dict = {
         "software": "deepmd-kit",

source/tests/common/dpmodel/test_serialization.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+from copy import (
+    deepcopy,
+)
+from pathlib import (
+    Path,
+)
+
+import h5py
+import numpy as np
+import pytest
+
+from deepmd.dpmodel.utils.serialization import (
+    load_dp_model,
+    save_dp_model,
+)
+
+
+@pytest.mark.parametrize(
+    "suffix",
+    [
+        pytest.param(".yaml", id="yaml"),
+        pytest.param(".dp", id="native-hdf5"),
+    ],
+)
+def test_save_dp_model_preserves_nested_input(tmp_path: Path, suffix: str) -> None:
+    """Saving must not modify caller-owned containers or variables."""
+    weights = np.arange(6, dtype=np.float64).reshape(2, 3)
+    model_dict = {
+        "model": {
+            "layers": [
+                {
+                    "@variables": {
+                        "weights": weights,
+                        "bias": np.array([0.25, -0.5], dtype=np.float64),
+                    }
+                }
+            ],
+            "metadata": {"labels": ["energy", "force"]},
+        }
+    }
+    expected = deepcopy(model_dict)
+
+    save_dp_model(str(tmp_path / f"model{suffix}"), model_dict)
+
+    np.testing.assert_equal(model_dict, expected)
+    assert model_dict["model"]["layers"][0]["@variables"]["weights"] is weights
+
+
+def test_save_dp_model_accepts_hdf5_dataset_without_mutation(tmp_path: Path) -> None:
+    """Native saving must preserve non-copyable HDF5 variable objects."""
+    values = np.arange(6, dtype=np.float64).reshape(2, 3)
+    with h5py.File(tmp_path / "variables.h5", "w") as variable_file:
+        weights = variable_file.create_dataset("weights", data=values)
+        variables = {"weights": weights}
+        layer = {"@variables": variables}
+        layers = [layer]
+        model_dict = {"model": {"layers": layers}}
+
+        output = tmp_path / "model.dp"
+        save_dp_model(str(output), model_dict)
+
+        assert model_dict["model"]["layers"] is layers
+        assert layers[0] is layer
+        assert layer["@variables"] is variables
+        assert variables["weights"] is weights
+        np.testing.assert_equal(weights[()], values)
+
+    loaded_model = load_dp_model(str(output))
+    np.testing.assert_equal(
+        loaded_model["model"]["layers"][0]["@variables"]["weights"], values
+    )