RGPotEngine Class Reference

Opaque rgpot-backed engine (nwchemc / cpmdc / metatomic / xtb). More...

#include <RGPotEngine.h>

Classes
struct	Impl

Public Member Functions
	RGPotEngine (const RGPotEngineOptions &opt)
	~RGPotEngine ()
	RGPotEngine (const RGPotEngine &)=delete
RGPotEngine &	operator= (const RGPotEngine &)=delete
const std::string &	backend () const noexcept
bool	available () const
void	force (long N, const double *R, const int *atomicNrs, double *F, double *U, const double *box) const
int	calculatorGroups () const noexcept
	Number of calculator groups the MPI world is split into (1 when ranks_per_image is off) and the group this rank belongs to.
int	calculatorIndex () const noexcept
int	calculatorWorld () const noexcept
	Ranks in the MPI world the groups were bound on (1 without MPI).
int	worldRank () const noexcept
	This process's rank in that world (0 without MPI).
void	broadcastFromDriver (void *data, std::size_t bytes) const
	Collective on MPI_COMM_WORLD: every rank leaves with world rank 0's bytes.
void	finalizeMpiAtExit () const
	Registers MPI_Finalize at exit (once per process) when the world has more than one rank.
void	armGroupedExit () const
	After MPI_Finalize, _Exit.
void	shutdownModule () noexcept
	Calls cpmdc_finalize while the engine is still mapped. MPI stays up.
bool	shareResult (int owner, long N, double *F, double *U, bool ok, std::string &error) const
	Collective on MPI_COMM_WORLD: every rank leaves with the energy and the 3N forces computed by the first rank of group owner.

Static Public Member Functions
static bool	mpiAbortRequested () noexcept
	True once rgpot asked for MPI_Abort at exit in this process.

Private Attributes
std::unique_ptr< Impl >	impl_
std::string	backend_

Detailed Description

Opaque rgpot-backed engine (nwchemc / cpmdc / metatomic / xtb).

Definition at line 46 of file RGPotEngine.h.

Constructor & Destructor Documentation

RGPotEngine() [1/2]

RGPotEngine::RGPotEngine ( const RGPotEngineOptions & opt )

explicit

