eonc::neb::OCINEBController Class Reference

Goswami (in prep). More...

#include <NEBOcinebController.h>

Classes
struct	Config
struct	MMFResult

Public Member Functions
	OCINEBController (const Config &cfg)
void	initBaseline (double baseline_force)
bool	shouldTrigger (double convForce, bool ci_active, long climbingImage, long numImages, int ciStabilityCounter) const
MMFResult	run (eonc::NudgedElasticBand &neb, double convForce)
void	resetStability ()
void	updateStability (long climbingImage)
int	stabilityCount () const
double	threshold () const

Static Public Member Functions
static Config	fromParams (const Parameters &params)
static bool	walkHelped (double walkedForce, double convForce, int mmfStatus)
static bool	convergedClimb (double bandForce, double forceTolerance, int mmfStatus)

Private Member Functions
int	runDimer (eonc::NudgedElasticBand &neb, double &alignment)
void	updateThresholdSuccess (double convForce, double newForce)
void	updateThresholdBackoff (double alignment)

Private Attributes
Config	cfg_
double	current_threshold_ {-1.0}
double	baseline_force_ {-1.0}
long	previousClimbingImage_ {-1}
int	ciStabilityCounter_ {0}
int	mmf_iterations_used_ {0}
bool	has_cached_mode_ {false}
AtomMatrix	cached_mode_

Detailed Description

Goswami (in prep).

Controller for OCINEB hybrid dimer refinement of the climbing image. Manages MMF triggering, threshold adaptation, and backoff logic.

Definition at line 26 of file NEBOcinebController.h.

Constructor & Destructor Documentation

OCINEBController()

eonc::neb::OCINEBController::OCINEBController ( const Config & cfg )

explicit

Definition at line 38 of file NEBOcinebController.cpp.

    : cfg_{cfg} {}

Member Function Documentation

convergedClimb()

bool eonc::neb::OCINEBController::convergedClimb ( double bandForce, double forceTolerance, int mmfStatus )

inlinestatic

Definition at line 65 of file NEBOcinebController.h.

                                            {
    return bandForce < forceTolerance && mmfStatus != -2;
  }

fromParams()

OCINEBController::Config eonc::neb::OCINEBController::fromParams ( const Parameters & params )

static

Definition at line 23 of file NEBOcinebController.cpp.

                                                     {
  auto &ci = params.neb_options().climbing_image;
  auto &r = ci.ocineb;
  return Config{
      r.use_mmf,
      r.trigger_force,
      r.trigger_factor,
      r.max_steps,
      r.ci_stability_count,
      r.angle_tol,
      params.neb_options().force_tolerance,
      r.restore_unhelpful,
  };
}

initBaseline()

void eonc::neb::OCINEBController::initBaseline

(

double

baseline_force

)

Definition at line 41 of file NEBOcinebController.cpp.

                                                         {
  baseline_force_ = baseline_force;
  current_threshold_ = std::max(baseline_force_ * cfg_.trigger_factor,
                                2.0 * cfg_.force_tolerance);
}

resetStability()

void eonc::neb::OCINEBController::resetStability ( )

inline

Definition at line 70 of file NEBOcinebController.h.

{ ciStabilityCounter_ = 0; }

run()

OCINEBController::MMFResult eonc::neb::OCINEBController::run	(	eonc::NudgedElasticBand &	neb,
		double	convForce )

