External Potential¶
conda-forge availability
Included in the conda-forge package. Always compiled in; no build flags required.
The external potential (ext_pot) interface allows eOn to use any energy and
force calculator by communicating through files and a system call. Because it
requires no compile-time dependencies, ext_pot is always available in every eOn
build, including the conda-forge package.
Tip
If you installed eOn from conda-forge and want to use an MLIP (DeePMD, MACE,
etc.) that is not available through the Metatomic
interface, ext_pot or LAMMPS is the recommended path.
The ASE potentials require additional compile-time flags
that are not enabled in the conda-forge build.
Start with a complete working example¶
This example needs Python and the eOn client only. It evaluates a harmonic potential, so it needs no electronic-structure executable, model download or pseudopotentials. The commands below target Linux, including Ubuntu under WSL. Run calculations inside your site’s compute allocation, not on its login node.
Install Pixi, then create a separate workspace:
curl -fsSL https://pixi.sh/install.sh | sh
export PATH="$HOME/.pixi/bin:$PATH"
mkdir eon-external-demo
cd eon-external-demo
pixi init --channel conda-forge
pixi add eon python
pixi run eonclient --version
pixi add installs the client and Python and records their resolved packages
in pixi.lock. Keep pixi.toml and pixi.lock together; a recipient can
recreate the environment with pixi install --locked. No compiler or MPI
installation is needed for this file-interface example.
Save the following executable as harmonic_extpot.py:
#!/usr/bin/env python3
"""Harmonic energy in eV and its negative derivative in eV/Angstrom."""
import math
from pathlib import Path
rows = [line.split() for line in
Path("from_eon_to_extpot").read_text().splitlines() if line.strip()]
if len(rows) < 4 or any(len(row) != 3 for row in rows[:3]):
raise ValueError("Expected three box rows followed by at least one atom")
positions = []
for row in rows[3:]:
if len(row) != 4:
raise ValueError("Expected atomic_number x y z")
int(row[0])
xyz = [float(value) for value in row[1:]]
if not all(math.isfinite(value) for value in xyz):
raise ValueError("Non-finite coordinate")
positions.append(xyz)
k = 1.0 # eV/Angstrom squared
energy = 0.5 * k * sum(x*x for xyz in positions for x in xyz)
forces = [[-k*x for x in xyz] for xyz in positions]
with Path("from_extpot_to_eon").open("w") as output:
output.write(f"{energy:.15g}\n")
for force in forces:
output.write(" ".join(f"{value:.15g}" for value in force) + "\n")
Create pos.con, with one silicon atom at (1, 0, 0) Angstrom in a 20 Angstrom
cube. The two blank lines between the cell angles and component count are
part of this structure format:
One atom harmonic example
0.0
20.0 20.0 20.0
90.0 90.0 90.0
1
1
28.0855
Si
Coordinates of Component 1
1.0 0.0 0.0 0 0
Make the wrapper executable, create the configuration and evaluate the point:
chmod +x harmonic_extpot.py
cat > config.ini <<EOF
[Main]
job = point
[Potential]
potential = ext_pot
ext_pot_path = $PWD/harmonic_extpot.py
EOF
pixi run eonclient > eon.log 2>&1
cat results.dat
The potential_energy result is 0.5 eV. The wrapper returns one force,
(-1, 0, 0) eV/Angstrom. This potential is a protocol demonstration:
its origin is fixed and it does not model periodic interatomic interactions.
The exact result-file formatting depends on the installed eOn release.
For example, the point check prints these result entries:
GOOD termination_reason_text
EXT_POT potential_type
1 total_force_calls
5.000000000000e-01 potential_energy
1.000000000000e+00 Max_Force
To check the wrapper independently, run it from a separate directory
containing this from_eon_to_extpot file:
20 0 0
0 20 0
0 0 20
14 1 0 0
Its from_extpot_to_eon must contain:
0.5
-1 -0 -0
Signed zero is equivalent to zero. A successful wrapper-only check tests the file protocol; the client run also tests the structure, configuration and executable lookup.
Protocol¶
When the client needs an energy/force evaluation it:
Creates a private exchange directory named
extpot_<pid>_<n>inside the directory eOn runs in, where<pid>is the client’s process id and<n>counts the potentials it built.Writes the file
from_eon_to_extpotin that directory.Calls the executable (or script) specified by
ext_pot_pathviasystem(), with the exchange directory as the command’s working directory.Reads the file
from_extpot_to_eonthat the script must create there.
The two filenames do not change, so a wrapper that opens them by relative name, as every example below does, needs no edit. The exchange directory is what keeps two clients started in one directory from reading each other’s numbers. The directory lives as long as the potential: each call reuses it, so a wrapper can keep state there between calls (the CPMD wrapper below keeps its wavefunction). When the potential is destroyed the client removes the two exchange files and then the directory, if nothing else is left in it. A failed call leaves everything in place for inspection.
One directory per image¶
[Main] parallel defaults to true. A dimer, and the two product
minimizations in a process search, then build a second potential when the
potential asks for one instance per image. ext_pot does. Each instance
takes the next extpot_<pid>_<n>, so the two calls do not share
from_eon_to_extpot. An error on the second thread is stored, the first
thread is joined, and the stored error is raised. parallel = false runs
both images on the one instance, one after the other.
Important
ext_pot_path is resolved against the directory eOn runs in when it names an
existing file, so ./ext_pot and an absolute path both work. A command line
with arguments (python wrapper.py) or a name looked up on PATH is passed
to the shell unchanged and therefore has to be written so it resolves from
the exchange directory: give the script an absolute path. On Windows,
cmd.exe does not honor a shebang: a resolved script whose first line names
python, or whose name ends in .py, is invoked as python <script>. A
wrapper that needs to reach files in the directory eOn runs in finds that
directory in the environment variable EON_EXTPOT_RUN_DIR.
Input file (from_eon_to_extpot)¶
Positions and box vectors are in Angstrom. The first three lines are the
3x3 box matrix (one lattice vector per row, tab-separated).
Each subsequent line contains one atom: atomic_number x y z
(tab-separated, double precision).
box_00 box_01 box_02
box_10 box_11 box_12
box_20 box_21 box_22
6 1.234 5.678 9.012
6 ...
Output file (from_extpot_to_eon)¶
The first line is the total energy in eV (scalar).
Each subsequent line contains the force on one atom in eV/Angstrom: fx fy fz
(space-separated). The atom order must match the input.
-42.12345
0.123 -0.456 0.789
...
Configuration¶
[Potential]
potential = ext_pot
ext_pot_path = /full/path/to/your_wrapper
Important
When running compound jobs (aKMC, process search, etc.) eOn copies
configuration into per-job scratch directories. Use absolute paths for
ext_pot_path and for any model files referenced inside your wrapper.
Examples¶
Use an existing HPC CPMD installation¶
Keep the eOn client in its Pixi environment and use the site’s existing CPMD executable for the expensive force evaluations. You need all of:
The absolute path to a working
cpmd.x(or site-named CPMD executable).Its compatible MPI runtime and the modules used to run it.
The licensed pseudopotentials for every element in
pos.con, with the correct functional and angular-momentum choices.A periodic
pos.con, the wrapper script andconfig.ini.
For example, clone the public eOn sources using Pixi’s Git. This supplies the CPMD wrapper and a small silicon-vacancy structure; it does not build or install another eOn client:
pixi add git
pixi run git clone --branch develop https://github.com/TheochemUI/eOn.git eon-source
pixi run git -C eon-source rev-parse HEAD
cp eon-source/examples/akmc-cpmd-slurm/potfiles/cpmd_extpot.py ./cpmd_extpot.py
cp eon-source/examples/akmc-cpmd-slurm/pos.con ./pos.con
chmod +x cpmd_extpot.py
Record the printed source commit alongside the Pixi lockfile. The silicon example contains seven atoms and requires a silicon pseudopotential; it is separate from the harmonic demonstration.
An executable built with Intel MPI must use its matching Intel MPI launcher.
Do not send it through Open MPI installed for another calculator. A launcher
script can restore the site’s compiler/MPI modules in the CPMD child process
without replacing the eOn environment. Save this as launch-cpmd-mpi.sh and
replace the module initialization and module names with those from the
working CPMD batch script:
#!/usr/bin/env bash
set -euo pipefail
source /etc/profile.d/modules.sh
module purge
unset LD_LIBRARY_PATH LD_PRELOAD LIBRARY_PATH CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
module load intel/oneAPI-2022 intelmpi/oneAPI-2022
exec mpirun "$@"
The module initialization path is site-specific. Add further modules only
when that CPMD binary needs them. Verify this launcher on the allocated node;
the mpirun it selects must belong to the MPI used to link CPMD.
The library-path cleanup belongs in this child launcher before loading its
modules; applying it to the parent process can break the eOn installation.
From the workspace root, set the actual executable and pseudopotential locations. These are examples of account-relative paths, not files supplied by Pixi:
chmod +x launch-cpmd-mpi.sh
export CPMD_BIN="$HOME/myCPMD/bin/cpmd4.3-oneAPI-2022-AMD.x"
export PP_LIBRARY_PATH="$HOME/pseudo/"
export CPMD_LAUNCH="$PWD/launch-cpmd-mpi.sh -np 4"
export CPMD_PP="14:Si_MT_BLYP.psp:LMAX=D LOC=D"
export CPMD_CUTOFF=70
export CPMD_FUNCTIONAL=BLYP
export CPMD_CONVERGENCE=1e-6
export OMP_NUM_THREADS=1
test -x "$CPMD_BIN"
test -f "${PP_LIBRARY_PATH}Si_MT_BLYP.psp"
cat > config.ini <<EOF
[Main]
job = point
[Potential]
potential = ext_pot
ext_pot_path = $PWD/cpmd_extpot.py
EOF
pixi run eonclient > eon-cpmd.log 2>&1
cat results.dat
Run this command inside a compute allocation with four MPI tasks available
for CPMD. The eOn client is one process; its wrapper launches those four
CPMD processes. For Slurm, request a node with --ntasks=4 and enter the
node using the site’s supported interactive-job procedure. A site that
requires srun instead of mpirun needs a launcher adapted to its MPI/PMI
configuration. Do not start four copies of eonclient for this file route.
For the Intel oneAPI 2022 setup, the source tree also supplies a complete
Slurm job at examples/akmc-cpmd-slurm/run_point.sbatch. From the workspace
root, copy it and edit its #SBATCH partition/account and the child
launcher’s module names to match the site. Submit through the Pixi
environment so the installed client and Python are inherited by the job:
cp eon-source/examples/akmc-cpmd-slurm/run_point.sbatch ./run_point.sbatch
# Edit the scheduler directives and site module names in run_point.sbatch.
export EON_REPO="$PWD/eon-source"
pixi run sbatch ./run_point.sbatch "$PWD/pos.con"
Keep CPMD_BIN, PP_LIBRARY_PATH and the method variables exported as
above. The script’s own defaults are the public Si7 vacancy demonstration
at 20 Ry with LMAX=P; an exported override changes those defaults.
Slurm prints Submitted batch job <jobid>. The calculation’s record is
eon-cpmd-point-<jobid>/, including the copied geometry, configuration,
wrapper and eon.log. The scheduler output prints the converted finite
energy when the point calculation succeeds. The script leaves that
directory in the submission filesystem for inspection.
The result contains a finite potential_energy. Its numerical value depends
on the supplied pseudopotential, cutoff, geometry and convergence settings;
the relaxed structure’s recorded example energy is not a universal check
at another cutoff. Inspect the exchange directory’s cpmd.out, input,
GEOMETRY and RESTART.1 if the call fails. Keep these with the result when
reporting an error.
The supplied wrapper builds a neutral, single-point BLYP deck by default. Its environment controls listed below do not provide a complete method description for a charged, spin-polarized, dispersion-corrected or constrained system. Such a calculation requires a wrapper/deck that explicitly retains those physical settings. A dynamics or restart deck cannot be substituted without checking its task, charge, cell, functional, dispersion, species, occupations and SCF convergence. The in-process RGPOT route uses a separate serialized CPMD method message; it does not read this wrapper’s environment as that message.
Units and force sign¶
The external interface expects the total energy in eV, positions and box vectors in Angstrom, and forces in eV/Angstrom. For CPMD:
energy_eV = energy_Hartree * 27.211386245988
force_eV_per_A = force_Hartree_per_Bohr * 51.4220674763
force = -gradient
The last line applies when the source quantity is an energy gradient.
CPMD’s GEOMETRY columns 4–6 already contain the ionic force fion:
convert the units without negating them. Returning a positive gradient as
a force drives minimization uphill. The header GRADIENTS (-FORCES) in
the printed CPMD table does not change what fion contains.
CPMD on several MPI ranks¶
examples/akmc-cpmd-slurm/potfiles/cpmd_extpot.py answers each call with a
cpmd.x wavefunction optimisation on the MPI ranks that CPMD_LAUNCH
starts. It reads its
settings from the environment:
Variable |
Meaning |
Default |
|---|---|---|
|
path to |
required |
|
MPI launcher put in front of |
|
|
pseudopotential directory, passed to |
required |
|
|
required |
|
plane-wave cutoff in Ry |
|
|
|
|
|
|
|
|
|
|
|
shared directory of converged |
unset |
|
path to the |
unset, no check |
A single point, a minimization or a nudged elastic band on one machine
needs nothing else than the script as ext_pot_path:
export CPMD_BIN=/path/to/cpmd.x PP_LIBRARY_PATH=/path/to/pseudopotentials/
export CPMD_LAUNCH="mpirun -np 4 --bind-to none" CPMD_CUTOFF=70
export CPMD_PP="14:Si_MT_BLYP.psp:LMAX=D,7:N_MT_BLYP.psp:LMAX=P"
cat > config.ini <<'EOF'
[Main]
job = point
[Potential]
potential = ext_pot
ext_pot_path = /absolute/path/to/eOn/examples/akmc-cpmd-slurm/potfiles/cpmd_extpot.py
EOF
eonclient
Inside a Slurm job, ask for as many tasks as CPMD_LAUNCH starts ranks
(--ntasks=4), or OpenMPI finds one slot and refuses -np 4.
--bind-to none keeps it from refusing to bind when the allocation is
hardware threads rather than physical cores.
examples/akmc-cpmd-slurm runs adaptive kinetic Monte Carlo on a silicon
vacancy with the same script. The cluster communicator submits each
process search as a Slurm job (see Communicator),
and inside the job ext_pot calls cpmd_extpot.py. The client stays one
process; the ranks belong to CPMD alone.
What the script hands CPMD and reads back:
The deck says
ANGSTROM. CPMD then converts eOn’s positions with its own Bohr, 0.529177210859 A. CPMD answers in Hartree and Hartree/Bohr. The script converts with CODATA 2018 (27.211386245988 eV, 0.529177210903 A), as the in-process RGPOT route does. The two Bohr values differ by 8.3e-11 relative;client/validation/cpmd_units.pyderives the chain.The table under
GRADIENTS (-FORCES)holds forces, not gradients:wrgeoprints the ionic forcefion. The first table, printed before the wavefunction optimisation, is all zeros; the last one is the result.That table carries three significant digits.
GEOMETRYholds the same forces in Ha/Bohr to twelve decimals in columns 4 to 6, so the script reads forces fromGEOMETRYand checks them against the table.The energy is the last
TOTAL ENERGYofcpmd.out, which CPMD prints with eight decimals: the file route’s energy is good to 5e-9 Ha (1.4e-7 eV). The in-process route returns it to full precision.CPMD lists atoms species by species, in the order each element first appears. The script maps them back to eOn’s order.
eOn’s cell goes to
CELL VECTORSunchanged, one lattice vector per row. CPMD refusesSYMMETRYbeside it, so the deck omitsSYMMETRY. A system without a cell reaches the script as a zero box, which it refuses: CPMD needs a periodic cell.
The script refuses a result whose wavefunction optimisation printed
BUT NO CONVERGENCE, after one retry from an atomic guess with
PCG MINIMIZE. It keeps RESTART.1 in the exchange directory, so every call
after the first in a job restarts from the previous wavefunction.
Troubleshooting¶
Symptom |
Check |
|---|---|
Wrapper cannot be executed or exit status 126/127 |
Make it executable; check its shebang/interpreter under |
No |
Run the wrapper manually from its exchange directory and inspect the calculator log and exit status. Write the response only after the calculation succeeds. |
Too few force rows |
Return exactly one force triple per input atom, in the same order; restore species-grouped calculator output to the input order. |
|
Use the compiler/MPI runtime matching that executable inside the CPMD launcher, not the Pixi MPI for a different build. |
SCF does not converge |
Inspect |
Minimization moves uphill |
Check force units and sign; forces are the negative energy derivative. |
Several concurrent image calculations exhaust the allocation |
Count calculator ranks per concurrent image, rather than counting the single eOn process alone. |
An external wrapper must return a nonzero status for a failed calculation; it must not invent an energy or reuse a stale response. Return finite values and preserve diagnostics. A point job validates setup before a minimization, NEB or aKMC run makes many expensive calls.
Performance considerations¶
Each force call spawns a new process and re-initializes the calculator. For calculators with substantial initialization or model-loading costs, startup can dominate the force evaluation. Measure it for the actual calculator. In that scenario consider:
The built-in ASE interface (requires building from source with
-Dwith_python=True -Dwith_ase=True), which embeds the interpreter and avoids per-call process overhead.The Metatomic interface for models that support the metatensor format (compiled into the
conda-forgebuild).The serve mode to expose any eOn potential over RPC to external callers.