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 <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.

EON

Development

This page