diff --git a/README.md b/README.md index 851973b1..fe3e6de2 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,7 @@ DPGEN2 is the 2nd generation of the Deep Potential GENerator. The document is available at [this page](https://docs.deepmodeling.com/projects/dpgen2) +See the [supported-feature matrix](docs/features.md) for the exploration engines, +labeling backends, workflows, and known gaps available in the current release. + For developers please read the [developers guide](docs/developer.md) diff --git a/docs/developer.md b/docs/developer.md index 00ef490d..234efbee 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -12,7 +12,7 @@ DPGEN2 implements the concurrent learning algorithm named DP-GEN, described in [ The DP-GEN algorithm is iterative. In each iteration, four steps are consecutively executed: training, exploration, selection, and labeling. 1. **Training**. A set of DP models are trained with the same dataset and the same hyperparameters. The only difference is the random seed initializing the model parameters. -2. **Exploration**. One of the DP models is used to explore the configuration space. The strategy of exploration highly depends on the purpose of the application case of the model. The simulation technique for exploration can be molecular dynamics, Monte Carlo, structure search/optimization, enhanced sampling, or any combination of them. Current DPGEN2 only supports exploration based on molecular simulation platform [LAMMPS](https://www.lammps.org/). +2. **Exploration**. One of the DP models is used to explore the configuration space. The strategy of exploration highly depends on the purpose of the application case of the model. The simulation technique for exploration can be molecular dynamics, Monte Carlo, structure search/optimization, enhanced sampling, or any combination of them. The built-in exploration paths currently include LAMMPS, CALYPSO, and DiffCSP; see the [supported-feature matrix](./features.md) for their support level and examples. 3. **Selection**. Not all the explored configurations are labeled, rather, the model prediction errors on the configurations are estimated by the ***model deviation***, which is defined as the standard deviation in predictions of the set of the models. The critical configurations with large and not-that-large errors are selected for labeling. The configurations with very large errors are not selected because the large error is usually caused by non-physical configurations, e.g. overlapping atoms. 4. **Labeling**. The selected configurations are labeled with energy, forces, and virial calculated by a method of first-principles accuracy. The usually used method is the [density functional theory](https://doi.org/10.1103/PhysRev.140.A1133) implemented in [VASP](https://www.vasp.at/), [Quantum Expresso](https://www.quantum-espresso.org/), [CP2K](https://www.cp2k.org/), and etc.. The labeled data are finally added to the training dataset to start the next iteration. diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000..6056db42 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,54 @@ +# Supported features + +This page records the features wired into the main `dpgen2 submit` workflow on +the current branch. It replaces the historical project status that described +DPGEN2 as supporting only DeePMD-kit, LAMMPS, and VASP. + +The support levels used below are: + +- **Supported**: integrated into the configuration schema and concurrent-learning workflow, with tests or an example in this repository. +- **Partial**: a useful lower-level capability exists, but the complete DP-GEN behavior still requires additional implementation. +- **Not implemented**: no built-in workflow integration exists yet. + +## Workflows and training + +| Capability | Status | Implementation and examples | +| --- | --- | --- | +| Concurrent learning | Supported | The [DP-GEN loop](../dpgen2/flow/dpgen_loop.py) is exposed through the [submit and resubmit commands](quickcli.md). | +| DeePMD-kit training | Supported | The `dp` training style uses [PrepRunDPTrain](../dpgen2/superop/prep_run_dp_train.py); the [Al-Mg example](../examples/almg/input.json) provides a compact configuration. | +| Knowledge distillation | Supported | The `dp-dist` training style and DeepMD labeling backend are demonstrated by the [distillation example](../examples/water/input_distill.json). | +| Multitask training and finetuning | Supported | See the [multitask example](../examples/water/input_multitask.json) and the [pretrained-model finetuning example](../examples/water/input_dpgen.json). | +| Simplify workflow | Not implemented | Open a focused feature request describing the desired CLI, artifacts, and compatibility with the DP-GEN simplify workflow. | +| Initial-data generation workflow | Not implemented | Configuration files and existing datasets can be supplied as inputs, but DPGEN2 does not yet generate an initial dataset as a standalone workflow. | + +## Exploration and selection + +| Engine or feature | Status | Configuration and examples | +| --- | --- | --- | +| LAMMPS molecular dynamics | Supported | Use exploration type `lmp` and task type `lmp-md`; see the [Al-Mg example](../examples/almg/input.json). | +| LAMMPS templates and PLUMED | Supported | The `lmp-template` and `customized-lmp-template` task groups support user-provided LAMMPS and PLUMED inputs; see the [CHNO LAMMPS-template example](../examples/chno/input.json) and the [PLUMED template tests](../tests/exploration/test_lmp_templ_task_group.py). | +| CALYPSO structure search | Supported | Use `calypso`, `calypso:default`, or `calypso:merge`; see the [CALYPSO example](../examples/calypso/input.test.json) and [PrepRunCaly](../dpgen2/superop/prep_run_calypso.py). | +| DiffCSP structure generation | Supported | Use exploration type `diffcsp`; see the [DiffCSP example](../examples/diffcsp/dpgen.json) and [PrepRunDiffCSP](../dpgen2/superop/prep_run_diffcsp.py). | +| Atomic model deviation and cluster extraction | Partial | `lmp-md` can request atomic model-deviation output with `use_clusters`, but the built-in selector still labels complete frames rather than extracting local clusters. | +| Gromacs molecular dynamics | Not implemented | No Gromacs exploration OP or submit configuration is registered. | +| AMBER molecular dynamics | Not implemented | No AMBER exploration OP or submit configuration is registered. | + +## Labeling backends + +| Backend | Status | Configuration and examples | +| --- | --- | --- | +| VASP | Supported | Use FP type `vasp`; see the [Al-Mg example](../examples/almg/input.json) and [VASP implementation](../dpgen2/fp/vasp.py). | +| Gaussian | Supported | Use FP type `gaussian`; see the [CHNO example](../examples/chno/input.json) and [Gaussian implementation](../dpgen2/fp/gaussian.py). | +| CP2K | Supported | Use FP type `fpop_cp2k`; see the [CP2K example](../examples/water/input_dpgen_cp2k.json) and [CP2K adapter](../dpgen2/fp/cp2k.py). This adapter requires the optional FPOP dependency. | +| ABACUS | Supported | Use FP type `fpop_abacus`; see the [ABACUS example](../examples/water/input_dpgen_abacus.json) and [ABACUS adapter](../dpgen2/fp/abacus.py). This adapter requires the optional FPOP dependency. | +| DeePMD-kit inference | Supported | Use FP type `deepmd` for teacher-model labeling in distillation workflows; see the [DeepMD implementation](../dpgen2/fp/deepmd.py). | +| Siesta | Not implemented | No Siesta preparation, execution, or output-collection adapter is registered. | + +## Adding a missing capability + +The remaining entries are intentionally listed as focused gaps instead of one +umbrella implementation task. A feature request for one engine or workflow +should define its configuration schema, required executables and files, +prepared task layout, collected output format, unit tests, and a runnable +example. The [operator guide](operator.md) and [exploration extension guide](exploration.md) +describe the integration points. diff --git a/docs/index.rst b/docs/index.rst index 4e549ed1..0a9d68df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ DPGEN2 is the 2nd generation of the Deep Potential GENerator. :caption: User Guide quickcli + features.md cli input.md submit_args diff --git a/tests/test_feature_matrix.py b/tests/test_feature_matrix.py new file mode 100644 index 00000000..90a7ef83 --- /dev/null +++ b/tests/test_feature_matrix.py @@ -0,0 +1,25 @@ +import re +from pathlib import ( + Path, +) + +from dpgen2.fp import ( + fp_styles, +) + + +def test_feature_matrix_matches_registered_fp_styles(): + """Keep every submit-time FP backend discoverable in the feature matrix.""" + feature_doc = Path("docs/features.md").read_text() + for style in fp_styles: + assert f"`{style}`" in feature_doc + + +def test_feature_matrix_local_links_exist(): + """Prevent source and example links in the support table from going stale.""" + feature_path = Path("docs/features.md") + feature_doc = feature_path.read_text() + local_links = re.findall(r"\[[^]]+\]\((?!https?://)([^)#]+)", feature_doc) + assert local_links + for link in local_links: + assert (feature_path.parent / link).resolve().exists(), link