How to use eOn when I want to set potential = ext_pot

[wangsl613]

Hello,

I would like to use the external potential interface in eOn by setting potential = ext (or ext_pot) in my configuration file to link with a custom external calculator.

However, I am unsure about the correct workflow and necessary steps to run eOn in this mode. Specifically:

How should I prepare and structure the external potential program (e.g., the ext_pot executable or script)?

How should the filenames from_eon_to_ext and from_ext_to_eon be handled, and what exact data should be read/written?

Are there any example scripts or minimal working examples available for this interface?

Any recommended environment setup or important caveats to be aware of?

I tried to but eOn prints no any results.
I have reviewed the eOn documentation and examples, but would appreciate a detailed guide or suggestion to successfully integrate an external potential with eOn.

Thank you very much in advance for your help!

[HaoZeke]

Hi @wangsl613.

Thanks for reaching out.

Design

The core idea is a simple loop:

• eOn writes the current atomic structure to a file (from_eon_to_extpot).

• eOn executes your script specified by ext_pot_path.

• Your script reads the structure, performs a calculation, and writes the resulting energy and forces to a second file (from_extpot_to_eon).

• eOn reads this file and continues its work (e.g., minimization step, dynamics, etc.).

The idea is simple and robust enough to work for NEB methods as well.

External script

File format

from_eon_to_extpot is structured as follows:

• The first three lines are the box vectors, with x y and z components separated by spaces

xx yx zx
xy yy zy
xz yz zz

• The rest consist of atomic information, one per line

atomic_number x_pos y_pos z_pos

The from_extpot_to_eon script is defined by:

energy (single floating point number)
f_x f_y f_z
...

Basically:

• Line 1: A single floating-point number for the total potential energy.
• Line 2 onwards: One line per atom, containing the x, y, z components of the force vector.

Example

So this is what a nominal example will look like:

[Main]
job = point

[Potential]
potential = ext
ext_pot_path = ./external_potential.py

For this example I'll just demonstrate an ASE connection, but really anything will do.

#!/usr/bin/env python3

import numpy as np
from ase import Atoms

from ase.calculators.lj import LennardJones

# --- These cannot change, they're hardcoded in EON (for now) ---
INPUT_FILE = "from_eon_to_extpot"
OUTPUT_FILE = "from_extpot_to_eon"


def main():
    """
    Trivial main execution function.
    1. Reads atomic structure from the input file.
    2. Calculates energy and forces using an ASE calculator.
    3. Writes the results to the output file.
    """
    try:
        # --- Read the input file written by EON ---
        with open(INPUT_FILE, "r") as f:
            lines = f.readlines()

        # Parse the periodic box vectors (first 3 lines)
        box = np.array([list(map(float, line.split())) for line in lines[0:3]])

        # Parse the atomic numbers and positions
        atomic_numbers = []
        positions = []
        for line in lines[3:]:
            parts = line.split()
            atomic_numbers.append(int(parts[0]))
            positions.append([float(p) for p in parts[1:4]])

        # --- Build the system in ASE and run the calculation ---
        # Create the ASE Atoms object
        atoms = Atoms(numbers=atomic_numbers, positions=positions, cell=box, pbc=True)

        atoms.calc = LennardJones()

        # Get the potential energy and forces
        energy = atoms.get_potential_energy()
        forces = atoms.get_forces()

        # --- Write back for EON ---
        with open(OUTPUT_FILE, "w") as f:
            # Ordering matters here!!
            # Write total energy on the first line
            f.write(f"{energy}\n")

            # Write forces for each atom on subsequent lines
            for force_vector in forces:
                f.write(
                    f"{force_vector[0]:.15f} {force_vector[1]:.15f} {force_vector[2]:.15f}\n"
                )

    except Exception as e:
        with open("extpot_error.log", "w") as f_err:
            f_err.write(f"An error occurred in external_potential.py:\n{str(e)}\n")
        exit(1)


if __name__ == "__main__":
    main()

This can be used with a random system:

Generated by ASE
preBox_header_2
25.000000   25.000000   25.000000 
90.000000   90.000000   90.000000 
postBox_header_1
postBox_header_2
1
10
12.011
C
Coordinates of Component 1
  106.186272   105.438910   106.773837 0 0
  106.456366   104.599763   106.229101 0 1
  105.470481   104.918846   106.226977 0 2
  105.474695   105.955884   106.224370 0 3
  106.459658   106.280396   106.227013 0 4
  107.067777   105.441323   106.229104 0 5
  105.909487   104.599761   105.344227 0 6
  105.301468   105.438906   105.342188 0 7
  105.912823   106.280394   105.342211 0 8
  106.898766   105.961428   105.344250 0 9
  106.896149   104.923121   105.345870 0 10

