Loading...
Searching...
No Matches
eonc::Potential Class Referenceabstract

#include <Potential.h>

Inheritance diagram for eonc::Potential:

Public Types

enum class  PotLayout : unsigned { InProcess = 1u << 0 , NeedsWorkingDirectory = 1u << 1 , Subprocess = 1u << 2 }
 How the pot is executed. Combine with bitwise or. More...

Public Member Functions

void recordForceCall () noexcept
 Charge one evaluated geometry to this potential and its owning registry.
IPotRegistry & registry () const noexcept
 The registry this potential charges its force calls to.
 Potential (PotType a_ptype)
 Production default: construction-scope registry, else PotRegistry::get().
 Potential (PotType a_ptype, IPotRegistry &registry)
 Test seam: injected registry, no process-default get() counters.
 Potential (PotType a_ptype, const Parameters &p)
 Potential (const Parameters &a_params)
virtual ~Potential ()
virtual void force (long nAtoms, const double *positions, const int *atomicNrs, double *forces, double *energy, double *variance, const double *box)=0
void force (std::span< const double > positions, std::span< const int > atomicNrs, std::span< double > forces, double *energy, double *variance, std::span< const double > box)
 C++ call site: size-checked view over the raw FFI force().
virtual void setFixedMask (long nAtoms, const double *isFixed)
 Optional frozen-atom mask (nAtoms*3, 1.0 = fixed).
std::tuple< double, AtomMatrix > get_ef (const AtomMatrix &pos, const VectorXi &atmnrs, const Matrix3d &box)
PotType getType () const
virtual unsigned long long surfaceEpoch () const noexcept
 Host-visible surface generation.
virtual double finiteCutoff () const noexcept
 Finite interaction range in position length units.
virtual bool isSurrogate () const noexcept
 Whether this is a surrogate (GP) potential.
virtual bool requiresIsolatedMoleculeLayout () const noexcept
 True for molecular QM / non-PBC backends (NWChem socket, ASE ORCA/NWChem, …).
virtual bool isThreadSafe () const noexcept
 Whether this potential's force() can be called from multiple threads on the SAME instance.
virtual unsigned layoutFlags () const noexcept
virtual bool isSharedInstanceThreadSafe () const noexcept
 Conservative gate for sharing one Potential instance across threads.
virtual bool needsPerImageInstance () const noexcept
 Whether NEB should create separate Potential instances per image for true parallel force evaluation.
virtual std::shared_ptr< Potential > clonePotential () const
 Independent instance that does not reload from disk.
virtual bool supportsBatchEvaluation () const noexcept
 Whether this potential supports batched evaluation of N systems in a single call.
virtual void bindBand (const std::vector< std::shared_ptr< Matter > > &)
 NEB calls this with the finished band before the first force evaluation, so a host surface can name each image.
virtual bool forwardsStoredCell () const noexcept
 A host that owns the cell reads the stored matrix.
virtual bool computesStress () const noexcept
 True when force() leaves a Cauchy stress that cauchyStress() can read until the next force() on this instance.
virtual Matrix3d cauchyStress () const
 Cauchy stress in eV/Angstrom^3.
virtual void forceBatchOwned (long nSystems, long nAtoms, const double *const *positions, const int *const *atomicNrs, double *const *forces, double *energies, double *variances, const double *const *boxes, const long *owners)
 Evaluate forces for N systems in a single call.
virtual void forceBatch (long nSystems, long nAtoms, const double *const *positions, const int *const *atomicNrs, double *const *forces, double *energies, double *variances, const double *const *boxes)
virtual double hessianRange () const noexcept
 Distance beyond which every Hessian block between two atoms is exactly zero, in position length units.

Public Attributes

std::atomic< size_t > forceCallCounter

Protected Attributes

PotType ptype

Private Attributes

IPotRegistry & registry_
std::shared_ptr< RegistryLifetime > lifetime_
uint64_t m_registry_id
IPotRegistry::TimePoint m_created_at
bool force_serial_ {false}

Detailed Description

Definition at line 45 of file Potential.h.

Member Enumeration Documentation

◆ PotLayout

enum class eonc::Potential::PotLayout : unsigned
strong

How the pot is executed. Combine with bitwise or.

Enumerator
InProcess 
NeedsWorkingDirectory 
Subprocess 

