Tier-2 C ABI: eOn as a dlopen relaxation engine. More...

#include <stddef.h>
#include <stdint.h>

Classes
struct	eon_relax_version_t
	Version head carried by every wire struct (dlpack DLPackVersion). More...
struct	eon_relax_band_t
	Caller-owned band. More...
struct	eon_relax_outcome_t
	Engine-written result. More...
struct	eon_relax_surface_request_t
	Host-surface request: one struct, engine-stamped version, so the callback contract grows behind the version head instead of by new symbols. More...

Macros
#define	EON_RELAX_API __attribute__((visibility("default")))
#define	EON_RELAX_ABI_MAJOR 2u
#define	EON_RELAX_ABI_MINOR 1u
#define	EON_RELAX_VERSION_INIT {EON_RELAX_ABI_MAJOR, EON_RELAX_ABI_MINOR}
#define	EON_RELAX_KIND_IS_KNOWN(k)
#define	EON_RELAX_IMAGE_NONE INT64_C(-1)

Typedefs
typedef struct EonRelaxEngine	EonRelaxEngine
typedef int(*	eon_relax_surface_fn) (void user, eon_relax_surface_request_t req)
	Return 0 on success, positive recoverable, negative fatal.

Enumerations
enum	eon_relax_kind_t { EON_RELAX_KIND_INVALID = 0 , EON_RELAX_KIND_NEB = 1 , EON_RELAX_KIND_SADDLE = 2 }
enum	eon_relax_rc_t { EON_RELAX_OK = 0 , EON_RELAX_NULL_ENGINE = -1 , EON_RELAX_NULL_BAND = -2 , EON_RELAX_NULL_SURFACE = -3 , EON_RELAX_NULL_OUTCOME = -4 , EON_RELAX_NULL_POSITIONS = -5 , EON_RELAX_NULL_ATOMIC_NRS = -6 , EON_RELAX_NULL_BOXES = -7 , EON_RELAX_NULL_MODE = -8 , EON_RELAX_BAND_TOO_SHORT = -9 , EON_RELAX_NATOMS = -10 , EON_RELAX_UNKNOWN_KIND = -11 , EON_RELAX_UNKNOWN_STATUS = -12 , EON_RELAX_CAPNP_ROOT = -13 , EON_RELAX_SURFACE_FATAL = -15 , EON_RELAX_SADDLE_NIMAGES = -17 , EON_RELAX_BAND_SIZE = -18 , EON_RELAX_ALLOC = -19 , EON_RELAX_UNAVAILABLE = -21 , EON_RELAX_INVALID_PARAMETER = -22 , EON_RELAX_ABI_MISMATCH = -23 }
	Call rc: 0 success (read outcome), positive recoverable, negative a named fail. More...
enum	eon_relax_neb_status_t { EON_RELAX_NEB_GOOD = 0 , EON_RELAX_NEB_INIT = 1 , EON_RELAX_NEB_BAD_MAX_ITERATIONS = 2 , EON_RELAX_NEB_RUNNING = 3 , EON_RELAX_NEB_MAX_UNCERTAINTY = 4 }
	NudgedElasticBand::NEBStatus integers. More...

Functions
EON_RELAX_API int	eon_relax_abi_version (void)
	(major << 16) \| minor.
EON_RELAX_API int	eon_relax_available (void)
EON_RELAX_API int	eon_relax_abi_stamp (eon_relax_version_t *out)
EON_RELAX_API const char *	eon_relax_version_hash_str (void)
	Immortal dest identity string.
EON_RELAX_API uint64_t	eon_relax_version_hash (void)
	64-bit FNV-1a hash of eon_relax_version_hash_str().
EON_RELAX_API EonRelaxEngine *	eon_relax_create (const void config, size_t config_len, char errbuf, size_t errlen)
	Create.
EON_RELAX_API int	eon_relax_set_surface_epoch (EonRelaxEngine *eng, uint64_t epoch)
EON_RELAX_API int	eon_relax_last_error (const EonRelaxEngine *eng)
	Last named create/run/step/reset/set_epoch rc on this handle.
EON_RELAX_API int	eon_relax_run (EonRelaxEngine eng, eon_relax_band_t band, eon_relax_surface_fn surface, void user, eon_relax_outcome_t out)
	Run the bound engine to completion.
