eonc::Potential Class Reference

#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
	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 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 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)

Public Attributes
std::atomic< size_t >	forceCallCounter

Protected Attributes
PotType	ptype

Private Attributes
IPotRegistry &	registry_
uint64_t	m_registry_id
IPotRegistry::TimePoint	m_created_at
bool	force_serial_ {false}

Detailed Description

Definition at line 42 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 129 of file Potential.h.

                       : unsigned {
    InProcess = 1u << 0,
    NeedsWorkingDirectory = 1u << 1,
    Subprocess = 1u << 2,
  };

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.

    : Potential(a_ptype, tls_construction_registry ? *tls_construction_registry
                                                   : 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 59 of file Potential.h.

      : ptype{a_ptype}, registry_{registry},
        m_registry_id{registry.on_created(a_ptype)},
        m_created_at{IPotRegistry::Clock::now()}, forceCallCounter{0} {}

Potential() [3/4]

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

Definition at line 33 of file PotentialParams.cpp.

    : Potential(a_ptype) {
  force_serial_ = !p.potential_options().thread_safe;
}

Potential() [4/4]

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

explicit

Definition at line 38 of file PotentialParams.cpp.

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

~Potential()

virtual eonc::Potential::~Potential ( )

inlinevirtual

Definition at line 70 of file Potential.h.

                       {
    registry_.on_destroyed(m_registry_id, ptype, forceCallCounter,
                           m_created_at);
  }

Member Function Documentation

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 >, SocketNWChemPot, and XTBPot.

Definition at line 176 of file Potential.h.

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

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 159 of file Potential.h.

                                                                        {
    return nullptr;
  }

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 >, SocketNWChemPot, and XTBPot.

Definition at line 172 of file Potential.h.

{ return false; }

finiteCutoff()

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

inlinenodiscardvirtualnoexcept

Finite interaction range in position length units.

0 means the potential is not finite-cutoff; the FD Hessian then stays one column per coordinate.

Reimplemented in RgpotAdapter< RPot >.

Definition at line 109 of file Potential.h.

{ 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

Implemented in AMS, AMS_IO, ASE, ASENwchemPot, ASEOrcaPot, CatLearnPot, EAM, EffectiveMediumTheory, eonc::MetatomicDynPot, ExtPot, GPRPotential, LAMMPSPot, MetatomicPotential, MPIPot, RgpotAdapter< RPot >, RgpotPot, SocketNWChemPot, SpceCcl, Tip4p, Tip4p_Pt, VASP, and XTBPot.

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 82 of file Potential.h.

                                        {
    if (positions.size() % 3 != 0 || positions.size() / 3 != atomicNrs.size() ||
        forces.size() != positions.size() || box.size() != 9) {
      throw std::invalid_argument("Potential::force span size mismatch");
    }
    force(static_cast<long>(atomicNrs.size()), positions.data(),
          atomicNrs.data(), forces.data(), energy, variance, box.data());
  }

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, MetatomicPotential, RgpotAdapter< RPot >, and RgpotPot.

Definition at line 198 of file Potential.h.

                                                      {
    for (long i = 0; i < nSystems; i++) {
      double var = 0;
      force(nAtoms, positions[i], atomicNrs[i], forces[i], &energies[i], &var,
            boxes[i]);
      if (variances)
        variances[i] = var;
      forceCallCounter++;
      registry_.on_force_call(ptype);
    }
  }

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 187 of file Potential.h.

                                                   {
    (void)owners;
    forceBatch(nSystems, nAtoms, positions, atomicNrs, forces, energies,
               variances, boxes);
  }

get_ef()

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

Definition at line 118 of file Potential.cpp.

                                                                            {
  double energy{std::numeric_limits<double>::infinity()};
  long nAtoms = static_cast<long>(pos.rows());
  AtomMatrix forces{MatrixXd::Zero(nAtoms, 3)};
  double var{0}; // no variance for true potentials
  const auto n = static_cast<size_t>(nAtoms);
  this->force(std::span<const double>(pos.data(), n * 3),
              std::span<const int>(atmnrs.data(), n),
              std::span<double>(forces.data(), n * 3), &energy, &var,
              std::span<const double>(box.data(), 9));
  forceCallCounter++;
  registry_.on_force_call(ptype);
  if (!std::isfinite(energy) || !forces.allFinite()) {
    throw std::runtime_error("Potential::get_ef: non-finite energy or forces");
  }
 
  return std::make_tuple(energy, forces);
}

getType()

PotType eonc::Potential::getType ( ) const

inlinenodiscard

Definition at line 104 of file Potential.h.

{ return this->ptype; }

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 EAM, and EffectiveMediumTheory.

Definition at line 142 of file Potential.h.

                                                                         {
    if (force_serial_)
      return false;
    return isThreadSafe();
  }

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 113 of file Potential.h.

{ 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, ExtPot, GPRPotential, MetatomicPotential, MPIPot, RgpotAdapter< RPot >, RgpotPot, SocketNWChemPot, VASP, and XTBPot.

Definition at line 126 of file Potential.h.

{ return true; }

layoutFlags()

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

inlinenodiscardvirtualnoexcept

Reimplemented in ExtPot.

Definition at line 134 of file Potential.h.

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

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, VASP, and XTBPot.

Definition at line 153 of file Potential.h.

                                                                    {
    return false;
  }

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, RgpotAdapter< RPot >, RgpotPot, and SocketNWChemPot.

Definition at line 117 of file Potential.h.

                                                                             {
    return false;
  }

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 96 of file Potential.h.

                                                                {
    (void)nAtoms;
    (void)isFixed;
  }

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, MetatomicPotential, RgpotAdapter< RPot >, and RgpotPot.

Definition at line 166 of file Potential.h.

                                                                      {
    return false;
  }

Member Data Documentation

force_serial_

bool eonc::Potential::force_serial_ {false}

private

Definition at line 50 of file Potential.h.

{false};

forceCallCounter

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

Definition at line 53 of file Potential.h.

m_created_at

IPotRegistry::TimePoint eonc::Potential::m_created_at

private

Definition at line 49 of file Potential.h.

m_registry_id

uint64_t eonc::Potential::m_registry_id

private

Definition at line 48 of file Potential.h.

ptype

PotType eonc::Potential::ptype

protected

Definition at line 44 of file Potential.h.

registry_

IPotRegistry& eonc::Potential::registry_

private

Definition at line 47 of file Potential.h.

---

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

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