Skip to content

style: use mdformat to format Markdown #5209

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 7 commits into
base: master
Choose a base branch
from
Draft

style: use mdformat to format Markdown #5209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d72bce1
style: use mdformat to format Markdown
njzjz Feb 8, 2026
d734d76
Merge branch 'master' into mdformat
njzjz Feb 8, 2026
a3243a1
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 8, 2026
c8f8114
Revert "[pre-commit.ci] auto fixes from pre-commit.com hooks"
njzjz Feb 8, 2026
5eb9116
use a developing version of mdformat-myst
njzjz Feb 8, 2026
57ab0bd
add exclude
njzjz Feb 8, 2026
e310deb
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 8, 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
22 changes: 16 additions & 6 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
exclude: ^source/3rdparty/.+/
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
Expand Down Expand Up @@ -53,23 +54,32 @@ repos:
- id: velin
args: ["--write"]
exclude: ^source/3rdparty
# Python inside docs
- repo: https://github.com/asottile/blacken-docs
rev: 1.20.0
# markdown
- repo: https://github.com/hukkin/mdformat
rev: 1.0.0
hooks:
- id: blacken-docs
- id: mdformat
additional_dependencies:
# - mdformat-myst==0.3.0
# See https://github.com/executablebooks/mdformat-myst/issues/13
- "git+https://github.com/brunobeltran/mdformat-myst@4b3ff3a800e2877b78c11a9f5d713d667b0ecccf#egg=mdformat-myst"
- mdformat-ruff==0.1.3
- mdformat-web==0.2.0
- mdformat-config==0.2.1
- mdformat-beautysh==1.0.0
- mdformat-gfm-alerts==2.0.0
# C++
- repo: https://github.com/pre-commit/mirrors-clang-format
rev: v21.1.8
hooks:
- id: clang-format
exclude: ^(source/3rdparty|source/lib/src/gpu/cudart/.+\.inc|.+\.ipynb$|.+\.json$)
# markdown, yaml, CSS, javascript
# yaml, CSS, javascript
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v4.0.0-alpha.8
hooks:
- id: prettier
types_or: [markdown, yaml, css]
types_or: [yaml, css]
# workflow files cannot be modified by pre-commit.ci
exclude: ^(source/3rdparty|\.clang-format)
# Shell
Expand Down
18 changes: 9 additions & 9 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ DeePMD-kit is a deep learning package for many-body potential energy representat
### Lint and Format Code

- Install linter: `uv pip install ruff`
- Run linting: `ruff check .` -- takes <1 second
- Format code: `ruff format .` -- takes <1 second
- Run linting: `ruff check .` -- takes \<1 second
- Format code: `ruff format .` -- takes \<1 second
- **Always run `ruff check .` and `ruff format .` before committing changes or the CI will fail.**

### Training and Validation
Expand All @@ -40,19 +40,19 @@ DeePMD-kit is a deep learning package for many-body potential energy representat
### Basic Functionality Validation

1. **CLI Interface**: Run `dp --version` and `dp -h` to verify installation
2. **Python Interface**: Run `python -c "import deepmd; import deepmd.tf; print('Both interfaces work')"`
3. **Backend Selection**: Test `dp --tf -h`, `dp --pt -h`, `dp --jax -h`, `dp --pd -h`
1. **Python Interface**: Run `python -c "import deepmd; import deepmd.tf; print('Both interfaces work')"`
1. **Backend Selection**: Test `dp --tf -h`, `dp --pt -h`, `dp --jax -h`, `dp --pd -h`

### Training Workflow Validation

1. **TensorFlow Training**: `cd examples/water/se_e2_a && timeout 60 dp train input.json --skip-neighbor-stat` -- should start training and show decreasing loss
2. **PyTorch Training**: `cd examples/water/se_e2_a && timeout 60 dp --pt train input_torch.json --skip-neighbor-stat` -- should start training and show decreasing loss
3. **Verify training output**: Look for "batch X: trn: rmse" messages showing decreasing error values
1. **PyTorch Training**: `cd examples/water/se_e2_a && timeout 60 dp --pt train input_torch.json --skip-neighbor-stat` -- should start training and show decreasing loss
1. **Verify training output**: Look for "batch X: trn: rmse" messages showing decreasing error values

### Test-Based Validation

1. **Core Tests**: `pytest source/tests/tf/test_dp_test.py::TestDPTestEner::test_1frame -v` -- should pass in ~10 seconds
2. **Multi-backend**: Test both TensorFlow and PyTorch components work
1. **Multi-backend**: Test both TensorFlow and PyTorch components work

## Common Commands and Timing

Expand Down Expand Up @@ -127,8 +127,8 @@ source/ # C++ source code and tests

### Linting and Formatting

- **Ruff check**: <1 second
- **Ruff format**: <1 second
- **Ruff check**: \<1 second
- **Ruff format**: \<1 second
- **Pre-commit hooks**: May have network issues, use individual tools

### Commit Messages and PR Titles
Expand Down
23 changes: 12 additions & 11 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Please perform the following steps to create your Pull Request to this repositor
### Step 1: Fork the repository