EON_RELAX_API int	eon_relax_step (EonRelaxEngine eng, eon_relax_band_t band, eon_relax_surface_fn surface, void user, eon_relax_outcome_t out)
	One band optimizer step (kind=NEB only).
EON_RELAX_API int	eon_relax_reset (EonRelaxEngine *eng)
	Drop the stepper's band state and optimizer history; the next eon_relax_step reinitializes from the caller's band.
EON_RELAX_API void	eon_relax_destroy (EonRelaxEngine *eng)
EON_RELAX_API const char *	eon_relax_status_name (eon_relax_kind_t kind, int status)
	NULL if kind or status is unknown.

Detailed Description

Tier-2 C ABI: eOn as a dlopen relaxation engine.

Reverse of include/eon/potentials/Rgpot/engine_c_abi.h: the host supplies the surface (energy/forces/variance for a band), eOn owns NudgedElasticBand / MinModeSaddleSearch. Configuration is a Cap'n Proto flat-array whose root is RelaxEngineParams in schema/eon_relax_engine.capnp (NebParams / SaddleParams arms). NULL config selects Parameters NSDMI defaults and kind=NEB.

Units: positions Angstrom, energy eV, forces eV/Angstrom.

Plugin Matters use the Matter default (PBC on for a non-isolated pot). fill and endpoint dirty write positions with PBC off so the caller frame is kept (a 10 A box must not map x=-0.3 to 9.7).

Layout discipline (dlpack.h is the model):

Every wire struct opens with an eon_relax_version_t and a uint64 flags word. The writer stamps the version it was built against; the reader refuses a major it does not know (EON_RELAX_ABI_MISMATCH). Growth is append-only behind the version head, gated on minor.
Fixed-width integer types only. Never long in a wire struct.
The surface callback takes ONE request struct, so the callback contract can grow without a new function symbol.
Return values are three-valued: 0 success (read the outcome), positive recoverable, negative a named fail. SURFACE_FATAL makes the instance unusable. Every other named fail leaves the handle reusable.
Closed enums. Unknown kind is EON_RELAX_UNKNOWN_KIND; other unknown enumerants are EON_RELAX_INVALID_PARAMETER. Never a silent fallback.
Optional symbols are discovered by dlsym; absence means the operation is unsupported.

Definition in file eon_relax_engine.h.

Macro Definition Documentation

◆ EON_RELAX_ABI_MAJOR

#define EON_RELAX_ABI_MAJOR 2u

Definition at line 72 of file eon_relax_engine.h.

◆ EON_RELAX_ABI_MINOR

#define EON_RELAX_ABI_MINOR 1u

Definition at line 73 of file eon_relax_engine.h.

◆ EON_RELAX_API

#define EON_RELAX_API __attribute__((visibility("default")))

Definition at line 67 of file eon_relax_engine.h.

◆ EON_RELAX_IMAGE_NONE

#define EON_RELAX_IMAGE_NONE INT64_C(-1)

Definition at line 128 of file eon_relax_engine.h.

◆ EON_RELAX_KIND_IS_KNOWN

#define EON_RELAX_KIND_IS_KNOWN ( k )

Value:

((k) == EON_RELAX_KIND_NEB || (k) == EON_RELAX_KIND_SADDLE)

EON_RELAX_KIND_SADDLE

@ EON_RELAX_KIND_SADDLE

Definition eon_relax_engine.h:86

EON_RELAX_KIND_NEB

@ EON_RELAX_KIND_NEB

Definition eon_relax_engine.h:85

Definition at line 89 of file eon_relax_engine.h.

89#define EON_RELAX_KIND_IS_KNOWN(k) \

90 ((k) == EON_RELAX_KIND_NEB || (k) == EON_RELAX_KIND_SADDLE)

◆ EON_RELAX_VERSION_INIT

#define EON_RELAX_VERSION_INIT {EON_RELAX_ABI_MAJOR, EON_RELAX_ABI_MINOR}

Definition at line 81 of file eon_relax_engine.h.

Typedef Documentation

◆ eon_relax_surface_fn

typedef int(* eon_relax_surface_fn) (void *user, eon_relax_surface_request_t *req)

Return 0 on success, positive recoverable, negative fatal.

