From 4af3cfaa0d99f8646acc36039592be37056d0b4e Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Thu, 27 Jun 2024 17:09:09 -0400 Subject: [PATCH 1/3] docs: developer docs for the universal unit tests Fix #3736. Signed-off-by: Jinzhe Zeng --- doc/development/create-a-model-pt.md | 21 ++++++++++++++++++++- doc/development/create-a-model-tf.md | 2 +- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md index c6d372b195..1f686b3c25 100644 --- a/doc/development/create-a-model-pt.md +++ b/doc/development/create-a-model-pt.md @@ -1,4 +1,10 @@ -# Create a model in PyTorch +# Create a model in other backends {{ pytorch_icon }} {{ dpmodel_icon }} + +:::{note} +**Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }} + +In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above. +::: If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainner, etc, you may want to read this section. @@ -164,6 +170,19 @@ The arguments here should be consistent with the class arguments of your new com ## Unit tests +### Universal tests + +The `source/tests/universal` directory provides universal test suites for different models and backends. +The subdirectory `cases` defines fixtures for different cases of models, atomic models, descriptors, and fitting networks. +The subdirectory `dpmodel` and `pt` are backend-specific test fixtures and suites. +Each test suite tests APIs and whether the serialized models gives the same results as the original models. +Specially, the test suite for models also tests whether the model is permutation, translation, and rotation invariant, whether the model is differentiable and smooth near the cutoff radius, and whether the force is the negative gradient of the energy. + +When adding a new model, add the fixture to the `cases` subdiretory and then apply the test fixture in the suite of different backends. +When implementing an existing model in a new backend, directly apply the existing test fixture to the test suite of that backend. + +### Consistent tests + When transferring features from another backend to the PyTorch backend, it is essential to include a regression test in `/source/tests/consistent` to validate the consistency of the PyTorch backend with other backends. Presently, the regression tests cover self-consistency and cross-backend consistency between TensorFlow, PyTorch, and DP (Numpy) through the serialization/deserialization technique. During the development of new components within the PyTorch backend, it is necessary to provide a DP (Numpy) implementation and incorporate corresponding regression tests. For PyTorch components, developers are also required to include a unit test using `torch.jit`. diff --git a/doc/development/create-a-model-tf.md b/doc/development/create-a-model-tf.md index b39313a8d3..2794387403 100644 --- a/doc/development/create-a-model-tf.md +++ b/doc/development/create-a-model-tf.md @@ -1,4 +1,4 @@ -# Create a model in TensorFlow +# Create a model in TensorFlow {{ tensorflow_icon }} If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainner, etc, you may want to read this section. From e65759b13c0bc9e4d3cb512c73a1644e03e2bb73 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Thu, 27 Jun 2024 17:19:56 -0400 Subject: [PATCH 2/3] fix the grammar Signed-off-by: Jinzhe Zeng --- doc/development/create-a-model-pt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md index 1f686b3c25..8f0830f8db 100644 --- a/doc/development/create-a-model-pt.md +++ b/doc/development/create-a-model-pt.md @@ -175,7 +175,7 @@ The arguments here should be consistent with the class arguments of your new com The `source/tests/universal` directory provides universal test suites for different models and backends. The subdirectory `cases` defines fixtures for different cases of models, atomic models, descriptors, and fitting networks. The subdirectory `dpmodel` and `pt` are backend-specific test fixtures and suites. -Each test suite tests APIs and whether the serialized models gives the same results as the original models. +Each test suite tests APIs and whether the serialized models give the same results as the original models. Specially, the test suite for models also tests whether the model is permutation, translation, and rotation invariant, whether the model is differentiable and smooth near the cutoff radius, and whether the force is the negative gradient of the energy. When adding a new model, add the fixture to the `cases` subdiretory and then apply the test fixture in the suite of different backends. From 1d60923e684ff39ca91e526a69c376f2fe82be5e Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Sun, 30 Jun 2024 23:00:38 -0400 Subject: [PATCH 3/3] Update create-a-model-pt.md Co-authored-by: Han Wang <92130845+wanghan-iapcm@users.noreply.github.com> Signed-off-by: Jinzhe Zeng --- doc/development/create-a-model-pt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md index 8f0830f8db..3c07e404ae 100644 --- a/doc/development/create-a-model-pt.md +++ b/doc/development/create-a-model-pt.md @@ -173,7 +173,7 @@ The arguments here should be consistent with the class arguments of your new com ### Universal tests The `source/tests/universal` directory provides universal test suites for different models and backends. -The subdirectory `cases` defines fixtures for different cases of models, atomic models, descriptors, and fitting networks. +The subdirectory `cases` defines fixtures for different test cases of models, atomic models, descriptors, and fitting networks. The subdirectory `dpmodel` and `pt` are backend-specific test fixtures and suites. Each test suite tests APIs and whether the serialized models give the same results as the original models. Specially, the test suite for models also tests whether the model is permutation, translation, and rotation invariant, whether the model is differentiable and smooth near the cutoff radius, and whether the force is the negative gradient of the energy.