Definition at line 260 of file RGPotEngine.cpp.

    : impl_(std::make_unique<Impl>()) {
  backend_ = to_lower(opt.backend);
  if (backend_ == "nwchem" || backend_ == "nwchemc" ||
      backend_ == "nwchempot") {
    backend_ = "nwchemc";
    impl_->backend = Impl::Backend::Nwchemc;
    ::capnp::MallocMessageBuilder msg;
    auto params = msg.initRoot<::NWChemParams>();
    params.setBasis(opt.basis);
    params.setTheory(opt.theory);
    params.setScfType(opt.scf_type);
    params.setCharge(opt.charge);
    params.setMultiplicity(opt.multiplicity);
    if (!opt.engine_path.empty())
      params.setEnginePath(opt.engine_path);
    else if (!opt.engine_library.empty())
      params.setEnginePath(opt.engine_library);
    if (!opt.engine_root.empty())
      params.setNwchemRoot(opt.engine_root);
    if (!opt.title.empty())
      params.setTitle(opt.title);
    if (opt.memory_mb > 0)
      params.setMemoryMb(static_cast<uint32_t>(opt.memory_mb));
    if (!opt.scratch_dir.empty())
      params.setScratchDir(opt.scratch_dir);
    // DFT XC as inputBlocks when theory=dft and scfType is an XC label
    std::string block = opt.input_block;
    if (block.empty()) {
      if (const char *env = std::getenv("RGPOT_NWCHEM_INPUT_BLOCK"))
        block = env;
    }
    if (block.empty() && (opt.theory == "dft" || opt.theory == "DFT") &&
        looks_like_dft_xc(opt.scf_type)) {
      block = "dft\n  xc " + opt.scf_type + "\n  mult " +
              std::to_string(opt.multiplicity) + "\nend";
    } else if (block.empty() && looks_like_dft_xc(opt.theory)) {
      block = "dft\n  xc " + opt.theory + "\n  mult " +
              std::to_string(opt.multiplicity) + "\nend";
    }
    if (!block.empty()) {
      auto blocks = params.initInputBlocks(1);
      blocks.set(0, block);
    }
    impl_->nwchem = std::make_unique<rgpot::NWChemPot>(params.asReader());
    if (!impl_->nwchem->available())
      throw std::runtime_error(
          "RGPOT(nwchemc): engine not available (set NWCHEMC_LIBRARY / "
          "RGPOT_NWCHEMC_ENGINE or [RgpotPot] engine_path)");
  } else if (backend_ == "cpmd" || backend_ == "cpmdc" ||
             backend_ == "cpmdpot") {
    backend_ = "cpmdc";
    impl_->backend = Impl::Backend::Cpmdc;
    std::string local_error;
    try {
      ::capnp::MallocMessageBuilder msg;
      ::CPMDParams::Builder params = eon::fillCpmdParams(msg, opt);
      impl_->cpmd = std::make_unique<rgpot::CPMDPot>(params.asReader());
      pin_cpmd_library(opt.engine_path.empty() ? opt.engine_library
                                               : opt.engine_path);
      if (!impl_->cpmd->available())
        throw std::runtime_error(
            "RGPOT(cpmdc): engine not available (set CPMDC_LIBRARY / "
            "RGPOT_CPMDC_ENGINE or [RgpotPot] engine_path)");
    } catch (const std::exception &ex) {
      local_error = ex.what();
    }
    // Several ranks: agree before MPI_Comm_split. One rank that cannot
    // read params_path must not leave the others inside the split.
    if (mpi_world_hint() <= 1 && !local_error.empty())
      throw std::runtime_error(local_error);
#if defined(__linux__) && defined(EON_RGPOT_MPI)
    // rgpot reports MPI only once MPI_Init has run, and agree_construction
    // is what initialises it, so the agreement keys on the launch size.
    if (mpi_world_hint() > 1 && !agree_construction(local_error)) {
      armGroupedExit();
      throw std::runtime_error(
          local_error.empty()
              ? std::string(
                    "RGPOT(cpmdc): a rank failed before the calculator split")
              : local_error);
    }
#endif
    if (!local_error.empty())
      throw std::runtime_error(local_error);
    if (::rgpot::calculatorsUseMpi()) {
      // Collective on MPI_COMM_WORLD, before the first force: the engine
      // installs the group communicator ahead of CPMD's mp_start.
      // ranks_per_image = 0 is one calculator on the whole world.
      const rgpot::CalculatorGroup g =
          ::rgpot::bindCalculators(opt.ranks_per_image);
      ::rgpot::finalizeMpiAtExit();
      if (mpi_world_hint() > 1)
        armGroupedExit();
      if (g.index < 0)
        throw std::runtime_error(
            "RGPOT(cpmdc): ranks_per_image=" +
            std::to_string(opt.ranks_per_image) +
            " does not divide the MPI world into calculator groups");
      impl_->groups = ::rgpot::calculatorCount();
      impl_->group = g.index;
      impl_->world = ::rgpot::calculatorWorldSize();
    } else if (opt.ranks_per_image > 0) {
      throw std::runtime_error(
          "RGPOT(cpmdc): ranks_per_image needs rgpot built with MPI "
          "(-Drgpot:with_mpi=enabled)");
    }
  } else if (backend_ == "metatomic" || backend_ == "mta" ||
             backend_ == "metatomicpot") {
    backend_ = "metatomic";
    impl_->backend = Impl::Backend::Metatomic;
    MetatomicEngineOptions mopt;
    mopt.model_path = opt.model_path;
    mopt.device = opt.device;
    mopt.length_unit = opt.length_unit;
    mopt.extensions_directory = opt.extensions_directory;
    mopt.check_consistency = opt.check_consistency;
    mopt.uncertainty_threshold = opt.uncertainty_threshold;
    mopt.engine_path =
        !opt.engine_path.empty() ? opt.engine_path : opt.engine_library;
    mopt.torch_determinism_strict = opt.torch_determinism_strict;
    impl_->metatomic = std::make_unique<MetatomicEngineLoader>(mopt);
    if (!impl_->metatomic->available())
      throw std::runtime_error(
          "RGPOT(metatomic): engine not available (set RGPOT_METATOMIC_ENGINE "
          "or [RgpotPot] engine_path to libmetatomic_engine.so)");
  } else if (backend_ == "xtb" || backend_ == "xtbpot" || backend_ == "gfn" ||
             backend_ == "gfnxtb") {
    backend_ = "xtb";
    impl_->backend = Impl::Backend::Xtb;
    XTBEngineOptions xopt;
    xopt.method = xtb_method_from_paramset(opt.xtb_paramset);
    xopt.accuracy = opt.xtb_accuracy;
    xopt.electronic_temperature = opt.xtb_electronic_temperature;
    xopt.max_iterations = opt.xtb_max_iterations;
    xopt.charge = opt.xtb_charge;
    xopt.uhf = opt.xtb_uhf;
    xopt.engine_path =
        !opt.engine_path.empty() ? opt.engine_path : opt.engine_library;
    impl_->xtb = std::make_unique<XTBEngineLoader>(xopt);
    if (!impl_->xtb->available())
      throw std::runtime_error(
          "RGPOT(xtb): engine not available (set RGPOT_XTB_ENGINE or "
          "[RgpotPot] engine_path to libxtb_engine.so)");
  } else {
    throw std::runtime_error("RGPOT: unknown backend '" + opt.backend +
                             "' (expected nwchemc, cpmdc, metatomic, or xtb)");
  }
}

