Loading...
Searching...
No Matches
eonc::tunneling::RingPolymerPotential Class Reference

One structure whose coordinates are the beads of a closed ring. More...

#include <RingPolymerPotential.h>

Inheritance diagram for eonc::tunneling::RingPolymerPotential:

Public Member Functions

 RingPolymerPotential (BatchPotential beads, long nBeads, long dof, double spring, double energyShift, std::vector< double > eta, bool fold, VectorXd modeDir)
void force (long nAtoms, const double *positions, const int *atomicNrs, double *forces, double *energy, double *variance, const double *box) override
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) override
bool supportsBatchEvaluation () const noexcept override
 Whether this potential supports batched evaluation of N systems in a single call.
bool requiresIsolatedMoleculeLayout () const noexcept override
 True for molecular QM / non-PBC backends (NWChem socket, ASE ORCA/NWChem, …).
bool isThreadSafe () const noexcept override
 The bead batch is a caller-supplied function and is not safe to enter from two threads.
long structureAtoms () const
long activeBeads () const
void setPhysicalBath (std::shared_ptr< const PhysicalQuadraticBath > bath)
void setDiscretization (std::vector< double > weights)
void packActive (const std::vector< VectorXd > &active, double *positions) const
std::vector< VectorXd > unpack (const double *positions) const
void packMode (const VectorXd &dir, AtomMatrix &mode) const
Public Member Functions inherited from eonc::Potential
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 ()
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 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 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 double hessianRange () const noexcept
 Distance beyond which every Hessian block between two atoms is exactly zero, in position length units.

Private Member Functions

void fixLayout (long nBeads, long dof, bool fold, const VectorXd &modeDir)
double writeForces (const std::vector< VectorXd > &grad, const double *positions, double *forces) const

Private Attributes

BatchPotential beads_
long nBeads_ {0}
long dof_ {0}
long nActive_ {0}
long atomsPerBead_ {0}
int usedOnLast_ {3}
long nAtoms_ {0}
double spring_ {0.0}
double energyShift_ {0.0}
std::vector< double > eta_
std::vector< double > discretization_
std::shared_ptr< const PhysicalQuadraticBath > physicalBath_
bool fold_ {false}
VectorXd modeDir_

Additional Inherited Members

Public Types inherited from eonc::Potential
enum class  PotLayout : unsigned { InProcess = 1u << 0 , NeedsWorkingDirectory = 1u << 1 , Subprocess = 1u << 2 }
 How the pot is executed. Combine with bitwise or. More...
Public Attributes inherited from eonc::Potential
std::atomic< size_t > forceCallCounter
Protected Attributes inherited from eonc::Potential
PotType ptype

Detailed Description

One structure whose coordinates are the beads of a closed ring.

The energy is U_N and the forces are minus its gradient. A call evaluates every bead through the batch potential, so a calculator group can spread the beads. An even ring with the fold set stores one turning point to the other and mirrors the rest.

Definition at line 28 of file RingPolymerPotential.h.

Constructor & Destructor Documentation

◆ RingPolymerPotential()

eonc::tunneling::RingPolymerPotential::RingPolymerPotential ( BatchPotential beads,
long nBeads,
long dof,
double spring,
double energyShift,
std::vector< double > eta,
bool fold,
VectorXd modeDir )

Definition at line 3776 of file Tunneling.cpp.

3782 beads_(std::move(beads)),
3783 spring_(spring),
3784 energyShift_(energyShift),
3785 eta_(std::move(eta)) {
3786 if (!(spring > 0.0) || !std::isfinite(spring)) {
3787 throw std::invalid_argument(
3788 "ring structure: the spring constant must be positive");
3789 }
3790 fixLayout(nBeads, dof, fold, modeDir);
3791}
Potential(PotType a_ptype)
Production default: construction-scope registry, else PotRegistry::get().
void fixLayout(long nBeads, long dof, bool fold, const VectorXd &modeDir)

Member Function Documentation

◆ activeBeads()

long eonc::tunneling::RingPolymerPotential::activeBeads ( ) const
inlinenodiscard

Definition at line 56 of file RingPolymerPotential.h.

◆ fixLayout()

void eonc::tunneling::RingPolymerPotential::fixLayout ( long nBeads,
long dof,
bool fold,
const VectorXd & modeDir )
private

Definition at line 3750 of file Tunneling.cpp.

