Loading...
Searching...
No Matches
Potential.h
Go to the documentation of this file.
1/*
2** This file is part of eOn.
3**
4** SPDX-License-Identifier: BSD-3-Clause
5**
6** Copyright (c) 2010--present, eOn Development Team
7** All rights reserved.
8**
9** Repo:
10** https://github.com/TheochemUI/eOn
11*/
12#pragma once
13#include "EonLogger.h"
14
15#include "Eigen.h"
16#include "PotRegistry.h"
17#include <atomic>
18#include <memory>
19#include <span>
20#include <stdexcept>
21#include <utility>
22#include <vector>
23
24namespace eonc {
25
26class Matter;
27class Parameters;
28class Runtime;
29
44
45class Potential {
46protected:
48
49private:
51 std::shared_ptr<RegistryLifetime> lifetime_;
52 uint64_t m_registry_id;
54 bool force_serial_{false};
55
56public:
57 std::atomic<size_t> forceCallCounter;
58
60 void recordForceCall() noexcept;
61
63 [[nodiscard]] IPotRegistry &registry() const noexcept { return registry_; }
64
66 explicit Potential(PotType a_ptype);
67
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} {}
73
74 // Out-of-line in eoncbase (PotentialParams.cpp) so shared plugins
75 // that link only eoncbase get the symbols. This header only
76 // forward-declares Parameters (header-surface contract).
77 Potential(PotType a_ptype, const Parameters &p);
78 explicit Potential(const Parameters &a_params);
79
80 virtual ~Potential() {
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 }
88
89 // Does not take into account the fixed / free atoms
90 // Variance here is null when not needed and that's OK
91 void virtual force(long nAtoms, const double *positions, const int *atomicNrs,
92 double *forces, double *energy, double *variance,
93 const double *box) = 0;
94
96 void force(std::span<const double> positions, std::span<const int> atomicNrs,
97 std::span<double> forces, double *energy, double *variance,
98 std::span<const double> box) {
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 }
106
110 virtual void setFixedMask(long nAtoms, const double *isFixed) {
111 (void)nAtoms;
112 (void)isFixed;
113 }
114
115 std::tuple<double, AtomMatrix>
116 get_ef(const AtomMatrix &pos, const VectorXi &atmnrs, const Matrix3d &box);
117
118 [[nodiscard]] PotType getType() const { return this->ptype; }
119
124 [[nodiscard]] virtual unsigned long long surfaceEpoch() const noexcept {
125 return 0;
126 }
127
133 [[deprecated("Override hessianRange() instead.")]]
134 [[nodiscard]] virtual double finiteCutoff() const noexcept { return 0.0; }
135
138 [[nodiscard]] virtual bool isSurrogate() const noexcept { return false; }
139
142 [[nodiscard]] virtual bool requiresIsolatedMoleculeLayout() const noexcept {
143 return false;
144 }
145
151 [[nodiscard]] virtual bool isThreadSafe() const noexcept { return true; }
152
154 enum class PotLayout : unsigned {
155 InProcess = 1u << 0,
157 Subprocess = 1u << 2,
158 };
159 [[nodiscard]] virtual unsigned layoutFlags() const noexcept {
160 return static_cast<unsigned>(PotLayout::InProcess);
161 }
162
167 [[nodiscard]] virtual bool isSharedInstanceThreadSafe() const noexcept {
168 if (force_serial_)
169 return false;
170 return isThreadSafe();
171 }
172
178 [[nodiscard]] virtual bool needsPerImageInstance() const noexcept {
179 return false;
180 }
181
184 [[nodiscard]] virtual std::shared_ptr<Potential> clonePotential() const {
185 return nullptr;
186 }
187
191 [[nodiscard]] virtual bool supportsBatchEvaluation() const noexcept {
192 return false;
193 }
194
197 virtual void bindBand(const std::vector<std::shared_ptr<Matter>> &) {}
198
202 [[nodiscard]] virtual bool forwardsStoredCell() const noexcept {
203 return false;
204 }
205
208 [[nodiscard]] virtual bool computesStress() const noexcept { return false; }
209
212 [[nodiscard]] virtual Matrix3d cauchyStress() const {
213 throw std::logic_error("Potential::cauchyStress is not implemented");
214 }
215
223 virtual void forceBatchOwned(long nSystems, long nAtoms,
224 const double *const *positions,
225 const int *const *atomicNrs,
226 double *const *forces, double *energies,
227 double *variances, const double *const *boxes,
228 const long *owners) {
229 (void)owners;
230 forceBatch(nSystems, nAtoms, positions, atomicNrs, forces, energies,
231 variances, boxes);
232 }
233
234 virtual void forceBatch(long nSystems, long nAtoms,
235 const double *const *positions,
236 const int *const *atomicNrs, double *const *forces,
237 double *energies, double *variances,
238 const double *const *boxes) {
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 }
248
259 [[nodiscard]] virtual double hessianRange() const noexcept {
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 }
277};
278
279namespace helpers {
282[[nodiscard]] std::unique_ptr<Potential>
283makePotential(const Parameters &params);
284[[nodiscard]] std::unique_ptr<Potential>
285makePotential(PotType ptype, const Parameters &params);
286[[nodiscard]] std::unique_ptr<Potential>
287makePotential(PotType ptype, const Parameters &params, Runtime &runtime);
288
291[[nodiscard]] inline std::shared_ptr<Potential>
292sharePotential(std::unique_ptr<Potential> pot) {
293 return std::shared_ptr<Potential>(std::move(pot));
294}
295
301[[nodiscard]] std::shared_ptr<Potential>
302makeImagePotential(const Potential &pot, const Parameters &params);
303} // namespace helpers
304
305} // namespace eonc
Eigen::Matrix< double, 3, 3, eOnStorageOrder > Matrix3d
Definition Eigen.h:35
Eigen::Matrix< double, Eigen::Dynamic, 3, eOnStorageOrder > AtomMatrix
Definition Eigen.h:37
Clock::time_point TimePoint
Definition PotRegistry.h:37
PotentialConstructionScope(IPotRegistry &registry)
PotentialConstructionScope & operator=(const PotentialConstructionScope &)=delete
PotentialConstructionScope(const PotentialConstructionScope &)=delete
IPotRegistry & registry() const noexcept
The registry this potential charges its force calls to.
Definition Potential.h:63
virtual bool computesStress() const noexcept
True when force() leaves a Cauchy stress that cauchyStress() can read until the next force() on this ...
Definition Potential.h:208
std::atomic< size_t > forceCallCounter
Definition Potential.h:57
virtual unsigned long long surfaceEpoch() const noexcept
Host-visible surface generation.
Definition Potential.h:124
virtual bool supportsBatchEvaluation() const noexcept
Whether this potential supports batched evaluation of N systems in a single call.
Definition Potential.h:191
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.
Definition Potential.h:223
Potential(PotType a_ptype, IPotRegistry &registry)
Test seam: injected registry, no process-default get() counters.
Definition Potential.h:69
PotType getType() const
Definition Potential.h:118
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().
Definition Potential.h:96
virtual ~Potential()
Definition Potential.h:80
virtual std::shared_ptr< Potential > clonePotential() const
Independent instance that does not reload from disk.
Definition Potential.h:184
virtual bool forwardsStoredCell() const noexcept
A host that owns the cell reads the stored matrix.
Definition Potential.h:202
PotLayout
How the pot is executed. Combine with bitwise or.
Definition Potential.h:154
virtual double hessianRange() const noexcept
Distance beyond which every Hessian block between two atoms is exactly zero, in position length units...
Definition Potential.h:259
virtual bool isSharedInstanceThreadSafe() const noexcept
Conservative gate for sharing one Potential instance across threads.
Definition Potential.h:167
virtual bool isSurrogate() const noexcept
Whether this is a surrogate (GP) potential.
Definition Potential.h:138
uint64_t m_registry_id
Definition Potential.h:52
virtual bool needsPerImageInstance() const noexcept
Whether NEB should create separate Potential instances per image for true parallel force evaluation.
Definition Potential.h:178
virtual double finiteCutoff() const noexcept
Finite interaction range in position length units.
Definition Potential.h:134
virtual Matrix3d cauchyStress() const
Cauchy stress in eV/Angstrom^3.
Definition Potential.h:212
std::tuple< double, AtomMatrix > get_ef(const AtomMatrix &pos, const VectorXi &atmnrs, const Matrix3d &box)
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
std::shared_ptr< RegistryLifetime > lifetime_
Definition Potential.h:51
IPotRegistry & registry_
Definition Potential.h:50
virtual unsigned layoutFlags() const noexcept
Definition Potential.h:159
PotType ptype
Definition Potential.h:47
virtual bool requiresIsolatedMoleculeLayout() const noexcept
True for molecular QM / non-PBC backends (NWChem socket, ASE ORCA/NWChem, …).
Definition Potential.h:142
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 e...
Definition Potential.h:197
IPotRegistry::TimePoint m_created_at
Definition Potential.h:53
void recordForceCall() noexcept
Charge one evaluated geometry to this potential and its owning registry.
virtual void setFixedMask(long nAtoms, const double *isFixed)
Optional frozen-atom mask (nAtoms*3, 1.0 = fixed).
Definition Potential.h:110
virtual bool isThreadSafe() const noexcept
Whether this potential's force() can be called from multiple threads on the SAME instance.
Definition Potential.h:151
Potential(PotType a_ptype)
Production default: construction-scope registry, else PotRegistry::get().
Move-only composition root for process resources (dlopen loaders and the potential registry).
Definition Runtime.h:27
std::shared_ptr< Potential > makeImagePotential(const Potential &pot, const Parameters &params)
A separate instance of pot for one image of a band, dimer or pair of minimizations: a clone when the ...
std::unique_ptr< Potential > makePotential(const Parameters &params)
Exclusive ownership.
std::shared_ptr< Potential > sharePotential(std::unique_ptr< Potential > pot)
Multi-owner boundary: one instance observed by several Matters, images, or a binding.
Definition Potential.h:292
RAII resource manager for the ARTn C library with global synchronization.