Skip to content

docs: format json/c++ codes in markdown #5187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
njzjz wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

docs: format json/c++ codes in markdown #5187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0e6c423
docs: format json/c++ codes in markdown
njzjz Feb 2, 2026
a4b12e3
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 2, 2026
a12ea0c
Add args to clang-format-docs hook
njzjz Feb 2, 2026
b50a012
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 2, 2026
de6fbe7
Enable BreakArrays in clang-format configuration
njzjz Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .clang-format
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,5 @@
BasedOnStyle: Google
BinPackParameters: false
InsertBraces: true
BreakArrays: true
...
6 changes: 6 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,12 @@ repos:
rev: 1.20.0
hooks:
- id: blacken-docs
- repo: https://github.com/finsberg/clang-format-docs
rev: v0.4.0
hooks:
- id: clang-format-docs
args: ["--style=file:.clang-format"]
additional_dependencies: [clang-format==21.1.8]
# C++
- repo: https://github.com/pre-commit/mirrors-clang-format
rev: v21.1.8
Expand Down
6 changes: 1 addition & 5 deletions doc/development/create-a-model-pt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,11 +168,7 @@ def descrpt_some_args() -> list[Argument]:
allows one to use your new descriptor as below:

```json
"descriptor" :{
"type": "some_descrpt",
"arg1": true,
"arg2": 6.0
}
"descriptor" : {"type" : "some_descrpt", "arg1" : true, "arg2" : 6.0}
```

The arguments here should be consistent with the class arguments of your new component.
Expand Down
6 changes: 1 addition & 5 deletions doc/development/create-a-model-tf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,7 @@ def descrpt_some_args() -> list[Argument]:
allows one to use your new descriptor as below:

```json
"descriptor" :{
"type": "some_descrpt",
"arg1": true,
"arg2": 6.0
}
"descriptor" : {"type" : "some_descrpt", "arg1" : true, "arg2" : 6.0}
```

