NEBOcinebController.h

Go to the documentation of this file.

/*
** This file is part of eOn.
**
** SPDX-License-Identifier: BSD-3-Clause
**
** Copyright (c) 2010--present, eOn Development Team
** All rights reserved.
**
** Repo:
** https://github.com/TheochemUI/eOn
*/
#pragma once
 
#include "Eigen.h"
#include "Parameters.h"
 
namespace eonc {
class NudgedElasticBand; // forward declaration
}
 
namespace eonc::neb {

class OCINEBController {
public:
  struct Config {
    bool use_mmf;
    double trigger_force;
    double trigger_factor;
    long max_steps;
    long ci_stability_count;
    double angle_tol;
    double force_tolerance;
    bool restore_unhelpful;
  };
 
  static Config fromParams(const Parameters &params);
  explicit OCINEBController(const Config &cfg);
 
  void initBaseline(double baseline_force);
 
  bool shouldTrigger(double convForce, bool ci_active, long climbingImage,
                     long numImages, int ciStabilityCounter) const;
 
  struct MMFResult {
    double newForce;
    bool convergedAfterMMF;
    bool shouldResetOptimizer;
  };
 
  MMFResult run(eonc::NudgedElasticBand &neb, double convForce);
 
  // Help is the walked image's raw force, not band convergenceForce().
  // After a downhill dimer step maxEnergyImage can hop; the band CI
  // force is then a neighbor and is the wrong score for restore.
  static bool walkHelped(double walkedForce, double convForce, int mmfStatus) {
    return walkedForce < convForce && mmfStatus != -2;
  }
 
  // Positive curvature (status -2) is a well, not a saddle. A band
  // force under tolerance after that walk is not convergence; run()
  // restores the climbing image first.
  static bool convergedClimb(double bandForce, double forceTolerance,
                             int mmfStatus) {
    return bandForce < forceTolerance && mmfStatus != -2;
  }
 
  void resetStability() { ciStabilityCounter_ = 0; }
  void updateStability(long climbingImage);
  int stabilityCount() const { return ciStabilityCounter_; }
  double threshold() const { return current_threshold_; }
 
private:
  Config cfg_;
  double current_threshold_{-1.0};
  double baseline_force_{-1.0};
  long previousClimbingImage_{-1};
  int ciStabilityCounter_{0};
  int mmf_iterations_used_{0};
 
  // Warm-start: cache converged eigenvector for next dimer call
  bool has_cached_mode_{false};
  AtomMatrix cached_mode_;
 
  int runDimer(eonc::NudgedElasticBand &neb, double &alignment);
  void updateThresholdSuccess(double convForce, double newForce);
  void updateThresholdBackoff(double alignment);
};
 
} // namespace eonc::neb