deepmd-kit 3.1.2__tar.gz → 3.2.0b0__tar.gz

deepmd_kit-3.2.0b0/.devcontainer/README.md

@@ -0,0 +1,40 @@
+# DeePMD-kit devcontainer environment
+
+This [devcontainer](https://vscode.js.cn/docs/devcontainers/devcontainer-cli) environment setups Python and C++ environment to develop DeePMD-kit.
+One can setup locally or use [GitHub Codespaces](https://docs.github.com/en/codespaces) by clicking the Code button on the DeePMD-kit repository page.
+The whole setup process requires about 10 minutes, so one needs to be patient.
+
+## Python environment
+
+The following packages are installed into the Python environment `.venv`:
+
+- DeePMD-kit (in edit mode)
+- Backends including TensorFlow, PyTorch, JAX
+- LAMMPS
+- MPICH
+- CMake
+- prek (including hooks)
+- Test packages including pytest
+- Doc packages including sphinx
+
+## C++ interface
+
+The C++ interface with TensorFlow and PyTorch support is installed into `dp` directory.
+
+When calling and debuging LAMMPS with DeePMD-kit, use the following scripts instead of the regular `lmp`:
+
+- `.devcontainer/lmp`
+- `.devcontainer/gdb_lmp`
+
+Use the following scripts for `pytest` with LAMMPS:
+
+- `.devcontainer/pytest_lmp`
+- `.devcontainer/gdb_pytest_lmp`
+
+## Rebuild
+
+Usually the Python package does not need to reinstall.
+But when one wants to recompile the C++ code, the following scripts can be executed.
+
+- `.devcontainer/build_cxx.sh`
+- `.devcontainer/build_py.sh`

deepmd_kit-3.2.0b0/.devcontainer/build_py.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -ev
+
+SCRIPT_PATH=$(dirname $(realpath -s $0))
+cd ${SCRIPT_PATH}/..
+
+uv sync --dev --python 3.12 --extra cpu --extra torch --extra jax --extra lmp --extra test --extra docs
+prek install

deepmd_kit-3.2.0b0/.devcontainer/devcontainer.json

@@ -0,0 +1,16 @@
+{
+  "name": "DeePMD-kit",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "postCreateCommand": ".devcontainer/build_py.sh && .devcontainer/download_libtorch.sh && .devcontainer/build_cxx.sh && prek install-hooks",
+  "remoteEnv": {
+    "PATH": "${containerEnv:PATH}:${containerWorkspaceFolder}/.venv/bin",
+    "DP_ENABLE_PYTORCH": "1",
+    "DP_VARIANT": "cpu",
+    "UV_EXTRA_INDEX_URL": "https://download.pytorch.org/whl/cpu"
+  }
+}

deepmd_kit-3.2.0b0/.gitignore

@@ -0,0 +1,76 @@
+*~
+*.d
+*.o
+*.aux
+*.dvi
+*.pdf
+*.so
+*.bin
+*.intbin
+*.meta
+*.log
+*.gz
+*.bz2
+*.pyc
+*.pb
+*.DS_Store
+tmp*
+CMakeCache.txt
+CMakeFiles
+*.bk
+build
+_skbuild
+deepmd_kit.egg-info/
+dist
+.eggs
+/deepmd/_version.py
+venv*
+.vscode/**
+_build
+_templates
+doc/API_CC/
+doc/api_py/
+doc/api_core/
+doc/api_c/
+dp/
+dp_test/
+dp_test_cc/
+dp_test_c/
+dp_c/
+build_lammps/
+.idea/
+build_tests/
+build_cc_tests
+build_c_tests
+build_c/
+libdeepmd_c/
+.uv/
+libtorch/
+uv.lock
+buildcxx/
+node_modules/
+*.bib.original
+
+# Coverage files
+.coverage
+.coverage.*
+
+# Test output files (temporary)
+test_dp_test/
+test_dp_test_*.out
+*_detail.out
+
+# Training and model output files
+*.pth
+*.pte
+*.pt2
+*.ckpt*
+checkpoint
+lcurve.out
+out.json
+input_v2_compat.json
+frozen_model.*
+
+# Test system directories
+system/
+*.expected

deepmd_kit-3.2.0b0/.pre-commit-config.yaml

@@ -0,0 +1,163 @@
+# 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
+    hooks:
+      - id: trailing-whitespace
+        exclude: "^.+\\.pbtxt$"
+      - id: end-of-file-fixer
+        exclude: "^.+\\.pbtxt$|deeppot_sea.*\\.json$"
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: ["--maxkb=1024", "--enforce-all"]
+        exclude: |
+          (?x)^(
+              source/tests/infer/dipolecharge_e.pbtxt|
+              source/tests/infer/deeppolar_new.pbtxt
+          )$
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+  # Python
+  - repo: https://github.com/PyCQA/isort
+    rev: 9.0.0a3
+    hooks:
+      - id: isort
+        files: \.py$
+        exclude: ^source/3rdparty
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.15
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+        exclude: ^source/3rdparty
+        types_or: [python, pyi, jupyter]
+      - id: ruff-format
+        exclude: ^source/3rdparty
+        types_or: [python, pyi, jupyter]
+  # numpydoc
+  - repo: https://github.com/Carreau/velin
+    rev: 0.0.12
+    hooks:
+      - id: velin
+        args: ["--write"]
+        exclude: ^source/3rdparty
+  # markdown
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          # - mdformat-myst==0.3.0
+          # See https://github.com/executablebooks/mdformat-myst/issues/13
+          - "git+https://github.com/njzjz-bothub/mdformat-myst@d9c414e#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: v22.1.5
+    hooks:
+      - id: clang-format
+        exclude: ^(source/3rdparty|source/lib/src/gpu/cudart/.+\.inc|.+\.ipynb$|source/tests/infer/.+\.json$)
+  # yaml, CSS, javascript
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [yaml, css]
+        # workflow files cannot be modified by pre-commit.ci
+        exclude: ^(source/3rdparty|\.clang-format)
+  # Shell
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: v3.13.1-1
+    hooks:
+      - id: shfmt
+  # CMake
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: v0.6.13
+    hooks:
+      - id: cmake-format
+      #- id: cmake-lint
+  - repo: https://github.com/njzjz/mirrors-bibtex-tidy
+    rev: v1.14.0
+    hooks:
+      - id: bibtex-tidy
+        args:
+          - --curly
+          - --numeric
+          - --align=13
+          - --blank-lines
+          # disable sort: the order of keys and fields has explict meanings
+          #- --sort=key
+          - --duplicates=key,doi,citation,abstract
+          - --merge=combine
+          #- --sort-fields
+          #- --strip-comments
+          - --trailing-commas
+          - --encode-urls
+          - --remove-empty-fields
+          - --wrap=80
+  # license header
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.6
+    hooks:
+      # C++, js
+      - id: insert-license
+        files: \.(c|cc|cpp|js|ts|h|hpp)$
+        args:
+          - --license-filepath
+          - .license-header.txt
+          - --comment-style
+          - //
+          - --no-extra-eol
+        exclude: ^source/3rdparty|source/lib/src/gpu/cudart/.+\.inc
+      # CSS
+      - id: insert-license
+        files: \.(css|scss)$
+        args:
+          - --license-filepath
+          - .license-header.txt
+          - --comment-style
+          - /*| *| */
+          - --no-extra-eol
+      # Python
+      - id: insert-license
+        files: \.(py|pyx)$
+        args:
+          - --license-filepath
+          - .license-header.txt
+          - --comment-style
+          - "#"
+          - --no-extra-eol
+        exclude: ^source/3rdparty
+      # HTML
+      - id: insert-license
+        files: \.(html|vue|xml)$
+        args:
+          - --license-filepath
+          - .license-header.txt
+          - --comment-style
+          - <!--|  ~|  -->
+          - --no-extra-eol
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: DeepMD|DeepMd|Pytorch|Tensorflow|Numpy|Github|Lammps|I-Pi|I-PI|i-Pi
+        # unclear why PairDeepMD is used instead of PairDeePMD
+        exclude: .pre-commit-config.yaml|source/lmp
+  # customized pylint rules
+  - repo: https://github.com/pylint-dev/pylint/
+    rev: v4.0.5
+    hooks:
+      - id: pylint
+        entry: env PYTHONPATH=source/checker pylint
+        files: ^deepmd/

deepmd_kit-3.2.0b0/.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+build:
+  os: ubuntu-26.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      - pip install uv
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install -r doc/requirements.txt
+  apt_packages:
+    - inkscape
+sphinx:
+  configuration: doc/conf.py
+formats:
+  - pdf

deepmd_kit-3.2.0b0/AGENTS.md

@@ -0,0 +1,191 @@
+# DeePMD-kit
+
+DeePMD-kit is a deep learning package for many-body potential energy representation and molecular dynamics. It supports multiple backends (TensorFlow, PyTorch, JAX, Paddle) and integrates with MD packages like LAMMPS and i-PI.
+
+**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Working Effectively
+
+### Bootstrap and Build Repository
+
+- Create virtual environment: `uv venv venv && source venv/bin/activate`
+- Install base dependencies: `uv pip install tensorflow-cpu` (takes ~8 seconds)
+- Install PyTorch: `uv pip install torch --index-url https://download.pytorch.org/whl/cpu` (takes ~5 seconds)
+- Build Python package: `uv pip install -e .[cpu,test]` -- takes 67 seconds. **NEVER CANCEL. Set timeout to 120+ seconds.**
+- Build C++ components: `export TENSORFLOW_ROOT=$(python -c 'import importlib.util,pathlib;print(pathlib.Path(importlib.util.find_spec("tensorflow").origin).parent)')` then `export PYTORCH_ROOT=$(python -c 'import torch;print(torch.__path__[0])')` then `./source/install/build_cc.sh` -- takes 164 seconds. **NEVER CANCEL. Set timeout to 300+ seconds.**
+
+### Test Repository
+
+- Run single test: `pytest source/tests/tf/test_dp_test.py::TestDPTestEner::test_1frame -v` -- takes 8-13 seconds
+- Run test subset: `pytest source/tests/tf/test_dp_test.py -v` -- takes 15 seconds. **NEVER CANCEL. Set timeout to 60+ seconds.**
+- **Recommended: Use single test cases for validation instead of full test suite** -- full suite has 314 test files and takes 60+ minutes
+
+### Lint and Format Code
+
+- Install linter: `uv pip install ruff`
+- 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
+
+- Test TensorFlow training: `cd examples/water/se_e2_a && dp train input.json --skip-neighbor-stat` -- training proceeds but is slow on CPU
+- Test PyTorch training: `cd examples/water/se_e2_a && dp --pt train input_torch.json --skip-neighbor-stat` -- training proceeds but is slow on CPU
+- **Training examples are for validation only. Real training takes hours/days. Timeout training tests after 60 seconds for validation.**
+
+## Validation Scenarios
+
+**ALWAYS manually validate any new code through at least one complete scenario:**
+
+### Basic Functionality Validation
+
+1. **CLI Interface**: Run `dp --version` and `dp -h` to verify installation
+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
+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
+1. **Multi-backend**: Test both TensorFlow and PyTorch components work
+
+## Common Commands and Timing
+
+### Repository Structure
+
+```
+ls -la [repo-root]
+.github/               # GitHub workflows and templates
+CONTRIBUTING.md        # Contributing guide
+README.md             # Project overview
+deepmd/               # Python package source
+doc/                  # Documentation
+examples/             # Training examples and configurations
+pyproject.toml        # Python build configuration
+source/               # C++ source code and tests
+```
+
+### Key Directories and Files
+
+- `deepmd/` - Main Python package with backend implementations
+- `source/lib/` - Core C++ library
+- `source/op/` - Backend-specific operators (TF, PyTorch, etc.)
+- `source/api_cc/` - C++ API
+- `source/api_c/` - C API
+- `source/tests/` - Test suite (314 test files)
+- `examples/water/se_e2_a/` - Basic water training example
+- `examples/` - Various model examples for different scenarios
+
+### Common CLI Commands
+
+- `dp --version` - Show version information
+- `dp -h` - Show help and available commands
+- `dp train input.json` - Train a model (TensorFlow backend)
+- `dp --pt train input.json` - Train with PyTorch backend
+- `dp --jax train input.json` - Train with JAX backend
+- `dp --pd train input.json` - Train with Paddle backend
+- `dp test -m model.pb -s system/` - Test a trained model
+- `dp freeze -o model.pb` - Freeze/save a model
+
+### Build Dependencies and Setup
+
+- **Python 3.10+** required
+- **Virtual environment** strongly recommended: `uv venv venv && source venv/bin/activate`
+- **Backend dependencies**: TensorFlow, PyTorch, JAX, or Paddle (install before building)
+- **Build tools**: CMake, C++ compiler, scikit-build-core
+- **C++ build requires**: Both TensorFlow and PyTorch installed, set TENSORFLOW_ROOT and PYTORCH_ROOT environment variables
+
+### Key Configuration Files
+
+- `pyproject.toml` - Python build configuration and dependencies
+- `source/CMakeLists.txt` - C++ build configuration
+- `examples/water/se_e2_a/input.json` - Basic TensorFlow training config
+- `examples/water/se_e2_a/input_torch.json` - Basic PyTorch training config
+
+## Frequent Patterns and Time Expectations
+
+### Installation and Build Times
+
+- **Virtual environment setup**: ~5 seconds
+- **TensorFlow CPU install**: ~8 seconds
+- **PyTorch CPU install**: ~5 seconds
+- **Python package build**: ~67 seconds. **NEVER CANCEL.**
+- **C++ components build**: ~164 seconds. **NEVER CANCEL.**
+- **Full fresh setup**: ~3-4 minutes total
+
+### Testing Times
+
+- **Single test**: 8-13 seconds
+- **Test file (~5 tests)**: ~15 seconds
+- **Backend-specific test subset**: 15-30 minutes. **Use sparingly.**
+- **Full test suite (314 files)**: 60+ minutes. **Avoid in development - use single tests instead.**
+
+### Linting and Formatting
+
+- **Ruff check**: \<1 second
+- **Ruff format**: \<1 second
+- **Pre-commit hooks**: May have network issues, use individual tools
+
+### Commit Messages and PR Titles
+
+**All commit messages and PR titles must follow [conventional commit specification](https://www.conventionalcommits.org/):**
+
+- **Format**: `type(scope): description`
+- **Common types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+- **Examples**:
+  - `feat(core): add new descriptor type`
+  - `fix(tf): resolve memory leak in training`
+  - `docs: update installation guide`
+  - `ci: add workflow for testing`
+
+### Training and Model Operations
+
+- **Training initialization**: 10-30 seconds
+- **Training per batch**: 0.1-1 second (CPU), much faster on GPU
+- **Model freezing**: 5-15 seconds
+- **Model testing**: 10-30 seconds
+
+## Backend-Specific Notes
+
+### TensorFlow Backend
+
+- **Default backend** when no flag specified
+- **Configuration**: Use `input.json` format
+- **Training**: `dp train input.json`
+- **Requirements**: `tensorflow` or `tensorflow-cpu` package
+
+### PyTorch Backend
+
+- **Activation**: Use `--pt` flag or `export DP_BACKEND=pytorch`
+- **Configuration**: Use `input_torch.json` format typically
+- **Training**: `dp --pt train input_torch.json`
+- **Requirements**: `torch` package
+
+### JAX Backend
+
+- **Activation**: Use `--jax` flag
+- **Training**: `dp --jax train input.json`
+- **Requirements**: `jax` and related packages
+- **Note**: Experimental backend, may have limitations
+
+### Paddle Backend
+
+- **Activation**: Use `--pd` flag
+- **Training**: `dp --pd train input.json`
+- **Requirements**: `paddlepaddle` package
+- **Note**: Less commonly used
+
+## Critical Warnings
+
+- **NEVER CANCEL BUILD OPERATIONS**: Python build takes 67 seconds, C++ build takes 164 seconds
+- **USE SINGLE TESTS FOR VALIDATION**: Run individual tests instead of full test suite for faster feedback
+- **ALWAYS activate virtual environment**: Build and runtime failures occur without proper environment
+- **ALWAYS install backend dependencies first**: TensorFlow/PyTorch required before building C++ components
+- **ALWAYS run linting before commits**: `ruff check . && ruff format .` or CI will fail
+- **ALWAYS test both Python and C++ components**: Some features require both to be built
+- **ALWAYS follow conventional commit format**: All commit messages and PR titles must use conventional commit specification (`type(scope): description`)