Potential backed by rgpot NWChemPot / CPMDPot (in-process dlopen of libnwchemc / libcpmdc). More...

#include <RgpotPot.h>

Inheritance diagram for RgpotPot:

Public Member Functions
	RgpotPot (const eonc::Parameters &p)
	~RgpotPot () override
	RgpotPot (const RgpotPot &)=delete
RgpotPot &	operator= (const RgpotPot &)=delete
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
	Whether this potential's force() can be called from multiple threads on the SAME instance.
bool	supportsBatchEvaluation () const noexcept override
	With cpmdc calculator groups ([RgpotPot] ranks_per_image), a batch is spread over the groups: system j runs on group j mod G, then every rank receives every result, so all ranks keep the same band.
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
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) override
	System j runs on group owners[j] mod G when owners is given (an owner below zero falls back to j), so a NEB image keeps its group across partial band updates.
bool	requiresIsolatedMoleculeLayout () const noexcept override
	NWChem molecular SCF does not support PBC; CPMD may be periodic.
const std::string &	backend () const noexcept
bool	engineAvailable () const
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 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	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.

Private Member Functions
void	serveWorker ()
void	computeSingle (long N, const double R, const int atomicNrs, double F, double U, const double *box)
void	computeBatch (long nSystems, long nAtoms, const double const positions, const int const atomicNrs, double const forces, double energies, const double const boxes, const std::int64_t owners)
void	sendStop ()
void	stopAndDrop ()
void	releaseWorkersAtExit ()

