Skip to content

Commit

Permalink
docs: developer docs for the universal unit tests (#3921)
Browse files Browse the repository at this point in the history
Fix #3736.

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

- **Documentation**
- Updated documentation to include information on creating models in
various backends (PyTorch, DP).
- Added sections on unit tests and regression tests for ensuring
consistency across different backends.
- Incorporated icons and notes to denote supported backends in the
documentation.
- Added a TensorFlow icon in the "Create a model in TensorFlow" section.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>
Co-authored-by: Han Wang <92130845+wanghan-iapcm@users.noreply.github.com>
  • Loading branch information
njzjz and wanghan-iapcm authored Jul 3, 2024
1 parent ec1cf86 commit 5f70fce
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 2 deletions.
21 changes: 20 additions & 1 deletion doc/development/create-a-model-pt.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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 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.

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`.
2 changes: 1 addition & 1 deletion doc/development/create-a-model-tf.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down

0 comments on commit 5f70fce

Please sign in to comment.