3751 {
3752 if (nBeads < 4 || dof < 1 || modeDir.size() != dof) {
3753 throw std::invalid_argument(
3754 "ring structure: need at least 4 beads and a mode of the bead "
3755 "dimension");
3756 }
3757 if (fold && nBeads % 2 != 0) {
3758 throw std::invalid_argument(
3759 "ring structure: a folded ring needs an even bead count");
3760 }
3761 nBeads_ = nBeads;
3762 dof_ = dof;
3763 fold_ = fold;
3764 nActive_ = fold ? (nBeads / 2 + 1) : nBeads;
3765 atomsPerBead_ = (dof + 2) / 3;
3766 usedOnLast_ = static_cast<int>(dof % 3 == 0 ? 3 : dof % 3);
3768 modeDir_ = modeDir;
3769 const double nrm = modeDir_.norm();
3770 if (!(nrm > 0.0)) {
3771 throw std::invalid_argument("ring structure: the saddle direction is zero");
3772 }
3773 modeDir_ /= nrm;
3774}

◆ force()

void eonc::tunneling::RingPolymerPotential::force ( long nAtoms,
const double * positions,
const int * atomicNrs,
double * forces,
double * energy,
double * variance,
const double * box )
overridevirtual

Implements eonc::Potential.

Definition at line 3882 of file Tunneling.cpp.

3885 {
3886 const double *pos[] = {positions};
3887 const int *nrs[] = {atomicNrs};
3888 double *frc[] = {forces};
3889 const double *boxes[] = {box};
3890 double var = 0.0;
3891 forceBatch(1, nAtoms, pos, nrs, frc, energy, variance ? &var : &var, boxes);
3892 if (variance) {
3893 *variance = var;
3894 }
3895 forceCallCounter -= 1;
3896}
std::atomic< size_t > forceCallCounter
Definition Potential.h:57
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) override

◆ forceBatch()

void eonc::tunneling::RingPolymerPotential::forceBatch ( long nSystems,
long nAtoms,
const double *const * positions,
const int *const * atomicNrs,
double *const * forces,
double * energies,
double * variances,
const double *const * boxes )
overridevirtual

Reimplemented from eonc::Potential.

Definition at line 3898 of file Tunneling.cpp.

