.. _ase_interface:

=============
ASE Interface
=============

In order to build EON client with the ability to use ASE calculators as a potential,
one must have `Python3 <https://www.python.org/downloads/>`_ and
`pybind11 <https://pybind11.readthedocs.io/en/stable/index.html>`_ 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 <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_
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 <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_
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 <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_
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 <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.