Definition at line 198 of file eon_relax_engine.h.

◆ EonRelaxEngine

typedef struct EonRelaxEngine EonRelaxEngine

Definition at line 70 of file eon_relax_engine.h.

Enumeration Type Documentation

◆ eon_relax_kind_t

enum eon_relax_kind_t

Enumerator
EON_RELAX_KIND_INVALID
EON_RELAX_KIND_NEB
EON_RELAX_KIND_SADDLE

Definition at line 83 of file eon_relax_engine.h.

             {
  EON_RELAX_KIND_INVALID = 0,
  EON_RELAX_KIND_NEB = 1,
  EON_RELAX_KIND_SADDLE = 2
} eon_relax_kind_t;

◆ eon_relax_neb_status_t

enum eon_relax_neb_status_t

NudgedElasticBand::NEBStatus integers.

Written to outcome.status for NEB.

Enumerator
EON_RELAX_NEB_GOOD
EON_RELAX_NEB_INIT
EON_RELAX_NEB_BAD_MAX_ITERATIONS
EON_RELAX_NEB_RUNNING
EON_RELAX_NEB_MAX_UNCERTAINTY

Definition at line 120 of file eon_relax_engine.h.

             {
  EON_RELAX_NEB_GOOD = 0,
  EON_RELAX_NEB_INIT = 1,
  EON_RELAX_NEB_BAD_MAX_ITERATIONS = 2,
  EON_RELAX_NEB_RUNNING = 3,
  EON_RELAX_NEB_MAX_UNCERTAINTY = 4
} eon_relax_neb_status_t;

◆ eon_relax_rc_t

enum eon_relax_rc_t

Call rc: 0 success (read outcome), positive recoverable, negative a named fail.

SURFACE_FATAL makes the instance unusable. Every other named fail leaves the handle reusable.

Enumerator
EON_RELAX_OK
EON_RELAX_NULL_ENGINE
EON_RELAX_NULL_BAND
EON_RELAX_NULL_SURFACE
EON_RELAX_NULL_OUTCOME
EON_RELAX_NULL_POSITIONS
EON_RELAX_NULL_ATOMIC_NRS
EON_RELAX_NULL_BOXES
EON_RELAX_NULL_MODE
EON_RELAX_BAND_TOO_SHORT
EON_RELAX_NATOMS
EON_RELAX_UNKNOWN_KIND
EON_RELAX_UNKNOWN_STATUS
EON_RELAX_CAPNP_ROOT
EON_RELAX_SURFACE_FATAL
EON_RELAX_SADDLE_NIMAGES
EON_RELAX_BAND_SIZE
EON_RELAX_ALLOC
EON_RELAX_UNAVAILABLE
EON_RELAX_INVALID_PARAMETER
EON_RELAX_ABI_MISMATCH

Definition at line 95 of file eon_relax_engine.h.

             {
  EON_RELAX_OK = 0,
  EON_RELAX_NULL_ENGINE = -1,
  EON_RELAX_NULL_BAND = -2,
  EON_RELAX_NULL_SURFACE = -3,
  EON_RELAX_NULL_OUTCOME = -4,
  EON_RELAX_NULL_POSITIONS = -5,
  EON_RELAX_NULL_ATOMIC_NRS = -6,
  EON_RELAX_NULL_BOXES = -7,
  EON_RELAX_NULL_MODE = -8,
  EON_RELAX_BAND_TOO_SHORT = -9,
  EON_RELAX_NATOMS = -10,
  EON_RELAX_UNKNOWN_KIND = -11,
  EON_RELAX_UNKNOWN_STATUS = -12,
  EON_RELAX_CAPNP_ROOT = -13,
  EON_RELAX_SURFACE_FATAL = -15,
  EON_RELAX_SADDLE_NIMAGES = -17,
  EON_RELAX_BAND_SIZE = -18,
  EON_RELAX_ALLOC = -19,
  EON_RELAX_UNAVAILABLE = -21,
  EON_RELAX_INVALID_PARAMETER = -22,
  EON_RELAX_ABI_MISMATCH = -23
} eon_relax_rc_t;

Function Documentation

◆ eon_relax_abi_stamp()

EON_RELAX_API int eon_relax_abi_stamp ( eon_relax_version_t * out )

