Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
39 changes: 39 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -102,3 +102,42 @@ jobs:
raise SystemExit("direct-force models must be rejected")
print("capability wheel smoke ok on", sys.version)
PY

# Really executes scripts/install_mliport.sh for the NEP backend (network,
# uv, a fresh .venv-nep) and runs doctor from the result. Plan-level checks
# live in tests/mliport/mliport/test_install_plan.py and run everywhere.
installer-real-nep:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@v5
- uses: astral-sh/setup-uv@v7
with:
python-version: "3.12"
enable-cache: true
cache-dependency-glob: "mliport/pyproject.toml"
- name: Install pytest only
run: |
uv venv .venv-ci --python 3.12
uv pip install --python .venv-ci/bin/python pytest
- name: Real NEP install, doctor, reinstall, mirror, offline
env:
MLIPORT_REAL_INSTALL: "1"
MLIPORT_REAL_INSTALL_LOGDIR: ${{ runner.temp }}/nep-install-logs
run: |
.venv-ci/bin/python -m pytest tests/mliport/mliport/test_install_nep_real.py -v -rA -p no:cacheprovider
- name: Print install logs
if: always()
run: |
for f in "${{ runner.temp }}"/nep-install-logs/*.log; do
echo "::group::$(basename "$f")"
cat "$f"
echo "::endgroup::"
done
- name: Upload install logs
if: always()
uses: actions/upload-artifact@v4
with:
name: nep-install-logs
path: ${{ runner.temp }}/nep-install-logs
if-no-files-found: warn
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,25 @@

## Unreleased

NEP installer and documentation integration (tracking #61):

- **`--engines nep` now installs mliport into `.venv-nep`.** The NEP install step
only installed `calorine`, ASE and NumPy, so the verify stage failed with
`FileNotFoundError` on `.venv-nep/bin/mliport`. It is now one resolver run with
an editable `./mliport[analysis-all]` plus the pinned `calorine==4.1`, built from
the same `_uv_pip` and package-source arguments as the other backends. The NEP
step previously set `PIP_EXTRA_INDEX_URL` (which the installer strips for managed
profiles) and read a non-existent `profile.index_url`, so `--source china*` and
`--source offline` were silently ignored for NEP; they are honoured now. NEP stays
opt-in and isolated in `.venv-nep`; the plans of the other backends are unchanged.
The installer still does not build `gpumd`.
- **Docs.** `README.md`/`README_CN.md` describe the NEP backend (install, environment
table, example, limits). The generated environment table no longer prints
`calorine==4.1 (12.9)`: for NEP the NumPy/ASE dependency is resolved by the
installer and 12.9 is the CUDA Toolkit used to build `gpumd`. The manual NEP
install route now includes mliport, and the docs state that `doctor` finds
`gpumd` on `PATH` or via `MLIPORT_GPUMD_COMMAND` (not `NEP_GPUMD_COMMAND`).

Internal (no user-visible behaviour change):

- **Shared runner safety helpers.** The numerical-safety gates that MD already
Expand Down
37 changes: 31 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**English** | [简体中文](README_CN.md)

Run machine-learned interatomic potentials — MACE, DPA, GRACE and UMA — from one
Run machine-learned interatomic potentials — MACE, DPA, GRACE, UMA and NEP — from one
command line, one terminal UI and one Python API. Give it a structure and a
checkpoint; it relaxes, runs molecular dynamics, finds NEB barriers, searches adsorbate
configurations on a slab or analyzes a trajectory, and writes the files a VASP user expects: `OUTCAR`, `OSZICAR`,
Expand All @@ -14,10 +14,12 @@ your chemistry depends on the checkpoint you choose.

What you get:

- **The same workflow on four backends.** Single point, fixed- and variable-cell
- **The same workflow on every backend.** Single point, fixed- and variable-cell
relaxation, NVE/NVT MD (Langevin, Bussi, Nosé–Hoover chain), NEB and CI-NEB,
MD-based configuration search for an adsorbate on a slab, batch sweeps and a job
queue, from the CLI, an INCAR-style file, the TUI or Python.
queue, from the CLI, an INCAR-style file, the TUI or Python. NEP's native `gpumd`
runtime covers only single point, relaxation and MD (see
[NEP](docs/backends/nep.md)).
- **No silent guessing.** There is no default backend, and a misspelled option, or
one that belongs to another backend, stops the run. Configuration errors fail
closed.
Expand All @@ -37,7 +39,7 @@ The full documentation is at <https://hydrogen1222.github.io/mliport/> (English
| run my first calculation | [Quickstart](docs/quickstart.md) |
| check a model on a system with a known answer | [Test systems](docs/test-systems.md) |
| install one or more backends, on GPU or CPU | [Installation](docs/installation.md) |
| understand what MACE, DPA, GRACE and UMA are and pick one | [Backends](docs/backends/index.md), [Models](docs/models.md) |
| understand what MACE, DPA, GRACE, UMA and NEP are and pick one | [Backends](docs/backends/index.md), [Models](docs/models.md) |
| set options through the CLI, an INCAR-style file or `settings.ini` | [Configuration](docs/configuration.md) |
| single point, relaxation, MD, NEB, configuration search, batch, queue | [Workflows](docs/workflows/index.md) |
| MSD, diffusion, conductivity, RDF, spectra, Arrhenius | [Analysis](docs/analysis/index.md) |
Expand All @@ -60,6 +62,9 @@ cd mliport

# or CPU only
./scripts/install_mliport.sh --engines mace dpa grace uma --device cpu

# NEP is opt-in (add it explicitly, alone or with the others)
./scripts/install_mliport.sh --engines nep --device cpu
```

The installer pins the upstream backend versions, installs the analysis extras and
Expand All @@ -76,6 +81,15 @@ together with CPU, offline and proxy setups and uninstalling.
| DPA | `.venv-dpa` | `bin/mliport-dpa` |
| GRACE | `.venv-grace` | `bin/mliport-grace` |
| UMA | `.venv` | `bin/mliport-uma` |
| NEP | `.venv-nep` | `bin/mliport-nep` |

NEP is not part of the default engine list. The installer puts the pinned `calorine`
and an editable mliport into `.venv-nep`, which is enough for the CPU ASE runtime
(`CPUNEP`, float64). The native runtime and `GPUNEP` also need a `gpumd` executable,
which the installer does **not** build (it needs your CUDA toolkit and a matching
`-arch=sm_XX`). On a GPU host, `--device auto|cuda` makes the closing `doctor` demand `gpumd`, so
use `--device cpu` until you have built it; see [docs/backends/nep.md](docs/backends/nep.md) for the build and for
`mliport doctor --engine nep`.

Run mliport from the environment of the backend you want, or through its launcher:

Expand All @@ -99,6 +113,7 @@ path with `--model`; a local directory works offline.
| DPA | `DPA-3.1-3M.pt` | [deepmodelingcommunity/DPA-3.1-3M](https://huggingface.co/deepmodelingcommunity/DPA-3.1-3M) |
| GRACE | `GRACE-2L-OMAT-medium-base` | [AMS-ICAMS-RUB/grace-foundation-models](https://huggingface.co/AMS-ICAMS-RUB/grace-foundation-models) |
| UMA | `uma-s-1p2.pt` | [facebook/UMA](https://huggingface.co/facebook/UMA) |
| NEP | your own `nep.txt` | trained for your elements and conditions; mliport ships and downloads none |

The hashes the validation suite uses are pinned in
[`validation/science/model_manifest.json`](validation/science/model_manifest.json).
Expand Down Expand Up @@ -135,6 +150,7 @@ fails; mliport never falls back to another model on its own.
.venv-dpa/bin/mliport sp LGPS.vasp --model DPA-3.1-3M.pt --model-type dpa --task bulk --head Omat24 --device cuda
.venv-grace/bin/mliport sp LGPS.vasp --model GRACE-2L-OMAT-medium-base --model-type grace --task bulk --device cuda
.venv/bin/mliport sp LGPS.vasp --model uma-s-1p2.pt --model-type uma --task omat --device cuda
.venv-nep/bin/mliport sp LGPS.vasp --model nep.txt --model-type nep --nep-runtime ase --device cpu
```

| Engine | `--model-type` | Task / head | Good to know |
Expand All @@ -143,6 +159,7 @@ fails; mliport never falls back to another model on its own.
| DPA | `dpa` | `bulk`, `--head Omat24` | multitask checkpoint; a missing head is an error, not a guess |
| GRACE | `grace` | `bulk` | TensorFlow runtime, CPU and GPU |
| UMA | `uma` (`fairchem` is an alias) | `omat` | `--task omol` for molecules; non-commercial research license |
| NEP | `nep` + required `--nep-runtime ase\|gpumd` | `bulk` (PBC only) | runtime is never inferred; `ase` = Calorine (`cpu` float64, `cuda` float32 via one `gpumd` process per call), `gpumd` = one native process per run (float32) |

DPA and GRACE cannot change GPU after their framework has loaded, so when
`CUDA_VISIBLE_DEVICES` is unset the CLI restarts the command in a fresh process with
Expand Down Expand Up @@ -255,8 +272,8 @@ Options for each task are in [docs/analysis/index.md](docs/analysis/index.md).

## Configuration

The backend is always explicit (`--model-type mace|dpa|grace|uma` plus `--model`, or
an alias). Configuration is strict: unknown and cross-backend keys are errors, and
The backend is always explicit (`--model-type mace|dpa|grace|uma|nep` plus `--model`,
or an alias; `nep` also needs `--nep-runtime`). Configuration is strict: unknown and cross-backend keys are errors, and
`--lenient-config` downgrades them for exploratory runs. `mliport config` inspects
settings; a project `settings.ini` can define aliases, and `--settings PATH` wins
over the user and project files. Each run writes `resolved_config.json` with the
Expand All @@ -273,6 +290,14 @@ entry point (API, direct CLI, INCAR, TUI) can express is recorded in
`validation/science/capability_matrix.json`; a `no` or `partial` there means that
entry point cannot say it, and nothing is translated silently.

NEP limits: you supply the `nep.txt`, and mliport cannot say whether it fits your
material. The native `gpumd` runtime has no CPU path and refuses NEB, batch and
confsearch instead of switching to the ASE runtime; DFT-D3 is rejected; `qNEP`,
`TNEP` and `nep4-vdw` models are unsupported; partial PBC is refused. NEP is not part
of the validation campaign summarised below: its real-hardware evidence is a V100 with
GPUMD 5.9.1 and CUDA 12.9, and other GPUs and toolkits are unverified. Details:
[docs/backends/nep.md](docs/backends/nep.md).

Model accuracy belongs to the upstream checkpoint. Short MD runs check the workflow,
not equilibration. NEB's pre-flight shows the forces match the energy, which says
nothing about how accurate the barrier is. Transport analyses fail closed with an
Expand Down
28 changes: 23 additions & 5 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[English](README.md) | **简体中文**

mliport 用一套命令行、终端界面(TUI)和 Python API 运行四种机器学习势:MACE、DPA、GRACE 和 UMA。
mliport 用一套命令行、终端界面(TUI)和 Python API 运行五种机器学习势:MACE、DPA、GRACE、UMA 和 NEP。
准备好结构和模型文件,就可以做结构优化、分子动力学、NEB 势垒、slab 上吸附分子的构型搜索和轨迹分析。
输出沿用 VASP 的文件格式:`OUTCAR`、`OSZICAR`、`CONTCAR`、`XDATCAR`。

Expand All @@ -11,9 +11,9 @@ POTCAR。模型对你的体系准不准,取决于你选的模型文件。

主要功能:

- **四个后端,用法一致。** 单点、结构优化(固定或可变晶胞)、NVE/NVT 分子动力学(Langevin、Bussi、
- **各后端用法一致。** 单点、结构优化(固定或可变晶胞)、NVE/NVT 分子动力学(Langevin、Bussi、
Nosé–Hoover 链)、NEB 和 CI-NEB、slab 吸附构型搜索、批量计算和任务队列。可以用命令行、INCAR 风格
的输入文件、TUI 或 Python 调用。
的输入文件、TUI 或 Python 调用。NEP 的原生 `gpumd` 运行时只支持单点、结构优化和 MD(见 [NEP](docs/backends/nep.zh.md))。
- **不做默认猜测。** 没有默认后端。选项拼错,或者用了别的后端的选项,程序会报错停下。
- **完整的计算记录。** 每次运行都记录模型文件和它的 SHA-256、请求的设备和实际使用的设备、最终生效
的配置以及 mliport 版本。
Expand All @@ -31,7 +31,7 @@ POTCAR。模型对你的体系准不准,取决于你选的模型文件。
| 跑第一个计算 | [快速上手](docs/quickstart.zh.md) |
| 在答案已知的体系上检验一个模型 | [测试体系](docs/test-systems.zh.md) |
| 安装一个或多个后端(GPU 或 CPU) | [安装](docs/installation.zh.md) |
| 了解 MACE、DPA、GRACE、UMA 是什么并选一个 | [后端](docs/backends/index.zh.md)、[模型](docs/models.zh.md) |
| 了解 MACE、DPA、GRACE、UMA、NEP 是什么并选一个 | [后端](docs/backends/index.zh.md)、[模型](docs/models.zh.md) |
| 通过 CLI、INCAR 风格文件或 `settings.ini` 设置选项 | [配置](docs/configuration.zh.md) |
| 单点、弛豫、MD、NEB、构型搜索、批量、队列 | [工作流](docs/workflows/index.zh.md) |
| MSD、扩散、电导率、RDF、谱、Arrhenius | [分析](docs/analysis/index.zh.md) |
Expand All @@ -54,6 +54,9 @@ cd mliport

# 或者只用 CPU
./scripts/install_mliport.sh --engines mace dpa grace uma --device cpu

# NEP 默认不装,需要显式加上(可单独装,也可和其他后端一起装)
./scripts/install_mliport.sh --engines nep --device cpu
```

安装脚本会锁定各后端的上游版本,装好分析用的依赖,最后对每个后端运行一次 `mliport doctor`。四个后端
Expand All @@ -67,6 +70,13 @@ GPU 要用不同的安装包,见 [docs/installation.md](docs/installation.md)
| DPA | `.venv-dpa` | `bin/mliport-dpa` |
| GRACE | `.venv-grace` | `bin/mliport-grace` |
| UMA | `.venv` | `bin/mliport-uma` |
| NEP | `.venv-nep` | `bin/mliport-nep` |

NEP 不在默认后端列表里。安装器会在 `.venv-nep` 里装好锁定版本的 `calorine` 和 editable 的 mliport,这足够
运行 CPU 的 ASE 运行时(`CPUNEP`,float64)。原生运行时和 `GPUNEP` 还需要 `gpumd` 可执行文件,安装器**不会**
编译它(要用你的 CUDA toolkit 和匹配的 `-arch=sm_XX`)。在有 GPU 的机器上,`--device auto|cuda` 会让结尾的 `doctor` 要求 `gpumd`,
编译好之前请用 `--device cpu`;编译方法和 `mliport doctor --engine nep` 见
[docs/backends/nep.zh.md](docs/backends/nep.zh.md)。

用哪个后端,就在哪个后端的环境里运行 mliport,或者用它的启动脚本:

Expand All @@ -89,6 +99,7 @@ mliport 不会自动下载模型。请从上游下载,再用 `--model` 传入
| DPA | `DPA-3.1-3M.pt` | [deepmodelingcommunity/DPA-3.1-3M](https://huggingface.co/deepmodelingcommunity/DPA-3.1-3M) |
| GRACE | `GRACE-2L-OMAT-medium-base` | [AMS-ICAMS-RUB/grace-foundation-models](https://huggingface.co/AMS-ICAMS-RUB/grace-foundation-models) |
| UMA | `uma-s-1p2.pt` | [facebook/UMA](https://huggingface.co/facebook/UMA) |
| NEP | 你自己的 `nep.txt` | 针对你的元素和条件训练;mliport 不附带也不下载 |

验证时用的模型哈希记录在 [`validation/science/model_manifest.json`](validation/science/model_manifest.json)。
模型的许可证以上游为准,UMA 只能用于非商业研究。Hugging Face 镜像和 SOCKS 代理的设置见
Expand Down Expand Up @@ -119,6 +130,7 @@ mliport 不会自动下载模型。请从上游下载,再用 `--model` 传入
.venv-dpa/bin/mliport sp LGPS.vasp --model DPA-3.1-3M.pt --model-type dpa --task bulk --head Omat24 --device cuda
.venv-grace/bin/mliport sp LGPS.vasp --model GRACE-2L-OMAT-medium-base --model-type grace --task bulk --device cuda
.venv/bin/mliport sp LGPS.vasp --model uma-s-1p2.pt --model-type uma --task omat --device cuda
.venv-nep/bin/mliport sp LGPS.vasp --model nep.txt --model-type nep --nep-runtime ase --device cpu
```

| 引擎 | `--model-type` | Task / head | 说明 |
Expand All @@ -127,6 +139,7 @@ mliport 不会自动下载模型。请从上游下载,再用 `--model` 传入
| DPA | `dpa` | `bulk`、`--head Omat24` | 多任务模型,必须指定 head |
| GRACE | `grace` | `bulk` | 基于 TensorFlow,支持 CPU 和 GPU |
| UMA | `uma`(也可写 `fairchem`) | `omat` | 分子用 `--task omol`;仅限非商业研究 |
| NEP | `nep`,另需 `--nep-runtime ase\|gpumd` | `bulk`(仅周期性体系) | 运行时从不自动推断;`ase` 为 Calorine(`cpu` 为 float64,`cuda` 为 float32,每次调用起一个 `gpumd` 进程),`gpumd` 为每次运行一个原生进程(float32) |

DPA 和 GRACE 的框架加载后就不能再换 GPU。没有设置 `CUDA_VISIBLE_DEVICES` 时,命令行会新开一个设好 GPU
的进程来运行;在 Python 里调用时,请在导入这些框架之前设置 `CUDA_VISIBLE_DEVICES`。详见
Expand Down Expand Up @@ -225,7 +238,7 @@ result = run_single_point("LGPS.vasp", "model.model", model_type="mace", device=

## 配置

后端必须明确指定(`--model-type mace|dpa|grace|uma` 加 `--model`,或者用模型别名)。配置检查是严格的:
后端必须明确指定(`--model-type mace|dpa|grace|uma|nep` 加 `--model`,或者用模型别名;`nep` 还需要 `--nep-runtime`)。配置检查是严格的:
不认识的参数和别的后端的参数都会报错,试算时可以用 `--lenient-config` 降为警告。`mliport config` 用来查看
设置;项目里的 `settings.ini` 可以定义别名,`--settings PATH` 指定的文件优先于用户和项目配置。每次运行都
会写出 `resolved_config.json`,记录每个参数的取值和来源。
Expand All @@ -239,6 +252,11 @@ INCAR 风格输入只支持常用参数。API、命令行、INCAR 和 TUI 各自
`validation/science/capability_matrix.json` 里;标为 `no` 或 `partial` 的项在该入口无法设置,程序也不会
自动换成别的设置。

NEP 的限制:`nep.txt` 要你自己提供,mliport 无法判断它是否适合你的材料。原生 `gpumd` 运行时没有 CPU 路径,
遇到 NEB、批量和 confsearch 会直接拒绝,不会改用 ASE 运行时;DFT-D3 会被拒绝;不支持 `qNEP`、`TNEP` 和
`nep4-vdw` 模型;部分周期性边界会被拒绝。NEP 不在下面这份验证汇总的范围内:它在真实硬件上的证据是一台 V100
配 GPUMD 5.9.1 和 CUDA 12.9,其他 GPU 和 toolkit 没有验证过。详见 [docs/backends/nep.zh.md](docs/backends/nep.zh.md)。

模型精度由上游模型决定。短时间 MD 只用来检查流程能否跑通,不代表体系已经平衡。NEB 预检通过只说明力和
能量自洽,不代表势垒准确。采样不足时,输运分析会报告 insufficient-sampling,不给出数值。

Expand Down
Loading
Loading