1. Visit the project: <https://github.com/deepmodeling/deepmd-kit>
2. Click the **Fork** button on the top right and wait it to finish.
1. Click the **Fork** button on the top right and wait it to finish.

### Step 2: Clone the forked repository to local storage and set configurations

Expand All @@ -58,7 +58,7 @@ Please perform the following steps to create your Pull Request to this repositor
# Replace `$username` with your GitHub ID
```

2. Add deepmodeling's repo as your remote repo, we can name it "upstream". And fetch upstream's latest codes to your workstation.
1. Add deepmodeling's repo as your remote repo, we can name it "upstream". And fetch upstream's latest codes to your workstation.

```bash
git remote add upstream https://github.com/deepmodeling/deepmd-kit.git
Expand All @@ -70,9 +70,9 @@ Please perform the following steps to create your Pull Request to this repositor
git merge upstream/master
```

3. Modify your codes and design unit tests.
1. Modify your codes and design unit tests.

4. Commit your changes to a new branch
1. Commit your changes to a new branch

```bash
git checkout -b branch1
Expand All @@ -81,7 +81,8 @@ Please perform the following steps to create your Pull Request to this repositor
git commit -m "commit-message: update the xx"
```

5. Push the changed codes to your original repo on github.
1. Push the changed codes to your original repo on github.

```bash
git push origin branch1
```
Expand All @@ -97,31 +98,31 @@ Please perform the following steps to create your Pull Request to this repositor
git rebase upstream/master
```

2. Create a new branch based on the master branch.
1. Create a new branch based on the master branch.

```bash
git checkout -b new-branch-name
```

3. Modify your codes and design unit tests.
1. Modify your codes and design unit tests.

4. Commit your changes
1. Commit your changes

```bash
git status # Checks the local status
git add <file> ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.`
git commit -m "commit-message: update the xx"
```

5. Keep your branch in sync with upstream/master
1. Keep your branch in sync with upstream/master

```bash
# While on your new branch
git fetch upstream
git rebase upstream/master
```

6. Push your changes to the remote
1. Push your changes to the remote

```bash
git push -u origin new-branch-name # "-u" is used to track the remote branch from origin
Expand All @@ -130,7 +131,7 @@ Please perform the following steps to create your Pull Request to this repositor
### Step 3: Create a pull request

1. Visit your fork at <https://github.com/$username/deepmd-kit> (replace `$username` with your GitHub ID)
2. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR.
1. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR.

Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to DeePMD-kit.

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[<picture><source media="(prefers-color-scheme: dark)" srcset="./doc/_static/logo-dark.svg"><source media="(prefers-color-scheme: light)" srcset="./doc/_static/logo.svg"><img alt="DeePMD-kit logo" src="./doc/_static/logo.svg"></picture>](./doc/logo.md)

---
______________________________________________________________________

# DeePMD-kit