Definition at line 262 of file RelaxEngineAbi.cpp.

                                                  {
  if (!out) {
    return EON_RELAX_INVALID_PARAMETER;
  }
  out->major = EON_RELAX_ABI_MAJOR;
  out->minor = EON_RELAX_ABI_MINOR;
  return EON_RELAX_OK;
}

◆ eon_relax_abi_version()

EON_RELAX_API int eon_relax_abi_version ( void )

(major << 16) | minor.

Definition at line 256 of file RelaxEngineAbi.cpp.

                                {
  return static_cast<int>((EON_RELAX_ABI_MAJOR << 16) | EON_RELAX_ABI_MINOR);
}

◆ eon_relax_available()

EON_RELAX_API int eon_relax_available ( void )

Definition at line 260 of file RelaxEngineAbi.cpp.

260{ return 1; }

◆ eon_relax_create()

EON_RELAX_API EonRelaxEngine * eon_relax_create	(	const void *	config,
		size_t	config_len,
		char *	errbuf,
		size_t	errlen )

Create.

NULL config && config_len==0 selects Parameters NSDMI defaults and kind=NEB. A non-empty buffer is a Cap'n Proto flat-array whose root is RelaxEngineParams. kind tokens are "neb" and "saddle"; any other token fails closed (EON_RELAX_UNKNOWN_KIND). An unparseable buffer is EON_RELAX_CAPNP_ROOT. config!=NULL && config_len==0 is refused.

Definition at line 282 of file RelaxEngineAbi.cpp.

                                                              {
  auto make_engine = [&]() -> std::unique_ptr<EonRelaxEngine> {
    try {
      return std::make_unique<EonRelaxEngine>();
    } catch (const std::bad_alloc &) {
      set_err(errbuf, errlen, "-19 out of memory");
      return nullptr;
    }
  };
  if (config == nullptr && config_len == 0) {
    auto eng = make_engine();
    if (!eng) {
      return nullptr;
    }
    eng->kind = EON_RELAX_KIND_NEB;
    return eng.release();
  }
  if (config == nullptr || config_len == 0) {
    set_err(errbuf, errlen, "-13 RelaxEngineParams capnp root");
    return nullptr;
  }
  auto eng = make_engine();
  if (!eng) {
    return nullptr;
  }
  const int prc = apply_relax_params(eng->params, &eng->kind, &eng->epoch,
                                     config, config_len, errbuf, errlen);
  if (prc != EON_RELAX_OK) {
    return nullptr;
  }
  return eng.release();
}

◆ eon_relax_destroy()

EON_RELAX_API void eon_relax_destroy ( EonRelaxEngine * eng )

Definition at line 637 of file RelaxEngineAbi.cpp.

                                            {
  std::unique_ptr<EonRelaxEngine> owned(eng);
}

◆ eon_relax_last_error()

EON_RELAX_API int eon_relax_last_error ( const EonRelaxEngine * eng )

Last named create/run/step/reset/set_epoch rc on this handle.

0 if none.

Definition at line 331 of file RelaxEngineAbi.cpp.

                                                    {
  if (!eng) {
    return EON_RELAX_NULL_ENGINE;
  }
  return eng->last_rc;
}

◆ eon_relax_reset()

EON_RELAX_API int eon_relax_reset ( EonRelaxEngine * eng )

Drop the stepper's band state and optimizer history; the next eon_relax_step reinitializes from the caller's band.

This is the host's model-update hook: quasi-Newton memory taken on one surface epoch must not survive onto the next.

Definition at line 625 of file RelaxEngineAbi.cpp.

                                         {
  if (!eng) {
    return EON_RELAX_NULL_ENGINE;
  }
  if (eng->unusable) {
    return stamp_rc(eng, EON_RELAX_SURFACE_FATAL);
  }
  clear_stepper(eng);
  eng->last_rc = EON_RELAX_OK;
  return EON_RELAX_OK;
}

◆ eon_relax_run()

EON_RELAX_API int eon_relax_run	(	EonRelaxEngine *	eng,
		eon_relax_band_t *	band,
		eon_relax_surface_fn	surface,
		void *	user,
		eon_relax_outcome_t *	out )

Run the bound engine to completion.