Private Attributes
std::unique_ptr< RGPotEngine >	impl_
std::string	backend_
bool	driver_ {true}
bool	stopped_ {false}
bool	dropped_ {false}
bool	acked_ {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

Potential backed by rgpot NWChemPot / CPMDPot (in-process dlopen of libnwchemc / libcpmdc).

Not potserv RPC. Configure via [RgpotPot] INI; energy eV, forces eV/Angstrom.

Definition at line 25 of file RgpotPot.h.

Constructor & Destructor Documentation

◆ RgpotPot() [1/2]

RgpotPot::RgpotPot ( const eonc::Parameters & p )

explicit

Definition at line 18 of file RgpotPot.cpp.

    : eonc::Potential(eonc::PotType::RGPOT, p) {
  RGPotEngineOptions opt;
  const auto &o = p.rgpot_options();
  opt.backend = o.backend;
  opt.basis = o.basis;
  opt.theory = o.theory;
  opt.scf_type = o.scf_type;
  opt.functional = o.functional;
  opt.cutoff_ry = o.cutoff_ry;
  opt.charge = o.charge;
  opt.multiplicity = o.multiplicity;
  opt.engine_path = o.engine_path;
  opt.engine_library = o.engine_library;
  opt.engine_root = o.engine_root;
  opt.title = o.title;
  opt.memory_mb = o.memory_mb;
  opt.scratch_dir = o.scratch_dir;
  opt.input_block = o.input_block;
  opt.permanent_dir = o.permanent_dir;
  opt.params_path = o.params_path;
  opt.ranks_per_image = o.ranks_per_image;
  opt.model_path = o.model_path;
  opt.device = o.device;
  opt.length_unit = o.length_unit;
  opt.extensions_directory = o.extensions_directory;
  opt.check_consistency = o.check_consistency;
  opt.uncertainty_threshold = o.uncertainty_threshold;
  opt.torch_determinism_strict = o.torch_determinism_strict;
  opt.xtb_paramset = o.xtb_paramset;
  opt.xtb_accuracy = o.xtb_accuracy;
  opt.xtb_electronic_temperature = o.xtb_electronic_temperature;
  opt.xtb_max_iterations = o.xtb_max_iterations;
  opt.xtb_charge = o.xtb_charge;
  opt.xtb_uhf = o.xtb_uhf;
 
  // Env overrides (CI / benchmarks)
  if (const char *e = std::getenv("RGPOT_BACKEND"))
    opt.backend = e;
  if (const char *e = std::getenv("RGPOT_NWCHEM_BASIS"))
    opt.basis = e;
  if (const char *e = std::getenv("RGPOT_NWCHEM_THEORY"))
    opt.theory = e;
  if (const char *e = std::getenv("RGPOT_NWCHEM_SCF_TYPE"))
    opt.scf_type = e;
  if (const char *e = std::getenv("RGPOT_PARAMS_PATH"))
    opt.params_path = e;
  // Engine-path env overrides are backend-scoped: NWCHEMC_LIBRARY must not
  // leak into a cpmdc configure (CPMDPot resolves CPMDC_LIBRARY itself).
  std::string backend_lc = opt.backend;
  std::ranges::transform(backend_lc, backend_lc.begin(),
                         [](unsigned char c) { return std::tolower(c); });
  if (backend_lc.rfind("nwchem", 0) == 0) {
    if (const char *e = std::getenv("NWCHEMC_LIBRARY"))
      opt.engine_path = e;
    else if (const char *e = std::getenv("RGPOT_NWCHEMC_ENGINE"))
      opt.engine_path = e;
    else if (const char *e = std::getenv("RGPOT_NWCHEM_ENGINE"))
      opt.engine_path = e;
  } else if (backend_lc.rfind("cpmd", 0) == 0) {
    if (const char *e = std::getenv("CPMDC_LIBRARY"))
      opt.engine_path = e;
    else if (const char *e = std::getenv("RGPOT_CPMDC_ENGINE"))
      opt.engine_path = e;
  } else if (backend_lc.rfind("meta", 0) == 0 || backend_lc == "mta") {
    if (const char *e = std::getenv("RGPOT_METATOMIC_ENGINE"))
      opt.engine_path = e;
    else if (const char *e = std::getenv("METATOMIC_ENGINE"))
      opt.engine_path = e;
    if (const char *e = std::getenv("RGPOT_METATOMIC_MODEL"))
      opt.model_path = e;
  } else if (backend_lc == "xtb" || backend_lc == "xtbpot" ||
             backend_lc == "gfn" || backend_lc == "gfnxtb") {
    if (const char *e = std::getenv("RGPOT_XTB_ENGINE"))
      opt.engine_path = e;
    else if (const char *e = std::getenv("XTB_ENGINE"))
      opt.engine_path = e;
    if (opt.xtb_paramset.empty() || opt.xtb_paramset == "GFN2xTB") {
      if (!p.xtb_options().paramset.empty())
        opt.xtb_paramset = p.xtb_options().paramset;
    }
  }
 
  // Dual-read [Metatomic] when RGPOT backend is metatomic
  if ((backend_lc.rfind("meta", 0) == 0 || backend_lc == "mta") &&
      opt.model_path.empty())
    opt.model_path = p.metatomic_options().model_path;
  if ((backend_lc.rfind("meta", 0) == 0 || backend_lc == "mta") &&
      opt.device == "cpu" && !p.metatomic_options().device.empty())
    opt.device = p.metatomic_options().device;
 
  impl_ = std::make_unique<RGPotEngine>(opt);
  backend_ = impl_->backend();
  driver_ = impl_->worldRank() == 0;
  std::cout
      << "RgpotPot: in-process rgpot backend=" << backend_
      << " (dlopen: libnwchemc/libcpmdc/libmetatomic_engine/libxtb_engine)"
      << std::endl;
  // Finalize is registered first. The grouped-exit handler is next, and
  // the stop handler is last, so exit runs stop, then Finalize, then _Exit.
  impl_->finalizeMpiAtExit();
  impl_->armGroupedExit();
  releaseWorkersAtExit();
  if (!driver_)
    serveWorker();
}

◆ ~RgpotPot()

RgpotPot::~RgpotPot ( )

override

Definition at line 125 of file RgpotPot.cpp.

                    {
  const bool grouped = impl_ && impl_->calculatorWorld() > 1;
  stopAndDrop();
  // ~CPMDPot dlcloses libcpmdc. On several ranks that runs Fortran
  // destructors while another rank may already be in MPI_Finalize.
  // The process reclaims the engine at _Exit.
  if (grouped)
    (void)impl_.release();
}

◆ RgpotPot() [2/2]

RgpotPot::RgpotPot ( const RgpotPot & )

delete

Member Function Documentation

◆ backend()

const std::string & RgpotPot::backend ( ) const

inlinenodiscardnoexcept

Definition at line 58 of file RgpotPot.h.

58{ return backend_; }

◆ computeBatch()

void RgpotPot::computeBatch	(	long	nSystems,
		long	nAtoms,
		const double const	positions,
		const int const	atomicNrs,
		double const	forces,
		double *	energies,
		const double const	boxes,
		const std::int64_t *	owners )

private

Definition at line 225 of file RgpotPot.cpp.

                                                      {
  const int groups = impl_->calculatorGroups();
  const int mine = impl_->calculatorIndex();
  auto ownerOf = [&](long j) {
    const std::int64_t id = owners && owners[j] >= 0 ? owners[j] : j;
    return static_cast<int>(id % groups);
  };
  if (impl_->calculatorWorld() <= 1) {
    for (long j = 0; j < nSystems; j++)
      impl_->force(nAtoms, positions[j], atomicNrs[j], forces[j], &energies[j],
                   boxes[j]);
    return;
  }
  std::vector<char> ok(static_cast<size_t>(nSystems), 1);
  std::vector<std::string> errors(static_cast<size_t>(nSystems));
  for (long j = 0; j < nSystems; j++) {
    if (ownerOf(j) == mine)
      ok[static_cast<size_t>(j)] =
          try_force(*impl_, nAtoms, positions[j], atomicNrs[j], forces[j],
                    &energies[j], boxes[j], errors[static_cast<size_t>(j)]);
  }
  // Every share runs before any rank raises, so all ranks leave together.
  long failed = -1;
  for (long j = 0; j < nSystems; j++) {
    const int owner = ownerOf(j);
    if (!impl_->shareResult(owner, nAtoms, forces[j], &energies[j],
                            ok[static_cast<size_t>(j)] != 0,
                            errors[static_cast<size_t>(j)]) &&
        failed < 0)
      failed = j;
  }
  if (failed >= 0)
    raise_failure(failed, ownerOf(failed), errors[static_cast<size_t>(failed)]);
}

◆ computeSingle()

void RgpotPot::computeSingle	(	long	N,
		const double *	R,
		const int *	atomicNrs,
		double *	F,
		double *	U,
		const double *	box )

private

Definition at line 214 of file RgpotPot.cpp.

                                                                      {
  // Group 0 computes; its first rank's result reaches every rank.
  std::string error;
  bool ok = true;
  if (impl_->calculatorIndex() == 0)
    ok = try_force(*impl_, N, R, atomicNrs, F, U, box, error);
  if (!impl_->shareResult(0, N, F, U, ok, error))
    raise_failure(0, 0, error);
}

◆ engineAvailable()

bool RgpotPot::engineAvailable ( ) const

nodiscard

Definition at line 135 of file RgpotPot.cpp.

135{ return impl_ && impl_->available(); }

◆ force()

void RgpotPot::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 317 of file RgpotPot.cpp.

                                                                     {
  if (variance)
    *variance = 0.0;
  if (impl_->calculatorWorld() <= 1) {
    impl_->force(N, R, atomicNrs, F, U, box);
    return;
  }
  std::int64_t hdr[3] = {kSingle, N, 1};
  impl_->broadcastFromDriver(hdr, sizeof(hdr));
  impl_->broadcastFromDriver(const_cast<double *>(R), 3 * N * sizeof(double));
  impl_->broadcastFromDriver(const_cast<int *>(atomicNrs), N * sizeof(int));
  impl_->broadcastFromDriver(const_cast<double *>(box), 9 * sizeof(double));
  // Before the evaluation, so a failure that ends the job still stops
  // the workers.
  releaseWorkersAtExit();
  computeSingle(N, R, atomicNrs, F, U, box);
}

◆ forceBatch()

void RgpotPot::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 340 of file RgpotPot.cpp.

                                                      {
  forceBatchOwned(nSystems, nAtoms, positions, atomicNrs, forces, energies,
                  variances, boxes, nullptr);
}

◆ forceBatchOwned()

void RgpotPot::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 )

