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