From 989e592eab6b2f9f9123a7a791639a222039c8e0 Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Mon, 24 Aug 2026 04:10:45 +0800 Subject: [PATCH] docs: define HDF5 trajectory storage Document dflow HDF5 dataset artifacts as distinct from native LAMMPS H5MD and preserve the public use_hdf5 option with regression coverage. Coding-Agent: Codex Codex-Version: codex-cli 0.149.1 Model: gpt-5.6-sol Reasoning-Effort: xhigh --- docs/input.md | 4 ++++ dpgen2/entrypoint/args.py | 5 ++++- dpgen2/op/run_lmp.py | 6 +++++- tests/op/test_run_lmp.py | 5 +++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/input.md b/docs/input.md index 6fc03bd1..015910e7 100644 --- a/docs/input.md +++ b/docs/input.md @@ -131,6 +131,10 @@ The {dargs:argument}`"stages"` defines the exploration stag The {dargs:argument}`"n_sample"` tells the number of confgiruations randomly sampled from the set picked by {dargs:argument}`"conf_idx"` from {dargs:argument}`"configurations"` for each exploration task. All configurations has the equal possibility to be sampled. The default value of `"n_sample"` is `null`, in this case all picked configurations are sampled. In the example, we have 3 samples for stage 0 task group 0 and 2 thermodynamic states (NVT, T=50 and 100K), then the task group has 3x2=6 NVT DPMD tasks. +Set `explore.config.use_hdf5` to `true` to store LAMMPS trajectories and model deviations as dflow HDF5 dataset artifacts. LAMMPS still writes the standard text `traj.dump` and `model_devi.out` files inside each task; DPGEN2 serializes their data at the artifact boundary and reads it back transparently during selection. This avoids depending on the optional LAMMPS H5MD package and preserves the frame/model-deviation alignment expected by DPGEN2. + +This option is not the native LAMMPS `dump h5md` format. A custom H5MD dump cannot replace `traj.dump` in the built-in selector because its schema differs from the `lammps/dump` text consumed by dpdata. Use `extra_output_files` if a native H5MD file is needed as an additional output for another analysis tool. + ### FP diff --git a/dpgen2/entrypoint/args.py b/dpgen2/entrypoint/args.py index df11ff7f..bf0fadc6 100644 --- a/dpgen2/entrypoint/args.py +++ b/dpgen2/entrypoint/args.py @@ -359,7 +359,10 @@ def run_diffcsp_args(): doc_gen_tasks = "Number of DiffCSP generation tasks" doc_gen_command = "Command for DiffCSP generation" doc_relax_group_size = "Group size for relaxation" - doc_use_hdf5 = "Use HDF5 to store trajs and model_devis" + doc_use_hdf5 = ( + "Store trajectories and model deviations as dflow HDF5 dataset " + "artifacts; this is independent of LAMMPS dump h5md." + ) return [ Argument( "gen_tasks", diff --git a/dpgen2/op/run_lmp.py b/dpgen2/op/run_lmp.py index 60cd9305..ddd09c08 100644 --- a/dpgen2/op/run_lmp.py +++ b/dpgen2/op/run_lmp.py @@ -230,7 +230,11 @@ def lmp_args(): doc_shuffle_models = "Randomly pick a model from the group of models to drive theexploration MD simulation" doc_head = "Select a head from multitask" doc_use_ele_temp = "Whether to use electronic temperature, 0 for no, 1 for frame temperature, and 2 for atomic temperature" - doc_use_hdf5 = "Use HDF5 to store trajs and model_devis" + doc_use_hdf5 = ( + "Store the standard LAMMPS dump trajectory and model-deviation " + "values in dflow HDF5 dataset artifacts. This does not enable " + "LAMMPS's native dump h5md command." + ) doc_extra_output_files = "Extra output file names, support wildcards" return [ Argument("command", str, optional=True, default="lmp", doc=doc_lmp_cmd), diff --git a/tests/op/test_run_lmp.py b/tests/op/test_run_lmp.py index 650fd82e..41db5514 100644 --- a/tests/op/test_run_lmp.py +++ b/tests/op/test_run_lmp.py @@ -67,6 +67,11 @@ def tearDown(self): if Path(self.task_name).is_dir(): shutil.rmtree(self.task_name) + def test_hdf5_storage_option_is_normalized(self): + config = RunLmp.normalize_config({"use_hdf5": True}) + + self.assertTrue(config["use_hdf5"]) + @patch("dpgen2.op.run_lmp.run_command") def test_success(self, mocked_run): mocked_run.side_effect = [(0, "foo\n", "")]