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
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,32 @@ MACE model-class gate:
embedding block, and a test pins that.
- `docs/backends/mace.md` (+ `.zh.md`) documents the gate.

UMA runtime upgrade for UMA-S 1.2.1:

- `fairchem-core` moves from 2.21.0 (torch 2.8.0) to the newest release whose
torch pin still has a CUDA 12.6 wheel for Volta: 2.25.0 on torch 2.13.0
(`torch~=2.13.0`, Python >=3.11,<3.15). Volta stays on `cu126`; Turing and
newer use `cu130`, the CUDA version of the default PyPI torch 2.13.0 build,
because CUDA 13 has no kernels below Turing.
- `FRAMEWORK_PYTHON` gains torch 2.13.0 and `_torch_modern_cuda` maps it to
`cu130`, so an unknown version still fails closed until audited.
- The install docs and the UMA backend page are regenerated from the registry.
- UMA Nitro is not exposed. fairchem-core 2.22+ redefined the upstream
`default` preset as UMA Nitro and removed `turbo`, so mliport now maps its own
two names onto the presets that keep the documented numbers: `default` ->
upstream `batch` (tf32 off, no compile, no merged MOLE) and `turbo` ->
upstream `multigpu` (upstream's "turbo's former settings"). A preset that
would enable Nitro is refused, a missing preset fails closed with an upgrade
message, and the effective preset, its tf32 flag and its Nitro flag are
recorded in the model identity. Regression tests pin the mapping.
- `docs/backends/uma.md` (+ `.zh.md`) records that the beta scientific
validation of `uma_omat` ran on fairchem-core 2.21.0 and does not carry over
to this runtime.
- `docs/installation.md` (+ `.zh.md`) and the UMA page state the driver
requirement: the CUDA 13 `cu130` wheels used on Turing and newer need an
NVIDIA driver of 580 or newer, while Volta stays on `cu126` and keeps working
with older drivers.

DPA-3.1 checkpoints load on the DPA4 runtime:

- The pinned deepmd-kit 3.2.1 builds the three DPA-3.1 statistics tensors
Expand Down
18 changes: 17 additions & 1 deletion docs/backends/uma.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ either works as `--model-type`.
<!-- BEGIN GENERATED: environment -->
| Environment | Python | Runtime stack |
|---|---|---|
| `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.21.0` (torch 2.8.0) |
| `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.25.0` (torch 2.13.0) |

```bash
./scripts/install_mliport.sh --engines uma --device auto
Expand Down Expand Up @@ -70,6 +70,22 @@ license is non-commercial research only; see [Citations](../citations.md).
trades speed for GPU memory.
- **Precision** is defined by the model; mliport reports the framework version
rather than pretending to control the weights.
- **Runtime pin.** `fairchem-core==2.25.0` on torch 2.13.0. Volta (V100) stays on
the `cu126` wheels, Turing and newer use `cu130`, because the CUDA 13 builds
carry no kernel below Turing and need an NVIDIA driver of 580 or newer; the
`cu126` wheels work with older drivers. 2.25.0 is the pinned release that loads
`uma-s-1p2p1` (UMA-S 1.2.1). The beta scientific validation of `uma_omat` ran
on `fairchem-core==2.21.0` with torch 2.8.0; it describes that runtime and is
not carried over to this one, which has its own callable check.
- **No Nitro.** fairchem-core 2.22 and later made UMA Nitro the upstream
`default` preset and removed `turbo`; Nitro needs Ampere or newer and runs at
reduced precision. mliport keeps its own two names and maps them onto
upstream presets that carry the numbers it has always documented:
`default` runs upstream `batch` (tf32 off, no compile, no merged MOLE) and
`turbo` runs upstream `multigpu` (upstream calls this "turbo's former
settings": tf32, compile, merged MOLE). A preset that would enable Nitro is
refused, and the preset that really ran, its tf32 flag and its Nitro flag are
written to the run record.
- **NEB and configuration search** need forces that are the gradient of the
energy. mliport decides this at run time, not from this page: a predictor that
reports `direct_forces = true` is refused, otherwise a finite-difference
Expand Down
13 changes: 12 additions & 1 deletion docs/backends/uma.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Meta FAIR 的 UMA 模型通过上游的 `fairchem-core` 加载。`--model-type`
<!-- BEGIN GENERATED: environment -->
| 环境 | Python | 运行时 |
|---|---|---|
| `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.21.0` (torch 2.8.0) |
| `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.25.0` (torch 2.13.0) |

```bash
./scripts/install_mliport.sh --engines uma --device auto
Expand Down Expand Up @@ -56,6 +56,17 @@ Meta FAIR 的 UMA 模型通过上游的 `fairchem-core` 加载。`--model-type`
- **推理模式。** `--inference-mode` 可选 `default` 或 `turbo`。`turbo`(TF32 加 `torch.compile`)
需要手动开启,MD 默认不用,以保证精度。`--activation-checkpointing` 可以用速度换显存。
- **精度**由模型决定,mliport 只记录框架版本。
- **固定的运行环境。** `fairchem-core==2.25.0` 配 torch 2.13.0。Volta(V100)继续用 `cu126`
的 wheel,Turing 及更新的卡用 `cu130`,因为 CUDA 13 的构建不再包含 Turing 以下的内核,并且
需要 580 或更新的 NVIDIA 驱动;`cu126` 的 wheel 在更老的驱动上也能用。
2.25.0 是能加载 `uma-s-1p2p1`(UMA-S 1.2.1)的固定版本。`uma_omat` 的 beta 科学验证是在
`fairchem-core==2.21.0` 和 torch 2.8.0 上做的,那批结论只对那套环境成立,不能直接套用到
这里;新环境有它自己的可调用性检查记录。
- **不提供 Nitro。** fairchem-core 从 2.22 起把 UMA Nitro 当成上游的 `default` 预设,并取消了
`turbo`;Nitro 需要 Ampere 或更新的显卡,而且精度更低。mliport 保留自己的两个名字,把它们
映射到数值行为与本文档一直描述一致的上游预设:`default` 走上游 `batch`(不开 tf32、不编译、
不合并 MOLE),`turbo` 走上游 `multigpu`(上游称其为"turbo 原来的设置":tf32、编译、合并
MOLE)。会启用 Nitro 的预设会被拒绝;实际使用的预设、tf32 开关和 Nitro 开关都会写进运行记录。
- **NEB 和构型搜索**要求力等于能量的负梯度。这在运行时检查:模型声明 `direct_forces = true` 就
拒绝,否则用有限差分在你的结构上实测(见 [NEB](../workflows/neb.md))。
- **应力**只有模型支持时才会输出。
Expand Down
8 changes: 6 additions & 2 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ any scientific option for you.
<!-- BEGIN GENERATED: backend-matrix -->
| Backend | Environment | Python | Runtime stack |
|---|---|---|---|
| UMA (FAIRChem) | `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.21.0` (torch 2.8.0) |
| UMA (FAIRChem) | `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.25.0` (torch 2.13.0) |
| MACE | `.venv-mace` | 3.10, 3.11, 3.12, 3.13 | `mace-torch==0.3.16` (torch 2.8.0) |
| DPA (DeepMD-kit) | `.venv-dpa` | 3.10, 3.11, 3.12, 3.13 | `deepmd-kit @ git+https://github.com/deepmodeling/deepmd-kit.git@0edeaef5617e9878edeb2346bf37bb6a035a4f51` (torch 2.11.0) |
| NEP (Calorine / GPUMD) | `.venv-nep` | 3.10, 3.11, 3.12, 3.13 | `calorine==4.1` (NumPy/ASE, resolved by the installer; gpumd built with CUDA Toolkit 12.9) |
Expand Down Expand Up @@ -165,6 +165,9 @@ through `uv`, which reads the same proxy variables.
PyTorch and TensorFlow ship different CUDA builds for different GPU
generations, and the installer picks the right one for yours: Maxwell, Pascal
and Volta use the cu126 legacy channel, Turing and newer use cu128 or later.
The CUDA 13 channel (`cu130`, which the UMA runtime uses from torch 2.13)
requires an NVIDIA driver of 580 or newer, and it carries no kernels below
Turing — Volta therefore stays on `cu126`, which works with older drivers.
`mliport setup` prints the GPU it detected and the route it would take.

<!-- BEGIN GENERATED: gpu-routes -->
Expand All @@ -189,7 +192,8 @@ claiming a verification.

Pre-Turing GPUs depend on the CUDA 12.6 channel, and PyTorch stops publishing
it from 2.15. In those environments keep the installer's pins and do not
upgrade the framework.
upgrade the framework; a CUDA 13 build is not an alternative there, because it
has no kernels below Turing regardless of the driver.

## Offline machines

Expand Down
10 changes: 6 additions & 4 deletions docs/installation.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Python 版本符合要求、且不含其他后端的软件包)会被复用,
<!-- BEGIN GENERATED: backend-matrix -->
| 后端 | 环境 | Python | 运行时 |
|---|---|---|---|
| UMA (FAIRChem) | `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.21.0` (torch 2.8.0) |
| UMA (FAIRChem) | `.venv` | 3.11, 3.12, 3.13 | `fairchem-core==2.25.0` (torch 2.13.0) |
| MACE | `.venv-mace` | 3.10, 3.11, 3.12, 3.13 | `mace-torch==0.3.16` (torch 2.8.0) |
| DPA (DeepMD-kit) | `.venv-dpa` | 3.10, 3.11, 3.12, 3.13 | `deepmd-kit @ git+https://github.com/deepmodeling/deepmd-kit.git@0edeaef5617e9878edeb2346bf37bb6a035a4f51` (torch 2.11.0) |
| NEP (Calorine / GPUMD) | `.venv-nep` | 3.10, 3.11, 3.12, 3.13 | `calorine==4.1`(NumPy/ASE 由安装器解析;gpumd 需用 CUDA Toolkit 12.9 编译) |
Expand Down Expand Up @@ -138,8 +138,10 @@ mliport 不负责下载模型。请用上游工具下载模型文件,再用 `-
## GPU 架构

PyTorch 和 TensorFlow 针对不同代的 GPU 提供不同的 CUDA 版本,安装脚本会自动选择:
Maxwell、Pascal、Volta 用 cu126,Turing 及更新的用 cu128 或更高。`mliport setup` 会打印检测
到的 GPU 和准备采用的安装方案。
Maxwell、Pascal、Volta 用 cu126,Turing 及更新的用 cu128 或更高。CUDA 13 频道(`cu130`,
UMA 运行时从 torch 2.13 起使用)需要 **580 或更新**的 NVIDIA 驱动,而且该构建不包含 Turing
以下的内核,所以 Volta 继续留在 `cu126`,老驱动也能用。`mliport setup` 会打印检测到的 GPU
和准备采用的安装方案。

<!-- BEGIN GENERATED: gpu-routes -->
| 引擎 | Maxwell | Pascal | Volta / V100 | Ada / RTX 4090 | Other Turing+ | Hopper / Blackwell |
Expand All @@ -159,7 +161,7 @@ Maxwell、Pascal、Volta 用 cu126,Turing 及更新的用 cu128 或更高。`m
`mliport doctor` 会对检测到的 GPU 打印这个分类。