Definition at line 71 of file NEBOcinebController.cpp.

                                                                    {
  auto *log = eonc::log::get();
 
  QUILL_LOG_DEBUG(log,
                  "Triggering MMF.  Force: {:.4f}, Threshold: {:.4f} "
                  "({:.2f}x baseline)",
                  convForce, current_threshold_,
                  current_threshold_ / baseline_force_);
 
  // The dimer moves this image. updateForces() may then hop
  // climbingImage to a neighbor; band CI force is that neighbor.
  const long walked = neb.climbingImage;
  AtomMatrix savedPositions = neb.path[walked]->getPositions();
  // The saved geometry is evaluated already; a restore puts its forces
  // back instead of asking the potential again.
  const AtomMatrix savedForces = neb.path[walked]->getForcesRaw();
  const double savedEnergy = neb.path[walked]->getPotentialEnergy();
 
  double alignment = 0.0;
  int mmfResult = runDimer(neb, alignment);
 
  // Always update forces after MMF
  neb.movedAfterForceCall = true;
  neb.updateForces();
  double newForce = neb.convergenceForce();
 
  // A positive-curvature walk can put the band force under tolerance
  // while the climbing image sits in a well. Restore that image
  // before accepting the band.
  if (convergedClimb(newForce, cfg_.force_tolerance, mmfResult)) {
    QUILL_LOG_DEBUG(log, "NEB converged after MMF. Force: {:.4f}", newForce);
    return {newForce, true, false};
  }
 
  const double walkedForce = neb.path[walked]->getForcesFreeV().norm();
  const bool mmfHelped = walkHelped(walkedForce, convForce, mmfResult);
 
  if (mmfHelped) {
    updateThresholdSuccess(convForce, walkedForce);
    QUILL_LOG_DEBUG(log,
                    "MMF helped (status={}, walked={}, now_ci={}). "
                    "Walked force: {:.4f} -> {:.4f} ({:.2f}x baseline). "
                    "Band CI force: {:.4f}. New threshold: {:.4f}",
                    mmfResult, walked, neb.climbingImage, convForce,
                    walkedForce, walkedForce / baseline_force_, newForce,
                    current_threshold_);
  } else {
    // Frontiers OCI-NEB (doi:10.3389/fchem.2026.1807063, Algorithm 1)
    // restores only on positive curvature (status -2). Alignment
    // failure keeps the walked CI and applies the linear penalty.
    // restore_unhelpful also restores on alignment reject / force
    // increase on the walked image. Default false: the paper setting.
    const bool restore = cfg_.restore_unhelpful || mmfResult == -2;
    if (restore) {
      neb.path[walked]->setPositions(savedPositions);
      neb.path[walked]->setEvaluation(savedForces, savedEnergy);
      neb.movedAfterForceCall = true;
      has_cached_mode_ = false;
      newForce = convForce;
    }
    updateThresholdBackoff(alignment);
    QUILL_LOG_DEBUG(
        log,
        "MMF backoff (status={}, walked={}, now_ci={}). "
        "Walked force: {:.4f} -> {:.4f}, band CI: {:.4f}, "
        "Alignment:  {:.3f}. {}New threshold: {:.4f} ({:.2f}x baseline)",
        mmfResult, walked, neb.climbingImage, convForce, walkedForce, newForce,
        alignment, restore ? "Restored CI. " : "", current_threshold_,
        current_threshold_ / baseline_force_);
  }
 
  bool shouldReset =
      (savedPositions - neb.path[walked]->getPositions()).norm() >
      neb.params.optimizer_options().max_move *
          neb.params.neb_options().image_count;
 
  if (shouldReset) {
    QUILL_LOG_DEBUG(log, "Resetting optimization history.");
  }
 
  ciStabilityCounter_ = 0;
 
  return {newForce, false, shouldReset};
}

runDimer()

int eonc::neb::OCINEBController::runDimer ( eonc::NudgedElasticBand & neb, double & alignment )

private