Writes updated interior coordinates into band->positions (caller-owned); endpoints stay in the caller frame. Endpoint minimization stays with the host (NudgedElasticBand::compute does not minimize endpoints). surface may not be NULL. Kind is bound at create (NULL config => NEB). Returns eon_relax_rc_t; on 0, out->status is the dest NEB or saddle table.

Definition at line 338 of file RelaxEngineAbi.cpp.

                                            {
  if (!eng) {
    return EON_RELAX_NULL_ENGINE;
  }
  if (eng->unusable) {
    return fail_out(eng, out, EON_RELAX_SURFACE_FATAL, eng->kind, eng->epoch);
  }
  if (!band) {
    return fail_out(eng, out, EON_RELAX_NULL_BAND, eng->kind, eng->epoch);
  }
  if (!surface) {
    return fail_out(eng, out, EON_RELAX_NULL_SURFACE, eng->kind, eng->epoch);
  }
  if (!out) {
    return stamp_rc(eng, EON_RELAX_NULL_OUTCOME);
  }
  clear_stepper(eng);
  if (band->n_atoms <= 0) {
    return fail_out(eng, out, EON_RELAX_NATOMS, eng->kind, eng->epoch);
  }
  if (!band->positions) {
    return fail_out(eng, out, EON_RELAX_NULL_POSITIONS, eng->kind, eng->epoch);
  }
  if (!band->atomic_nrs) {
    return fail_out(eng, out, EON_RELAX_NULL_ATOMIC_NRS, eng->kind, eng->epoch);
  }
  if (!band->boxes) {
    return fail_out(eng, out, EON_RELAX_NULL_BOXES, eng->kind, eng->epoch);
  }
  if (band->version.major != EON_RELAX_ABI_MAJOR) {
    return fail_out(eng, out, EON_RELAX_ABI_MISMATCH, eng->kind, eng->epoch);
  }
  if (!known_kind(eng->kind)) {
    return fail_out(eng, out, EON_RELAX_UNKNOWN_KIND, eng->kind, eng->epoch);
  }
  const int mass_rc = masses_ok(band);
  if (mass_rc != EON_RELAX_OK) {
    return fail_out(eng, out, mass_rc, eng->kind, eng->epoch);
  }
  stamp_outcome(out, eng->kind, eng->epoch);
 
  auto pot =
      std::make_shared<eonc::HostSurfacePotential>(surface, user, eng->epoch);
  try {
    if (eng->kind == EON_RELAX_KIND_NEB) {
      if (band->n_images < 3) {
        out->status = -1;
        return stamp_rc(eng, EON_RELAX_BAND_TOO_SHORT);
      }
      const int64_t want =
          static_cast<int64_t>(eng->params.neb_options().image_count) + 2;
      if (band->n_images != want) {
        out->status = -1;
        return stamp_rc(eng, EON_RELAX_BAND_SIZE);
      }
      std::vector<Matter> path;
      path.reserve(static_cast<size_t>(band->n_images));
      for (int64_t i = 0; i < band->n_images; ++i) {
        Matter img(pot, eng->params);
        fill_matter(img, band, static_cast<long>(i), eng->epoch);
        path.push_back(std::move(img));
      }
      auto neb = std::make_unique<NudgedElasticBand>(std::move(path),
                                                     eng->params, pot);
      pot->bindPath(neb->path);
      dirty_endpoints(*neb);
      const auto st = neb->compute();
      if (st == NudgedElasticBand::NEBStatus::INIT ||
          st == NudgedElasticBand::NEBStatus::RUNNING) {
        out->status = neb_status(st);
        return stamp_rc(eng, EON_RELAX_UNKNOWN_STATUS);
      }
      out->status = neb_status(st);
      NEBObjectiveFunction ranked(neb.get(), eng->params);
      if (ranked.isUncertain()) {
        out->status = EON_RELAX_NEB_MAX_UNCERTAINTY;
      }
      out->iterations = neb->lastIteration();
      out->climbing_image = neb->climbingImage;
      out->max_force = neb->convergenceForce();
      out->surface_epoch = pot->surfaceEpoch();
      for (int64_t i = 1; i + 1 < band->n_images; ++i) {
        write_image(band->positions + i * 3 * band->n_atoms,
                    *neb->path[static_cast<size_t>(i)],
                    static_cast<long>(band->n_atoms));
      }
      return stamp_rc(eng, EON_RELAX_OK);
    }
 
    if (band->n_images != 1) {
      out->status = -1;
      return stamp_rc(eng, EON_RELAX_SADDLE_NIMAGES);
    }
    if (!band->mode) {
      out->status = -1;
      return stamp_rc(eng, EON_RELAX_NULL_MODE);
    }
    auto matter = std::make_shared<Matter>(pot, eng->params);
    fill_matter(*matter, band, 0, eng->epoch);
    AtomMatrix mode(band->n_atoms, 3);
    Eigen::Map<const AtomMatrix> mmap(band->mode, band->n_atoms, 3);
    mode = mmap;
    const double reactant_e = matter->getPotentialEnergy();
    MinModeSaddleSearch search(matter, mode, reactant_e, eng->params, pot);
    const int sst = search.run();
    write_image(band->positions, *matter, static_cast<long>(band->n_atoms));
    out->iterations = search.getIterationCount();
    out->surface_epoch = pot->surfaceEpoch();
    out->status = sst;
    return stamp_rc(eng, EON_RELAX_OK);
  } catch (const eonc::SurfaceRecoverable &rec) {
    out->status = -1;
    return stamp_rc(eng, rec.rc);
  } catch (const std::exception &) {
    out->status = -1;
    eng->unusable = true;
    return stamp_rc(eng, EON_RELAX_SURFACE_FATAL);
  }
}