Definition at line 154 of file Potential.h.

154 : unsigned {
155 InProcess = 1u << 0,
156 NeedsWorkingDirectory = 1u << 1,
157 Subprocess = 1u << 2,
158 };

Constructor & Destructor Documentation

◆ Potential() [1/4]

eonc::Potential::Potential ( PotType a_ptype)
explicit

Production default: construction-scope registry, else PotRegistry::get().

Definition at line 29 of file PotentialParams.cpp.

30 : Potential(a_ptype, tls_construction_registry ? *tls_construction_registry
31 : PotRegistry::get()) {}
static PotRegistry & get() noexcept
Process-lifetime singleton.
Potential(PotType a_ptype)
Production default: construction-scope registry, else PotRegistry::get().

◆ Potential() [2/4]

eonc::Potential::Potential ( PotType a_ptype,
IPotRegistry & registry )
inline

Test seam: injected registry, no process-default get() counters.

Definition at line 69 of file Potential.h.

70 : ptype{a_ptype}, registry_{registry}, lifetime_{registry.lifetime()},
71 m_registry_id{registry.on_created(a_ptype)},
72 m_created_at{IPotRegistry::Clock::now()}, forceCallCounter{0} {}
IPotRegistry & registry() const noexcept
The registry this potential charges its force calls to.
Definition Potential.h:63
std::atomic< size_t > forceCallCounter
Definition Potential.h:57
uint64_t m_registry_id
Definition Potential.h:52
std::shared_ptr< RegistryLifetime > lifetime_
Definition Potential.h:51
IPotRegistry & registry_
Definition Potential.h:50
PotType ptype
Definition Potential.h:47
IPotRegistry::TimePoint m_created_at
Definition Potential.h:53

◆ Potential() [3/4]

eonc::Potential::Potential ( PotType a_ptype,
const Parameters & p )

Definition at line 33 of file PotentialParams.cpp.

34 : Potential(a_ptype) {
36}
const potential_options_t & potential_options() const
bool thread_safe
When false, NEB/dimer/process_search never share one Potential across threads, even if the backend re...

◆ Potential() [4/4]

eonc::Potential::Potential ( const Parameters & a_params)
explicit

Definition at line 38 of file PotentialParams.cpp.

39 : Potential(a_params.potential_options().potential, a_params) {}

◆ ~Potential()

virtual eonc::Potential::~Potential ( )
inlinevirtual

Definition at line 80 of file Potential.h.

80 {
81 // The registry reference dangles once its owner is gone. The lifetime
82 // flag is a separate allocation and stays readable.
83 if (lifetime_ && lifetime_->alive.load(std::memory_order_acquire)) {
86 }
87 }

Member Function Documentation

◆ bindBand()

virtual void eonc::Potential::bindBand ( const std::vector< std::shared_ptr< Matter > > & )
inlinevirtual

NEB calls this with the finished band before the first force evaluation, so a host surface can name each image.

Reimplemented in eonc::HostSurfacePotential.

Definition at line 197 of file Potential.h.

197{}

◆ cauchyStress()

virtual Matrix3d eonc::Potential::cauchyStress ( ) const
inlinenodiscardvirtual

Cauchy stress in eV/Angstrom^3.

sigma = (1/V) dE/dε for the right strain h <- h (I+ε) at fixed fractional coordinates.

Reimplemented in LAMMPSPot, RgpotAdapter< RPot >, and SocketNWChemPot.

Definition at line 212 of file Potential.h.

212 {
213 throw std::logic_error("Potential::cauchyStress is not implemented");
214 }

◆ clonePotential()

virtual std::shared_ptr< Potential > eonc::Potential::clonePotential ( ) const
inlinenodiscardvirtual

Independent instance that does not reload from disk.

nullptr means the caller should use makePotential().

Reimplemented in MetatomicPotential.

Definition at line 184 of file Potential.h.

184 {
185 return nullptr;
186 }

◆ computesStress()

virtual bool eonc::Potential::computesStress ( ) const
inlinenodiscardvirtualnoexcept

True when force() leaves a Cauchy stress that cauchyStress() can read until the next force() on this instance.

Reimplemented in LAMMPSPot, RgpotAdapter< RPot >, and SocketNWChemPot.

Definition at line 208 of file Potential.h.

208{ return false; }