To get:

eonclient
EON Client
VERSION: d4c16168
BUILD DATE: Thu Jul 31 12:05:22 AM GMT 2025

OS: linux
Arch: x86_64
Hostname: rgx1gen11
PID: 53006
DIR: /eon_extpot
Loading parameter file config.ini
* [Main] job: point
* [Potential] potential: ext
* [Potential] ext_pot_path: ./external_potential.py
Energy:         -16.856539034852
Max atom force: 27.553294641114
timing information:
real      0.262 seconds
user      0.226 seconds
sys       0.049 seconds

Similarly, the minimization and everything else will work too:

[Main]
job = point

[Potential]
potential = ext
ext_pot_path = ./external_potential.py

[Optimizer]
max_iterations = 200
opt_method = lbfgs
max_move = 0.05
converged_force = 0.01

[Debug]
write_movies = True

STDOUT Log

eonclient
EON Client
VERSION: d4c16168
BUILD DATE: Thu Jul 31 12:05:22 AM GMT 2025

OS: linux
Arch: x86_64
Hostname: rgx1gen11
PID: 55113
DIR: /eon_extpot
Loading parameter file config.ini
* [Main] job: minimization
* [Potential] potential: ext
* [Potential] ext_pot_path: ./external_potential.py
* [Debug] write_movies: True
* [Optimizer] opt_method: lbfgs
* [Optimizer] converged_force: 0.01
* [Optimizer] max_iterations: 200
* [Optimizer] max_move: 0.05

Beginning minimization of pos.con
[Matter] Iter        Step size       ||Force||           Energy       

[Matter]          0     0.00000e+00         7.79543e+01      -16.85654

[Matter]          1     4.15322e-02         2.20148e+01      -22.28107
[Matter]          2     1.64390e-02         9.45726e+00      -23.01723
[Matter]          3     1.43859e-02         2.74592e+00      -23.23933
[Matter]          4     7.39766e-03         1.84771e+00      -23.27610
[Matter]          5     1.38047e-02         2.51169e+00      -23.31275
[Matter]          6     9.17449e-03         2.02817e+00      -23.34426
[Matter]          7     3.34660e-02         3.91686e+00      -23.42580
[Matter]          8     5.31614e-03         2.85479e+00      -23.46282
[Matter]          9     2.50969e-02         3.54545e+00      -23.55450
[Matter]         10     9.22399e-03         3.10366e+00      -23.60418
[Matter]         11     1.02844e-02         3.25930e+00      -23.65208
[Matter]         12     5.00000e-02         4.33988e+00      -23.92723
[Matter]         13     5.00000e-02         5.46683e+00      -24.28135
[Matter]         14     5.00000e-02         5.45217e+00      -24.68712
[Matter]         15     2.77798e-02         3.36781e+00      -24.87176
[Matter]         16     3.56342e-02         6.63633e+00      -24.86025
[Matter]         17     2.18292e-02         1.26935e+00      -24.92660
[Matter]         18     3.79455e-03         6.54511e-01      -24.93282
[Matter]         19     3.84488e-03         4.06718e-01      -24.93625
[Matter]         20     1.77281e-03         2.02733e-01      -24.93730
[Matter]         21     1.78804e-03         1.39562e-01      -24.93766
[Matter]         22     1.10273e-03         1.55200e-01      -24.93768
[Matter]         23     4.17791e-04         2.49541e-02      -24.93774
[Matter]         24     8.16084e-05         1.36310e-02      -24.93774
[Matter]         25     1.35109e-04         8.56987e-03      -24.93774
Minimization converged within tolerence
Saving result to min.con
Final Energy: -24.937741941369072
timing information:
real     13.267 seconds
user      0.247 seconds
sys       0.049 seconds

BTW, I'm converting this to a discussion (and will add documentation on this soon). Also it'd be great to hear what kind of systems you're working on.

Caveats

Off the top of my head, these are some:

• Executable Permissions: Your script must be executable. Run chmod +x external_potential.py.

