Line-integral NEB (LI-NEB)

job = lineb finds the optimal tunneling path at a fixed energy \(E\) with the line-integral nudged elastic band of Ásgeirsson, Arnaldsson and Jónsson, J. Chem. Phys. 148, 102334 (2018). The path is the mass-weighted band that minimizes the abbreviated action \(W(E) = \int \sqrt{2(V-E)}\,ds\), with endpoints held on \(V = E\).

Run eonclient --features on the installed client. A build with phase-resolved counts and rate orbit output reports

  rgsaddle fixed-energy LI-NEB: enabled
  LI-NEB phase-resolved counts: enabled
  LI-NEB rate orbit output: enabled
  LI-NEB measured turning point: enabled
  LI-NEB image Hessians and rate counts: enabled

The search runs in rgsaddle. Build eOn with -Dwith_rgsaddle=true and an rgsaddle library that exports rgsaddle_lineb_solve. Meson checks the installed library during configuration. Look for the following result in the setup log. A cached check also ends in YES (cached).

Checking for function "rgsaddle_lineb_solve" with dependency rgsaddle: YES

For phase-resolved counts, the library must also export rgsaddle_lineb_solve_counted. For bead-resolved gradients and residuals, use a matching header and library with RGSADDLE_HAS_LINEB_ORBIT and rgsaddle_lineb_solve_counted_orbit. These checks distinguish builds that share an ABI minor version but provide different entry points. The last two entries report support for rgsaddle_lineb_solve_counted_turning and rgsaddle_lineb_solve_counted_rate. Check the latter before submitting a rate job with interpolated_hessian = true.

If Meson finds the pkg-config package but cannot link rgsaddle_abi_stamp, inspect the linker error in meson-logs/meson-log.txt. Use matching headers and a library built for the C++ compiler’s target and C library. For example, a system rgsaddle build may require a newer glibc than the compiler in a packaged environment can link against.

Energies are in eV, lengths in Å and masses in amu. Defaults for hbar and boltzmann match eOn’s tunneling constants so the reported temperature is in kelvin.

Build the Linux client from source

Start in the eOn checkout containing examples/lineb-morse. Open the default Pixi shell as described in Installation. In that shell, run the project’s ensure_cbindgen task for the readcon build, which requires cbindgen 0.29.0 or newer. Install the rgsaddle C library under a private prefix. The revision below is the one selected by the LI-NEB row of .github/workflows/ci_rg_backends.yml in this checkout.

pixi run ensure_cbindgen
prefix="$PWD/build-lineb-deps"
mkdir -p "$prefix"
git clone https://github.com/OmniPotentRPC/rgsaddle.git "$prefix/src/rgsaddle"
git -C "$prefix/src/rgsaddle" checkout --detach 29381c1202b8c25f4e4343d363b43164048ccedb
cargo install cargo-c --version 0.10.23 --locked --root "$prefix/tools"
export PATH="$prefix/tools/bin:$PATH"
(cd "$prefix/src/rgsaddle" && cargo cinstall --locked --release --features capi \
  --prefix="$prefix" --libdir="$prefix/lib")
export PKG_CONFIG_PATH="$prefix/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
export LD_LIBRARY_PATH="$prefix/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
meson setup build-lineb --buildtype=release -Dwith_rgsaddle=true
meson compile -C build-lineb
export PATH="$PWD/build-lineb/client:$PATH"
eonclient --features

Keep this shell open for the Morse example so the client can load the same library that Meson checked.

Run a Morse barrier example

From the repository root, copy the example to a run directory and invoke the client built with rgsaddle and the morse_pt potential.

mkdir -p run/lineb-morse
cp examples/lineb-morse/{config.ini,seed.con} run/lineb-morse/
(cd run/lineb-morse && eonclient)

Two fixed Pt atoms sit 10 Å apart. A third Pt atom moves between two equivalent binding sites. The three seed frames bracket the barrier at the specified energy of −0.55436031 eV. The job writes the optimized path to run/lineb-morse/lineb.con. With the counted solve API, the first frame gives the action and the cost for the entire band:

import readcon

frame = readcon.read_con("run/lineb-morse/lineb.con")[0]
print(round(frame.metadata["lineb"]["action"], 4))
print(frame.metadata["evaluation_counts"]["potential_calls"])

A reference run gave an action of 36.6004 and used 1084 potential evaluations for the solve and three to write the image energies. The example requests the path only. Its JSON rate field is null.

To try the rate diagnostic, set beads = 8 in the copied [Lineb] section and run the client in the same directory. The reference run wrote eight frames to lineb-orbit.con. It used 35 rate evaluations, bringing the solver total to 1,119 and the job total to 1,122.

