--- myst: html_meta: "description": "Fixed-energy line-integral nudged elastic band (LI-NEB) in eOn through rgsaddle: optimal tunneling paths and optional harmonic quantum TST prefactors and actions." "keywords": "eOn LI-NEB, lineb, instanton, tunneling path, rgsaddle, Ásgeirsson." --- # Line-integral NEB (LI-NEB) `job = lineb` finds the optimal tunneling path at a fixed energy {math}`E` with the line-integral nudged elastic band of Ásgeirsson, Arnaldsson and Jónsson, [J. Chem. Phys. 148, 102334 (2018)](https://doi.org/10.1063/1.5007180). The path is the mass-weighted band that minimizes the abbreviated action {math}`W(E) = \int \sqrt{2(V-E)}\,ds`, with endpoints held on {math}`V = E`. Run `eonclient --features` on the installed client. A build with phase-resolved counts and rate orbit output reports ```text 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)`. ```text 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 {doc}`../install/index`. 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. ```bash 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. ```sh 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: ```python 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 {math}`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`. ```ini [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 ```ini [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. ```python 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, {math}`\ln(k Z_r)`. To compare with a rate in inverse seconds, subtract {math}`\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. ```sh 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. ```python 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. ```sh 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/Å.