RelaxEngineAbi.cpp File Reference

#include "eon/relax/eon_relax_engine.h"
#include "eon/Eigen.h"
#include "eon/Matter.h"
#include "eon/MinModeSaddleSearch.h"
#include "eon/NudgedElasticBand.h"
#include "eon/Optimizer.h"
#include "eon/Parameters.h"
#include "eon_relax_engine.capnp.h"
#include "relax/HostSurfacePotential.h"
#include "version.h"
#include <capnp/serialize.h>
#include <kj/array.h>
#include <kj/common.h>
#include <algorithm>
#include <cmath>
#include <cstdio>
#include <cstring>
#include <memory>
#include <new>
#include <stdexcept>
#include <string>
#include <vector>

Go to the source code of this file.

Classes
struct	EonRelaxEngine
class	Matter
class	MinModeSaddleSearch
class	NEBObjectiveFunction
class	NudgedElasticBand
class	Optimizer
	Abstract base of the structure optimizers. More...
class	Parameters
struct	ParametersLoadAccess
	Write hole for INI/JSON loaders and nanobind property setters. More...

Functions
uint64_t	eon_relax_version_hash (void)
	64-bit FNV-1a hash of eon_relax_version_hash_str().
static int	stamp_rc (EonRelaxEngine *eng, int rc)
static int	fail_out (EonRelaxEngine *eng, eon_relax_outcome_t *out, int rc, eon_relax_kind_t kind, uint64_t epoch)
static void	clear_stepper (EonRelaxEngine *eng)
int	eon_relax_abi_version (void)
	(major << 16) | minor.
int	eon_relax_available (void)
int	eon_relax_abi_stamp (eon_relax_version_t *out)
const char *	eon_relax_version_hash_str (void)
	Immortal dest identity string.
EonRelaxEngine *	eon_relax_create (const void *config, size_t config_len, char *errbuf, size_t errlen)
	Create.
int	eon_relax_set_surface_epoch (EonRelaxEngine *eng, uint64_t epoch)
int	eon_relax_last_error (const EonRelaxEngine *eng)
	Last named create/run/step/reset/set_epoch rc on this handle.
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.
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).
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.
void	eon_relax_destroy (EonRelaxEngine *eng)
const char *	eon_relax_status_name (eon_relax_kind_t kind, int status)
	NULL if kind or status is unknown.

Function Documentation

clear_stepper()

void clear_stepper ( EonRelaxEngine * eng )

static

Definition at line 243 of file RelaxEngineAbi.cpp.

                                               {
  eng->step_opt.reset();
  eng->step_objf.reset();
  eng->step_neb.reset();
  eng->step_pot.reset();
  eng->step_surface = nullptr;
  eng->step_user = nullptr;
  eng->step_baseline = 0.0;
  eng->step_iteration = 0;
}

eon_relax_abi_stamp()

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()

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()

int eon_relax_available

(

void

)

Definition at line 260 of file RelaxEngineAbi.cpp.

{ return 1; }

eon_relax_create()

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()

void eon_relax_destroy

(

EonRelaxEngine *

eng

)

Definition at line 637 of file RelaxEngineAbi.cpp.

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

eon_relax_last_error()

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()

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()

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()

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()

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()

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()

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()

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();
}

fail_out()

int fail_out ( EonRelaxEngine * eng, eon_relax_outcome_t * out, int rc, eon_relax_kind_t kind, uint64_t epoch )

static

Definition at line 234 of file RelaxEngineAbi.cpp.

                                                           {
  if (out) {
    stamp_outcome(out, kind, epoch);
    out->status = -1;
  }
  return stamp_rc(eng, rc);
}

stamp_rc()

int stamp_rc ( EonRelaxEngine * eng, int rc )

static

Definition at line 227 of file RelaxEngineAbi.cpp.

                                                 {
  if (eng) {
    eng->last_rc = rc;
  }
  return rc;
}