Turing 之前的 GPU 依赖 CUDA 12.6 版本,而 PyTorch 从 2.15 起不再提供。这类机器上请保持安装
脚本装的版本,不要升级框架。
脚本装的版本,不要升级框架;CUDA 13 的构建在这里也帮不上忙,因为它不包含 Turing 以下的内核。

## 离线机器

Expand Down
58 changes: 52 additions & 6 deletions mliport/mliport/calculators/uma.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,25 @@ class UMACalculator(BaseMLIPCalculator):
VALID_DEVICES: ClassVar[set[str]] = {"cpu", "cuda", "gpu"}
VALID_INFERENCE_MODES: ClassVar[set[str]] = {"default", "turbo"}

#: mliport preset -> upstream fairchem-core preset.
#:
#: fairchem-core 2.22+ made ``default`` mean UMA Nitro (Ampere and newer,
#: reduced precision) and removed ``turbo``. mliport keeps its own two-name
#: vocabulary and maps it onto the upstream presets that reproduce the
#: numerical settings mliport has always documented:
#:
#: * ``default`` -> upstream ``batch``: tf32 off, compile off, merge_mole
#: off, activation checkpointing on (exactly fairchem 2.21 ``default``);
#: * ``turbo`` -> upstream ``multigpu``: tf32 + compile + merge_mole
#: (upstream calls this "turbo's former settings").
#:
#: Neither preset can select Nitro, and the settings object is checked for
#: ``nitro`` before the predictor is built.
INFERENCE_PRESETS: ClassVar[dict[str, str]] = {
"default": "batch",
"turbo": "multigpu",
}

