# Relax engine library

`libeon_relax_engine` lets a host that owns a surface, such as a
Gaussian-process model, run eOn's nudged elastic band or saddle search
against that surface. The host supplies energies, forces and variances
for a batch of images. eOn owns the band, the optimizer and the
convergence logic. Each image's cell is passed back in row-major order,
the same layout the host stored, including when the image is not
periodic. `eon_relax_run` reports `MAX_UNCERTAINTY` when any image
variance is above the uncertainty limit (`0.05` for a NULL config).

The C header is `include/eon/relax/eon_relax_engine.h`. It is the
reverse of `engine_c_abi.h` used for rgpot engines: there eOn calls the
engine, here the host calls eOn.

| Symbol | Purpose |
|---|---|
| `eon_relax_create` | Build an engine from a Cap'n Proto `RelaxEngineParams`. A NULL config selects an NEB with the `Parameters` defaults. |
| `eon_relax_run` | Run the band or the saddle search to its stopping rule. |
| `eon_relax_step`, `eon_relax_reset` | Advance one optimizer step, or restart the stepper from new endpoints. |
| `eon_relax_destroy` | Release the engine. |
| `eon_relax_version_hash_str` | Identity of the build: the version plus the full git hash. |

`RelaxEngineParams` lives in `schema/eon_relax_engine.capnp`. Its `kind`
field is `neb` or `saddle`, and `NebParams` and `SaddleParams` carry
the image count, iteration cap and force tolerance. `surfaceEpoch`
tells the engine which generation of the host surface the call belongs
to.

Return values are three-valued. Zero means the call completed and the
outcome struct holds the result. A positive value is recoverable. A
negative value is a named failure, and only `EON_RELAX_SURFACE_FATAL`
leaves the engine unusable.

## Surface epochs

A refit surface returns different energies at identical positions.
`Matter::setSurfaceEpoch` and `Potential::surfaceEpoch` key the energy
and variance caches on the surface generation, so a refit invalidates
them without a change in positions.

## Build and test

The library builds with the default configuration and installs next to
`libeonclib`. Cap'n Proto writes the generated translation unit as
`.c++`. MSVC `cl` ignores that extension, so the build republishes it
as `eon_relax_engine.capnp.cpp` before compiling. The unit test
`test_relax_engine` links the library and
also opens it with `dlopen` through the `EON_RELAX_ENGINE` environment
variable that `meson test` sets:

```bash
meson test -C bbdir test_relax_engine --print-errorlogs
```