For the image-Hessian approximation in section II.D of the 2018 paper, set interpolated_hessian = true in [Lineb]. The solver computes Cartesian Hessians by central differences at the optimized path images and interpolates them to the rate beads. The default computes the curvature at the beads. The choice is independent of the orbit clock. Set image_hessian_step to a positive displacement in Å to control the finite differences at the images. Zero selects the solver default.

The job records the chosen method in lineb.hessian. With the counted rate interface, lineb.rate_calls.curvature and lineb.rate_calls.bead separate curvature evaluations from bead energy/gradient evaluations. These are subdivisions of surface_calls.rate. Include that rate total once when comparing the cost of a reactive flux.

Inputs

File / key

Role

[Main] job = lineb

Select the job

[Lineb] initial_path

Multi-frame seed band (for example neb.con), at least three images, interior images above energy

[Lineb] energy

Required tunneling energy \(E\) in eV

[Lineb] beads

At least two harmonic quantum TST replicas, or 0 for the path only (JSON rate is null)

[Lineb] molecular

false expands atom masses to coordinates (adsorbate / fixed field); true uses molecule alignment and needs every atom free

[Lineb] adjacent_alignment

With molecular = true: false fits every image to the first image; true fits each image to its neighbour along the band, the alignment of Ásgeirsson et al. (2018)

Frozen atoms are dropped from the path degrees of freedom when molecular = false. A per-axis freeze (only some of x, y, z fixed) is refused. Keep atom order, masses, cell, fixed masks and frozen substrate positions consistent across the seed. Under periodic boundaries the job joins adjacent images by their minimum-image displacements. Use a nonperiodic system with all atoms free for molecular alignment.

Set endpoint_kappa to a positive value for the fixed turning-surface force coefficient in Eqs. (19) and (21) of the paper. The coefficient multiplies the energy error in eV to give a force in mass-weighted action units. Its default of zero selects the gradient-normalized endpoint_scale restraint. A positive value requires the rgsaddle fixed-kappa solve API.

For the initialization and convergence test used in the paper’s Cu(110) calculation, supply a path that crosses the target energy on both sides of the saddle and set both linear_seed = true and endpoint_convergence = true. The first option joins the two energy crossings with a straight line. The second tests the nudged force at each endpoint and the perpendicular action gradient at each interior image. Each option can be used independently with a library that exposes the rgsaddle seed options.

The paper also uses velocity-projected velocity Verlet for optimizing the band. Set projected_verlet = true to request that optimizer with a library that defines RGSADDLE_LINEB_PROJECTED_VERLET. The default optimizer is FIRE 2.0.

To select the imaginary-time propagation described in section II.C, set interpolated_force_clock = true with a library that defines RGSADDLE_LINEB_INTERPOLATED_FORCE_CLOCK. This uses a cubic interpolation of the signed tangential image forces to determine the half-period, temperature and bead positions. The default obtains them by quadrature. The lineb.replica_clock field in the CON frame metadata records the selection. With a library exporting rgsaddle_lineb_solve_counted_turning, the lineb.turning object also gives the zero-based launch image, the mass-weighted path length and return arc coordinate (√amu Å), the largest Cartesian component of the displacement from the opposite image (Å), and the return energy relative to the target and to the opposite image (eV). These measurements show how closely the propagated orbit reaches the optimized turning point.

The eOn job uses the number of frames in initial_path as the number of LI-NEB images. For the straight initial path used for H₂/Cu(110), locate its two crossings of the target energy, interpolate ten frames along the straight line between them, and pass those frames as the seed. The accuracy of the crossings matters near the saddle. For the frozen Cu(110) reconstruction, following the intrinsic reaction coordinate from the saddle in both directions resolved the first pair of crossings at 0.05 eV below the barrier.

Set up the ammonia-borane energy ladder

For Figure 4, start from the molecular minimum-energy path (MEP). Use the saddle energy measured with the same potential and energy zero as the band. Set energy to that value minus 0.05 eV for the first level. Write ten ordered seed frames with readcon, spanning both crossings and following the shape of the MEP. Keep the B, N and six H atoms mobile. At each lower energy, use the preceding optimized band to seed the search and extend it along the reaction path far enough to bracket the new turning surfaces.

The following entries supplement initial_path and energy in the molecular job. They express the paper’s dimensionless-action controls using a reference mass of 1 amu and eOn’s default hbar = 0.06466.

[Lineb]
molecular = true
linear_seed = false
endpoint_convergence = true
projected_verlet = true
spring = 1.2932
endpoint_kappa = 6.466
opt_tol = 0.0006466
perp_tol = 0.0006466
interpolated_force_clock = true
beads = 240
interpolated_hessian = true
image_hessian_step = 0.005