# Known UMA tasks (used when fairchem-core is not importable, e.g. in
# lightweight parameter-validation tests). When fairchem-core is installed
# its UMATask enum is authoritative.
Expand Down Expand Up @@ -90,6 +109,10 @@ def __init__(
self._task = task.lower()
self.device = device or "cpu"
self._inference_mode = inference_mode.lower()
# Filled in by load_predictor(): the upstream preset that really ran and
# the numeric switches of its settings object.
self._effective_preset: str | None = None
self._effective_settings: object | None = None
self.torch_num_threads = torch_num_threads
self.activation_checkpointing = activation_checkpointing

Expand Down Expand Up @@ -259,19 +282,37 @@ def load_predictor(self) -> MLIPPredictUnit:
"""
if self._predictor is None:
self._check_gpu_compatibility()
# Start from the named preset ("default" / "turbo"), which sets
# external_graph_gen / internal_graph_gen_version to values that
# actually build a neighbor graph. Building a partial
# InferenceSettings by hand leaves those as None (checkpoint
# default) and breaks graph generation for some models.
# Start from a named upstream preset, which sets external_graph_gen /
# internal_graph_gen_version to values that actually build a
# neighbor graph. Building a partial InferenceSettings by hand
# leaves those as None (checkpoint default) and breaks graph
# generation for some models.
from fairchem.core.units.mlip_unit import ( # noqa: PLC0415
load_predict_unit,
)
from fairchem.core.units.mlip_unit.api.inference import ( # noqa: PLC0415
guess_inference_settings,
)

settings = copy.deepcopy(guess_inference_settings(self.inference_mode))
preset = self.INFERENCE_PRESETS[self.inference_mode]
try:
settings = copy.deepcopy(guess_inference_settings(preset))
except (AssertionError, KeyError, ValueError) as exc:
raise RuntimeError(
f"fairchem-core in this environment does not provide the "
f"inference preset {preset!r} that mliport's "
f"--inference-mode {self.inference_mode!r} maps to. "
f"Upgrade to fairchem-core 2.25.0 (the pinned version) "
f"instead of falling back to a preset that would change "
f"precision. Upstream said: {exc}"
) from exc
if getattr(settings, "nitro", False):
# Nitro is Ampere-and-newer only and changes numerical
# behaviour; mliport never selects it.
raise RuntimeError(
f"fairchem-core preset {preset!r} enables UMA Nitro. "
"mliport does not expose Nitro; pick a preset without it."
)
if self.activation_checkpointing is not None:
settings.activation_checkpointing = self.activation_checkpointing
if self.torch_num_threads is not None:
Expand All @@ -284,6 +325,8 @@ def load_predictor(self) -> MLIPPredictUnit:
# (tf32, merge_mole) still apply.
if settings.compile and not self._compile_supported():
settings.compile = False
self._effective_preset = preset
self._effective_settings = settings
self._predictor = load_predict_unit(
path=self.model_path,
device=self._backend_device(),
Expand Down Expand Up @@ -366,6 +409,9 @@ def info(self) -> dict:
"task": self.task,
"device": self.device,
"inference_mode": self.inference_mode,
"inference_preset": self._effective_preset,
"nitro_enabled": bool(getattr(self._effective_settings, "nitro", False)),
"tf32_enabled": bool(getattr(self._effective_settings, "tf32", False)),
"direct_forces": getattr(self._predictor, "direct_forces", None),
"compile_enabled": getattr(
getattr(self._predictor, "inference_settings", None), "compile", None
Expand Down
Loading
Loading