Expand Down
2 changes: 1 addition & 1 deletion doc/data/data-conv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ In the raw format, the property of one frame is provided per line, ending with `
```bash
$ cat force.raw
-0.724 2.039 -0.951 0.841 -0.464 0.363
6.737 1.554 -5.587 -2.803 0.062 2.222
6.737 1.554 -5.587 -2.803 0.062 2.222
-1.968 -0.163 1.020 -0.225 -0.789 0.343
```

Expand Down
50 changes: 25 additions & 25 deletions doc/data/system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,29 +12,29 @@ A system should contain system properties, input frame properties, and labeled f

The input frame properties contain the following property, the first axis of which is the number of frames:

| ID | Property | Raw file | Unit | Required/Optional | Shape | Description |
| --------- | --------------------------------------------------- | ---------- | ---- | -------------------- | ------------------------ | ----------------------------------------- |
| coord | Atomic coordinates | coord.raw | Å | Required | Nframes \* Natoms \* 3 |
| box | Boxes | box.raw | Å | Required if periodic | Nframes \* 3 \* 3 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| fparam | Extra frame parameters | fparam.raw | Any | Optional | Nframes \* Any |
| aparam | Extra atomic parameters | aparam.raw | Any | Optional | Nframes \* aparam \* Any |
| numb_copy | Each frame is copied by the `numb_copy` (int) times | prob.raw | 1 | Optional | Nframes | Integer; Default is 1 for all frames |
| ID | Property | Raw file | Unit | Required/Optional | Shape | Description |
| --------- | --------------------------------------------------- | ---------- | ---- | -------------------- | ---------------------- | ----------------------------------------- |
| coord | Atomic coordinates | coord.raw | Å | Required | Nframes * Natoms * 3 | |
| box | Boxes | box.raw | Å | Required if periodic | Nframes * 3 * 3 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| fparam | Extra frame parameters | fparam.raw | Any | Optional | Nframes * Any | |
| aparam | Extra atomic parameters | aparam.raw | Any | Optional | Nframes * aparam * Any | |
| numb_copy | Each frame is copied by the `numb_copy` (int) times | prob.raw | 1 | Optional | Nframes | Integer; Default is 1 for all frames |

The labeled frame properties are listed as follows, all of which will be used for training if and only if the loss function contains such property:

| ID | Property | Raw file | Unit | Shape | Description |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------- | ------ | ------------------------------------- | ----------------------------------------- |
| energy | Frame energies | energy.raw | eV | Nframes |
| force | Atomic forces | force.raw | eV/Å | Nframes \* Natoms \* 3 |
| virial | Frame virial | virial.raw | eV | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| hessian | Frame energy Hessian matrices | hessian.raw | eV/Å^2 | Nframes \* Natoms \* 3 \* Natoms \* 3 | full Hessian matrices |
| atom_ener | Atomic energies | atom_ener.raw | eV | Nframes \* Natoms |
| atom_pref | Weights of atomic forces | atom_pref.raw | 1 | Nframes \* Natoms |
| dipole | Frame dipole | dipole.raw | Any | Nframes \* 3 |
| atomic_dipole | Atomic dipole | atomic_dipole.raw | Any | Nframes \* Natoms \* 3 |
| polarizability | Frame polarizability | polarizability.raw | Any | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| atomic_polarizability | Atomic polarizability | atomic_polarizability.raw | Any | Nframes \* Natoms \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| drdq | Partial derivative of atomic coordinates with respect to generalized coordinates | drdq.raw | 1 | Nframes \* Natoms \* 3 \* Ngen_coords |
| ID | Property | Raw file | Unit | Shape | Description |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------- | ------ | ---------------------------------- | ----------------------------------------- |
| energy | Frame energies | energy.raw | eV | Nframes | |
| force | Atomic forces | force.raw | eV/Å | Nframes * Natoms * 3 | |
| virial | Frame virial | virial.raw | eV | Nframes * 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| hessian | Frame energy Hessian matrices | hessian.raw | eV/Å^2 | Nframes * Natoms * 3 * Natoms * 3 | full Hessian matrices |
| atom_ener | Atomic energies | atom_ener.raw | eV | Nframes * Natoms | |
| atom_pref | Weights of atomic forces | atom_pref.raw | 1 | Nframes * Natoms | |
| dipole | Frame dipole | dipole.raw | Any | Nframes * 3 | |
| atomic_dipole | Atomic dipole | atomic_dipole.raw | Any | Nframes * Natoms * 3 | |
| polarizability | Frame polarizability | polarizability.raw | Any | Nframes * 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| atomic_polarizability | Atomic polarizability | atomic_polarizability.raw | Any | Nframes * Natoms * 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` |
| drdq | Partial derivative of atomic coordinates with respect to generalized coordinates | drdq.raw | 1 | Nframes * Natoms * 3 * Ngen_coords | |

In general, we always use the following convention of units:

Expand Down Expand Up @@ -73,11 +73,11 @@ set.*/real_atom_types.npy

This system contains `Nframes` frames with the same atom number `Natoms`, the total number of element types contained in all frames is `Ntypes`. Most files are the same as those in [standard formats](../data/system.md), here we only list the distinct ones:

| ID | Property | File | Required/Optional | Shape | Description |
| -------- | -------------------------------- | ------------------- | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| / | Atom type indexes (place holder) | type.raw | Required | Natoms | All zeros to fake the type input |
| type_map | Atom type names | type_map.raw | Required | Ntypes | Atom names that map to atom type contained in all the frames, which is unnecessart to be contained in the periodic table |
| type | Atom type indexes of each frame | real_atom_types.npy | Required | Nframes \* Natoms | Integers that describe atom types in each frame, corresponding to indexes in type_map. `-1` means virtual atoms. |
| ID | Property | File | Required/Optional | Shape | Description |
| -------- | -------------------------------- | ------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| / | Atom type indexes (place holder) | type.raw | Required | Natoms | All zeros to fake the type input |
| type_map | Atom type names | type_map.raw | Required | Ntypes | Atom names that map to atom type contained in all the frames, which is unnecessart to be contained in the periodic table |
| type | Atom type indexes of each frame | real_atom_types.npy | Required | Nframes * Natoms | Integers that describe atom types in each frame, corresponding to indexes in type_map. `-1` means virtual atoms. |

With these edited files, one can put together frames with the same `Natoms`, instead of the same formula (like `H2O`).

Expand Down
2 changes: 1 addition & 1 deletion doc/development/cmake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ After DeePMD-kit C/C++ library is installed, one can find DeePMD-kit from CMake:
find_package(DeePMD REQUIRED)
```

Note that you may need to add ${deepmd_root} to the cached CMake variable `CMAKE_PREFIX_PATH`.
Note that you may need to add \$\{deepmd_root} to the cached CMake variable `CMAKE_PREFIX_PATH`.

To link against the C interface library, using

Expand Down
6 changes: 3 additions & 3 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 @@ -11,9 +11,9 @@ If you'd like to create a new model that isn't covered by the existing DeePMD-ki
To incorporate your custom model you'll need to:

1. Register and implement new components (e.g. descriptor) in a Python file.
2. Register new arguments for user inputs.
3. Package new codes into a Python package.
4. Test new models.
1. Register new arguments for user inputs.
1. Package new codes into a Python package.
1. Test new models.

## Design a new component

Expand Down
Loading