◆ finiteCutoff()

virtual double eonc::Potential::finiteCutoff ( ) const
inlinenodiscardvirtualnoexcept

Finite interaction range in position length units.

Deprecated. Override hessianRange() instead. The default hessianRange() returns this value, so an existing override still colors the finite-difference Hessian. 0 means the range is unknown.

Definition at line 134 of file Potential.h.

134{ return 0.0; }

◆ force() [1/2]

virtual void eonc::Potential::force ( long nAtoms,
const double * positions,
const int * atomicNrs,
double * forces,
double * energy,
double * variance,
const double * box )
pure virtual

◆ force() [2/2]

void eonc::Potential::force ( std::span< const double > positions,
std::span< const int > atomicNrs,
std::span< double > forces,
double * energy,
double * variance,
std::span< const double > box )
inline

C++ call site: size-checked view over the raw FFI force().

Definition at line 96 of file Potential.h.

98 {
99 if (positions.size() % 3 != 0 || positions.size() / 3 != atomicNrs.size() ||
100 forces.size() != positions.size() || box.size() != 9) {
101 throw std::invalid_argument("Potential::force span size mismatch");
102 }
103 force(static_cast<long>(atomicNrs.size()), positions.data(),
104 atomicNrs.data(), forces.data(), energy, variance, box.data());
105 }
virtual void force(long nAtoms, const double *positions, const int *atomicNrs, double *forces, double *energy, double *variance, const double *box)=0

◆ forceBatch()

virtual void eonc::Potential::forceBatch ( long nSystems,
long nAtoms,
const double *const * positions,
const int *const * atomicNrs,
double *const * forces,
double * energies,
double * variances,
const double *const * boxes )
inlinevirtual

Reimplemented in ASE, eonc::HostSurfacePotential, eonc::tunneling::RingPolymerPotential, MetatomicPotential, RgpotAdapter< RPot >, and RgpotPot.

Definition at line 234 of file Potential.h.

238 {
239 for (long i = 0; i < nSystems; i++) {
240 double var = 0;
241 force(nAtoms, positions[i], atomicNrs[i], forces[i], &energies[i], &var,
242 boxes[i]);
243 if (variances)
244 variances[i] = var;
246 }
247 }
void recordForceCall() noexcept
Charge one evaluated geometry to this potential and its owning registry.

◆ forceBatchOwned()

virtual void eonc::Potential::forceBatchOwned ( long nSystems,
long nAtoms,
const double *const * positions,
const int *const * atomicNrs,
double *const * forces,
double * energies,
double * variances,
const double *const * boxes,
const long * owners )
inlinevirtual

Evaluate forces for N systems in a single call.

Default: loops over force(). Override in potentials that support native batching (e.g. MetatomicPotential uses a single model.forward() for all N systems). forceBatch with an owner hint per system: a stable identity (a NEB image index) a potential that spreads a batch over calculators can route by, so the same calculator keeps seeing the same image and its stored state stays close to it. Default: the hint is ignored.

Reimplemented in RgpotPot.

Definition at line 223 of file Potential.h.

228 {
229 (void)owners;
230 forceBatch(nSystems, nAtoms, positions, atomicNrs, forces, energies,
231 variances, boxes);
232 }
virtual void forceBatch(long nSystems, long nAtoms, const double *const *positions, const int *const *atomicNrs, double *const *forces, double *energies, double *variances, const double *const *boxes)
Definition Potential.h:234

◆ forwardsStoredCell()

virtual bool eonc::Potential::forwardsStoredCell ( ) const
inlinenodiscardvirtualnoexcept

A host that owns the cell reads the stored matrix.

Pots that infer periodic boundaries from a non-zero box keep seeing a zero box when the image is not periodic.

Reimplemented in eonc::HostSurfacePotential.

Definition at line 202 of file Potential.h.

202 {
203 return false;
204 }

◆ get_ef()

std::tuple< double, AtomMatrix > eonc::Potential::get_ef ( const AtomMatrix & pos,
const VectorXi & atmnrs,
const Matrix3d & box )

Definition at line 114 of file Potential.cpp.