Definition at line 157 of file NEBOcinebController.cpp.

                                                  {
  auto *log = eonc::log::get();
  alignment = 0.0;
 
  if (neb.climbingImage <= 0 || neb.climbingImage > neb.numImages) {
    QUILL_LOG_WARNING(log, "Invalid climbing image for MMF:  {}",
                      neb.climbingImage);
    return -1;
  }
 
  AtomMatrix initialMode;
  if (has_cached_mode_) {
    initialMode = cached_mode_;
  } else {
    initialMode = *neb.tangent[neb.climbingImage];
  }
  double tangentNorm = initialMode.norm();
  if (tangentNorm < 1e-8) {
    QUILL_LOG_WARNING(log, "Tangent too small for MMF initialization");
    return -1;
  }
  initialMode /= tangentNorm;
 
  auto tempMinModeSearch = std::make_shared<MinModeSaddleSearch>(
      neb.path[neb.climbingImage], initialMode,
      neb.path[neb.climbingImage]->getPotentialEnergy(), neb.params, neb.pot);
 
  int minModeStatus;
  try {
    minModeStatus = tempMinModeSearch->run(cfg_.max_steps);
  } catch (const eonc::DimerModeRestoredException &) {
    minModeStatus = MinModeSaddleSearch::STATUS_DIMER_RESTORED_BEST;
    QUILL_LOG_DEBUG(log, "MMF:  Dimer restored to best state");
  } catch (const eonc::DimerModeLostException &) {
    minModeStatus = MinModeSaddleSearch::STATUS_DIMER_LOST_MODE;
    QUILL_LOG_WARNING(log, "Dimer lost mode during MMF refinement");
  }
 
  mmf_iterations_used_ += tempMinModeSearch->iteration;
 
  double eigenvalue = tempMinModeSearch->getEigenvalue();
  if (eigenvalue > 0.0) {
    QUILL_LOG_WARNING(log,
                      "MMF skipped: Positive curvature detected (eig={:.4f}).",
                      eigenvalue);
    return -2;
  }
 
  AtomMatrix finalModeMatrix = tempMinModeSearch->getEigenvector();
  VectorXd finalMode =
      VectorXd::Map(finalModeMatrix.data(), finalModeMatrix.size());
  VectorXd currentTangent =
      VectorXd::Map(neb.tangent[neb.climbingImage]->data(),
                    neb.tangent[neb.climbingImage]->size());
  if (finalMode.size() != currentTangent.size()) {
    QUILL_LOG_WARNING(log,
                      "MMF mode size {} != tangent size {}; skip alignment",
                      finalMode.size(), currentTangent.size());
    alignment = 0.0;
  } else if (finalMode.norm() == 0.0 || currentTangent.norm() == 0.0) {
    alignment = 0.0;
  } else {
    alignment =
        std::abs(finalMode.normalized().dot(currentTangent.normalized()));
  }
 
  if (minModeStatus == MinModeSaddleSearch::STATUS_GOOD ||
      minModeStatus == MinModeSaddleSearch::STATUS_DIMER_RESTORED_BEST) {
    if (alignment < cfg_.angle_tol) {
      QUILL_LOG_WARNING(
          log,
          "MMF converged/restored but mode drifted (alignment={:.3f} < {:.3f})",
          alignment, cfg_.angle_tol);
      return -1;
    }
    cached_mode_ = finalModeMatrix;
    has_cached_mode_ = true;
    return 0;
  } else if (minModeStatus == MinModeSaddleSearch::STATUS_BAD_MAX_ITERATIONS) {
    return 1;
  } else {
    QUILL_LOG_WARNING(log, "MMF failed.  Mode-tangent alignment: {:.3f}",
                      alignment);
    return -1;
  }
}

shouldTrigger()

bool eonc::neb::OCINEBController::shouldTrigger	(	double	convForce,
		bool	ci_active,
		long	climbingImage,
		long	numImages,
		int	ciStabilityCounter ) const

Definition at line 47 of file NEBOcinebController.cpp.

                                                                   {
  if (!cfg_.use_mmf || !ci_active)
    return false;
  if (climbingImage <= 0 || climbingImage > numImages)
    return false;
  if (ciStabilityCounter <= static_cast<int>(cfg_.ci_stability_count))
    return false;
  if (convForce <= cfg_.force_tolerance)
    return false;
  return convForce < current_threshold_;
}

stabilityCount()

