Installation

GRACE#

To use GRACE models, including fitting and utilizing pre-fitted models, you need to install the grace-tensorpotential package by following these steps.

Setting Up the Environment#

Micromamba (Recommended)#

For micromamba, install it by running the following command:

"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

Then, create a new environment:

micromamba create -n grace python=3.11 
micromamba activate grace

Installing TensorFlow and Tensorpotential#

Install tensorpotential from PyPI:

pip install tensorpotential

For the latest developer version, clone the grace-tensorpotential repository:

git clone https://github.com/ICAMS/grace-tensorpotential.git
cd grace-tensorpotential
pip install .

TensorFlow should be installed automatically. However, to manually install TensorFlow with GPU support:

pip install tensorflow[and-cuda]<2.20

TensorFlow & Keras Notes#

GPU Memory Leaks: If you experience a GPU memory leak with TensorFlow, first try updating your NVIDIA drivers. If the issue persists, you may need to downgrade your TensorFlow version:
```
pip install "tensorflow[and-cuda]==2.16.2" 
```
Keras Compatibility: This project requires the legacy Keras API that is bundled with TensorFlow. If you have a separate keras>=3.0.0 package installed, you must set the following environment variable to force TensorFlow to use its built-in version:
```
export TF_USE_LEGACY_KERAS=1
```
(Optional) Download foundation models (these will be stored in $HOME/.cache/grace):

grace_models download all

Learn more here.

GRACE/FS (CPU)#

This is a standalone C++ implementation of the GRACE/FS model that can be executed on a CPU without the TensorFlow library and parallelized using standard MPI.

Activate the conda environment:
```
conda activate grace
```

Clone the repository:

git clone -b feature/grace_fs https://github.com/ICAMS/python-ace.git

Install:
```
cd python-ace
pip install .
```

You may need to install cmake:

pip install cmake

Once installed, you can use the pace_activeset utility to generate the ASI for GRACE/FS models fitted with gracemaker.

LAMMPS with GRACE#

Activate the conda environment (it should contain TensorFlow):
```
conda activate grace
```

Clone the LAMMPS repository:

git clone -b grace --depth=1 https://github.com/yury-lysogorskiy/lammps.git

Prepare the compilation folder:
```
cd lammps
mkdir build
cd build
```

Configure with CMake:

cmake -DCMAKE_BUILD_TYPE=Release -D BUILD_MPI=ON -DPKG_ML-PACE=ON -DPKG_MC=ON ../cmake

Ensure that the line TensorFlow library is FOUND at ... appears after running the above command. You can manually specify the path to the TensorFlow library file (e.g., libtensorflow_cc.so, .dylib, or .dll) with -D TF_LIB_FILE=/path/to/library. This overrides automatic discovery and downloading.

Compile:
```
cmake --build . -- -j 8
```

NOTE: If you do NOT want TensorFlow support for LAMMPS but wish to use only exported grace/fs models, add the -DNO_GRACE_TF=ON flag:

cmake -DCMAKE_BUILD_TYPE=Release -D BUILD_MPI=ON -DPKG_ML-PACE=ON -DNO_GRACE_TF=ON ../cmake

KOKKOS build#

KOKKOS support is available for grace/fs, grace/1l/kk, and grace/2l/kk. The grace/1l/kk and grace/2l/kk pair styles read a .npz weights file produced by grace_utils export_kokkos (see utilities) and do not require TensorFlow at runtime.

Use following cmake configuration:

cmake ../cmake -DBUILD_MPI=ON -DCMAKE_BUILD_TYPE=Release -DPKG_MC=ON -DPKG_ML-PACE=ON -DPKG_KOKKOS=ON -DKokkos_ENABLE_CUDA=ON -DKokkos_ENABLE_OPENMP=ON -DKokkos_ARCH_NATIVE=ON

or -DKokkos_ARCH_HOPPER90=ON for H100/200 or -DKokkos_ARCH_AMPERE80=ON for A100.

Note, that for running LAMMPS with KOKKOS acceleration:

lmp_kk -k on g 1 -sf kk -pk kokkos newton on neigh half -in in.lammps