116 {
117 double energy{std::numeric_limits<double>::infinity()};
118 long nAtoms = static_cast<long>(pos.rows());
119 AtomMatrix forces{MatrixXd::Zero(nAtoms, 3)};
120 double var{0}; // no variance for true potentials
121 const auto n = static_cast<size_t>(nAtoms);
122 this->force(std::span<const double>(pos.data(), n * 3),
123 std::span<const int>(atmnrs.data(), n),
124 std::span<double>(forces.data(), n * 3), &energy, &var,
125 std::span<const double>(box.data(), 9));
127 if (!std::isfinite(energy) || !forces.allFinite()) {
128 throw std::runtime_error("Potential::get_ef: non-finite energy or forces");
129 }
130
131 return std::make_tuple(energy, forces);
132}
Eigen::Matrix< double, Eigen::Dynamic, 3, eOnStorageOrder > AtomMatrix
Definition Eigen.h:37

◆ getType()

PotType eonc::Potential::getType ( ) const
inlinenodiscard

Definition at line 118 of file Potential.h.

118{ return this->ptype; }

◆ hessianRange()

virtual double eonc::Potential::hessianRange ( ) const
inlinenodiscardvirtualnoexcept

Distance beyond which every Hessian block between two atoms is exactly zero, in position length units.

The default returns finiteCutoff(), so an override of that deprecated method still colors. 0, or any non-finite value, means the range is unknown. The finite-difference Hessian then stays one column per coordinate. A potential opts in by overriding this. An interaction cutoff is not this distance: a many-body kernel is nonzero out to twice its cutoff, and a kernel that merely has a cutoff field stays at 0.

Reimplemented in RgpotAdapter< RPot >.

Definition at line 259 of file Potential.h.

259 {
260#if defined(__GNUC__) || defined(__clang__)
261#pragma GCC diagnostic push
262#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
263#endif
264#if defined(_MSC_VER)
265#pragma warning(push)
266#pragma warning(disable : 4996)
267#endif
268 const double range = finiteCutoff();
269#if defined(_MSC_VER)
270#pragma warning(pop)
271#endif
272#if defined(__GNUC__) || defined(__clang__)
273#pragma GCC diagnostic pop
274#endif
275 return range;
276 }
virtual double finiteCutoff() const noexcept
Finite interaction range in position length units.
Definition Potential.h:134

◆ isSharedInstanceThreadSafe()

virtual bool eonc::Potential::isSharedInstanceThreadSafe ( ) const
inlinenodiscardvirtualnoexcept

Conservative gate for sharing one Potential instance across threads.

Defaults to isThreadSafe(); backends whose state lives outside the wrapper instance (global/common-block Fortran entry points) override this to false on their own classes.

Reimplemented in RgpotAdapter< RPot >.

Definition at line 167 of file Potential.h.

167 {
168 if (force_serial_)
169 return false;
170 return isThreadSafe();
171 }
virtual bool isThreadSafe() const noexcept
Whether this potential's force() can be called from multiple threads on the SAME instance.
Definition Potential.h:151

◆ isSurrogate()

virtual bool eonc::Potential::isSurrogate ( ) const
inlinenodiscardvirtualnoexcept

Whether this is a surrogate (GP) potential.

Override in SurrogatePotential.

Reimplemented in eonc::SurrogatePotential.

Definition at line 138 of file Potential.h.

138{ return false; }

◆ isThreadSafe()

virtual bool eonc::Potential::isThreadSafe ( ) const
inlinenodiscardvirtualnoexcept

Whether this potential's force() can be called from multiple threads on the SAME instance.

Python-based potentials return false. Potentials with internal mutex (MetatomicPotential) return true but serialize internally – use needsPerImageInstance() to check if separate instances would enable true parallelism.

Reimplemented in ASE, ASENwchemPot, ASEOrcaPot, CatLearnPot, eonc::MetatomicDynPot, eonc::tunneling::RingPolymerPotential, ExtPot, GPRPotential, MetatomicPotential, MPIPot, RgpotAdapter< RPot >, RgpotPot, SocketNWChemPot, and VASP.

Definition at line 151 of file Potential.h.

151{ return true; }

◆ layoutFlags()

virtual unsigned eonc::Potential::layoutFlags ( ) const
inlinenodiscardvirtualnoexcept

Reimplemented in ExtPot.

Definition at line 159 of file Potential.h.

159 {
160 return static_cast<unsigned>(PotLayout::InProcess);
161 }