◆ eon_relax_set_surface_epoch()

EON_RELAX_API int eon_relax_set_surface_epoch	(	EonRelaxEngine *	eng,
		uint64_t	epoch )

Definition at line 316 of file RelaxEngineAbi.cpp.

                                                                     {
  if (!eng) {
    return EON_RELAX_NULL_ENGINE;
  }
  if (eng->unusable) {
    return stamp_rc(eng, EON_RELAX_SURFACE_FATAL);
  }
  eng->epoch = epoch;
  if (eng->step_pot) {
    eng->step_pot->setEpoch(epoch);
  }
  eng->last_rc = EON_RELAX_OK;
  return EON_RELAX_OK;
}

◆ eon_relax_status_name()

EON_RELAX_API const char * eon_relax_status_name	(	eon_relax_kind_t	kind,
		int	status )

NULL if kind or status is unknown.

Definition at line 641 of file RelaxEngineAbi.cpp.

                                                                     {
  if (kind == EON_RELAX_KIND_NEB) {
    switch (status) {
    case EON_RELAX_NEB_GOOD:
      return "GOOD";
    case EON_RELAX_NEB_INIT:
      return "INIT";
    case EON_RELAX_NEB_BAD_MAX_ITERATIONS:
      return "BAD_MAX_ITERATIONS";
    case EON_RELAX_NEB_RUNNING:
      return "RUNNING";
    case EON_RELAX_NEB_MAX_UNCERTAINTY:
      return "MAX_UNCERTAINTY";
    default:
      return nullptr;
    }
  }
  if (kind == EON_RELAX_KIND_SADDLE) {
    const auto msg = MinModeSaddleSearch::statusMessage(status);
    if (msg == "Unknown status") {
      return nullptr;
    }
    return msg.data();
  }
  return nullptr;
}

◆ eon_relax_step()

EON_RELAX_API int eon_relax_step	(	EonRelaxEngine *	eng,
		eon_relax_band_t *	band,
		eon_relax_surface_fn	surface,
		void *	user,
		eon_relax_outcome_t *	out )

One band optimizer step (kind=NEB only).

The first call on a fresh or reset engine initializes the band state from the caller's positions and captures the baseline force; every call syncs band->positions in (the host may have moved images between steps), assembles NEB forces on the host surface, takes ONE optimizer step, and writes the stepped INTERIOR positions back (endpoints are the caller's and are never rewritten, so the caller's frame survives eOn's own cell wrapping). Climbing-image activation follows the engine's own trigger rule; saddle POLICY (MMF bursts, resampling, acquisition) stays with the host. outcome.status is RUNNING until convergenceForce() reaches the configured tolerance (GOOD), host variance exceeds the GP-surrogate threshold (MAX_UNCERTAINTY), or neb.max_iterations is hit (BAD_MAX_ITERATIONS). surface and user must not change across steps without an eon_relax_reset.