~RGPotEngine()

RGPotEngine::~RGPotEngine ( )

default

RGPotEngine() [2/2]

RGPotEngine::RGPotEngine ( const RGPotEngine & )

delete

Member Function Documentation

armGroupedExit()

void RGPotEngine::armGroupedExit

(

)

const

After MPI_Finalize, _Exit.

Library destructors do not run on a finalized MPI world. When rgpot requested an abort at exit (a failed engine call), MPI_Abort replaces MPI_Finalize. No-op unless this process was started as one of several ranks.

Definition at line 440 of file RGPotEngine.cpp.

                                       {
#if defined(__linux__) && defined(EON_RGPOT_MPI)
  if (mpi_world_hint() <= 1)
    return;
  static std::once_flag once;
  std::call_once(once, [] { ::on_exit(eon_rgpot_hard_exit, nullptr); });
#else
  (void)this;
#endif
}

available()

bool RGPotEngine::available ( ) const

nodiscard

Definition at line 504 of file RGPotEngine.cpp.

                                  {
  if (!impl_)
    return false;
  if (impl_->backend == Impl::Backend::Nwchemc && impl_->nwchem)
    return impl_->nwchem->available();
  if (impl_->backend == Impl::Backend::Cpmdc && impl_->cpmd)
    return impl_->cpmd->available();
  if (impl_->backend == Impl::Backend::Metatomic && impl_->metatomic)
    return impl_->metatomic->available();
  if (impl_->backend == Impl::Backend::Xtb && impl_->xtb)
    return impl_->xtb->available();
  return false;
}

backend()

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

inlinenodiscardnoexcept

Definition at line 53 of file RGPotEngine.h.

{ return backend_; }

broadcastFromDriver()

void RGPotEngine::broadcastFromDriver	(	void *	data,
		std::size_t	bytes ) const

Collective on MPI_COMM_WORLD: every rank leaves with world rank 0's bytes.

A no-op on one rank.

Definition at line 463 of file RGPotEngine.cpp.

                                                                       {
  if (!impl_ || impl_->world <= 1 || bytes == 0)
    return;
  // World rank 0 is the first rank of calculator 0.
  if (::rgpot::shareFromCalculator(0, data, bytes) == 0)
    throw std::runtime_error("RGPOT: could not broadcast from the driver rank");
}

calculatorGroups()

int RGPotEngine::calculatorGroups ( ) const

nodiscardnoexcept

Number of calculator groups the MPI world is split into (1 when ranks_per_image is off) and the group this rank belongs to.

Definition at line 412 of file RGPotEngine.cpp.

                                                 {
  return impl_ ? impl_->groups : 1;
}

calculatorIndex()

int RGPotEngine::calculatorIndex ( ) const

nodiscardnoexcept

Definition at line 416 of file RGPotEngine.cpp.

                                                {
  return impl_ ? impl_->group : 0;
}

calculatorWorld()

int RGPotEngine::calculatorWorld ( ) const

nodiscardnoexcept

Ranks in the MPI world the groups were bound on (1 without MPI).

Definition at line 420 of file RGPotEngine.cpp.

                                                {
  return impl_ ? impl_->world : 1;
}

finalizeMpiAtExit()

void RGPotEngine::finalizeMpiAtExit

(

)

const

Registers MPI_Finalize at exit (once per process) when the world has more than one rank.

Definition at line 431 of file RGPotEngine.cpp.

                                          {
  if (impl_ && impl_->world > 1)
    ::rgpot::finalizeMpiAtExit();
}

force()

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