overridevirtual

System j runs on group owners[j] mod G when owners is given (an owner below zero falls back to j), so a NEB image keeps its group across partial band updates.

Reimplemented from eonc::Potential.

Definition at line 349 of file RgpotPot.cpp.

                                                   {
  std::vector<std::int64_t> ids(static_cast<size_t>(nSystems), -1);
  if (owners) {
    for (long j = 0; j < nSystems; j++)
      ids[static_cast<size_t>(j)] = owners[j];
  }
  if (impl_->calculatorWorld() > 1) {
    std::int64_t hdr[3] = {kBatch, nAtoms, nSystems};
    impl_->broadcastFromDriver(hdr, sizeof(hdr));
    std::vector<double> R(static_cast<size_t>(3 * nAtoms * nSystems));
    std::vector<int> Z(static_cast<size_t>(nAtoms * nSystems));
    std::vector<double> box(static_cast<size_t>(9 * nSystems));
    for (long j = 0; j < nSystems; j++) {
      std::copy(positions[j], positions[j] + 3 * nAtoms,
                R.begin() + 3 * nAtoms * j);
      std::copy(atomicNrs[j], atomicNrs[j] + nAtoms, Z.begin() + nAtoms * j);
      std::copy(boxes[j], boxes[j] + 9, box.begin() + 9 * j);
    }
    impl_->broadcastFromDriver(R.data(), R.size() * sizeof(double));
    impl_->broadcastFromDriver(Z.data(), Z.size() * sizeof(int));
    impl_->broadcastFromDriver(box.data(), box.size() * sizeof(double));
    impl_->broadcastFromDriver(ids.data(), ids.size() * sizeof(std::int64_t));
  }
  releaseWorkersAtExit();
  computeBatch(nSystems, nAtoms, positions, atomicNrs, forces, energies, boxes,
               ids.data());
  for (long j = 0; j < nSystems; j++) {
    if (variances)
      variances[j] = 0.0;
    forceCallCounter++;
    eonc::PotRegistry::get().on_force_call(ptype);
  }
}

