.. _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.
Then, EON client's ``Rules.mk`` must be slightly modified. 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``.
In this section, ``CXXFLAGS`` and ``LDFLAGS`` must be customized according to the
installation of the dependencies.
**Before starting**: it may be possible that no customization is necessary because
the relevant directories are already visible to the compiler.
In the sections below, try to comment out the ``CXXFLAGS`` and ``LDFLAGS``
lines first and then run::
make ASE_POT=1
Only when the compilation is unsuccessful, follow the instructions in the next 2
sections.
``CXXFLAGS``
============
There are 2 directories 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``. 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!**
Compilation
============
Once the above is completed, build EON client with the ASE interface enabled::
$ make ASE_POT=1
If the compilation is successful, you should see a line containing ``+ASE`` at the very bottom
of the terminal.
Using the ASE interface
=======================
When using EON's ASE interface, the Python dynamic library must still be visible to the ``eonclient``
executable. This can be done by adding the directory from ``LDFLAGS`` above to the ``LD_LIBRARY_PATH``
environmental variable::
$ export LD_LIBRARY_PATH=/path/to/python/rootdir/lib:$LD_LIBRARY_PATH
To avoid repeating this step, this line can be included in ``~/.bash_profile`` or ``~/.bashrc``
so that it is automatically prepended when logged on.
*It is recommended that the Python version used to run EON client is the same as the
Python version used to build EON client.*
To use ASE calculators, ``config.ini`` should contain::
[Potential]
potential = ase
ext_pot_path = /full/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, **it is highly
recommended to write the full absolute path to the script**.
Python script contents
======================
EON client imports this Python script to get the energy and forces.
The script should look like this (e.g. using ASE's Lennard Jones calculator)::
from ase import Atoms
from ase.calculators.lj import LennardJones
def ase_calc():
# MODIFY THIS SECTION
calc = LennardJones(epsilon=0.0103, sigma=3.40, rc=10.0, ro=0.0, smooth=True)
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.