From 0b03212d6703ae6c7d57885a4c2d1582ec50715a Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sat, 14 Nov 2026 18:33:56 +0800 Subject: [PATCH 1/2] feat(uma): move to fairchem-core 2.25.0 and keep Nitro out of reach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracking: #61 (model-support spec §6.4) What was wrong: the pinned fairchem-core 2.21.0 cannot load the UMA-S 1.2.1 checkpoints (uma-s-1p2p1*.pt); they need >= 2.22. The runtime bump is also the first release whose upstream default changed semantics: 2.22+ made UMA Nitro the upstream "default" preset (Ampere and newer, reduced precision) and removed "turbo", so simply re-pointing the pin would have silently changed the precision of every mliport "default" run and could have selected Nitro. What changes: - fairchem-core 2.25.0 (latest, Requires-Python >=3.11,<3.15) on torch 2.13.0. 2.24 and 2.25 share the torch~=2.13.0 pin, and torch 2.13.0 still publishes cu126 wheels, so Volta keeps a supported route; 2.15 drops cu126 entirely. - FRAMEWORK_PYTHON gains torch 2.13.0 and _torch_modern_cuda maps it to cu130, the CUDA version of the default PyPI torch 2.13.0 build (cuda-toolkit 13.0.3). CUDA 13 carries no kernel below Turing, which matches the modern-architecture set; an unknown torch version still fails closed. - UMACalculator now owns the preset mapping: mliport "default" runs upstream "batch" (tf32 off, no compile, no merged MOLE = the 2.21 "default" numbers) and "turbo" runs upstream "multigpu" (upstream calls it "turbo's former settings"). A preset that would enable Nitro is refused, a missing preset fails closed with an upgrade message instead of degrading, and the effective preset, its tf32 flag and its Nitro flag are added to the model identity. - Generated install docs and the UMA backend page are regenerated; the page records that the beta scientific validation of uma_omat ran on 2.21.0 and does not carry over. - Tests updated for the new pins and new tests pin the preset mapping, the Nitro refusal and the fail-closed missing-preset path. Evidence (owner's V100, Tesla V100-SXM2-16GB, driver 580.173.02): ./scripts/install_mliport.sh --engines uma --device auto re-resolved the existing .venv and its closing `mliport doctor --engine uma --device auto` passed: fairchem-core 2.25.0, torch 2.13.0+cu126 (CUDA 12.6), a real tensor dot product on cuda:0, arch list sm_50/sm_60/sm_70/sm_75/sm_80/sm_86/sm_90. The UMA checkpoints themselves are not called here: facebook/UMA is a gated repository and this host has no HF token, so uma-s-1p2p1*.pt could not be downloaded. That callable check remains not_run. DATA IMPACT: no stored scientific record invalidated. Runs produced on fairchem-core 2.21.0 keep their recorded framework versions and stay valid for that runtime; they are not interchangeable with runs on 2.25.0, which the docs now say explicitly. --- CHANGELOG.md | 23 +++ docs/backends/uma.md | 17 ++- docs/backends/uma.zh.md | 12 +- docs/installation.md | 2 +- docs/installation.zh.md | 2 +- mliport/mliport/calculators/uma.py | 58 ++++++- mliport/mliport/install/compatibility.py | 49 +++--- mliport/mliport/model_record.py | 6 + tests/mliport/mliport/test_calculator.py | 143 ++++++++++++++++++ tests/mliport/mliport/test_doctor.py | 10 +- .../mliport/test_gpu_architecture_audit.py | 6 +- tests/mliport/mliport/test_gpu_setup.py | 16 +- tests/mliport/mliport/test_install_plan.py | 23 +-- 13 files changed, 313 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e5ebc836..7a1e9227 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,29 @@ ## Unreleased +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. + + Installer environment contract and CI repair: - An existing target environment is now inspected before any step runs. A diff --git a/docs/backends/uma.md b/docs/backends/uma.md index e836db90..501584ea 100644 --- a/docs/backends/uma.md +++ b/docs/backends/uma.md @@ -32,7 +32,7 @@ either works as `--model-type`. | 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 @@ -70,6 +70,21 @@ 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. 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 diff --git a/docs/backends/uma.zh.md b/docs/backends/uma.zh.md index d53f0af2..ed2f1fa3 100644 --- a/docs/backends/uma.zh.md +++ b/docs/backends/uma.zh.md @@ -24,7 +24,7 @@ Meta FAIR 的 UMA 模型通过上游的 `fairchem-core` 加载。`--model-type` | 环境 | 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 @@ -56,6 +56,16 @@ 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 以下的内核。 + 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))。 - **应力**只有模型支持时才会输出。 diff --git a/docs/installation.md b/docs/installation.md index 592e51fb..173ba7ae 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -78,7 +78,7 @@ any scientific option for you. | 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) | diff --git a/docs/installation.zh.md b/docs/installation.zh.md index f1297226..1e437ce4 100644 --- a/docs/installation.zh.md +++ b/docs/installation.zh.md @@ -65,7 +65,7 @@ Python 版本符合要求、且不含其他后端的软件包)会被复用, | 后端 | 环境 | 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 编译) | diff --git a/mliport/mliport/calculators/uma.py b/mliport/mliport/calculators/uma.py index c2eb85e1..f045ae90 100644 --- a/mliport/mliport/calculators/uma.py +++ b/mliport/mliport/calculators/uma.py @@ -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. @@ -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 @@ -259,11 +282,11 @@ 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, ) @@ -271,7 +294,25 @@ def load_predictor(self) -> MLIPPredictUnit: 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: @@ -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(), @@ -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 diff --git a/mliport/mliport/install/compatibility.py b/mliport/mliport/install/compatibility.py index a11fa6ec..f7de1492 100644 --- a/mliport/mliport/install/compatibility.py +++ b/mliport/mliport/install/compatibility.py @@ -44,6 +44,7 @@ ("torch", "2.8.0"): SpecifierSet(">=3.9,<3.14"), ("torch", "2.10.0"): SpecifierSet(">=3.10,<3.15"), ("torch", "2.11.0"): SpecifierSet(">=3.10,<3.15"), + ("torch", "2.13.0"): SpecifierSet(">=3.10,<3.15"), ("tensorflow", "2.20.0"): SpecifierSet(">=3.9,<3.14"), } @@ -186,6 +187,11 @@ class CudaChannel: # For legacy GPUs (Maxwell/Pascal/Volta) the channel is always cu126. # For modern GPUs (Turing+) the channel depends on the torch version: # torch 2.8.0 / 2.10.0 / 2.11.0 → cu128 +# torch 2.13.0 → cu130 +# The modern channel tracks the CUDA version of the default PyPI wheel: 2.13.0 +# is built against CUDA 13.0 (``cuda-toolkit==13.0.3`` in its metadata), and +# CUDA 13 has no kernels below Turing. Legacy parts stay on cu126, the last +# channel that carries sm_50/60/70 kernels. # Other releases require an explicit wheel compatibility audit. # This table is the single central mapping; update it when a new torch # version changes its modern CUDA channel. @@ -197,6 +203,7 @@ def _torch_modern_cuda(version: str) -> str: "2.8.0": "cu128", "2.10.0": "cu128", "2.11.0": "cu128", + "2.13.0": "cu130", } if version not in mapping: raise ValueError( @@ -354,54 +361,56 @@ def install_packages(self) -> tuple[str, ...]: engine="uma", label="UMA (FAIRChem)", distribution="fairchem-core", - version="2.21.0", + version="2.25.0", framework="torch", - upstream_constraint="torch~=2.8.0", - requires_python=SpecifierSet(">=3.11,<3.14"), + upstream_constraint="torch~=2.13.0", + requires_python=SpecifierSet(">=3.11,<3.15"), venv_name=".venv", arch_profiles={ "maxwell": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=False, - notes="Experimental. fairchem-core 2.21.0 → torch~=2.8.0. " + notes="Experimental. fairchem-core 2.25.0 → torch~=2.13.0. " "Maxwell via cu126 legacy channel; upstream does not test this GPU.", ), "pascal": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="torch 2.8.0+cu126 includes sm60 kernel. " - "fairchem-core 2.21.0 constraint torch~=2.8.0 satisfied.", + notes="torch 2.13.0+cu126 includes sm_60 kernel. " + "fairchem-core 2.25.0 constraint torch~=2.13.0 satisfied.", ), "volta": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, notes="Architecture profile: V100 (sm_70). " - "torch 2.8.0+cu126 includes sm70 kernel.", + "torch 2.13.0+cu126 is the last CUDA-12.6 build with sm70 kernels; " + "torch 2.15 drops cu126 wheels entirely.", ), "turing": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="Modern CUDA (cu128) for Turing+.", + notes="Modern CUDA (cu130) for Turing+; CUDA 13 has no kernels " + "below Turing.", ), "ampere": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="Modern CUDA (cu128) for Ampere.", + notes="Modern CUDA (cu130) for Ampere.", ), "ada": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="Architecture profile: RTX 4090. Modern CUDA (cu128) for Ada.", + notes="Architecture profile: RTX 4090. Modern CUDA (cu130) for Ada.", ), "hopper": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="Modern CUDA (cu128) for Hopper.", + notes="Modern CUDA (cu130) for Hopper.", ), "blackwell": BackendArchProfile( - framework_version="2.8.0", + framework_version="2.13.0", upstream_supported=True, - notes="Modern CUDA (cu128) for Blackwell.", + notes="Modern CUDA (cu130) for Blackwell.", ), }, ), diff --git a/mliport/mliport/model_record.py b/mliport/mliport/model_record.py index 7c13c9e8..b539739d 100644 --- a/mliport/mliport/model_record.py +++ b/mliport/mliport/model_record.py @@ -177,6 +177,12 @@ def build_model_record( ), "compile_enabled": info.get("compile_enabled"), "direct_forces": info.get("direct_forces"), + # The upstream preset that really ran (UMA maps mliport's + # default/turbo onto named fairchem presets), plus the numeric switches + # of that preset. None means the backend has no such notion. + "inference_preset": info.get("inference_preset"), + "nitro_enabled": info.get("nitro_enabled"), + "tf32_enabled": info.get("tf32_enabled"), "model_path": str(Path(resolved.model_path).expanduser().resolve()), "model_sha256": hash_model_path(resolved.model_path, error_class=error_class), "model_alias": model_alias, diff --git a/tests/mliport/mliport/test_calculator.py b/tests/mliport/mliport/test_calculator.py index 967a3825..8c353446 100644 --- a/tests/mliport/mliport/test_calculator.py +++ b/tests/mliport/mliport/test_calculator.py @@ -148,3 +148,146 @@ def test_compile_supported_probes_requested_index(self, monkeypatch): calc = UMACalculator(model_path="fake.pt", device="cuda:3") assert calc._compile_supported() is False fake_cuda.get_device_capability.assert_called_once_with(3) + + +class TestNoImplicitAccelerationPresets: + """UMA Nitro is Ampere+ only, so mliport must never select it. + + Spec #61 (model-support §6.4): fairchem-core 2.24.0 added a Nitro inference + path that cannot run on Volta. mliport exposes exactly two presets and + records the effective one; nothing can silently pick a third. + """ + + def test_only_the_two_supported_presets_exist(self): + modes = set(UMACalculator.VALID_INFERENCE_MODES) + assert modes == {"default", "turbo"} + assert "nitro" not in modes + + def test_presets_map_to_upstream_presets_without_nitro(self): + """default -> batch and turbo -> multigpu reproduce the old numbers.""" + mapping = dict(UMACalculator.INFERENCE_PRESETS) + assert mapping == {"default": "batch", "turbo": "multigpu"} + + def test_nitro_is_rejected_by_the_calculator(self): + with ( + patch.object(Path, "exists", return_value=True), + pytest.raises(ValueError, match="Invalid inference mode"), + ): + UMACalculator(model_path="fake.pt", inference_mode="nitro") + + def test_nitro_is_rejected_by_the_configuration_schema(self, tmp_path): + from mliport.config import resolve_config + + model = tmp_path / "uma.pt" + model.write_bytes(b"stub") + with pytest.raises(ValueError): + resolve_config( + calc_type="sp", + cli={ + "model_type": "uma", + "model_path": str(model), + "device": "cpu", + "inference_mode": "nitro", + }, + ) + + def test_the_effective_preset_is_recorded(self): + """Provenance must say which preset ran, not just that one was allowed.""" + from mliport.config import resolve_config + + resolved = resolve_config( + calc_type="sp", + cli={ + "model_type": "uma", + "model_path": "uma.pt", + "device": "cpu", + "inference_mode": "turbo", + }, + ) + assert resolved.inference_mode == "turbo" + assert str(resolved.sources["inference_mode"].value) == "turbo" + + +class _FakeSettings: + def __init__(self, **kwargs): + self.tf32 = kwargs.get("tf32", False) + self.compile = kwargs.get("compile", False) + self.nitro = kwargs.get("nitro", False) + self.activation_checkpointing = True + self.torch_num_threads = None + + +def _install_fake_fairchem(monkeypatch, guess): + """Register stub fairchem modules so load_predictor() runs without weights.""" + modules = {} + for name in ( + "fairchem", + "fairchem.core", + "fairchem.core.units", + "fairchem.core.units.mlip_unit", + "fairchem.core.units.mlip_unit.api", + "fairchem.core.units.mlip_unit.api.inference", + ): + modules[name] = types.ModuleType(name) + + recorded = {} + + def load_predict_unit(path=None, device=None, inference_settings=None): + recorded["settings"] = inference_settings + return types.SimpleNamespace(model=None, direct_forces=False) + + modules["fairchem.core.units.mlip_unit"].load_predict_unit = load_predict_unit + modules[ + "fairchem.core.units.mlip_unit.api.inference" + ].guess_inference_settings = guess + modules["fairchem.core.units"].mlip_unit = modules["fairchem.core.units.mlip_unit"] + for name, module in modules.items(): + monkeypatch.setitem(sys.modules, name, module) + return recorded + + +class TestInferencePresetMapping: + """The upstream preset that really runs is chosen by mliport, not upstream.""" + + def test_default_maps_to_the_upstream_batch_preset(self, monkeypatch): + recorded = _install_fake_fairchem( + monkeypatch, lambda name: _FakeSettings() if name == "batch" else None + ) + with patch.object(Path, "exists", return_value=True): + calc = UMACalculator(model_path="fake.pt", device="cpu") + calc.load_predictor() + assert calc._effective_preset == "batch" + assert recorded["settings"].nitro is False + + def test_turbo_maps_to_the_upstream_multigpu_preset(self, monkeypatch): + recorded = _install_fake_fairchem( + monkeypatch, + lambda name: _FakeSettings(tf32=True, compile=True) + if name == "multigpu" + else None, + ) + with patch.object(Path, "exists", return_value=True): + calc = UMACalculator( + model_path="fake.pt", device="cpu", inference_mode="turbo" + ) + calc.load_predictor() + assert calc._effective_preset == "multigpu" + assert recorded["settings"].tf32 is True + assert recorded["settings"].nitro is False + + def test_a_preset_that_turns_nitro_on_is_refused(self, monkeypatch): + _install_fake_fairchem(monkeypatch, lambda name: _FakeSettings(nitro=True)) + with patch.object(Path, "exists", return_value=True): + calc = UMACalculator(model_path="fake.pt", device="cpu") + with pytest.raises(RuntimeError, match="Nitro"): + calc.load_predictor() + + def test_a_missing_upstream_preset_fails_closed(self, monkeypatch): + def guess(name): + raise ValueError("inference_settings='batch' is not a preset") + + _install_fake_fairchem(monkeypatch, guess) + with patch.object(Path, "exists", return_value=True): + calc = UMACalculator(model_path="fake.pt", device="cpu") + with pytest.raises(RuntimeError, match="fairchem-core 2.25.0"): + calc.load_predictor() diff --git a/tests/mliport/mliport/test_doctor.py b/tests/mliport/mliport/test_doctor.py index d27517a5..01538b89 100644 --- a/tests/mliport/mliport/test_doctor.py +++ b/tests/mliport/mliport/test_doctor.py @@ -34,7 +34,7 @@ def _mock_4090_runtime(monkeypatch, arch_list, *, total_memory=24564 * 1024**2): _controlled_environment( monkeypatch, - **{"fairchem-core": "2.21.0", "torch": "2.8.0+cu128"}, + **{"fairchem-core": "2.25.0", "torch": "2.13.0+cu130"}, ) monkeypatch.setattr( "mliport.doctor.detect_gpus", @@ -45,8 +45,8 @@ def _mock_4090_runtime(monkeypatch, arch_list, *, total_memory=24564 * 1024**2): lambda engine, device, framework=None: { "ok": True, "framework": "torch", - "torch_version": "2.8.0+cu128", - "cuda_runtime": "12.8", + "torch_version": "2.13.0+cu130", + "cuda_runtime": "13.0", "cuda_available": True, "device_count": 1, "arch_list": arch_list, @@ -300,7 +300,7 @@ def test_cuda_target_fails_when_framework_cannot_see_gpu(monkeypatch): def _unexpected_failures(checks: list[dict]) -> list[dict]: """Failures other than the documented interpreter-vs-installer-pin one. - The UMA installer pin (fairchem-core==2.21.0) requires Python >=3.11, so + The UMA installer pin (fairchem-core==2.25.0) requires Python >=3.11, so on a 3.10 interpreter doctor reports "UMA installer Python constraint" as fail by design. These tests exercise the GPU recommendation logic, not that constraint. @@ -336,7 +336,7 @@ def test_doctor_reports_missing_4090_kernel_without_crashing(monkeypatch): assert runtime_gpu["status"] == "fail" assert "do not support sm_89" in runtime_gpu["detail"] - assert "torch 2.8.0+cu128" in runtime_gpu["detail"] + assert "torch 2.13.0+cu130" in runtime_gpu["detail"] unexpected = _unexpected_failures(checks) assert len(unexpected) == 1 and unexpected[0]["name"] == "Runtime GPU 0" diff --git a/tests/mliport/mliport/test_gpu_architecture_audit.py b/tests/mliport/mliport/test_gpu_architecture_audit.py index 44570db0..95c5f842 100644 --- a/tests/mliport/mliport/test_gpu_architecture_audit.py +++ b/tests/mliport/mliport/test_gpu_architecture_audit.py @@ -43,11 +43,11 @@ def _joined(plan) -> str: @pytest.mark.parametrize("cc, expected_arch", [((6, 0), "pascal"), ((6, 1), "pascal")]) def test_arch_t1_t2_pascal_sm60_and_sm61_plan(cc, expected_arch): """ARCH-T1/T2: Pascal sm60 and sm61 both plan the cu126 legacy route.""" - for engine in ("mace", "uma"): + for engine, torch_version in (("mace", "2.8.0"), ("uma", "2.13.0")): plan = generate_plan([_gpu(*cc)], engines=[engine], device="cuda") assert plan.gpu_arch == expected_arch joined = _joined(plan) - assert "torch==2.8.0+cu126" in joined, engine + assert f"torch=={torch_version}+cu126" in joined, engine assert any("needs smoke test" in w for w in plan.warnings), engine dpa = generate_plan([_gpu(*cc)], engines=["dpa"], device="cuda") @@ -70,6 +70,7 @@ def test_arch_t3_volta_sm70_plan(): joined = _joined(plan) assert "torch==2.8.0+cu126" in joined assert "torch==2.11.0+cu126" in joined + assert "torch==2.13.0+cu126" in joined @pytest.mark.parametrize( @@ -90,6 +91,7 @@ def test_modern_arches_use_cu128(cc, expected_arch): joined = _joined(plan) assert "torch==2.8.0+cu128" in joined assert "torch==2.11.0+cu128" in joined + assert "torch==2.13.0+cu130" in joined def test_grace_hopper_and_blackwell_are_experimental(): diff --git a/tests/mliport/mliport/test_gpu_setup.py b/tests/mliport/mliport/test_gpu_setup.py index b7468f4a..8c88b2d1 100644 --- a/tests/mliport/mliport/test_gpu_setup.py +++ b/tests/mliport/mliport/test_gpu_setup.py @@ -98,10 +98,10 @@ def test_recommend_torch_kepler_unsupported() -> None: def test_recommend_torch_pascal_uses_cu126() -> None: - """Pascal (sm_61) → torch 2.8.0+cu126 via legacy channel.""" + """Pascal (sm_61) → torch 2.13.0+cu126 via legacy channel (UMA default).""" rec = recommend_torch(6, 1) assert rec.supported is True - assert "2.8.0" in rec.version + assert "2.13.0" in rec.version assert "cu126" in rec.version @@ -113,11 +113,11 @@ def test_recommend_torch_pascal_dpa_preserves_deepmd_abi_pin() -> None: def test_recommend_torch_blackwell_uses_modern() -> None: - """Blackwell (sm_100) → torch 2.8.0+cu128 via modern channel.""" + """Blackwell (sm_100) → torch 2.13.0+cu130 via modern channel.""" rec = recommend_torch(10, 0) assert rec.supported is True - assert "2.8.0" in rec.version - assert "cu128" in rec.version + assert "2.13.0" in rec.version + assert "cu130" in rec.version def _gpu(cc_major: int, cc_minor: int) -> GpuInfo: @@ -184,7 +184,7 @@ def test_engine_install_commands_uma_explicit() -> None: cmds = engine_install_commands(None, "uma") joined = "\n".join(cmds) assert "uv sync" not in joined - assert "fairchem-core==2.21.0" in joined + assert "fairchem-core==2.25.0" in joined assert ( "-e './mliport[analysis-all]'" in joined or "-e ./mliport[analysis-all]" in joined @@ -196,5 +196,5 @@ def test_engine_install_commands_maxwell_experimental() -> None: cmds = engine_install_commands([_gpu(5, 2)], "uma") joined = "\n".join(cmds) # Should still produce explicit UMA install (torch + fairchem-core). - assert "fairchem-core==2.21.0" in joined - assert "torch==2.8.0" in joined + assert "fairchem-core==2.25.0" in joined + assert "torch==2.13.0" in joined diff --git a/tests/mliport/mliport/test_install_plan.py b/tests/mliport/mliport/test_install_plan.py index a092e09b..3ec411fd 100644 --- a/tests/mliport/mliport/test_install_plan.py +++ b/tests/mliport/mliport/test_install_plan.py @@ -13,7 +13,7 @@ def test_backend_python_intersection_before_clean_plan(): - with pytest.raises(InstallPlanError, match="fairchem-core==2.21.0"): + with pytest.raises(InstallPlanError, match="fairchem-core==2.25.0"): generate_plan(None, ["uma"], python_version="3.10", device="cpu", clean=True) for py in ("3.11", "3.12"): assert generate_plan(None, ["uma"], python_version=py, device="cpu").steps @@ -64,13 +64,13 @@ def test_normalize_engines_empty_raises() -> None: def test_uma_explicit_install_v100() -> None: - """V100: UMA must use torch 2.8.0 + cu126 + fairchem-core, no uv sync.""" + """V100: UMA must use torch 2.13.0 + cu126 + fairchem-core, no uv sync.""" plan = generate_plan([_gpu("V100", 7, 0)], ["uma"], verify=False) argv = _all_argv(plan) assert "uv sync" not in argv - assert "torch==2.8.0" in argv + assert "torch==2.13.0" in argv assert "cu126" in argv - assert "fairchem-core==2.21.0" in argv + assert "fairchem-core==2.25.0" in argv assert "-e ./mliport" in argv @@ -78,9 +78,9 @@ def test_uma_explicit_install_cpu() -> None: plan = generate_plan(None, ["uma"], device="cpu", verify=False) argv = _all_argv(plan) assert "uv sync" not in argv - assert "torch==2.8.0+cpu" in argv + assert "torch==2.13.0+cpu" in argv assert "https://download.pytorch.org/whl/cpu" in argv - assert "fairchem-core==2.21.0" in argv + assert "fairchem-core==2.25.0" in argv # --------------------------------------------------------------------------- @@ -136,12 +136,17 @@ def test_dpa_source_build_is_pinned_and_uses_selected_torch(): def test_4090_plan_modern() -> None: - """Ada (sm_89) → torch engines use cu128 (modern).""" + """Ada (sm_89) → each engine keeps its own modern channel. + + UMA is on torch 2.13.0, whose default PyPI build is CUDA 13.0 (cu130); + MACE stays on cu128 and DPA on cu128. No engine falls back to cu126. + """ plan = generate_plan([_gpu("RTX 4090", 8, 9)], ["uma", "mace", "dpa"], verify=False) argv = _all_argv(plan) - assert "cu128" in argv - assert "cu126" not in argv + assert "torch==2.13.0+cu130" in argv + assert "torch==2.8.0+cu128" in argv assert "torch==2.11.0+cu128" in argv + assert "cu126" not in argv assert any("DPA" in w and "needs smoke test" in w for w in plan.warnings) From eb3c2d514e8fd21bb3bb4d7d9600e7e8cf0b790e Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sat, 14 Nov 2026 22:15:23 +0800 Subject: [PATCH 2/2] docs(install): state the driver floor for the cu130 wheels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracking: #61 (model-support spec §11 task 4, review of #97) What was missing: the docs said Turing and newer use "cu128 or later" and that the UMA runtime is on cu130, but not that the CUDA 13 wheels require an NVIDIA driver of 580 or newer, and not that Volta stays on cu126 precisely so older drivers keep working. What changes: - `docs/installation.md` (+ `.zh.md`): the GPU-architecture section names the `cu130` driver floor and says a CUDA 13 build is not an alternative for pre-Turing GPUs because it has no kernels below Turing, whatever the driver. - `docs/backends/uma.md` (+ `.zh.md`): the "Runtime pin" bullet says the same in one sentence. - CHANGELOG entry. Verified on the owner's host: driver 580.173.02 runs torch 2.13.0+cu126 on the V100 (sm_70 kernels present in the wheel's arch list). DATA IMPACT: no scientific record invalidated; documentation only. --- CHANGELOG.md | 4 ++++ docs/backends/uma.md | 3 ++- docs/backends/uma.zh.md | 3 ++- docs/installation.md | 6 +++++- docs/installation.zh.md | 8 +++++--- 5 files changed, 18 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4407f8a..5054e2a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ UMA runtime upgrade for UMA-S 1.2.1: - `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: diff --git a/docs/backends/uma.md b/docs/backends/uma.md index 501584ea..8c170ce9 100644 --- a/docs/backends/uma.md +++ b/docs/backends/uma.md @@ -72,7 +72,8 @@ license is non-commercial research only; see [Citations](../citations.md). 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. 2.25.0 is the pinned release that loads + 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. diff --git a/docs/backends/uma.zh.md b/docs/backends/uma.zh.md index ed2f1fa3..3f3295e8 100644 --- a/docs/backends/uma.zh.md +++ b/docs/backends/uma.zh.md @@ -57,7 +57,8 @@ Meta FAIR 的 UMA 模型通过上游的 `fairchem-core` 加载。`--model-type` 需要手动开启,MD 默认不用,以保证精度。`--activation-checkpointing` 可以用速度换显存。 - **精度**由模型决定,mliport 只记录框架版本。 - **固定的运行环境。** `fairchem-core==2.25.0` 配 torch 2.13.0。Volta(V100)继续用 `cu126` - 的 wheel,Turing 及更新的卡用 `cu130`,因为 CUDA 13 的构建不再包含 Turing 以下的内核。 + 的 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 上做的,那批结论只对那套环境成立,不能直接套用到 这里;新环境有它自己的可调用性检查记录。 diff --git a/docs/installation.md b/docs/installation.md index 173ba7ae..bacd01ea 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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. @@ -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 diff --git a/docs/installation.zh.md b/docs/installation.zh.md index 1e437ce4..d554beb3 100644 --- a/docs/installation.zh.md +++ b/docs/installation.zh.md @@ -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 +和准备采用的安装方案。 | 引擎 | Maxwell | Pascal | Volta / V100 | Ada / RTX 4090 | Other Turing+ | Hopper / Blackwell | @@ -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 以下的内核。 ## 离线机器