◆ isThreadSafe()

bool RgpotPot::isThreadSafe ( ) const

inlinenodiscardoverridevirtualnoexcept

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

Definition at line 36 of file RgpotPot.h.

36{ return false; }

◆ operator=()

RgpotPot & RgpotPot::operator= ( const RgpotPot & )

delete

◆ releaseWorkersAtExit()

void RgpotPot::releaseWorkersAtExit ( )

private

Definition at line 175 of file RgpotPot.cpp.

                                    {
  if (g_driver || !impl_ || impl_->calculatorWorld() <= 1)
    return;
  // Runs before the MPI_Finalize handler registered in the constructor.
  // After a failed engine call the workers can sit in a collective that
  // the stop broadcast never meets; the grouped exit handler aborts the
  // world instead.
  g_driver = this;
  std::atexit([] {
    if (g_driver && !RGPotEngine::mpiAbortRequested())
      g_driver->stopAndDrop();
  });
}

◆ requiresIsolatedMoleculeLayout()

bool RgpotPot::requiresIsolatedMoleculeLayout ( ) const

inlinenodiscardoverridevirtualnoexcept

NWChem molecular SCF does not support PBC; CPMD may be periodic.

Reimplemented from eonc::Potential.

Definition at line 55 of file RgpotPot.h.

                                                                              {
    return backend_ == "nwchemc";
  }

◆ sendStop()

void RgpotPot::sendStop ( )

private

Definition at line 148 of file RgpotPot.cpp.

                        {
  if (!impl_ || !driver_ || stopped_ || impl_->calculatorWorld() <= 1)
    return;
  std::int64_t hdr[3] = {kStop, 0, 0};
  impl_->broadcastFromDriver(hdr, sizeof(hdr));
  stopped_ = true;
  if (g_driver == this)
    g_driver = nullptr;
}

◆ serveWorker()

void RgpotPot::serveWorker ( )

private

