ExtPot Class Reference

#include <ExtPot.h>

Inheritance diagram for ExtPot:

Public Member Functions
	ExtPot (const eonc::Parameters &p)
	~ExtPot ()
void	cleanMemory (void)
void	force (long N, const double *R, const int *atomicNrs, double *F, double *U, double *variance, const double *box) override
bool	isThreadSafe () const noexcept override
	One instance owns one exchange directory, so two threads in force() on it write the same structure file and read the same result.
bool	needsPerImageInstance () const noexcept override
	The external program runs as a subprocess and each instance runs it in a directory of its own, so separate instances are independent.
unsigned	layoutFlags () const noexcept override
Public Member Functions inherited from eonc::Potential
	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 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	isSharedInstanceThreadSafe () const noexcept
	Conservative gate for sharing one Potential instance across threads.
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)

Private Member Functions
void	passToSystem (long N, const double *R, const int *atomicNrs, const double *box)
void	recieveFromSystem (long N, double *F, double *U)
void	prepareExchangeDir ()

Private Attributes
std::string	eon_extpot_path
std::filesystem::path	exchangeDir
bool	retainExchangeDir {false}

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

Definition at line 19 of file ExtPot.h.

Constructor & Destructor Documentation

ExtPot()

ExtPot::ExtPot

(

const eonc::Parameters &

p

)

Definition at line 121 of file ExtPot.cpp.

    : eonc::Potential(p),
      eon_extpot_path{resolveCommand(p.potential_options().extPotPath)} {}

~ExtPot()

ExtPot::~ExtPot

(

)

Definition at line 137 of file ExtPot.cpp.

{ cleanMemory(); }

Member Function Documentation

cleanMemory()

void ExtPot::cleanMemory

(

void

)

Definition at line 125 of file ExtPot.cpp.

                             {
  if (exchangeDir.empty() || retainExchangeDir) {
    return;
  }
  std::error_code ec;
  std::filesystem::remove(exchangeDir / kToExtPot, ec);
  std::filesystem::remove(exchangeDir / kFromExtPot, ec);
  // Removes the directory only when it is empty, so whatever else the
  // external program wrote there stays.
  std::filesystem::remove(exchangeDir, ec);
}

force()

void ExtPot::force ( long N, const double * R, const int * atomicNrs, double * F, double * U, double * variance, const double * box )

overridevirtual

Implements eonc::Potential.

Definition at line 167 of file ExtPot.cpp.

                                                                   {
  if (variance != nullptr) {
    *variance = 0.0;
  }
  if (eon_extpot_path.empty()) {
    throw std::runtime_error(
        "ExtPot needs potential_options.extPotPath to name a program to run");
  }
  prepareExchangeDir();
  retainExchangeDir = true;
  passToSystem(N, R, atomicNrs, box);
  std::error_code ec;
  const std::filesystem::path runDir = std::filesystem::current_path(ec);
  eonc::pot::runOrThrow(composeCommand(exchangeDir.string(),
                                       ec ? std::string{} : runDir.string(),
                                       eon_extpot_path));
  recieveFromSystem(N, F, U);
  retainExchangeDir = false;
  return;
}

isThreadSafe()

bool ExtPot::isThreadSafe ( ) const

inlinenodiscardoverridevirtualnoexcept

One instance owns one exchange directory, so two threads in force() on it write the same structure file and read the same result.

Reimplemented from eonc::Potential.

Definition at line 29 of file ExtPot.h.

{ return false; }

layoutFlags()

unsigned ExtPot::layoutFlags ( ) const

inlinenodiscardoverridevirtualnoexcept

Reimplemented from eonc::Potential.

Definition at line 35 of file ExtPot.h.

                                                               {
    return static_cast<unsigned>(eonc::Potential::PotLayout::Subprocess) |
           static_cast<unsigned>(
               eonc::Potential::PotLayout::NeedsWorkingDirectory);
  }

needsPerImageInstance()

bool ExtPot::needsPerImageInstance ( ) const

inlinenodiscardoverridevirtualnoexcept

The external program runs as a subprocess and each instance runs it in a directory of its own, so separate instances are independent.

Reimplemented from eonc::Potential.