◆ needsPerImageInstance()

virtual bool eonc::Potential::needsPerImageInstance ( ) const
inlinenodiscardvirtualnoexcept

Whether NEB should create separate Potential instances per image for true parallel force evaluation.

When true, NEB calls makePotential() once per image instead of sharing one instance. Override in potentials that use internal mutexes (e.g. MetatomicPotential).

Reimplemented in ASE, ASENwchemPot, ASEOrcaPot, eonc::MetatomicDynPot, ExtPot, LAMMPSPot, MetatomicPotential, RgpotAdapter< RPot >, SocketNWChemPot, and VASP.

Definition at line 178 of file Potential.h.

178 {
179 return false;
180 }

◆ recordForceCall()

void eonc::Potential::recordForceCall ( )
noexcept

Charge one evaluated geometry to this potential and its owning registry.

Definition at line 41 of file PotentialParams.cpp.

41 {
43 registry_.on_force_call(ptype);
44}

◆ registry()

IPotRegistry & eonc::Potential::registry ( ) const
inlinenodiscardnoexcept

The registry this potential charges its force calls to.

Definition at line 63 of file Potential.h.

63{ return registry_; }

◆ requiresIsolatedMoleculeLayout()

virtual bool eonc::Potential::requiresIsolatedMoleculeLayout ( ) const
inlinenodiscardvirtualnoexcept

True for molecular QM / non-PBC backends (NWChem socket, ASE ORCA/NWChem, …).

Callers must not apply periodic wraps that can tear molecules (#188).

Reimplemented in ASENwchemPot, ASEOrcaPot, eonc::tunneling::RingPolymerPotential, RgpotAdapter< RPot >, RgpotPot, and SocketNWChemPot.

Definition at line 142 of file Potential.h.

142 {
143 return false;
144 }

◆ setFixedMask()

virtual void eonc::Potential::setFixedMask ( long nAtoms,
const double * isFixed )
inlinevirtual

Optional frozen-atom mask (nAtoms*3, 1.0 = fixed).

Default no-op. Matter calls this immediately before force() so wrappers that need it (LAMMPS setforce) see Atom.fixed without changing force().

Reimplemented in LAMMPSPot.

Definition at line 110 of file Potential.h.

110 {
111 (void)nAtoms;
112 (void)isFixed;
113 }

◆ supportsBatchEvaluation()

virtual bool eonc::Potential::supportsBatchEvaluation ( ) const
inlinenodiscardvirtualnoexcept

Whether this potential supports batched evaluation of N systems in a single call.

When true, callers (NEB, Dimer) should use forceBatch() instead of N individual force() calls for better GPU utilization.

Reimplemented in ASE, eonc::HostSurfacePotential, eonc::tunneling::RingPolymerPotential, MetatomicPotential, RgpotAdapter< RPot >, and RgpotPot.

Definition at line 191 of file Potential.h.

191 {
192 return false;
193 }

◆ surfaceEpoch()

virtual unsigned long long eonc::Potential::surfaceEpoch ( ) const
inlinenodiscardvirtualnoexcept

Host-visible surface generation.

A learning host increments this on every refit; Matter keys its energy and variance caches on the value so identical positions after a refit cannot return a stale energy or variance. Static pots stay 0.

Reimplemented in eonc::HostSurfacePotential.

Definition at line 124 of file Potential.h.

124 {
125 return 0;
126 }

Member Data Documentation

◆ force_serial_

bool eonc::Potential::force_serial_ {false}
private

Definition at line 54 of file Potential.h.

54{false};

◆ forceCallCounter

std::atomic<size_t> eonc::Potential::forceCallCounter

Definition at line 57 of file Potential.h.

◆ lifetime_

std::shared_ptr<RegistryLifetime> eonc::Potential::lifetime_
private

Definition at line 51 of file Potential.h.

◆ m_created_at

IPotRegistry::TimePoint eonc::Potential::m_created_at
private

Definition at line 53 of file Potential.h.

◆ m_registry_id

uint64_t eonc::Potential::m_registry_id
private

Definition at line 52 of file Potential.h.

◆ ptype

PotType eonc::Potential::ptype
protected

Definition at line 47 of file Potential.h.

◆ registry_

IPotRegistry& eonc::Potential::registry_
private

Definition at line 50 of file Potential.h.


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