3903 {
3904 static_cast<void>(atomicNrs);
3905 static_cast<void>(boxes);
3906 if (nSystems < 1 || nAtoms != nAtoms_ || positions == nullptr ||
3907 forces == nullptr || energies == nullptr) {
3908 throw std::invalid_argument(
3909 "ring structure: the atom count does not match the bead packing");
3910 }
3911 struct Item {
3912 std::vector<VectorXd> raw;
3913 std::vector<VectorXd> q;
3914 };
3915 std::vector<Item> items(static_cast<size_t>(nSystems));
3916 std::vector<VectorXd> all;
3917 all.reserve(static_cast<size_t>(nSystems * nActive_));
3918 for (long i = 0; i < nSystems; ++i) {
3919 items[static_cast<size_t>(i)].raw = unpack(positions[i]);
3920 items[static_cast<size_t>(i)].q = items[static_cast<size_t>(i)].raw;
3921 if (fold_) {
3922 projectMonotonePrefix(items[static_cast<size_t>(i)].q, nActive_ - 1,
3923 modeDir_);
3924 }
3925 all.insert(all.end(), items[static_cast<size_t>(i)].q.begin(),
3926 items[static_cast<size_t>(i)].q.end());
3927 }
3928 std::vector<double> vAll;
3929 std::vector<VectorXd> gAll;
3930 beads_(all, vAll, gAll);
3931 if (vAll.size() != all.size() || gAll.size() != all.size()) {
3932 throw std::runtime_error(
3933 "ring structure: the bead potential returned the wrong count");
3934 }
3935 size_t cursor = 0;
3936 const double kMono = std::max(4.0 * spring_, 1.0);
3937 for (long i = 0; i < nSystems; ++i) {
3938 const auto &q = items[static_cast<size_t>(i)].q;
3939 const auto &raw = items[static_cast<size_t>(i)].raw;
3940 std::vector<double> vActive(
3941 vAll.begin() + static_cast<std::ptrdiff_t>(cursor),
3942 vAll.begin() + static_cast<std::ptrdiff_t>(cursor + nActive_));
3943 std::vector<VectorXd> gActive(
3944 gAll.begin() + static_cast<std::ptrdiff_t>(cursor),
3945 gAll.begin() + static_cast<std::ptrdiff_t>(cursor + nActive_));
3946 cursor += static_cast<size_t>(nActive_);
3947 for (const auto &g : gActive) {
3948 if (g.size() != dof_) {
3949 throw std::runtime_error(
3950 "ring structure: a bead gradient has the wrong dimension");
3951 }
3952 }
3953 std::vector<VectorXd> fullQ = expandMirrored(q, nBeads_, fold_);
3954 std::vector<double> vFull(static_cast<size_t>(nBeads_));
3955 std::vector<VectorXd> gFull(static_cast<size_t>(nBeads_),
3956 VectorXd::Zero(dof_));
3957 if (!fold_) {
3958 vFull = std::move(vActive);
3959 gFull = std::move(gActive);
3960 } else {
3961 const long m = nBeads_ / 2;
3962 vFull[0] = vActive[0];
3963 gFull[0] = gActive[0];
3964 vFull[static_cast<size_t>(m)] = vActive[static_cast<size_t>(m)];
3965 gFull[static_cast<size_t>(m)] = gActive[static_cast<size_t>(m)];
3966 for (long j = 1; j < m; ++j) {
3967 vFull[static_cast<size_t>(j)] = vActive[static_cast<size_t>(j)];
3968 vFull[static_cast<size_t>(nBeads_ - j)] =
3969 vActive[static_cast<size_t>(j)];
3970 gFull[static_cast<size_t>(j)] = gActive[static_cast<size_t>(j)];
3971 gFull[static_cast<size_t>(nBeads_ - j)] =
3972 gActive[static_cast<size_t>(j)];
3973 }
3974 }
3975 auto replay = [&](const std::vector<VectorXd> &, std::vector<double> &v,
3976 std::vector<VectorXd> &g) {
3977 v = vFull;
3978 g = gFull;
3979 };
3980 const RingEval ev = evaluateRing(fullQ, spring_, replay, energyShift_, eta_,
3982 std::vector<VectorXd> reduced;
3983 if (!fold_) {
3984 reduced = ev.grad;
3985 } else {
3986 const long m = nBeads_ / 2;
3987 reduced.resize(static_cast<size_t>(m + 1));
3988 reduced[0] = ev.grad[0];
3989 reduced[static_cast<size_t>(m)] = ev.grad[static_cast<size_t>(m)];
3990 for (long j = 1; j < m; ++j) {
3991 reduced[static_cast<size_t>(j)] =
3992 ev.grad[static_cast<size_t>(j)] +
3993 ev.grad[static_cast<size_t>(nBeads_ - j)];
3994 }
3995 }
3996 double penalty = 0.0;
3997 if (fold_) {
3998 for (long j = 0; j < nActive_; ++j) {
3999 const VectorXd d =
4000 raw[static_cast<size_t>(j)] - q[static_cast<size_t>(j)];
4001 penalty += 0.5 * kMono * d.squaredNorm();
4002 reduced[static_cast<size_t>(j)] += kMono * d;
4003 }
4004 }
4005 const double axis = writeForces(reduced, positions[i], forces[i]);
4006 energies[i] = ev.u + penalty + axis;
4007 if (variances) {
4008 variances[i] = 0.0;
4009 }
4010 forceCallCounter += 1;
4011 }
4012}
double writeForces(const std::vector< VectorXd > &grad, const double *positions, double *forces) const
std::vector< VectorXd > unpack(const double *positions) const
std::shared_ptr< const PhysicalQuadraticBath > physicalBath_

◆ isThreadSafe()

bool eonc::tunneling::RingPolymerPotential::isThreadSafe ( ) const
inlinenodiscardoverridevirtualnoexcept

The bead batch is a caller-supplied function and is not safe to enter from two threads.

Reimplemented from eonc::Potential.

Definition at line 53 of file RingPolymerPotential.h.

53{ return false; }

◆ packActive()

void eonc::tunneling::RingPolymerPotential::packActive ( const std::vector< VectorXd > & active,
double * positions ) const

Definition at line 3793 of file Tunneling.cpp.

3794 {
3795 if (static_cast<long>(active.size()) != nActive_ || positions == nullptr) {
3796 throw std::invalid_argument("ring structure: bead count does not match");
3797 }
3798 std::fill(positions, positions + 3 * nAtoms_, 0.0);
3799 for (long j = 0; j < nActive_; ++j) {
3800 if (active[static_cast<size_t>(j)].size() != dof_) {
3801 throw std::invalid_argument(
3802 "ring structure: bead dimension does not match");
3803 }
3804 long flat = 0;
3805 const double *src = active[static_cast<size_t>(j)].data();
3806 for (long a = 0; a < atomsPerBead_; ++a) {
3807 double *atom = positions + (j * atomsPerBead_ + a) * 3;
3808 const int nax = (a + 1 == atomsPerBead_) ? usedOnLast_ : 3;
3809 for (int ax = 0; ax < nax; ++ax, ++flat) {
3810 atom[ax] = src[flat];
3811 }
3812 }
3813 }
3814}

◆ packMode()

void eonc::tunneling::RingPolymerPotential::packMode ( const VectorXd & dir,
AtomMatrix & mode ) const

Definition at line 3836 of file Tunneling.cpp.

3837 {
3838 if (mode.rows() != nAtoms_) {
3839 throw std::invalid_argument("ring mode: atom count does not match");
3840 }
3841 std::vector<VectorXd> beads(static_cast<size_t>(nActive_), dir);
3842 packActive(beads, mode.data());
3843 const double nrm = mode.norm();
3844 if (!(nrm > 0.0)) {
3845 throw std::invalid_argument("ring mode: the saddle direction is zero");
3846 }
3847 mode /= nrm;
3848}
void packActive(const std::vector< VectorXd > &active, double *positions) const

◆ requiresIsolatedMoleculeLayout()

bool eonc::tunneling::RingPolymerPotential::requiresIsolatedMoleculeLayout ( ) const
inlinenodiscardoverridevirtualnoexcept

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

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

Reimplemented from eonc::Potential.

Definition at line 47 of file RingPolymerPotential.h.

47 {
48 return true;
49 }

◆ setDiscretization()

void eonc::tunneling::RingPolymerPotential::setDiscretization ( std::vector< double > weights)
inline

Definition at line 65 of file RingPolymerPotential.h.

65 {
66 if (!weights.empty()) {
67 if (fold_ || static_cast<long>(weights.size()) != nBeads_) {
68 throw std::invalid_argument(
69 "link weights require one value per full-ring bead");
70 }
71 for (double value : weights) {
72 if (!(value > 0.0) || !std::isfinite(value)) {
73 throw std::invalid_argument(
74 "link weights must be positive and finite");
75 }
76 }
77 }
78 discretization_ = std::move(weights);
79 }

◆ setPhysicalBath()

void eonc::tunneling::RingPolymerPotential::setPhysicalBath ( std::shared_ptr< const PhysicalQuadraticBath > bath)
inline

Definition at line 57 of file RingPolymerPotential.h.

57 {
58 if (bath && fold_)
59 throw std::invalid_argument("physical bath uses the full ring");
60 if (bath)
61 bath->validate(dof_);
62 physicalBath_ = std::move(bath);
63 }

◆ structureAtoms()

long eonc::tunneling::RingPolymerPotential::structureAtoms ( ) const
inlinenodiscard

Definition at line 55 of file RingPolymerPotential.h.

55{ return nAtoms_; }

◆ supportsBatchEvaluation()

bool eonc::tunneling::RingPolymerPotential::supportsBatchEvaluation ( ) const
inlinenodiscardoverridevirtualnoexcept

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 from eonc::Potential.

Definition at line 43 of file RingPolymerPotential.h.

43 {
44 return true;
45 }

◆ unpack()

std::vector< VectorXd > eonc::tunneling::RingPolymerPotential::unpack ( const double * positions) const
nodiscard

Definition at line 3817 of file Tunneling.cpp.

3817 {
3818 if (positions == nullptr) {
3819 throw std::invalid_argument("ring structure: missing positions");
3820 }
3821 std::vector<VectorXd> active(static_cast<size_t>(nActive_),
3822 VectorXd::Zero(dof_));
3823 for (long j = 0; j < nActive_; ++j) {
3824 long flat = 0;
3825 for (long a = 0; a < atomsPerBead_; ++a) {
3826 const double *atom = positions + (j * atomsPerBead_ + a) * 3;
3827 const int nax = (a + 1 == atomsPerBead_) ? usedOnLast_ : 3;
3828 for (int ax = 0; ax < nax; ++ax, ++flat) {
3829 active[static_cast<size_t>(j)](flat) = atom[ax];
3830 }
3831 }
3832 }
3833 return active;
3834}

◆ writeForces()

double eonc::tunneling::RingPolymerPotential::writeForces ( const std::vector< VectorXd > & grad,
const double * positions,
double * forces ) const
nodiscardprivate

Definition at line 3850 of file Tunneling.cpp.

3852 {
3853 std::fill(forces, forces + 3 * nAtoms_, 0.0);
3854 for (long j = 0; j < nActive_; ++j) {
3855 long flat = 0;
3856 const double *src = grad[static_cast<size_t>(j)].data();
3857 for (long a = 0; a < atomsPerBead_; ++a) {
3858 double *atom = forces + (j * atomsPerBead_ + a) * 3;
3859 const int nax = (a + 1 == atomsPerBead_) ? usedOnLast_ : 3;
3860 for (int ax = 0; ax < nax; ++ax, ++flat) {
3861 atom[ax] = -src[flat];
3862 }
3863 }
3864 }
3865 double extra = 0.0;
3866 constexpr double kAxis = 1.0e3;
3867 if (usedOnLast_ == 3) {
3868 return extra;
3869 }
3870 for (long j = 0; j < nActive_; ++j) {
3871 const long atom = j * atomsPerBead_ + atomsPerBead_ - 1;
3872 double *frc = forces + atom * 3;
3873 const double *pos = positions + atom * 3;
3874 for (int ax = usedOnLast_; ax < 3; ++ax) {
3875 extra += 0.5 * kAxis * pos[ax] * pos[ax];
3876 frc[ax] = -kAxis * pos[ax];
3877 }
3878 }
3879 return extra;
3880}

Member Data Documentation

◆ atomsPerBead_

long eonc::tunneling::RingPolymerPotential::atomsPerBead_ {0}
private

Definition at line 95 of file RingPolymerPotential.h.

95{0};

◆ beads_

BatchPotential eonc::tunneling::RingPolymerPotential::beads_
private

Definition at line 91 of file RingPolymerPotential.h.

◆ discretization_

std::vector<double> eonc::tunneling::RingPolymerPotential::discretization_
private

Definition at line 101 of file RingPolymerPotential.h.

◆ dof_

long eonc::tunneling::RingPolymerPotential::dof_ {0}
private

Definition at line 93 of file RingPolymerPotential.h.

93{0};

◆ energyShift_

double eonc::tunneling::RingPolymerPotential::energyShift_ {0.0}
private

Definition at line 99 of file RingPolymerPotential.h.

99{0.0};

◆ eta_

std::vector<double> eonc::tunneling::RingPolymerPotential::eta_
private

Definition at line 100 of file RingPolymerPotential.h.

◆ fold_

bool eonc::tunneling::RingPolymerPotential::fold_ {false}
private

Definition at line 103 of file RingPolymerPotential.h.

103{false};

◆ modeDir_

VectorXd eonc::tunneling::RingPolymerPotential::modeDir_
private

Definition at line 104 of file RingPolymerPotential.h.

◆ nActive_

long eonc::tunneling::RingPolymerPotential::nActive_ {0}
private

Definition at line 94 of file RingPolymerPotential.h.

94{0};

◆ nAtoms_

long eonc::tunneling::RingPolymerPotential::nAtoms_ {0}
private

Definition at line 97 of file RingPolymerPotential.h.

97{0};

◆ nBeads_

long eonc::tunneling::RingPolymerPotential::nBeads_ {0}
private

Definition at line 92 of file RingPolymerPotential.h.

92{0};

◆ physicalBath_

std::shared_ptr<const PhysicalQuadraticBath> eonc::tunneling::RingPolymerPotential::physicalBath_
private

Definition at line 102 of file RingPolymerPotential.h.

◆ spring_

double eonc::tunneling::RingPolymerPotential::spring_ {0.0}
private

Definition at line 98 of file RingPolymerPotential.h.

98{0.0};

◆ usedOnLast_

int eonc::tunneling::RingPolymerPotential::usedOnLast_ {3}
private

Definition at line 96 of file RingPolymerPotential.h.

96{3};

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