Definition at line 32 of file ExtPot.h.

                                                                     {
    return true;
  }

passToSystem()

void ExtPot::passToSystem ( long N, const double * R, const int * atomicNrs, const double * box )

private

Definition at line 189 of file ExtPot.cpp.

{
  const std::filesystem::path toExtPot = exchangeDir / kToExtPot;
  std::ofstream out(toExtPot, std::ios::trunc);
  if (!out) {
    throw std::runtime_error(
        std::format("Could not open {} for writing", toExtPot.string()));
  }
 
  for (int i = 0; i < 3; i++) {
    out << std::format("{:.19f}\t{:.19f}\t{:.19f}\n", box[i * 3 + 0],
                       box[i * 3 + 1], box[i * 3 + 2]);
  }
 
  for (long i = 0; i < N; i++) {
    out << std::format("{}\t{:.19f}\t{:.19f}\t{:.19f}\n", atomicNrs[i],
                       R[i * 3 + 0], R[i * 3 + 1], R[i * 3 + 2]);
  }
 
  out.close();
  if (!out) {
    throw std::runtime_error(
        std::format("Could not write the structure to {}", toExtPot.string()));
  }
  return;
}

prepareExchangeDir()

void ExtPot::prepareExchangeDir ( )

private

Definition at line 139 of file ExtPot.cpp.

                                {
  std::error_code ec;
  if (exchangeDir.empty()) {
    // One directory per potential object. A client started alongside this
    // one carries a different process id, and a second potential in this
    // process a different index, so no two of them name the same file.
    static std::atomic<long> instanceCount{0};
    const std::filesystem::path named{
        std::format("extpot_{}_{}", processId(), instanceCount.fetch_add(1))};
    exchangeDir = std::filesystem::absolute(named, ec);
    if (ec) {
      exchangeDir.clear();
      throw std::runtime_error(std::format("Could not resolve {}: {}",
                                           named.string(), ec.message()));
    }
  }
  std::filesystem::create_directory(exchangeDir, ec);
  if (ec) {
    throw std::runtime_error(std::format("Could not create {} to run {} in: {}",
                                         exchangeDir.string(), eon_extpot_path,
                                         ec.message()));
  }
  // A result left by an earlier call, or by a client that died holding this
  // process id, is read as this call's forces when the external program
  // writes nothing.
  std::filesystem::remove(exchangeDir / kFromExtPot, ec);
}

recieveFromSystem()

void ExtPot::recieveFromSystem ( long N, double * F, double * U )

private

Create the directory the external command runs in and clear any exchange file left in it.

Definition at line 218 of file ExtPot.cpp.

{
  const std::filesystem::path fromExtPot = exchangeDir / kFromExtPot;
  std::ifstream in(fromExtPot);
  if (!in) {
    throw std::runtime_error(
        std::format("Could not open {}; the external program left no result",
                    fromExtPot.string()));
  }
 
  if (!(in >> *U)) {
    throw std::runtime_error(
        std::format("Could not read the energy from {}", fromExtPot.string()));
  }
 
  for (long i = 0; i < N; i++) {
    if (!(in >> F[i * 3 + 0] >> F[i * 3 + 1] >> F[i * 3 + 2])) {
      throw std::runtime_error(
          std::format("{} holds forces for {} atoms, expected {}",
                      fromExtPot.string(), i, N));
    }
  }
  return;
}

Member Data Documentation

eon_extpot_path

std::string ExtPot::eon_extpot_path

private

The directory this potential runs the external command in. The exchange files keep their documented names and live here, so two clients started in one directory cannot read each other's numbers.

Definition at line 50 of file ExtPot.h.

exchangeDir

std::filesystem::path ExtPot::exchangeDir

private

Set while a call is in flight, so a call that fails leaves its exchange files in place to be looked at.

Definition at line 54 of file ExtPot.h.

retainExchangeDir

bool ExtPot::retainExchangeDir {false}

private

Definition at line 57 of file ExtPot.h.

{false};

---

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

• /home/runner/work/eOn/eOn/include/eon/potentials/ExtPot/ExtPot.h
• /home/runner/work/eOn/eOn/client/potentials/ExtPot/ExtPot.cpp