Definition at line 460 of file RelaxEngineAbi.cpp.

                                             {
  if (!eng) {
    return EON_RELAX_NULL_ENGINE;
  }
  if (eng->unusable) {
    return fail_out(eng, out, EON_RELAX_SURFACE_FATAL, eng->kind, eng->epoch);
  }
  if (!band) {
    return fail_out(eng, out, EON_RELAX_NULL_BAND, eng->kind, eng->epoch);
  }
  if (!surface) {
    return fail_out(eng, out, EON_RELAX_NULL_SURFACE, eng->kind, eng->epoch);
  }
  if (!out) {
    return stamp_rc(eng, EON_RELAX_NULL_OUTCOME);
  }
  if (eng->kind == EON_RELAX_KIND_SADDLE) {
    return fail_out(eng, out, EON_RELAX_INVALID_PARAMETER, eng->kind,
                    eng->epoch);
  }
  if (eng->kind != EON_RELAX_KIND_NEB) {
    return fail_out(eng, out, EON_RELAX_UNKNOWN_KIND, eng->kind, eng->epoch);
  }
  if (band->n_atoms <= 0) {
    return fail_out(eng, out, EON_RELAX_NATOMS, EON_RELAX_KIND_NEB, eng->epoch);
  }
  if (!band->positions) {
    return fail_out(eng, out, EON_RELAX_NULL_POSITIONS, EON_RELAX_KIND_NEB,
                    eng->epoch);
  }
  if (!band->atomic_nrs) {
    return fail_out(eng, out, EON_RELAX_NULL_ATOMIC_NRS, EON_RELAX_KIND_NEB,
                    eng->epoch);
  }
  if (!band->boxes) {
    return fail_out(eng, out, EON_RELAX_NULL_BOXES, EON_RELAX_KIND_NEB,
                    eng->epoch);
  }
  if (band->version.major != EON_RELAX_ABI_MAJOR) {
    return fail_out(eng, out, EON_RELAX_ABI_MISMATCH, EON_RELAX_KIND_NEB,
                    eng->epoch);
  }
  const int mass_rc = masses_ok(band);
  if (mass_rc != EON_RELAX_OK) {
    return fail_out(eng, out, mass_rc, EON_RELAX_KIND_NEB, eng->epoch);
  }
  stamp_outcome(out, EON_RELAX_KIND_NEB, eng->epoch);
  if (eng->step_neb && (band->n_atoms != eng->step_neb->atoms ||
                        band->n_images != eng->step_neb->numImages + 2)) {
    out->status = -1;
    return stamp_rc(eng, EON_RELAX_INVALID_PARAMETER);
  }
  if (band->n_images < 3) {
    out->status = -1;
    return stamp_rc(eng, EON_RELAX_BAND_TOO_SHORT);
  }
  const int64_t want =
      static_cast<int64_t>(eng->params.neb_options().image_count) + 2;
  if (band->n_images != want) {
    out->status = -1;
    return stamp_rc(eng, EON_RELAX_BAND_SIZE);
  }
  if (eng->step_neb &&
      (eng->step_surface != surface || eng->step_user != user)) {
    out->status = -1;
    return stamp_rc(eng, EON_RELAX_INVALID_PARAMETER);
  }
 
  try {
    if (!eng->step_neb) {
      eng->step_pot = std::make_shared<eonc::HostSurfacePotential>(
          surface, user, eng->epoch);
      std::vector<Matter> path;
      path.reserve(static_cast<size_t>(band->n_images));
      for (int64_t i = 0; i < band->n_images; ++i) {
        Matter img(eng->step_pot, eng->params);
        fill_matter(img, band, static_cast<long>(i), eng->epoch);
        path.push_back(std::move(img));
      }
      eng->step_neb = std::make_unique<NudgedElasticBand>(
          std::move(path), eng->params, eng->step_pot);
      eng->step_pot->bindPath(eng->step_neb->path);
      dirty_endpoints(*eng->step_neb);
      eng->step_neb->E_ref =
          std::min(eng->step_neb->path[0]->getPotentialEnergy(),
                   eng->step_neb->path[eng->step_neb->numImages + 1]
                       ->getPotentialEnergy());
      eng->step_neb->updateForces();
      eng->step_objf = std::make_shared<NEBObjectiveFunction>(
          eng->step_neb.get(), eng->params);
      eng->step_opt = eonc::helpers::create::mkOptim(
          eng->step_objf, eng->params.neb_options().opt_method, eng->params);
      eng->step_surface = surface;
      eng->step_user = user;
      eng->step_baseline = eng->step_neb->convergenceForce();
      eng->step_iteration = 0;
    } else {
      // The host may have moved images between steps (acquisition,
      // reparameterization); resync and mark the band dirty.
      for (int64_t i = 0; i < band->n_images; ++i) {
        fill_matter(*eng->step_neb->path[static_cast<size_t>(i)], band,
                    static_cast<long>(i), eng->epoch);
      }
      eng->step_neb->movedAfterForceCall = true;
      eng->step_neb->updateForces();
    }
 
    NudgedElasticBand &neb = *eng->step_neb;
    const double convForce = neb.convergenceForce();
    const auto &ci_opt = eng->params.neb_options().climbing_image;
    const bool ci_active =
        ci_opt.enabled &&
        (convForce < eng->step_baseline * ci_opt.trigger_factor ||
         convForce < ci_opt.trigger_force);
    neb.setCIEnabled(ci_active);
 
    const double force_tol = eng->params.neb_options().force_tolerance;
    const long max_iter = eng->params.neb_options().max_iterations;
    int status = EON_RELAX_NEB_RUNNING;
    if (eng->step_objf && eng->step_objf->isUncertain()) {
      status = EON_RELAX_NEB_MAX_UNCERTAINTY;
    } else if (convForce <= force_tol) {
      status = EON_RELAX_NEB_GOOD;
    } else if (eng->step_iteration >= max_iter) {
      status = EON_RELAX_NEB_BAD_MAX_ITERATIONS;
    } else {
      eng->step_opt->step(eng->params.optimizer_options().max_move);
      ++eng->step_iteration;
      neb.updateForces();
      if (eng->step_objf && eng->step_objf->isUncertain()) {
        status = EON_RELAX_NEB_MAX_UNCERTAINTY;
      } else if (neb.convergenceForce() <= force_tol) {
        status = EON_RELAX_NEB_GOOD;
      } else if (eng->step_iteration >= max_iter) {
        status = EON_RELAX_NEB_BAD_MAX_ITERATIONS;
      }
    }
 
    // Interior images only: eOn never moves the endpoints, and Matter
    // wraps positions into the cell, so writing them back would hand
    // the caller a different frame than the one it supplied.
    for (int64_t i = 1; i + 1 < band->n_images; ++i) {
      write_image(band->positions + i * 3 * band->n_atoms,
                  *neb.path[static_cast<size_t>(i)],
                  static_cast<long>(band->n_atoms));
    }
    out->status = status;
    out->iterations = eng->step_iteration;
    out->climbing_image = neb.climbingImage;
    out->max_force = neb.convergenceForce();
    out->surface_epoch = eng->step_pot->surfaceEpoch();
    return stamp_rc(eng, EON_RELAX_OK);
  } catch (const eonc::SurfaceRecoverable &rec) {
    out->status = -1;
    clear_stepper(eng);
    return stamp_rc(eng, rec.rc);
  } catch (const std::exception &) {
    out->status = -1;
    eng->unusable = true;
    return stamp_rc(eng, EON_RELAX_SURFACE_FATAL);
  }
}

◆ eon_relax_version_hash()

EON_RELAX_API uint64_t eon_relax_version_hash ( void )

64-bit FNV-1a hash of eon_relax_version_hash_str().

Copied to outcome.version_hash.

Definition at line 278 of file RelaxEngineAbi.cpp.

                                      {
  return fnv1a64(eon_relax_version_hash_str());
}

◆ eon_relax_version_hash_str()

EON_RELAX_API const char * eon_relax_version_hash_str ( void )

Immortal dest identity string.

Never NULL.

Definition at line 271 of file RelaxEngineAbi.cpp.

                                             {
  static const std::string id =
      VERSION + "+git." + GIT_HASH_FULL + "+feat." +
      std::to_string(fnv1a64(FEATURES_STRING.c_str()));
  return id.c_str();
}

Classes

Macros

Typedefs

Enumerations

Functions