int eonc::neb::OCINEBController::stabilityCount ( ) const

inline

Definition at line 72 of file NEBOcinebController.h.

{ return ciStabilityCounter_; }

threshold()

double eonc::neb::OCINEBController::threshold ( ) const

inline

Definition at line 73 of file NEBOcinebController.h.

{ return current_threshold_; }

updateStability()

void eonc::neb::OCINEBController::updateStability

(

long

climbingImage

)

Definition at line 61 of file NEBOcinebController.cpp.

                                                         {
  if (climbingImage == previousClimbingImage_) {
    ciStabilityCounter_++;
  } else {
    ciStabilityCounter_ = 0;
    previousClimbingImage_ = climbingImage;
    has_cached_mode_ = false;
  }
}

updateThresholdBackoff()

void eonc::neb::OCINEBController::updateThresholdBackoff ( double alignment )

private

Definition at line 253 of file NEBOcinebController.cpp.

                                                              {
  double alpha = std::clamp(alignment, 0.0, 1.0);
  double penalty_factor = 0.5 + 0.5 * alpha;
  current_threshold_ = baseline_force_ * cfg_.trigger_factor * penalty_factor;
  // Lower bound on the MMF trigger threshold. Scaled by force_tolerance so
  // the MMF gate never collapses to zero when the NEB is already near
  // convergence, but also capped by the trigger_factor envelope so a
  // loose force_tolerance cannot push min_threshold above the cap and
  // starve MMF activation.
  double min_threshold = 2.0 * cfg_.force_tolerance;
  current_threshold_ = std::max(current_threshold_, min_threshold);
}

updateThresholdSuccess()

void eonc::neb::OCINEBController::updateThresholdSuccess ( double convForce, double newForce )

private

Definition at line 245 of file NEBOcinebController.cpp.

                                                               {
  current_threshold_ = newForce * (0.5 + 0.4 * (newForce / convForce));
  double max_threshold = std::max(baseline_force_ * cfg_.trigger_factor,
                                  2.0 * cfg_.force_tolerance);
  current_threshold_ = std::min(current_threshold_, max_threshold);
}

walkHelped()

bool eonc::neb::OCINEBController::walkHelped ( double walkedForce, double convForce, int mmfStatus )

inlinestatic

Definition at line 58 of file NEBOcinebController.h.

                                                                              {
    return walkedForce < convForce && mmfStatus != -2;
  }

Member Data Documentation

baseline_force_

double eonc::neb::OCINEBController::baseline_force_ {-1.0}

private

Definition at line 78 of file NEBOcinebController.h.

{-1.0};

cached_mode_

AtomMatrix eonc::neb::OCINEBController::cached_mode_

private

Definition at line 85 of file NEBOcinebController.h.

cfg_

Config eonc::neb::OCINEBController::cfg_

private

Definition at line 76 of file NEBOcinebController.h.

ciStabilityCounter_

int eonc::neb::OCINEBController::ciStabilityCounter_ {0}

private

Definition at line 80 of file NEBOcinebController.h.

{0};

current_threshold_

double eonc::neb::OCINEBController::current_threshold_ {-1.0}

private

Definition at line 77 of file NEBOcinebController.h.

{-1.0};

has_cached_mode_

bool eonc::neb::OCINEBController::has_cached_mode_ {false}

private

Definition at line 84 of file NEBOcinebController.h.

{false};

mmf_iterations_used_

int eonc::neb::OCINEBController::mmf_iterations_used_ {0}

private

Definition at line 81 of file NEBOcinebController.h.

{0};

previousClimbingImage_

long eonc::neb::OCINEBController::previousClimbingImage_ {-1}

private

Definition at line 79 of file NEBOcinebController.h.

{-1};

---

The documentation for this class was generated from the following files:

• /home/runner/work/eOn/eOn/include/eon/NEBOcinebController.h
• /home/runner/work/eOn/eOn/client/NEBOcinebController.cpp