The arguments here should be consistent with the class arguments of your new component.
Expand Down
6 changes: 1 addition & 5 deletions doc/development/type-embedding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,7 @@ A detailed introduction can be found at [`se_e2_a_tebd`](../model/train-se-e2-a-
An example of `type_embedding` is like

```json
"type_embedding":{
"neuron": [2, 4, 8],
"resnet_dt": false,
"seed": 1
}
"type_embedding" : {"neuron" : [ 2, 4, 8 ], "resnet_dt" : false, "seed" : 1}
```

## Code Modification
Expand Down
65 changes: 32 additions & 33 deletions doc/inference/cxx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ The C++ interface of DeePMD-kit is also available for the model interface, which
```cpp
#include "deepmd/DeepPot.h"

int main(){
deepmd::DeepPot dp ("graph.pb");
std::vector<double > coord = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
std::vector<double > cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
std::vector<int > atype = {1, 0, 1};
int main() {
deepmd::DeepPot dp("graph.pb");
std::vector<double> coord = {1., 0., 0., 0., 0., 1.5, 1., 0., 3.};
std::vector<double> cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
std::vector<int> atype = {1, 0, 1};
double e;
std::vector<double > f, v;
dp.compute (e, f, v, coord, atype, cell);
std::vector<double> f, v;
dp.compute(e, f, v, coord, atype, cell);
}
```

Expand Down Expand Up @@ -46,28 +46,31 @@ An example `infer_water.c` is given below:
```cpp
#include <stdio.h>
#include <stdlib.h>

#include "deepmd/c_api.h"

int main(){
int main() {
const char* model = "graph.pb";
double coord[] = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
double coord[] = {1., 0., 0., 0., 0., 1.5, 1., 0., 3.};
double cell[] = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
int atype[] = {1, 0, 1};
// init C pointers with given memory
double* e = malloc(sizeof(*e));
double* f = malloc(sizeof(*f) * 9); // natoms * 3
double* f = malloc(sizeof(*f) * 9); // natoms * 3
double* v = malloc(sizeof(*v) * 9);
double* ae = malloc(sizeof(*ae) * 9); // natoms
double* av = malloc(sizeof(*av) * 27); // natoms * 9
double* ae = malloc(sizeof(*ae) * 9); // natoms
double* av = malloc(sizeof(*av) * 27); // natoms * 9
// DP model
DP_DeepPot* dp = DP_NewDeepPot(model);
DP_DeepPotCompute (dp, 3, coord, atype, cell, e, f, v, ae, av);
DP_DeepPotCompute(dp, 3, coord, atype, cell, e, f, v, ae, av);
// print results
printf("energy: %f\n", *e);
for (int ii = 0; ii < 9; ++ii)
for (int ii = 0; ii < 9; ++ii) {
printf("force[%d]: %f\n", ii, f[ii]);
for (int ii = 0; ii < 9; ++ii)
}
for (int ii = 0; ii < 9; ++ii) {
printf("force[%d]: %f\n", ii, v[ii]);
}
// free memory
free(e);
free(f);
Expand Down Expand Up @@ -103,14 +106,14 @@ To use it, include `deepmd/deepmd.hpp`.
```cpp
#include "deepmd/deepmd.hpp"

int main(){
deepmd::hpp::DeepPot dp ("graph.pb");
std::vector<double > coord = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
std::vector<double > cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
std::vector<int > atype = {1, 0, 1};
int main() {
deepmd::hpp::DeepPot dp("graph.pb");
std::vector<double> coord = {1., 0., 0., 0., 0., 1.5, 1., 0., 3.};
std::vector<double> cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
std::vector<int> atype = {1, 0, 1};
double e;
std::vector<double > f, v;
dp.compute (e, f, v, coord, atype, cell);
std::vector<double> f, v;
dp.compute(e, f, v, coord, atype, cell);
}
```

Expand All @@ -132,17 +135,13 @@ and then run the program:
In some cases, one may want to pass the custom neighbor list instead of the native neighbor list. The above code can be revised as follows:

```cpp
// neighbor list
std::vector<std::vector<int >> nlist_vec = {
{1, 2},
{0, 2},
{0, 1}
};
std::vector<int> ilist(3), numneigh(3);
std::vector<int*> firstneigh(3);
InputNlist nlist(3, &ilist[0], &numneigh[0], &firstneigh[0]);
convert_nlist(nlist, nlist_vec);
dp.compute (e, f, v, coord, atype, cell, 0, nlist, 0);
// neighbor list
std::vector<std::vector<int>> nlist_vec = {{1, 2}, {0, 2}, {0, 1}};
std::vector<int> ilist(3), numneigh(3);
std::vector<int*> firstneigh(3);
InputNlist nlist(3, &ilist[0], &numneigh[0], &firstneigh[0]);
convert_nlist(nlist, nlist_vec);
dp.compute(e, f, v, coord, atype, cell, 0, nlist, 0);
```

Here, `nlist_vec` means the neighbors of atom 0 are atom 1 and atom 2, the neighbors of atom 1 are atom 0 and atom 2, and the neighbors of atom 2 are atom 0 and atom 1.
34 changes: 15 additions & 19 deletions doc/model/dplr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,23 +50,19 @@ It is noted that **the tutorial dataset is not enough for training a productive
Two settings make the training input script different from an energy training input:

```json
"fitting_net": {
"type": "dipole",
"dipole_type": [0],
"neuron": [128, 128, 128],
"seed": 1
},
"fitting_net" : {
"type" : "dipole",
"dipole_type" : [0],
"neuron" : [ 128, 128, 128 ],
"seed" : 1
},
```

The type of fitting is set to {ref}`dipole <model[standard]/fitting_net[dipole]>`. The dipole is associated with type 0 atoms (oxygens), by the setting `"dipole_type": [0]`. What we trained is the displacement of the WC from the corresponding oxygen atom. It shares the same training input as the atomic dipole because both are 3-dimensional vectors defined on atoms.
The loss section is provided as follows

```json
"loss": {
"type": "tensor",
"pref": 0.0,
"pref_atomic": 1.0
},
"loss" : {"type" : "tensor", "pref" : 0.0, "pref_atomic" : 1.0},
```

so that the atomic dipole is trained as labels. Note that the NumPy compressed file `atomic_dipole.npy` should be provided in each dataset. In the context of DPLR models, the atomic dipole data represents the displacement vector from each atom to its associated Wannier centroid (WC), which can be calculated as `atomic_dipole = wannier_centroid_position - atom_position` from DFT calculations using tools such as VASP with Wannier90.
Expand All @@ -82,14 +78,14 @@ dp train dw.json && dp freeze -o dw.pb
The training of the DPLR model is very similar to the standard short-range DP models. An example input script can be found in the example directory. The following section is introduced to compute the long-range energy contribution of the DPLR model, and modify the short-range DP model by this part.

```json
"modifier": {
"type": "dipole_charge",
"model_name": "dw.pb",
"model_charge_map": [-8],
"sys_charge_map": [6, 1],
"ewald_h": 1.00,
"ewald_beta": 0.40
},
"modifier" : {
"type" : "dipole_charge",
"model_name" : "dw.pb",
"model_charge_map" : [-8],
"sys_charge_map" : [ 6, 1 ],
"ewald_h" : 1.00,
"ewald_beta" : 0.40
},
```

The {ref}`model_name <model/modifier[dipole_charge]/model_name>` specifies which DW model is used to predict the position of WCs. {ref}`model_charge_map <model/modifier[dipole_charge]/model_charge_map>` gives the amount of charge assigned to WCs. {ref}`sys_charge_map <model/modifier[dipole_charge]/sys_charge_map>` provides the nuclear charge of oxygen (type 0) and hydrogen (type 1) atoms. {ref}`ewald_beta <model/modifier[dipole_charge]/ewald_beta>` (unit $\text{Å}^{-1}$) gives the spread parameter controls the spread of Gaussian charges, and {ref}`ewald_h <model/modifier[dipole_charge]/ewald_h>` (unit Å) assigns the grid size of Fourier transformation.
Expand Down
129 changes: 68 additions & 61 deletions doc/model/dprc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Two levels of data use the same MM method, so $E_\text{MM}$ is eliminated.
In a DPRc model, QM atoms and MM atoms have different atom types. Assuming we have 4 QM atom types (C, H, O, P) and 2 MM atom types (HW, OW):

```json
"type_map": ["C", "H", "HW", "O", "OW", "P"]
"type_map" : [ "C", "H", "HW", "O", "OW", "P" ]
```

As described in the paper, the DPRc model only corrects $E_\text{QM}$ and $E_\text{QM/MM}$ within the cutoff, so we use a hybrid descriptor to describe them separately:
Expand All @@ -73,31 +73,36 @@ As described in the paper, the DPRc model only corrects $E_\text{QM}$ and $E_\te
:::{tab-item} TensorFlow {{ tensorflow_icon }}

```json
"descriptor" :{
"type": "hybrid",
"list" : [
{
"type": "se_a_ebd_v2",
"sel": [6, 11, 0, 6, 0, 1],
"rcut_smth": 1.00,
"rcut": 9.00,
"neuron": [12, 25, 50],
"exclude_types": [[2, 2], [2, 4], [4, 4], [0, 2], [0, 4], [1, 2], [1, 4], [3, 2], [3, 4], [5, 2], [5, 4]],
"axis_neuron": 12,
"_comment": " QM/QM interaction"
},
{
"type": "se_a_ebd_v2",
"sel": [6, 11, 100, 6, 50, 1],
"rcut_smth": 0.50,
"rcut": 6.00,
"neuron": [12, 25, 50],
"exclude_types": [[0, 0], [0, 1], [0, 3], [0, 5], [1, 1], [1, 3], [1, 5], [3, 3], [3, 5], [5, 5], [2, 2], [2, 4], [4, 4]],
"axis_neuron": 12,
"set_davg_zero": true,
"_comment": " QM/MM interaction"
}
]
"descriptor" : {
"type" : "hybrid", "list" : [
{
"type" : "se_a_ebd_v2",
"sel" : [ 6, 11, 0, 6, 0, 1 ],
"rcut_smth" : 1.00,
"rcut" : 9.00,
"neuron" : [ 12, 25, 50 ],
"exclude_types" : [
[ 2, 2 ], [ 2, 4 ], [ 4, 4 ], [ 0, 2 ], [ 0, 4 ], [ 1, 2 ], [ 1, 4 ],
[ 3, 2 ], [ 3, 4 ], [ 5, 2 ], [ 5, 4 ]
],
"axis_neuron" : 12,
"_comment" : " QM/QM interaction"
},
{
"type" : "se_a_ebd_v2",
"sel" : [ 6, 11, 100, 6, 50, 1 ],
"rcut_smth" : 0.50,
"rcut" : 6.00,
"neuron" : [ 12, 25, 50 ],
"exclude_types" : [
[ 0, 0 ], [ 0, 1 ], [ 0, 3 ], [ 0, 5 ], [ 1, 1 ], [ 1, 3 ], [ 1, 5 ],
[ 3, 3 ], [ 3, 5 ], [ 5, 5 ], [ 2, 2 ], [ 2, 4 ], [ 4, 4 ]
],
"axis_neuron" : 12,
"set_davg_zero" : true,
"_comment" : " QM/MM interaction"
}
]
}
```

Expand All @@ -106,33 +111,38 @@ As described in the paper, the DPRc model only corrects $E_\text{QM}$ and $E_\te
:::{tab-item} PyTorch {{ pytorch_icon }}

```json
"descriptor" :{
"type": "hybrid",
"list" : [
{
"type": "se_e2_a",
"sel": [6, 11, 0, 6, 0, 1],
"rcut_smth": 1.00,
"rcut": 9.00,
"neuron": [12, 25, 50],
"exclude_types": [[2, 2], [2, 4], [4, 4], [0, 2], [0, 4], [1, 2], [1, 4], [3, 2], [3, 4], [5, 2], [5, 4]],
"axis_neuron": 12,
"type_one_side": true,
"_comment": " QM/QM interaction"
},
{
"type": "se_e2_a",
"sel": [6, 11, 100, 6, 50, 1],
"rcut_smth": 0.50,
"rcut": 6.00,
"neuron": [12, 25, 50],
"exclude_types": [[0, 0], [0, 1], [0, 3], [0, 5], [1, 1], [1, 3], [1, 5], [3, 3], [3, 5], [5, 5], [2, 2], [2, 4], [4, 4]],
"axis_neuron": 12,
"set_davg_zero": true,
"type_one_side": true,
"_comment": " QM/MM interaction"
}
]
"descriptor" : {
"type" : "hybrid", "list" : [
{
"type" : "se_e2_a",
"sel" : [ 6, 11, 0, 6, 0, 1 ],
"rcut_smth" : 1.00,
"rcut" : 9.00,
"neuron" : [ 12, 25, 50 ],
"exclude_types" : [
[ 2, 2 ], [ 2, 4 ], [ 4, 4 ], [ 0, 2 ], [ 0, 4 ], [ 1, 2 ], [ 1, 4 ],
[ 3, 2 ], [ 3, 4 ], [ 5, 2 ], [ 5, 4 ]
],
"axis_neuron" : 12,
"type_one_side" : true,
"_comment" : " QM/QM interaction"
},
{
"type" : "se_e2_a",
"sel" : [ 6, 11, 100, 6, 50, 1 ],
"rcut_smth" : 0.50,
"rcut" : 6.00,
"neuron" : [ 12, 25, 50 ],
"exclude_types" : [
[ 0, 0 ], [ 0, 1 ], [ 0, 3 ], [ 0, 5 ], [ 1, 1 ], [ 1, 3 ], [ 1, 5 ],
[ 3, 3 ], [ 3, 5 ], [ 5, 5 ], [ 2, 2 ], [ 2, 4 ], [ 4, 4 ]
],
"axis_neuron" : 12,
"set_davg_zero" : true,
"type_one_side" : true,
"_comment" : " QM/MM interaction"
}
]
}
```

Expand Down Expand Up @@ -166,10 +176,10 @@ print(
Also, DPRc assumes MM atom energies ({ref}`atom_ener <model[standard]/fitting_net[ener]/atom_ener>`) are zero:

```json
"fitting_net": {
"neuron": [240, 240, 240],
"resnet_dt": true,
"atom_ener": [null, null, 0.0, null, 0.0, null]
"fitting_net" : {
"neuron" : [ 240, 240, 240 ],
"resnet_dt" : true,
"atom_ener" : [ null, null, 0.0, null, 0.0, null ]
}
```

Expand Down Expand Up @@ -201,10 +211,7 @@ It is noted that the [`se_atten` descriptor](./train-se-atten.md) should be used
"model": {
"type": "pairwise_dprc",
"type_map": ["C", "P", "O", "H", "OW", "HW"],
"type_embedding": {
"neuron": [8],
"precision": "float32"
},
"type_embedding": { "neuron": [8], "precision": "float32" },
"qm_model": {
"descriptor": {
"type": "se_atten_v2",
Expand Down
Loading