From 7e94e7ac40b4bdd194b22ee6f5c1c3671ba81264 Mon Sep 17 00:00:00 2001 From: Yury Lysogorskiy Date: Sat, 31 Oct 2026 18:12:32 +0100 Subject: [PATCH] Keep public documentation concise and user focused --- .../releases.md => .github/RELEASING.md | 0 docs/pacemaker/install.md | 150 ++---------------- mkdocs.yml | 1 - 3 files changed, 12 insertions(+), 139 deletions(-) rename docs/pacemaker/releases.md => .github/RELEASING.md (100%) diff --git a/docs/pacemaker/releases.md b/.github/RELEASING.md similarity index 100% rename from docs/pacemaker/releases.md rename to .github/RELEASING.md diff --git a/docs/pacemaker/install.md b/docs/pacemaker/install.md index d4d31a7..8875d55 100644 --- a/docs/pacemaker/install.md +++ b/docs/pacemaker/install.md @@ -1,159 +1,33 @@ # Installation -`pacemaker` is installed by the `python-ace` package. TensorFlow fitting uses -`tensorpotential.compat.pace` from the current -[GRACE TensorPotential repository](https://github.com/ICAMS/grace-tensorpotential). -The old `ICAMS/TensorPotential` repository requires Python <3.11 and should not -be used for a new installation. - -## Create an environment - -Python 3.12 is a suitable starting point for a new environment: +Use Python 3.12 in a separate environment: ```bash mamba create -n ace python=3.12 pip mamba activate ace -python -m pip install --upgrade pip -``` - -`conda create` and `conda activate` can be used in place of the corresponding -`mamba` commands. Use the same environment to build and run both packages. -A C++ compiler is needed when building `python-ace` from source; its Python -build dependencies, including CMake and Ninja, are installed automatically. - -## Install the fitting backend - -Install the GRACE backend from PyPI. Its distribution name is -`tensorpotential`; `grace-tensorpotential` is the GitHub repository name. -The following released-package combination works around the PACE metrics -scalar-conversion bug in TensorPotential 0.6.2.1: - -```bash -python -m pip install 'tensorpotential==0.6.2.1' 'numpy>=2,<2.4' 'tensorflow~=2.20.0' 'tf-keras~=2.20.0' -``` - -Keep NumPy below 2.4 when using that backend release. The NumPy fix and -TensorFlow 2.21 support have been merged upstream but are not included in -PyPI's 0.6.2.1 release. See the development installation below to use them. - -On Linux the backend dependencies include `tensorflow[and-cuda]`. GPU execution -also requires a compatible NVIDIA driver. CPU fitting is available with -`CUDA_VISIBLE_DEVICES=-1`. TensorFlow 2.21 publishes wheels for Python -3.10–3.13; Python 3.14 is not covered by this installation recipe. - -## Install pacemaker - -Install the published pacemaker release candidate explicitly: - -```bash -python -m pip install 'python-ace==0.4.0rc1' ``` -The version is explicit because an unqualified `pip install python-ace` -selects the older stable 0.2.8 release. The modern package includes the maxvol -extension used by the active-learning tools; a separate `maxvolpy` -installation is unnecessary. - -### Development installation +You can use `conda` instead of `mamba`. -To use the merged TensorFlow 2.21 and NumPy fixes, install the backend from -GitHub and pacemaker from the default `master` branch: +## Install pacemaker and the GRACE backend ```bash -python -m pip install --upgrade 'tensorpotential @ git+https://github.com/ICAMS/grace-tensorpotential.git' 'tensorflow~=2.21.0' 'tf-keras~=2.21.0' -python -m pip install --upgrade 'python-ace @ git+https://github.com/ICAMS/python-ace.git' +python -m pip install --upgrade pip +python -m pip install 'python-ace==0.4.0rc1' 'tensorpotential==0.6.2.1' 'numpy>=2,<2.4' 'tensorflow~=2.20.0' 'tf-keras~=2.20.0' ``` -For a source checkout or to run the tests: +The GRACE backend is published on PyPI as `tensorpotential`. +Use the versions above together; this backend release requires NumPy below +2.4 for pacemaker fitting. -```bash -git clone https://github.com/ICAMS/python-ace.git -cd python-ace -python -m pip install . -``` - -Check the installed versions and command-line tools: +## Check the installation ```bash python -m pip check -python -c 'import pyace, tensorpotential, tensorflow as tf; print(pyace.__version__, tensorpotential.__version__, tf.__version__)' pacemaker --help -pace_info --help -``` - -To run the test suite from the `python-ace` checkout: - -```bash -python -m pip install pytest -CUDA_VISIBLE_DEVICES=-1 python -m pytest tests/ --runtensorpot -``` - -The test workflow is configured for Python 3.10–3.13 with TensorFlow 2.20 and -2.21 on Linux CPUs, plus Python 3.9 with TensorFlow 2.20. GPU execution needs -separate validation on the target hardware. - -### Tested development environment - -The source refresh was checked on 29 October 2026 with Python 3.12.15, -TensorFlow 2.21.0, tf-keras 2.21.0, NumPy 2.5.4, and pandas 2.3.3: - -| Execution target | Validation | -| --- | --- | -| Linux CPU | 294 tests and both Cu–I and Ethanol CLI workflows passed | -| NVIDIA H200 NVL, driver 595.58.03 | All 9 fitting tests passed; 185 fitting calls verified on GPU | -| NVIDIA A100 80 GB PCIe, driver 575.57.08 | All 9 fitting tests passed; 185 fitting calls verified on GPU | - -The GPU checks verify device placement of energies, forces, and coefficient -gradients as well as the fitting-test results. They cover short fits, rather -than long-running memory stability or performance. These results require the -source fixes described above and do not describe an unmodified TensorPotential -0.6.2.1 installation. - -## Troubleshooting - -### GPU validation - -To check fitting on a selected GPU from the source checkout: - -```bash -CUDA_VISIBLE_DEVICES=0 TF_FORCE_GPU_ALLOW_GROWTH=true python tools/validate_gpu.py ``` -This runs the TensorFlow fitting tests and checks that energies, forces, and -coefficient gradients reside on the GPU. It fails if no GPU is detected or if -those results fall back to the CPU. Select one GPU; pacemaker does not fit on -multiple GPUs in parallel. Memory growth keeps the test from reserving all -available device memory. - -If TensorFlow reports `Cannot dlopen some GPU libraries`, an existing system -CUDA installation may take precedence over the libraries installed by pip. -For the current shell, put the environment's CUDA library directories first: - -```bash -pace_cuda_libraries=$(python - <<'PY' -from pathlib import Path -import sysconfig -print(':'.join(str(path) for path in sorted( - (Path(sysconfig.get_paths()['purelib']) / 'nvidia').glob('*/lib') -))) -PY -) -export LD_LIBRARY_PATH="$pace_cuda_libraries${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" -``` - -Then rerun the GPU check. This changes the shell environment and leaves the -system CUDA installation untouched. - -### Python and dependency errors - -If fitting raises `TypeError: only 0-dimensional arrays can be converted to -Python scalars`, check that both `python-ace` and the backend include the -NumPy scalar-conversion fix, then rebuild the installed packages. - -For an import error or segmentation fault, check `which python` and rebuild -the extensions using the interpreter from the active environment. Avoid mixing -extensions built for different Python versions. +GPU fitting requires a compatible NVIDIA driver. To run on the CPU, set +`CUDA_VISIBLE_DEVICES=-1` before starting pacemaker. -For a protobuf descriptor error, check `python -m pip check` and reinstall a -consistent TensorFlow environment. The old TensorFlow 2.5/2.8 and protobuf -3.20 instructions do not describe the current dependency set. +Continue with the [quick start](quickstart.md) to prepare data and run a fit. diff --git a/mkdocs.yml b/mkdocs.yml index 90422ba..8a7eb78 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,7 +27,6 @@ extra_javascript: nav: - Home: index.md - Installation: pacemaker/install.md - - Building and publishing: pacemaker/releases.md - Quick start: pacemaker/quickstart.md - Pacemaker workflow: pacemaker/workflow.md - Extrapolation grade and active learning: pacemaker/active_learning.md