.. _ase_interface:
=============
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 :ref:`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 :ref:`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 `
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:
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:
``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!**