Definition at line 264 of file RgpotPot.cpp.

                           {
  for (;;) {
    std::int64_t hdr[3] = {kStop, 0, 0};
    impl_->broadcastFromDriver(hdr, sizeof(hdr));
    if (hdr[0] == kStop) {
      // Drop CPMD, wait until the driver has dropped it too, then exit 0.
      // MPI_Finalize is collective and runs from the exit handler.
      if (!dropped_) {
        impl_->shutdownModule();
        dropped_ = true;
      }
      std::int64_t ack[3] = {kDown, 0, 0};
      impl_->broadcastFromDriver(ack, sizeof(ack));
      std::exit(0);
    }
    const long n = static_cast<long>(hdr[1]);
    const long m = hdr[0] == kBatch ? static_cast<long>(hdr[2]) : 1;
    std::vector<double> R(static_cast<size_t>(3 * n * m));
    std::vector<int> Z(static_cast<size_t>(n * m));
    std::vector<double> box(static_cast<size_t>(9 * m));
    impl_->broadcastFromDriver(R.data(), R.size() * sizeof(double));
    impl_->broadcastFromDriver(Z.data(), Z.size() * sizeof(int));
    impl_->broadcastFromDriver(box.data(), box.size() * sizeof(double));
    std::vector<std::int64_t> ids(static_cast<size_t>(m), -1);
    if (hdr[0] == kBatch)
      impl_->broadcastFromDriver(ids.data(), ids.size() * sizeof(std::int64_t));
    std::vector<double> F(R.size()), U(static_cast<size_t>(m));
    // A failed request raised on the driver too; the driver decides
    // whether the job goes on, so a worker keeps serving.
    if (hdr[0] == kSingle) {
      try {
        computeSingle(n, R.data(), Z.data(), F.data(), U.data(), box.data());
      } catch (const std::runtime_error &) {
      }
      continue;
    }
    std::vector<const double *> pos(static_cast<size_t>(m)), bx(pos.size());
    std::vector<const int *> nrs(pos.size());
    std::vector<double *> frc(pos.size());
    for (long j = 0; j < m; j++) {
      pos[static_cast<size_t>(j)] = R.data() + 3 * n * j;
      nrs[static_cast<size_t>(j)] = Z.data() + n * j;
      frc[static_cast<size_t>(j)] = F.data() + 3 * n * j;
      bx[static_cast<size_t>(j)] = box.data() + 9 * j;
    }
    try {
      computeBatch(m, n, pos.data(), nrs.data(), frc.data(), U.data(),
                   bx.data(), ids.data());
    } catch (const std::runtime_error &) {
    }
  }
}

◆ stopAndDrop()

void RgpotPot::stopAndDrop ( )

private

Definition at line 158 of file RgpotPot.cpp.

                           {
  if (!impl_)
    return;
  const bool grouped = driver_ && impl_->calculatorWorld() > 1;
  if (grouped && !stopped_)
    sendStop();
  if (!dropped_) {
    impl_->shutdownModule();
    dropped_ = true;
  }
  if (grouped && !acked_) {
    std::int64_t hdr[3] = {kDown, 0, 0};
    impl_->broadcastFromDriver(hdr, sizeof(hdr));
    acked_ = true;
  }
}

◆ supportsBatchEvaluation()

bool RgpotPot::supportsBatchEvaluation ( ) const

nodiscardoverridevirtualnoexcept

With cpmdc calculator groups ([RgpotPot] ranks_per_image), a batch is spread over the groups: system j runs on group j mod G, then every rank receives every result, so all ranks keep the same band.

Reimplemented from eonc::Potential.

Definition at line 336 of file RgpotPot.cpp.

                                                      {
  return impl_ && impl_->calculatorGroups() > 1;
}

Member Data Documentation

◆ acked_

bool RgpotPot::acked_ {false}

private

Definition at line 81 of file RgpotPot.h.

81{false};

◆ backend_

std::string RgpotPot::backend_

private

Definition at line 77 of file RgpotPot.h.

◆ driver_

bool RgpotPot::driver_ {true}

private

Definition at line 78 of file RgpotPot.h.

78{true};

◆ dropped_

bool RgpotPot::dropped_ {false}

private

Definition at line 80 of file RgpotPot.h.

80{false};

◆ impl_

std::unique_ptr<RGPotEngine> RgpotPot::impl_

private

Definition at line 76 of file RgpotPot.h.

◆ stopped_

bool RgpotPot::stopped_ {false}

private

Definition at line 79 of file RgpotPot.h.

79{false};

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

/home/runner/work/eOn/eOn/include/eon/potentials/Rgpot/RgpotPot.h
/home/runner/work/eOn/eOn/client/potentials/Rgpot/RgpotPot.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ RgpotPot() [1/2]

◆ ~RgpotPot()

◆ RgpotPot() [2/2]

Member Function Documentation

◆ backend()

◆ computeBatch()

◆ computeSingle()

◆ engineAvailable()

◆ force()

◆ forceBatch()

◆ forceBatchOwned()

◆ isThreadSafe()

◆ operator=()

◆ releaseWorkersAtExit()

◆ requiresIsolatedMoleculeLayout()

◆ sendStop()

◆ serveWorker()

◆ stopAndDrop()

◆ supportsBatchEvaluation()

Member Data Documentation

◆ acked_

◆ backend_

◆ driver_

◆ dropped_

◆ impl_

◆ stopped_