The 0.005 Å displacement is a reconstruction choice for the image Hessians. Read the temperature for each level from the computed period. A fixed-temperature comparison with another instanton solver should use that temperature. To compare fixed energies as well, evaluate both orbits on the same potential and check their inferred tunneling energies.

Restart from a saved band

A saved turning point can evaluate slightly above or below the target when an electronic-structure calculation starts from a different orbital guess. If both endpoint energies are at or above the target, rgsaddle treats the input as a prepared band and relaxes its endpoints toward the turning surfaces. If one end is above and the other below, the prepared-band restart requires both gaps to fit within the solver’s energy roundoff tolerance. A seed extending below the target on both sides lets the solver locate both crossings around the barrier.

If the job reports a missing reactant- or product-side crossing, its error gives the target and both endpoint energies in eV. Subtract the target from each reported energy to see which end needs attention.

To construct a bracketed seed, follow the reaction path outward on the affected side until its endpoint energy falls below the target. Keep an interior image above the target and verify the other crossing. To measure an endpoint separately, write that frame to pos.con with readcon and run an eOn job = point with the same potential and electronic-structure settings. Count these measurements as seed preparation when reporting the total cost. The LI-NEB run locates the turning points for the requested energy from the supplied band.

For a frozen Cu substrate with two mobile hydrogen atoms of mass 1.00793 amu, the paper uses a spring of 20 Å⁻² and an endpoint coefficient of 1000 eV⁻¹ Å⁻¹ for the dimensionless action. With eOn’s default hbar, the corresponding inputs for projected velocity Verlet are

[Lineb]
linear_seed = true
endpoint_convergence = true
projected_verlet = true
spring = 1.28291
endpoint_kappa = 64.3993
opt_tol = 0.000643993
perp_tol = 0.000643993

Supply initial_path and an absolute energy from the same potential. These numbers use the fact that every mobile coordinate has the same mass. They convert the published controls and do not establish a converged rate.

Both optimizer tolerances have units of √eV in eOn. They apply to derivatives of the abbreviated action with respect to mass-weighted coordinates. For equal mobile masses $m$, a tolerance $g$ on the Cartesian gradient of the dimensionless action converts to $g\hbar/\sqrt{m}$, as in the hydrogen example above. For a molecule with different atomic masses, each Cartesian gradient component carries its own factor $1/\sqrt{m_a}$ before the norm is taken. Use the force residual in lineb-orbit.con to check stationarity in eV/Å.

The remaining keys (spring, endpoint_scale, time_step, max_move, turning_width, quadrature_pairs, max_steps) match rgsaddle’s LinebConfig defaults unless you change them.

During optimization, rgsaddle smooths the square-root momentum near each turning point. The smoothing width in eV is turning_width times the height of the highest starting image above the target energy. The default fraction is 0.001. To check sensitivity, repeat the run from the same seed at the same energy with a smaller positive fraction and compare the optimized band and temperature. For a rate run, also compare the rate and the bead force residual. The endpoint_convergence switch controls the stopping criterion independently of this smoothing.

Outputs

File

Contents

lineb.con

Optimized band, per-image energy and job-wide force-call counts in the second-line JSON of each frame

lineb-orbit.con

Equal-time rate replicas, mobile-atom potential gradients, and finite-bead stationarity for a rate run with an orbit-capable backend

results.dat

Action, both half periods and temperatures, optional log_rate_over_reactant, call counts

Read the counters from any frame with readcon. Every frame of the optimized band repeats the same job totals and has its own neb_bead and image energy.

import readcon

frame = readcon.read_con("lineb.con")[0]
ledger = frame.metadata["evaluation_counts"]
counts = ledger["surface_calls"]
backend = ledger["potential_calls"]
print(counts)

With rgsaddle_lineb_solve_counted, the six disjoint counts sum to total. Each surface call evaluates one atomic configuration.

Key

Evaluations counted

seed

Inspecting the supplied band and locating the initial energy crossings

optimization

Relaxing the band, including trial steps

path_preparation

Preparing the converged path and refining its turning points

quadrature

Integrating the action and building the imaginary-time table

dynamics

Integrating the independent constrained trajectory

rate

Evaluating the rate prefactor, zero for a path-only job

The sibling potential_calls object records changes to eOn’s potential counter during setup, solve and output, plus their total. Caching can make these counts differ from the solver’s requests. An MEP computed by a separate job has its own cost. Older rgsaddle libraries supply the combined optimizer_reported and measure_reported fields, plus dynamics, rate and the observed remainder in unclassified.

To measure work inside rgpot, set result_cache in [Lineb] to a RocksDB directory and use an rgpot potential with cache support (-Drgpot:with_cache=true for the bundled dependency). A new directory starts cold. Reusing the directory lets rgpot serve matching geometries. The readcon metadata field evaluation_counts.rgpot_results gives computed and served for the job and for each of setup, solve, and output under phases. Without an attached cache this field is null. For cost comparisons, record whether the database was cold or reused.

