ASE Interface

In order to build EON client with the ability to use ASE calculators as a potential, one must have Python3 and pybind11 installed and available in the compilation environment (if using Conda: activate your environment before compilation).

Compilation

Go into eon/client (where Rules.mk should exist), and build EON client with the ASE interface enabled:

$ make ASE_POT=1  # can optionally add -jN for parallel compilation with N threads

In some weird cases, this command needs to be run twice to complete the compilation.

If the compilation is successful, you should see a line containing +ASE at the very bottom of the terminal.

On the other hand, if there is a compilation error similar to “fatal error: Python.h: No such file or directory”, then EON client has failed to automatically detect the Python-related paths that are needed to compile the ASE interface. For automatic detection to work, the python3-config command must be available. Verify its availability by running:

$ which python3-config  # should print out the path to python3-config

Conda environments already come with this command by default. If using a systemwide Python, the Python development package should be installed by the system administrator using the appropriate package managers, like apt, yum, dnf, etc (the package name is python3-dev, python3-devel, or similar).

If automatic detection is not possible, refer to this section for information on how to manually add the paths for compilation.

After Compilation

For most installations, the binary eonclient can be copied to a directory in your $PATH. If you added $HOME/eon/bin to your path during the server installation the following command will install the client:

$ cp eonclient ../bin/eonclient

Otherwise you will need to give the path to the client binary in your config.ini.

Using the ASE interface

When using EON’s ASE interface, the Python dynamic library must still be visible to the eonclient executable:

$ export LD_LIBRARY_PATH="$(python3-config --prefix)/lib:$LD_LIBRARY_PATH"

It is recommended that the Python version used to run EON client is the same as the Python version used to build EON client.

If python3-config is not available, replace $(python3-config --prefix)/lib with /path/to/python/rootdir/lib from the LDFLAGS section.

To use ASE calculators, config.ini should contain:

[Potential]
potential = ase
ext_pot_path = /path/to/the/ase_script.py

The last line (ext_pot_path) is required, and it may be the relative or the absolute path to the Python script containing the desired ASE calculator (see next section).

When running EON (e.g. AKMC jobs), which calls eonclient in the back, you can either 1) provide the full absolute path to the Python script, or 2) create a directory called potfiles/, place the script inside that directory, and simply write ext_pot_path = ase_script.py. For example, your EON job directory might look like:

[user@cluster eon_ase_test]$ ls
config.ini  pos.con  potfiles/
[user@cluster eon_ase_test]$ ls potfiles/
ase_script.py
[usre@cluster eon_ase_test]$ grep "ext_pot_path" config.ini  # print the ext_pot_path line in config.ini
ext_pot_path = ase_script.py

Python script contents

EON client imports this Python script to get the energy and forces. The script should look like this (e.g. using fairchem’s UMA model):

from ase import Atoms
from fairchem.core import pretrained_mlip, FAIRChemCalculator
import torch  # just for setting number of threads


def ase_calc():
    # MODIFY THIS FUNCTION TO RETURN DESIRED ASE CALCULATOR

    # For GPU, omit setting num_threads
    torch.set_num_threads(32)  # limit to 0.5-1 socket for max efficiency (for CPU)
    print(f"PyTorch will use {num_threads} threads for computations.", flush=True)

    try:  # if potential file was downloaded to disk
        model_path = '/scratch/common/uma/uma-m-1p1.pt'
        calc = FAIRChemCalculator.from_model_checkpoint(
            model_path,
            device="cpu",  # use "cuda" for GPU
            task_name="omat",  # Or "omol", "oc20", etc., depending on the model
            seed=None,  # to suppress the deprecation error
        )
    except ValueError:  # if model_path wasn't found
        predictor = pretrained_mlip.get_predict_unit("uma-m-1p1", device="cpu",)
        calc = FAIRChemCalculator(predictor, task_name="omat")

    return calc

#=======================================================================
# DO NOT EDIT
def _calculate(R, atomicNrs, box, calc):
    system = Atoms(symbols=atomicNrs, positions=R, pbc=True, cell=box)
    system.calc = calc
    forces = system.get_forces()
    energy = system.get_potential_energy()
    return energy, forces
#=======================================================================


if __name__ == '__main__':
    # This is just to verify that the script runs properly with `python3 <this_script>`
    from ase.io import read
    atoms = read("...")  # structure file name
    pos = atoms.positions  # array of positions (n x 3)
    atomicNrs = atoms.get_atomic_numbers()  # array of atomic numbers (n)
    cell = atoms.cell  # cell array (3 x 3)
    calc = ase_calc()
    e, f = _calculate(pos, atomicNrs, cell, calc)
    print(f"E = {e}")
    print("F =")
    print(f)

The user should customize the content of the function ase_calc() to use the desired ASE calculator, but not that of ``_calculate()`` nor the function names.

Often, the ASE calculator may require an external potential file. When running EON (e.g. AKMC jobs) and an external file name is used in this script, it is highly recommended to write the full absolute path to the external file.

Before using it, make sure that this script contains no errors on the Python side.

Manually Adding Paths

If compilation was successful, there is no need to read this section.

If automatic path detection is not possible during compilation, EON client’s Rules.mk must be slightly modified by hand. With EON’s installed at $EON_DIR, open the file $EON_DIR/client/Rules.mk with a text editor and find the section that begins with ifdef ASE_POT.

Comment out the lines that begin with PYBIND11_INCLUDES and PYTHON_LDFLAGS. Modify the lines that begin with CXXFLAGS and LDFLAGS according to the subsections below.

CXXFLAGS

2 paths should be included here:

CXXFLAGS += -DASE_POT -I/path/to/python/rootdir/include -I/path/to/python/rootdir/include/python3.xx

The first is where the directory pybind11/ is located, which contains pybind11 header files. To be clear, the header file /path/to/python/rootdir/include/pybind11/pybind.h should exist, but write only -I/path/to/python/rootdir/include, not anything after (i.e. pybind11/pybind11.h).

It is usually located in the include/ directory of the Python installation. If using Python through a Conda environment, this directory is at $CONDA_PREFIX/include and/or $CONDA_PREFIX/lib/python3.xx/site-packages/pybind11/include. If using a systemwide Python, it may be /usr/include or something similar, depending on the type of OS and the distro. If pybind11 is a user pip installation for a systemwide Python, it may be located at $HOME/.local/lib/python3.xx/site-packages/pybind11/include.

The second is the directory where the header file Python.h is located. The directory python3.xx/ is typically in the same parent directory as pybind11.

If using Python through a Conda environment, this directory is at $CONDA_PREFIX/include/python3.xx. If using a systemwide Python, it may be /usr/include/python3.xx or something similar, depending on the type of OS and the distro.

MAKE SURE TO CHANGE THE xx IN python3.xx TO THE PYTHON VERSION YOU’RE USING!

LDFLAGS

The LDFLAGS line looks like this:

LDFLAGS += -L/path/to/python/rootdir/lib -lpython3.xx

The directory /path/to/python/rootdir/lib contains the Python dynamic library libpython3.xx.so. It is usually located in the lib/ directory of the Python installation, thus sharing the same parent directory as /path/to/python/rootdir/include from the CXXFLAGS line above.

If using Python through a Conda environment, this directory is at $CONDA_PREFIX/lib. If using a systemwide Python it may be /usr/lib, /usr/lib/x86_64-linux-gnu, /usr/lib64, or something similar depending on the OS.

The second part -lpython3.xx is referring to the dynamic library. Once again, MAKE SURE TO CHANGE THE xx IN python3.xx TO THE PYTHON VERSION YOU’RE USING!