Definition at line 518 of file RGPotEngine.cpp.

                                                                       {
  // Set on one rank by the multi-rank failure test. The text is the
  // engine error that rank has to deliver to rank 0.
  if (const char *fail = std::getenv("RGPOT_FORCE_FAIL")) {
    if (fail[0] != '\0')
      throw std::runtime_error(fail);
  }
  if (N <= 0)
    throw std::runtime_error("RGPotEngine::force called with N <= 0");
 
  AtomMatrix positions(static_cast<int>(N), 3);
  for (long i = 0; i < N; ++i) {
    const int ii = static_cast<int>(i);
    positions(ii, 0) = R[3 * i + 0];
    positions(ii, 1) = R[3 * i + 1];
    positions(ii, 2) = R[3 * i + 2];
  }
  std::vector<int> atmtypes(atomicNrs, atomicNrs + N);
  const auto cell = box_from_row_major(box);
 
  if (impl_->backend == Impl::Backend::Metatomic) {
    impl_->metatomic->force(N, R, atomicNrs, F, U, nullptr, box);
    return;
  }
  if (impl_->backend == Impl::Backend::Xtb) {
    impl_->xtb->force(N, R, atomicNrs, F, U, nullptr, box);
    return;
  }
 
  // rgpot >= 2.5.0: operator() returns (energy, forces, variance).
  std::tuple<double, AtomMatrix, double> result;
  if (impl_->backend == Impl::Backend::Nwchemc)
    result = (*impl_->nwchem)(positions, atmtypes, cell);
  else
    result = (*impl_->cpmd)(positions, atmtypes, cell);
 
  *U = std::get<0>(result);
  const auto &forces = std::get<1>(result);
  for (long i = 0; i < N; ++i) {
    const int ii = static_cast<int>(i);
    F[3 * i + 0] = forces(ii, 0);
    F[3 * i + 1] = forces(ii, 1);
    F[3 * i + 2] = forces(ii, 2);
  }
}

mpiAbortRequested()

bool RGPotEngine::mpiAbortRequested ( )

staticnodiscardnoexcept

True once rgpot asked for MPI_Abort at exit in this process.

Definition at line 436 of file RGPotEngine.cpp.

                                             {
  return ::rgpot::mpiAbortRequested();
}

operator=()

RGPotEngine & RGPotEngine::operator= ( const RGPotEngine & )

delete

shareResult()

bool RGPotEngine::shareResult	(	int	owner,
		long	N,
		double *	F,
		double *	U,
		bool	ok,
		std::string &	error ) const

Collective on MPI_COMM_WORLD: every rank leaves with the energy and the 3N forces computed by the first rank of group owner.

Only CPMD's parent rank holds the true forces, so this also keeps the ranks of one group on the same step. ok is the owner's status; the return value is the owner's status on every rank. error is the owner's engine message on every rank.

Definition at line 471 of file RGPotEngine.cpp.

                                                      {
  if (!impl_ || impl_->world <= 1) {
    (void)error;
    return ok;
  }
  // Slot 0 carries the owner's status, so a failed evaluation reaches
  // every rank through the same broadcast as a good one.
  std::vector<double> buf(static_cast<size_t>(3 * N + 2));
  if (owner == impl_->group) {
    buf[0] = ok ? 1.0 : 0.0;
    buf[1] = *U;
    std::copy(F, F + 3 * N, buf.begin() + 2);
  }
  if (::rgpot::shareFromCalculator(owner, buf.data(),
                                   buf.size() * sizeof(double)) == 0)
    throw std::runtime_error("RGPOT: could not share a calculator result");
  *U = buf[1];
  std::copy(buf.begin() + 2, buf.end(), F);
  // The owner's engine text travels with the status. Other ranks hold an
  // empty string until this broadcast.
  std::array<char, 512> msg{};
  if (owner == impl_->group && !error.empty()) {
    const auto n = std::min(error.size(), msg.size() - 1);
    std::memcpy(msg.data(), error.data(), n);
  }
  if (::rgpot::shareFromCalculator(owner, msg.data(), msg.size()) == 0)
    throw std::runtime_error("RGPOT: could not share a calculator error");
  if (msg[0] != '\0')
    error.assign(msg.data());
  return buf[0] == 1.0;
}

shutdownModule()

void RGPotEngine::shutdownModule ( )

noexcept

Calls cpmdc_finalize while the engine is still mapped. MPI stays up.

Definition at line 451 of file RGPotEngine.cpp.

                                          {
  if (!impl_ || impl_->module_down)
    return;
  impl_->module_down = true;
#if !defined(_WIN32)
  if (auto *fin =
          reinterpret_cast<void (*)()>(dlsym(RTLD_DEFAULT, "cpmdc_finalize")))
    fin();
  pin_cpmd_library({});
#endif
}

worldRank()

int RGPotEngine::worldRank ( ) const

nodiscardnoexcept

This process's rank in that world (0 without MPI).

Definition at line 424 of file RGPotEngine.cpp.

                                          {
  if (!impl_ || impl_->world <= 1)
    return 0;
  const rgpot::CalculatorGroup &g = ::rgpot::thisCalculator();
  return g.index * g.ranks + g.rank_in_group;
}

Member Data Documentation

backend_

std::string RGPotEngine::backend_

private

Definition at line 93 of file RGPotEngine.h.

impl_

std::unique_ptr<Impl> RGPotEngine::impl_

private

Definition at line 92 of file RGPotEngine.h.

---

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

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