For positive replica counts, log_rate_over_reactant is the natural logarithm of the rate times the reactant partition function, \(\ln(k Z_r)\). To compare with a rate in inverse seconds, subtract \(\ln Z_r\) evaluated at the same temperature, energy zero and rigid-mode convention, then convert from the eOn time unit (about 10.18 fs). A path-only run writes NaN for this field. A solver failure appears in the job log with the rgsaddle status. When the solver exhausts max_steps, the diagnostic reports both final force norms and the tolerance for each.

For an unconstrained nonlinear molecule, rgpycrumbs can read the full orbit through readcon and normalize the rate. The command below pins the revision with native eOn orbit support. Supply the optimized reactant in extended XYZ format with matching species, atom order and isotope masses. Its spectrum JSON supplies the electronic energy in electronic_energy_eV and the $3N-6$ positive internal frequencies in signed_wavenumbers_cm-1. Use the same potential, energy zero and unit conversion for the reactant and the instanton. The native frames record the run’s lineb.hbar, lineb.boltzmann and lineb.molecular settings.

uvx --from git+https://github.com/HaoZeke/rgpycrumbs.git@0c8cbb32a6060b5670af91a93d790f234e54ef9e \
    rgpycrumbs eon molecular-instanton-rate lineb-orbit.con \
    reactant_spectrum.json reactant.extxyz --confirm-same-energy-zero

The log10_rate_per_s output includes the finite-bead harmonic reactant partition function and the rotational inertia ratio for a single reaction path. Apply any symmetry-equivalent path multiplicity separately when comparing to a total experimental or published rate.

The readcon field lineb.spectrum reports the number of retained ring modes and the number with negative eigenvalues when a backend with RGSADDLE_HAS_LINEB_RATE_DIAGNOSTICS evaluates the rate. It is null for a path-only run or a backend that does not return the spectrum. A first-order instanton has one negative mode. Check the force residual around the ring as well as the mode count and rate when increasing the number of replicas.

For a rate job (beads > 0) with RGSADDLE_HAS_LINEB_ORBIT, open lineb-orbit.con with readcon. Each frame holds one replica of the full ring in continuous Cartesian coordinates, including the fixed atoms. The fields temperature_K and tau_over_beta give the temperature and the bead’s imaginary time as a fraction of the full period. The second-line JSON records the energy gradients of the mobile atoms at those coordinates, in the order of their CON atom IDs. Returning replicas repeat their outbound partner’s coordinates exactly. The image-Hessian rate requests all bead gradients and an rgpot cache can serve the repeated geometries. The direct bead-Hessian rate reuses its outbound measurements. The diagnostic uses the potential evaluations already counted in the rate.

import readcon

ring = readcon.read_con("lineb-orbit.con")
frame = ring[0].metadata
print(frame["lineb_orbit"]["mobile_atom_ids"])
print(frame["lineb_orbit"]["gradients_eV_per_angstrom"])
print(frame["lineb"]["stationarity"])

For replica $j$ and mobile coordinate $a$, the discrete residual is $R_{ja}=\partial_a V(x_j)+m_a(P/\tau)^2(2x_{ja}-x_{j-1,a}-x_{j+1,a})$. Indices wrap around the ring, $P$ is the number of beads, and $\tau$ is twice the reported half period. max_abs_eV_per_angstrom and rms_eV_per_angstrom summarize all mobile Cartesian components. max_bead and max_axis are zero-based. max_atom_id identifies the CON atom. Compare these values as the path images and bead count increase. A continuum residual requires differentiating the path in continuous imaginary time.

The fixed-energy optimizer tests forces on the band images. The residual above tests the reconstructed equal-time ring used for the rate. A band can satisfy both optimizer tolerances while its ring exceeds the desired Cartesian force tolerance. For a convergence study, hold the target energy and potential fixed, refine the image count and bead count separately, and record the resulting temperature, residual and normalized rate for each run. Use the reported temperature when comparing to a temperature-indexed rate curve. Compare only within the reference curve’s temperature range.

To check both residuals from the saved gradients, run the following command in the job directory. It reads the ring through readcon and uses twice the recorded half-period. It requires no calculator or electronic evaluations.

uvx --from git+https://github.com/HaoZeke/rgpycrumbs.git@0c8cbb32a6060b5670af91a93d790f234e54ef9e \
    rgpycrumbs eon orbit-residual lineb-orbit.con --compare-discretizations

For the eight-bead Morse example, the largest finite-bead residual is 0.0229891 eV/Å, which agrees with the native lineb.stationarity field. Fourier differentiation on the same eight coordinates gives 0.0234458 eV/Å.