• Shebang: The script needs a shebang line (e.g., #!/usr/bin/env python3) so the system knows how to run it.

• Units: eOn internally uses eV and Ångströms. It does not perform unit conversions for external potentials. You must ensure your script reads and writes values in these units.

• Environment on HPC: On a cluster, ensure that the environment where eOn runs has access to Python, ASE, and any other libraries your script needs. You may need to configure your job submission script to load the correct modules.

• Performance: This file-based interface has overhead. For very fast potentials, the I/O might become a bottleneck.

• Interrupts (CTRL-C): This may not work as expected. It might terminate your inner executable but leave the parent eOn process running. (killall -9 eonclient is a better choice here)

Let me know if there are any other questions!

[wangsl613]

Thank you for your detailed reply. It has been very helpful to me. The software I originally planned to use doesn’t seem to be compatible with ASE, and calling it through potential = ext to get the results I need is very slow. Therefore, I intend to use machine learning software that supports ASE in combination with eOn to run the calculations.

[HaoZeke]

Generally for a large system, the reading and writing out to file will be slow (along with possible startup times). What is the software of interest? If it has a good C interface (or better, a C++ one), if you open an issue perhaps we can support it as a native potential (e.g. I added support for Metatomic quite recently).

[wangsl613]

Thank you for your suggestion regarding file I/O performance and potential native integration. The software I'm working with is DeePMD, which is primarily used for machine learning-based molecular simulations.
Regarding the issue I'm encountering:

For normally trained DeePMD models, eOn can successfully call ASE (Atomic Simulation Environment) to perform kMC (kinetic Monte Carlo) simulations

However, when using models fine-tuned from larger base models, I'm encountering an error [error details would go here]

Notably, I've verified that the energy and force outputs from these models don't show zero values, so the error appears to be unrelated to zero-output problems

WARNING:communicator: job failed: .//jobs/scratch/0_4: b'To get the best performance, it is recommended to adjust the number of threads by setting the environment variables OMP_NUM_THREADS, DP_INTRA_OP_PARALLELISM_THREADS, and DP_INTER_OP_PARALLELISM_THREADS. See https://deepmd.rtfd.io/parallelism/ for more information.\n[fbc8a4c0fa7c:85466:0:85466] Caught signal 8 (Floating point exception: floating-point invalid operation)\n==== backtrace (tid: 85466) ====\n 0 /root/deepmd-kit/lib/python3.12/site-packages/h5py/../../../././libucs.so.0(ucs_handle_error+0x2fd) [0x7fdbf4b07c1d]\n 1 /root/deepmd-kit/lib/python3.12/site-packages/h5py/../../../././libucs.so.0(+0x2de11) [0x7fdbf4b07e11]\n 2 /root/deepmd-kit/lib/python3.12/site-packages/h5py/../../../././libucs.so.0(+0x2e0da) [0x7fdbf4b080da]\n 3 /lib/x86_64-linux-gnu/libc.so.6(+0x43090) [0x7fdc05104090]\n 4 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x31ef3d) [0x7fdc05927f3d]\n 5 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x24ddd8) [0x7fdc05856dd8]\n 6 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112d10) [0x7fdc0571bd10]\n 7 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n 8 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n 9 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n10 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n11 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n12 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n13 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n14 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x265226) [0x7fdc0586e226]\n15 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n16 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n17 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n18 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n19 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0xc0f) [0x7fdc0585eb6f]\n20 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n21 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n22 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n23 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n24 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n25 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n26 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n27 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n28 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n29 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n30 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n31 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n32 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n33 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n34 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n35 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n36 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n37 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n38 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n39 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n40 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n41 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n42 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n43 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n44 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n45 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n46 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n47 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n48 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n49 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n50 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n51 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n52 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n53 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n54 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2dccf0) [0x7fdc058e5cf0]\n55 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x21e306) [0x7fdc05827306]\n56 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x112a35) [0x7fdc0571ba35]\n57 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x2284e6) [0x7fdc058314e6]\n58 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyObject_CallMethodObjArgs+0x101) [0x7fdc0585f671]\n59 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyImport_ImportModuleLevelObject+0x9a5) [0x7fdc0585e905]\n60 /root/deepmd-kit/lib/libpython3.12.so.1.0(+0x117296) [0x7fdc05720296]\n61 /root/deepmd-kit/lib/libpython3.12.so.1.0(PyEval_EvalCode+0xaf) [0x7fdc058c9b2f]\n=================================\n'