grace-runtime 0.1.0__tar.gz → 0.1.2__tar.gz

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/.github/workflows/cpu-wheels.yml

@@ -9,6 +9,7 @@ on:
   workflow_dispatch:
   pull_request:
     branches: [dev]      # the release pull request
+    paths-ignore: [docs/**, '*.md']
   workflow_call:         # from release.yml
 
 permissions:
@@ -51,7 +52,7 @@ jobs:
       matrix:
         platform:
           - {artifact: cpu-wheels, os: ubuntu-latest, mamba: linux-64}
-          - {artifact: cpu-wheels-macos-arm64, os: macos-14, mamba: osx-arm64}
+          - {artifact: cpu-wheels-macos-arm64, os: macos-15, mamba: osx-arm64}
     runs-on: ${{ matrix.platform.os }}
     timeout-minutes: 120
     steps:
@@ -80,7 +81,7 @@ jobs:
       matrix:
         platform:
           - {artifact: cpu-wheels, os: ubuntu-latest, mamba: linux-64}
-          - {artifact: cpu-wheels-macos-arm64, os: macos-14, mamba: osx-arm64}
+          - {artifact: cpu-wheels-macos-arm64, os: macos-15, mamba: osx-arm64}
         python: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.platform.os }}
     timeout-minutes: 120

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/.github/workflows/cuda-wheels.yml

@@ -10,6 +10,7 @@ on:
   workflow_dispatch:
   pull_request:
     branches: [dev]      # the release pull request
+    paths-ignore: [docs/**, '*.md']
   workflow_call:         # from release.yml
 
 permissions:

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/CHANGELOG.md

@@ -3,6 +3,80 @@
 Notable changes of grace-runtime, grace-runtime-cuda12 and grace-runtime-rocm6 (they share one version). Each
 release has a section "Changed defaults" when a default behaves differently.
 
+## [0.1.2](https://github.com/ICAMS/grace-runtime/releases/tag/0.1.2) (2026-11-01)
+
+The early GRACE-1L/2L models, and fast GPU kernels for more GRACE-1L/2L fits.
+
+### Added
+
+- **Early GRACE-1L/2L models:** GRACE-1L-OAM, GRACE-1L-OMAT, GRACE-2L-OAM and GRACE-2L-OMAT (and their older aliases)
+  are in the registry and run on the CPU, NVIDIA and AMD GPUs, in Python and in LAMMPS, without an uncertainty head.
+  Own fits of the early GRACE-1L/2L presets run as well: tensorpotential exports them as `kokkos.npz` format 2.
+- **More GRACE-1L/2L fits on the fast GPU kernels.** A fit whose layers are narrower than compiled GPU kernels runs
+  zero-padded to them, with the same results and a warning that names the widths (not models with an uncertainty
+  head). GRACE-2L has kernels for the widths of the current registry models, of the early ones, and of fits with 48
+  layer-2 radial channels; GRACE-1L fits run with up to 64 radial channels. The models guide lists the widths.
+- `GRACE_GENERIC_KERNELS=1`: a GRACE-2L fit wider than all compiled GPU kernels runs on generic GPU kernels, several
+  times slower, with a warning. Without the variable such a fit stops with an error that names its widths.
+
+### LAMMPS (`grace-runtime` branch of the LAMMPS fork)
+
+- `grace/runtime` and `grace/runtime/kk` run the early GRACE-1L/2L models and own fits of their presets. The Kokkos
+  style pads narrower fits like Python does, and with `GRACE_GENERIC_KERNELS=1` runs wider GRACE-2L fits on the
+  generic GPU kernels. Warnings appear as LAMMPS `WARNING` lines.
+
+### Documentation
+
+- Benchmarks: H200, MI250X, L40S and CPU charts; the front page shows the execution speed.
+- Models: which fits run on the fast GPU kernels, padded or not, and `GRACE_GENERIC_KERNELS`.
+
+### Changed defaults
+
+- A GRACE-1L/2L model without GPU kernels of its own widths stopped with an error on a GPU. A narrower one now runs
+  zero-padded with a warning; a wider GRACE-2L one still stops, and the error names `GRACE_GENERIC_KERNELS=1`.
+- `device="auto"`: such a wider GRACE-2L model raises instead of running on the CPU.
+- `kokkos.npz` format version 2 for the early GRACE-1L/2L layouts. grace-runtime 0.1.1 and older refuse these files
+  and ask for an update. Files of current models stay format 1.
+- The GPU modules of `grace-runtime-cuda12` / `grace-runtime-rocm6` 0.1.2 have interface version 7; grace-runtime
+  0.1.2 refuses older modules. The packages pin each other, so a normal `pip install` matches them.
+
+## [0.1.1](https://github.com/ICAMS/grace-runtime/releases/tag/0.1.1) (2026-10-29)
+
+Bug fixes and documentation.
+
+### Fixed
+
+- NVIDIA and AMD GPUs: GRACE-1L with 33.5 million atoms (2^25) or more stopped the whole process instead of running.
+  It now runs up to the GPU memory (A100 80 GB: 41 million atoms) and beyond that raises the usual "does not fit the
+  GPU memory" error.
+- The PyPI page of `grace-runtime` shows the README.
+- macOS: `pip install "grace-runtime[torchsim]"` installed PyTorch from PyPI, whose OpenMP runtime clashes with the
+  one of grace-runtime (`OMP: Error #15`). On macOS the extra now installs nothing; install PyTorch from conda-forge
+  (see the installation guide).
+- macOS: `grace-runtime info` says that the GPU modules are Linux-only, instead of listing where it looked for the
+  NVIDIA driver.
+
+### LAMMPS (`grace-runtime` branch of the LAMMPS fork)
+
+- CPU styles: `GRACE_BLAS=AUTO` uses a BLAS only if it is MKL, OpenBLAS, BLIS or Accelerate, otherwise the built-in
+  kernel. Other BLAS libraries (for example ATLAS) made GRACE-3L about 4x slower, and on HPE Cray systems the BLAS
+  linked by the compiler made the link fail.
+- CMake warns when the CPU styles are built with GCC older than 12: with GCC 11 GRACE-3L runs about 37 % slower,
+  with GCC 9 GRACE-1L about 4.6x and GRACE-3L about 6.6x slower.
+
+### Documentation
+
+- LAMMPS guide: build the fork for CPU, NVIDIA and AMD GPUs (with an example for LUMI), get a model, and run a first
+  input that also prints the extrapolation grade.
+- Windows through WSL2; GCC 12 or newer for source builds.
+- Benchmarks: time per atom and the largest system per GPU (L40S, A100, MI250X), and time per atom on a CPU.
+
+### Changed defaults
+
+- LAMMPS `GRACE_BLAS=AUTO` (see above): with a BLAS other than MKL, OpenBLAS, BLIS or Accelerate the CPU styles use
+  the built-in kernel. `-D GRACE_BLAS=ON` uses any BLAS that provides `cblas_sgemm`.
+- macOS: the `torchsim` extra installs no packages.
+
 ## [0.1.0](https://github.com/ICAMS/grace-runtime/releases/tag/0.1.0) (2026-10-29)
 
 First release on PyPI: `grace-runtime` (CPU), `grace-runtime-cuda12` (NVIDIA) and `grace-runtime-rocm6` (AMD). It

grace_runtime-0.1.2/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.2
+Name: grace-runtime
+Version: 0.1.2
+Summary: Fast CPU and GPU inference of GRACE and PACE interatomic potentials with ASE, batching and TorchSim
+License: Academic Software License (ASL); bundled third-party code: see THIRD_PARTY_NOTICES.md
+Classifier: License :: Other/Proprietary License
+Project-URL: Homepage, https://github.com/ICAMS/grace-runtime
+Project-URL: Issues, https://github.com/ICAMS/grace-runtime/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: ase
+Requires-Dist: tqdm
+Requires-Dist: spglib>=2.5
+Provides-Extra: torchsim
+Requires-Dist: torch>=2; python_version >= "3.12" and sys_platform != "darwin" and extra == "torchsim"
+Requires-Dist: torch-sim-atomistic>=0.6; python_version >= "3.12" and sys_platform != "darwin" and extra == "torchsim"
+Provides-Extra: phonons
+Requires-Dist: phonopy>=2.20; extra == "phonons"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pyyaml; extra == "test"
+Description-Content-Type: text/markdown
+
+# grace-runtime
+
+Fast, efficient execution of GRACE-1L, GRACE-2L and GRACE-3L interatomic potentials without TensorFlow, PyTorch or JAX.
+CPU execution is standalone; GPU execution uses Kokkos for NVIDIA CUDA and AMD HIP.
+Use ASE-compatible calculators, batch processing, an optional TorchSim adapter or the shared kernels in LAMMPS with MPI.
+PACE (ACE) potentials fitted with pacemaker run from their `.yaml` ([PACE models](https://github.com/ICAMS/grace-runtime/blob/master/docs/pace.md)).
+
+One call computes energy, forces and stress. On one NVIDIA H200 that takes about 1 µs per atom for GRACE-1L,
+3.5 µs for GRACE-2L and 13 µs for GRACE-3L (large OMAT models); a 16-core Xeon is 5 to 13 times slower.
+[Benchmarks](https://github.com/ICAMS/grace-runtime/blob/master/docs/benchmarks.md) gives the setup and the largest system per GPU.
+
+![Time per atom for GRACE-1L, 2L and 3L on NVIDIA H200, AMD MI250X, NVIDIA L40S and a 16-core Xeon](https://raw.githubusercontent.com/ICAMS/grace-runtime/master/docs/images/benchmarks-time.png)
+
+**[Read the manual](https://github.com/ICAMS/grace-runtime/blob/master/docs/index.md)** · [Installation](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md) · [API reference](https://github.com/ICAMS/grace-runtime/blob/master/docs/api.md)
+
+## Install
+
+Install one package from PyPI ([source builds](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md#cpu-from-source) for other targets):
+
+| Backend | Install |
+| --- | --- |
+| CPU | `pip install grace-runtime` |
+| NVIDIA | `pip install "grace-runtime-cuda12[cublas]"` |
+| AMD | `pip install grace-runtime-rocm6` |
+
+GPU packages install the matching CPU package automatically.
+See the manual for [GPU requirements](https://github.com/ICAMS/grace-runtime/blob/master/docs/backends.md) and [environment setup](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md#python-environment).
+
+## First calculation
+
+```python
+from ase.build import bulk
+from grace_runtime import GRACERuntimeCalculator
+
+atoms = bulk("W", "bcc", a=3.165, cubic=True)
+atoms.calc = GRACERuntimeCalculator("GRACE-2L-OMAT-medium-ft-E")
+print(atoms.get_potential_energy())  # eV
+print(atoms.get_forces())            # eV/Å; reuses the calculation above
+print(atoms.calc.backend)
+```
+
+Device and CPU-thread selection are automatic. Energy, forces and stress are computed together and cached.
+Named models download on first use; local `kokkos.npz` files work too.
+
+## Guides
+
+The [manual](https://github.com/ICAMS/grace-runtime/blob/master/docs/index.md#guides) covers [batching and MD](https://github.com/ICAMS/grace-runtime/blob/master/docs/usage.md), [relaxation](https://github.com/ICAMS/grace-runtime/blob/master/docs/relax.md),
+[properties](https://github.com/ICAMS/grace-runtime/blob/master/docs/properties.md), [dispersion](https://github.com/ICAMS/grace-runtime/blob/master/docs/dispersion.md), [PACE models](https://github.com/ICAMS/grace-runtime/blob/master/docs/pace.md), [TorchSim](https://github.com/ICAMS/grace-runtime/blob/master/docs/torchsim.md) and
+[development](https://github.com/ICAMS/grace-runtime/blob/master/docs/development.md). An interactive tour is in the [ASE notebook](https://github.com/ICAMS/grace-runtime/blob/master/python/examples/ase/grace_runtime_ase.ipynb).
+
+## LAMMPS
+
+The [LAMMPS fork](https://github.com/yury-lysogorskiy/lammps/tree/grace-runtime) supplies pair styles
+`grace/runtime` (CPU) and `grace/runtime/kk` (GPU), which take the GRACE-1L / 2L / 3L model from the `kokkos.npz` given to
+`pair_coeff`, and `pace/runtime(/kk)` for PACE models. Installing the Python package does not install LAMMPS:
+[build and run it](https://github.com/ICAMS/grace-runtime/blob/master/docs/lammps.md).
+
+## Licence
+
+Academic Software Licence (ASL, [LICENSE.md](https://github.com/ICAMS/grace-runtime/blob/master/LICENSE.md)): academic non-commercial use. For commercial use contact
+ACEworks GmbH, contact@aceworks.works. Bundled third-party code keeps its own licence
+([THIRD_PARTY_NOTICES.md](https://github.com/ICAMS/grace-runtime/blob/master/THIRD_PARTY_NOTICES.md)). Changes: [CHANGELOG.md](https://github.com/ICAMS/grace-runtime/blob/master/CHANGELOG.md).
+
+## Reference
+
+Please cite:
+
+* Y. Lysogorskiy, A. Bochkarev, R. Drautz, Graph atomic cluster expansion for foundational machine learning interatomic
+  potentials. npj Computational Materials 12(1), 114 (2026), https://www.nature.com/articles/s41524-026-01979-1
+* For UQ (extrapolation grade `gamma`): Y. Lysogorskiy, A. Bochkarev, R. Drautz, A latent-space extrapolation grade
+  built into graph atomic cluster expansion foundation potentials. arXiv:2609.40060 (2026),
+  https://arxiv.org/abs/2609.40060
+* A. Bochkarev, Y. Lysogorskiy, R. Drautz, Graph Atomic Cluster Expansion for Semilocal Interactions beyond Equivariant
+  Message Passing. Phys. Rev. X 14, 021036 (2024), https://doi.org/10.1103/PhysRevX.14.021036
+
+```bibtex
+@article{lysogorskiy2026graph,
+  title={Graph atomic cluster expansion for foundational machine learning interatomic potentials},
+  author={Lysogorskiy, Yury and Bochkarev, Anton and Drautz, Ralf},
+  journal={npj Computational Materials}, volume={12}, number={1}, pages={114}, year={2026},
+  doi={10.1038/s41524-026-01979-1}
+}
+@article{lysogorskiy2026calm,
+  title={A latent-space extrapolation grade built into graph atomic cluster expansion foundation potentials},
+  author={Lysogorskiy, Yury and Bochkarev, Anton and Drautz, Ralf},
+  journal={arXiv preprint arXiv:2609.40060}, year={2026}
+}
+@article{PhysRevX.14.021036,
+  title={Graph Atomic Cluster Expansion for Semilocal Interactions beyond Equivariant Message Passing},
+  author={Bochkarev, Anton and Lysogorskiy, Yury and Drautz, Ralf},
+  journal={Phys. Rev. X}, volume={14}, pages={021036}, year={2024}, doi={10.1103/PhysRevX.14.021036}
+}
+```

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/README.md

@@ -3,14 +3,19 @@
 Fast, efficient execution of GRACE-1L, GRACE-2L and GRACE-3L interatomic potentials without TensorFlow, PyTorch or JAX.
 CPU execution is standalone; GPU execution uses Kokkos for NVIDIA CUDA and AMD HIP.
 Use ASE-compatible calculators, batch processing, an optional TorchSim adapter or the shared kernels in LAMMPS with MPI.
-PACE (ACE) potentials fitted with pacemaker run from their `.yaml` ([PACE models](docs/pace.md)).
+PACE (ACE) potentials fitted with pacemaker run from their `.yaml` ([PACE models](https://github.com/ICAMS/grace-runtime/blob/master/docs/pace.md)).
 
-**[Read the manual](docs/index.md)** · [Installation](docs/installation.md) · [API reference](docs/api.md)
+One call computes energy, forces and stress. On one NVIDIA H200 that takes about 1 µs per atom for GRACE-1L,
+3.5 µs for GRACE-2L and 13 µs for GRACE-3L (large OMAT models); a 16-core Xeon is 5 to 13 times slower.
+[Benchmarks](https://github.com/ICAMS/grace-runtime/blob/master/docs/benchmarks.md) gives the setup and the largest system per GPU.
+
+![Time per atom for GRACE-1L, 2L and 3L on NVIDIA H200, AMD MI250X, NVIDIA L40S and a 16-core Xeon](https://raw.githubusercontent.com/ICAMS/grace-runtime/master/docs/images/benchmarks-time.png)
+
+**[Read the manual](https://github.com/ICAMS/grace-runtime/blob/master/docs/index.md)** · [Installation](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md) · [API reference](https://github.com/ICAMS/grace-runtime/blob/master/docs/api.md)
 
 ## Install
 
-**Runtime packages are not yet released on PyPI; current packages are placeholders.**
-For now, [install from source](docs/installation.md#cpu-from-source). Once published, choose one package:
+Install one package from PyPI ([source builds](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md#cpu-from-source) for other targets):
 
 | Backend | Install |
 | --- | --- |
@@ -19,7 +24,7 @@ For now, [install from source](docs/installation.md#cpu-from-source). Once publi
 | AMD | `pip install grace-runtime-rocm6` |
 
 GPU packages install the matching CPU package automatically.
-See the manual for [GPU requirements](docs/backends.md) and [environment setup](docs/installation.md#python-environment).
+See the manual for [GPU requirements](https://github.com/ICAMS/grace-runtime/blob/master/docs/backends.md) and [environment setup](https://github.com/ICAMS/grace-runtime/blob/master/docs/installation.md#python-environment).
 
 ## First calculation
 
@@ -39,22 +44,22 @@ Named models download on first use; local `kokkos.npz` files work too.
 
 ## Guides
 
-The [manual](docs/index.md#guides) covers [batching and MD](docs/usage.md), [relaxation](docs/relax.md),
-[properties](docs/properties.md), [dispersion](docs/dispersion.md), [PACE models](docs/pace.md), [TorchSim](docs/torchsim.md) and
-[development](docs/development.md). An interactive tour is in the [ASE notebook](python/examples/ase/grace_runtime_ase.ipynb).
+The [manual](https://github.com/ICAMS/grace-runtime/blob/master/docs/index.md#guides) covers [batching and MD](https://github.com/ICAMS/grace-runtime/blob/master/docs/usage.md), [relaxation](https://github.com/ICAMS/grace-runtime/blob/master/docs/relax.md),
+[properties](https://github.com/ICAMS/grace-runtime/blob/master/docs/properties.md), [dispersion](https://github.com/ICAMS/grace-runtime/blob/master/docs/dispersion.md), [PACE models](https://github.com/ICAMS/grace-runtime/blob/master/docs/pace.md), [TorchSim](https://github.com/ICAMS/grace-runtime/blob/master/docs/torchsim.md) and
+[development](https://github.com/ICAMS/grace-runtime/blob/master/docs/development.md). An interactive tour is in the [ASE notebook](https://github.com/ICAMS/grace-runtime/blob/master/python/examples/ase/grace_runtime_ase.ipynb).
 
 ## LAMMPS
 
 The [LAMMPS fork](https://github.com/yury-lysogorskiy/lammps/tree/grace-runtime) supplies pair styles
 `grace/runtime` (CPU) and `grace/runtime/kk` (GPU), which take the GRACE-1L / 2L / 3L model from the `kokkos.npz` given to
-`pair_coeff`, and `pace/runtime(/kk)` for PACE models. Follow that repository's build instructions; installing the
-Python package does not install LAMMPS.
+`pair_coeff`, and `pace/runtime(/kk)` for PACE models. Installing the Python package does not install LAMMPS:
+[build and run it](https://github.com/ICAMS/grace-runtime/blob/master/docs/lammps.md).
 
 ## Licence
 
-Academic Software Licence (ASL, [LICENSE.md](LICENSE.md)): academic non-commercial use. For commercial use contact
+Academic Software Licence (ASL, [LICENSE.md](https://github.com/ICAMS/grace-runtime/blob/master/LICENSE.md)): academic non-commercial use. For commercial use contact
 ACEworks GmbH, contact@aceworks.works. Bundled third-party code keeps its own licence
-([THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). Changes: [CHANGELOG.md](CHANGELOG.md).
+([THIRD_PARTY_NOTICES.md](https://github.com/ICAMS/grace-runtime/blob/master/THIRD_PARTY_NOTICES.md)). Changes: [CHANGELOG.md](https://github.com/ICAMS/grace-runtime/blob/master/CHANGELOG.md).
 
 ## Reference
 

grace_runtime-0.1.2/docs/benchmarks.md

@@ -0,0 +1,20 @@
+# Benchmarks
+
+How fast grace-runtime evaluates the GRACE foundation models, and how many atoms fit on one GPU.
+
+![Time per atom for GRACE-1L, 2L and 3L on NVIDIA H200, AMD MI250X, NVIDIA L40S and a 16-core Xeon](images/benchmarks-time.png)
+
+![Largest system on one GPU for GRACE-1L, 2L and 3L on NVIDIA H200, AMD MI250X and NVIDIA L40S](images/benchmarks-atoms.png)
+
+## How we measured
+
+| | |
+|---|---|
+| Models | GRACE-1L-OMAT-large-base, GRACE-2L-OMAT-large-base, GRACE-3L-OMAT-large (cutoff 6 Å) |
+| System | bcc crystal (a = 3.165 Å) with 25 elements (Al to Os) in random order, atoms displaced by about 0.02 Å; about 58 neighbours per atom |
+| Calculation | `GRACERuntimeCalculator` with default settings; each call computes energy, forces and stress |
+| Time per atom | median of 3 calls after the first; the lowest value over system sizes from about 1000 atoms up. It changes little above about 16000 atoms (GPU) or 2000 atoms (CPU). H200: lowest of 31,250 and 128,000 atoms |
+| Largest system | double the number of atoms until a structure does not fit the GPU memory, then bisect; the largest structure that runs, each size in a new process |
+| GPUs | NVIDIA H200 NVL 141 GB, NVIDIA L40S 48 GB, AMD Instinct MI250X: one GCD (half of the card) with 64 GB |
+| CPU | Intel Xeon Gold 6526Y (16 cores per socket); 16 threads on one socket (`OMP_NUM_THREADS`) |
+| Software | grace-runtime 0.1 wheels from PyPI (`grace-runtime`, `grace-runtime-cuda12`, `grace-runtime-rocm6`) |

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/docs/index.md

@@ -4,6 +4,12 @@ Run GRACE-1L, GRACE-2L and GRACE-3L interatomic potentials on CPU or GPU without
 CPU execution is standalone; GPU execution uses Kokkos for NVIDIA CUDA and AMD HIP.
 The kernels also run in LAMMPS, with MPI support.
 
+One call computes energy, forces and stress. On one NVIDIA H200 that takes about 1 µs per atom for GRACE-1L,
+3.5 µs for GRACE-2L and 13 µs for GRACE-3L (large OMAT models); a 16-core Xeon is 5 to 13 times slower.
+[Benchmarks](benchmarks.md) gives the setup and the largest system per GPU.
+
+![Time per atom for GRACE-1L, 2L and 3L on NVIDIA H200, AMD MI250X, NVIDIA L40S and a 16-core Xeon](images/benchmarks-time.png)
+
 Start with [installation](installation.md), then try a calculation below.
 The optional TorchSim adapter requires PyTorch and TorchSim.
 
@@ -48,7 +54,9 @@ print([r["energy"] for r in results])
 | Add DFT-D3 | [Dispersion](dispersion.md) |
 | Run PACE (ACE) models from pacemaker `.yaml` | [PACE models](pace.md) |
 | Use TorchSim integrators and optimizers | [TorchSim](torchsim.md) |
+| Build LAMMPS and run GRACE or PACE in it | [LAMMPS](lammps.md) |
 | Manage memory, threads and fallbacks | [Performance and diagnostics](advanced.md) |
+| See speed and the largest systems per GPU | [Benchmarks](benchmarks.md) |
 | Look up parameters, defaults, CLI and results | [API reference](api.md) |
 | Build and test | [Development](development.md) |
 
@@ -56,5 +64,5 @@ print([r["energy"] for r in results])
 
 The [LAMMPS fork](https://github.com/yury-lysogorskiy/lammps/tree/grace-runtime) supplies pair styles
 `grace/runtime` (CPU) and `grace/runtime/kk` (GPU) for GRACE-1L / 2L / 3L models (`kokkos.npz`), and
-`pace/runtime` / `pace/runtime/kk` for [PACE models](pace.md). Follow that repository's build instructions;
-installing the Python package does not install LAMMPS.
+`pace/runtime` / `pace/runtime/kk` for [PACE models](pace.md). Installing the Python package does not install
+LAMMPS: [LAMMPS](lammps.md) shows how to build it (CPU, CUDA, HIP) and run a first input.

{grace_runtime-0.1.0 → grace_runtime-0.1.2}/docs/installation.md

@@ -2,9 +2,6 @@
 
 [Manual](index.md) · [GPU requirements](backends.md)
 
-**Runtime packages are not yet released on PyPI; current packages are placeholders.**
-The package commands below apply once published. For now, use [source installation](#cpu-from-source).
-
 ## Python environment
 
 We recommend [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html)
@@ -19,7 +16,7 @@ micromamba activate grace-runtime
 
 | Backend | Install | Wheel requirements |
 | --- | --- | --- |
-| CPU | `pip install grace-runtime` | Linux x86-64 (AVX2/FMA); macOS arm64 (Apple M1 and newer) |
+| CPU | `pip install grace-runtime` | Linux x86-64 (AVX2/FMA), also [WSL2 on Windows](#windows); macOS arm64 (Apple M1 and newer) |
 | NVIDIA CUDA 12 | `pip install "grace-runtime-cuda12[cublas]"` | Linux x86-64, compatible NVIDIA driver |
 | AMD ROCm 6 | `pip install grace-runtime-rocm6` | Linux x86-64, system ROCm 6.2+ |
 
@@ -40,11 +37,26 @@ grace-runtime info
 Then run the [first calculation](index.md#first-calculation). If a visible GPU cannot run natively,
 `grace-runtime info` returns 1; see [backend diagnostics](advanced.md#backend-diagnostics).
 
+## Windows
+
+Native Windows is not supported yet. Use [WSL2](https://learn.microsoft.com/windows/wsl/install) (Windows 10 or 11)
+with an Ubuntu distribution, and install the Linux packages inside it:
+
+```bash
+pip install grace-runtime                    # CPU
+pip install "grace-runtime-cuda12[cublas]"   # NVIDIA GPU
+grace-runtime info
+```
+
+NVIDIA GPUs work through the Windows NVIDIA driver ([CUDA on WSL](https://docs.nvidia.com/cuda/wsl-user-guide/)):
+install the driver on Windows only, not inside WSL. `grace-runtime info` shows whether the GPU is visible.
+
 ## Build from source
 
 ### CPU from source
 
-If needed, install a compiler with C++17 and OpenMP support:
+If needed, install a compiler with C++17 and OpenMP support. Use GCC 12 or newer: older GCC builds much slower CPU
+kernels (with GCC 11 GRACE-3L about 37 % slower, with GCC 9 up to 6.6x slower).
 
 ```bash
 micromamba install -c conda-forge cxx-compiler
@@ -67,8 +79,13 @@ micromamba install -c conda-forge llvm-openmp
 ```
 
 The macOS wheel ships its OpenMP runtime and shares it with conda-forge packages in the same process (NumPy, PyTorch).
-PyTorch from PyPI ships its own, and the two abort with `OMP: Error #15`: for TorchSim on macOS, use conda-forge
-PyTorch, which shares the environment's OpenMP runtime.
+PyTorch from PyPI ships its own, and the two abort with `OMP: Error #15`. So on macOS the `torchsim` extra installs
+nothing; install PyTorch from conda-forge, which shares the environment's OpenMP runtime, and then TorchSim:
+
+```bash
+micromamba install -c conda-forge pytorch
+pip install grace-runtime torch-sim-atomistic
+```
 
 ### GPU source builds
 
@@ -81,7 +98,7 @@ For editable installs and library tests, see [development](development.md).
 | Feature | Install |
 | --- | --- |
 | Phonons | `pip install "grace-runtime[phonons]"` |
-| TorchSim adapter (Python >= 3.12; on a CUDA 12 driver torch from the CUDA 12 index, see [TorchSim](torchsim.md)) | `pip install "grace-runtime[torchsim]"` |
+| TorchSim adapter (Python >= 3.12; on a CUDA 12 driver torch from the CUDA 12 index, see [TorchSim](torchsim.md); on macOS see [macOS](#macos)) | `pip install "grace-runtime[torchsim]"` |
 | Tests | `pip install "grace-runtime[test]"` |
 | cuBLAS for the NVIDIA package (GRACE-3L up to ~15 % faster, UQ slightly faster) | `pip install "grace-runtime-cuda12[cublas]"` |