eonc::ReplicaExchangeJob Class Reference

#include <ReplicaExchangeJob.h>

Inheritance diagram for eonc::ReplicaExchangeJob:

Public Member Functions
	~ReplicaExchangeJob ()=default
std::vector< std::string >	run (void) override
	Virtual run; used solely for dynamic dispatch.
std::shared_ptr< Matter >	runFromMatter (std::shared_ptr< Matter > initial)
	Matter-first; returns replica-0 Matter after sampling.
	Job (std::unique_ptr< Parameters > parameters, Runtime &rt)
	Borrow: caller keeps Runtime alive (CLI stack / Python Session).
	Job (std::unique_ptr< Parameters > parameters, std::unique_ptr< Runtime > rt)
	Own a Runtime (one-shot makeJob / rvalue).
	Job (std::unique_ptr< Parameters > parameters)
	Own a default-constructed Runtime.
	Job (std::shared_ptr< Potential > potPassed, const Parameters &parameters)
Public Member Functions inherited from eonc::Job
void	adoptRuntime (std::unique_ptr< Runtime > rt)
	Take ownership of a Runtime previously passed as Runtime&.
	Job (std::unique_ptr< Parameters > parameters, Runtime &rt)
	Borrow: caller keeps Runtime alive (CLI stack / Python Session).
	Job (std::unique_ptr< Parameters > parameters, std::unique_ptr< Runtime > rt)
	Own a Runtime (one-shot makeJob / rvalue).
	Job (std::unique_ptr< Parameters > parameters)
	Own a default-constructed Runtime.
	Job (std::shared_ptr< Potential > potPassed, const Parameters &parameters)
virtual	~Job ()=default
JobType	getType ()
PotRegistry &	pots () noexcept
void	releasePotential ()
	Drop the Potential so on_destroyed is recorded before Runtime dies.

Private Member Functions
void	saveData ()

Private Attributes
size_t	forceCalls {0}
std::shared_ptr< Matter >	pos
std::vector< std::string >	returnFiles
eonc::log::Scoped	log

Additional Inherited Members
Protected Attributes inherited from eonc::Job
JobType	jtype
Parameters	params
std::unique_ptr< Runtime >	owned_runtime_
	Non-null when this Job owns the composition root (one-shot makeJob).
Runtime *	runtime_
	Always valid: either owned_runtime_.get() or a caller-owned Runtime.
std::shared_ptr< Potential >	pot

Detailed Description

Definition at line 21 of file ReplicaExchangeJob.h.

Constructor & Destructor Documentation

~ReplicaExchangeJob()

eonc::ReplicaExchangeJob::~ReplicaExchangeJob ( )

default

Member Function Documentation

Job() [1/4]

eonc::Job::Job ( std::shared_ptr< Potential > potPassed, const Parameters & parameters )

inline

Definition at line 91 of file Job.h.

      : jtype{parameters.main_options().job},
        params{parameters},
        owned_runtime_{std::make_unique<Runtime>()},
        runtime_{owned_runtime_.get()},
        pot{potPassed} {}

Job() [2/4]

eonc::Job::Job ( std::unique_ptr< Parameters > parameters )

inlineexplicit

Own a default-constructed Runtime.

Definition at line 89 of file Job.h.

      : Job(std::move(parameters), std::make_unique<Runtime>()) {}

Job() [3/4]

eonc::Job::Job ( std::unique_ptr< Parameters > parameters, Runtime & rt )

inline

Borrow: caller keeps Runtime alive (CLI stack / Python Session).

Definition at line 76 of file Job.h.

      : jtype{parameters->main_options().job},
        params{*std::move(parameters)},
        owned_runtime_{},
        runtime_{&rt},
        pot{helpers::makePotential(params.potential_options().potential, params,
                                   rt)} {}

Job() [4/4]

eonc::Job::Job ( std::unique_ptr< Parameters > parameters, std::unique_ptr< Runtime > rt )

inline

Own a Runtime (one-shot makeJob / rvalue).

Definition at line 84 of file Job.h.

      : Job(std::move(parameters), *rt) {
    adoptRuntime(std::move(rt));
  }

run()

std::vector< std::string > eonc::ReplicaExchangeJob::run ( void )

overridevirtual

Virtual run; used solely for dynamic dispatch.

Implements eonc::Job.

Definition at line 31 of file ReplicaExchangeJob.cpp.

                                             {
  std::string posFilename =
      eonc::helpers::getRelevantFile(params.main_options().conFilename);
  pos = std::make_shared<Matter>(pot, params);
  if (!eonc::io::io_ok(pos->con2matter(posFilename))) {
    QUILL_LOG_CRITICAL(log, "Failed to load {}", posFilename);
    throw std::runtime_error("failed to load " + posFilename);
  }
  (void)runFromMatter(pos);
  return returnFiles;
}

runFromMatter()

std::shared_ptr< Matter > eonc::ReplicaExchangeJob::runFromMatter

(

std::shared_ptr< Matter >

initial

)

Matter-first; returns replica-0 Matter after sampling.

Definition at line 44 of file ReplicaExchangeJob.cpp.

                                                               {
  if (!initial) {
    throw std::runtime_error("ReplicaExchangeJob::runFromMatter: null Matter");
  }
  pos = initial;
  pos->setPotential(pot);
 
  auto &rex = ParametersLoadAccess::replica_exchange_options(params);
  if (rex.replicas < 1) {
    throw std::invalid_argument(
        "ReplicaExchangeJob: replica_exchange.replicas must be >= 1");
  }
  if (rex.temperature_low <= 0.0) {
    rex.temperature_low = params.main_options().temperature > 0.0
                              ? params.main_options().temperature
                              : 300.0;
  }
  if (rex.temperature_high <= rex.temperature_low) {
    rex.temperature_high = rex.temperature_low * 1.5;
  }
 
  long samplingSteps =
      static_cast<long>(params.replica_exchange_options().sampling_time /
                            params.dynamics_options().time_step +
                        0.5);
  long exchangePeriodSteps =
      static_cast<long>(params.replica_exchange_options().exchange_period /
                            params.dynamics_options().time_step +
                        0.5);
  const double kB = params.constants().kB;
  if (samplingSteps <= 0)
    samplingSteps = 1;
  if (exchangePeriodSteps <= 0)
    exchangePeriodSteps = 1;
 
  QUILL_LOG_DEBUG(log, "Running Replica Exchange");
 
  long refForceCalls = PotRegistry::get().total_force_calls();
 
  const long nReplicas = params.replica_exchange_options().replicas;
  std::vector<std::shared_ptr<Matter>> replica(nReplicas);
  std::vector<std::unique_ptr<Dynamics>> replicaDynamics(nReplicas);
 
  // Per-image potentials: each replica gets its own potential instance when
  // the potential requires it (e.g. ML potentials with internal state)
  const bool perImage = pot->needsPerImageInstance();
  for (long i = 0; i < nReplicas; i++) {
    auto replicaPot = perImage ? eonc::helpers::makePotential(params) : pot;
    replica[i] = std::make_shared<Matter>(replicaPot, params);
    *replica[i] = *pos;
    replica[i]->setPotential(replicaPot);
    replicaDynamics[i] = std::make_unique<Dynamics>(replica[i].get(), params);
  }
 
  std::vector<double> replicaTemperature(nReplicas);
 
  QUILL_LOG_DEBUG(log, "Temperature distribution:");
  if (nReplicas < 2) {
    replicaTemperature[0] = params.replica_exchange_options().temperature_low;
    replicaDynamics[0]->setTemperature(replicaTemperature[0]);
    replicaDynamics[0]->setThermalVelocity();
  } else if (params.replica_exchange_options().temperature_distribution ==
             "linear") {
    for (long i = 0; i < nReplicas; i++) {
      replicaTemperature[i] =
          params.replica_exchange_options().temperature_low +
          static_cast<double>(i) / static_cast<double>(nReplicas - 1) *
              (params.replica_exchange_options().temperature_high -
               params.replica_exchange_options().temperature_low);
      replicaDynamics[i]->setTemperature(replicaTemperature[i]);
      replicaDynamics[i]->setThermalVelocity();
    }
  } else if (params.replica_exchange_options().temperature_distribution ==
             "exponential") {
    double kTemp = std::log(params.replica_exchange_options().temperature_high /
                            params.replica_exchange_options().temperature_low) /
                   static_cast<double>(nReplicas - 1);
    for (long i = 0; i < nReplicas; i++) {
      replicaTemperature[i] =
          params.replica_exchange_options().temperature_low *
          std::exp(kTemp * static_cast<double>(i));
      replicaDynamics[i]->setTemperature(replicaTemperature[i]);
      replicaDynamics[i]->setThermalVelocity();
      QUILL_LOG_DEBUG(log, "replica: {} temperature {:.0f}", i + 1,
                      replicaTemperature[i]);
    }
  } else {
    throw std::invalid_argument(
        "replica_exchange.temperature_distribution must be linear or "
        "exponential");
  }
 
  QUILL_LOG_DEBUG(
      log, "Replica Exchange sampling for {:.0f} fs; {} steps; {} replicas.",
      params.replica_exchange_options().sampling_time * 10.18, samplingSteps,
      params.replica_exchange_options().replicas);
 
  // Parallel replica dynamics when enabled and potential supports it
  const bool canParallel = params.main_options().parallel &&
                           (eonc::potAllowsSharedInstance(*pot) || perImage);
 
  for (long step = 1; step <= samplingSteps; step++) {
    if (canParallel && nReplicas > 1) {
      // Parallel: each replica runs its MD step in a separate thread
      std::vector<std::thread> threads;
      threads.reserve(nReplicas);
      for (long i = 0; i < nReplicas; i++) {
        threads.emplace_back([&, i] {
          // New std::thread, new TLS ran2. Split the stream by replica and
          // step so Langevin/Andersen noise is not identical across replicas.
          const long userSeed = params.main_options().randomSeed;
          const long base = (userSeed > 0) ? userSeed : 1;
          eonc::rng::random(base + (step + 1) * 10007 + (i + 1));
          replicaDynamics[i]->oneStep();
        });
      }
      for (auto &t : threads) {
        t.join();
      }
    } else {
      for (long i = 0; i < nReplicas; i++) {
        replicaDynamics[i]->oneStep();
      }
    }
 
    // Metropolis replica exchange
    if (nReplicas >= 2 && (step % exchangePeriodSteps) == 0) {
      for (long trial = 0;
           trial < params.replica_exchange_options().exchange_trials; trial++) {
        long i = eonc::rng::randomInt(0, nReplicas - 2);
        double energyLow = replica[i]->getPotentialEnergy();
        double energyHigh = replica[i + 1]->getPotentialEnergy();
        double kbTLow = kB * replicaTemperature[i];
        double kbTHigh = kB * replicaTemperature[i + 1];
        double pAcc =
            std::min(1.0, std::exp((energyHigh - energyLow) *
                                   (eonc::safemath::safe_recip(kbTHigh, 0.0) -
                                    eonc::safemath::safe_recip(kbTLow, 0.0))));
        double rnd = eonc::rng::randomDouble();
        QUILL_LOG_INFO(log,
                       "step: {} trial swap, i {}, elow: {:.5f}, ehigh: "
                       "{:.5f}, pAcc: {:.5f}, rand: {}",
                       step, i, energyLow, energyHigh, pAcc, rnd);
        if (rnd < pAcc) {
          QUILL_LOG_INFO(log, "swap");
          // Swap configurations, not pointers. Dynamics stays on its T slot.
          auto potLow = replica[i]->getPotential();
          auto potHigh = replica[i + 1]->getPotential();
          Matter tmp = *replica[i];
          *replica[i] = *replica[i + 1];
          *replica[i + 1] = tmp;
          replica[i]->setPotential(potLow);
          replica[i + 1]->setPotential(potHigh);
          replicaDynamics[i]->setThermalVelocity();
          replicaDynamics[i + 1]->setThermalVelocity();
        } else {
          QUILL_LOG_INFO(log, "no swap");
        }
      }
    }
  }
 
  forceCalls = PotRegistry::get().total_force_calls() - refForceCalls;
  if (!replica.empty()) {
    *pos = *replica[0];
  }
  saveData();
  return pos;
}

saveData()

void eonc::ReplicaExchangeJob::saveData ( )

private

Definition at line 214 of file ReplicaExchangeJob.cpp.

                                  {
  std::string resultsFilename("results.dat");
  returnFiles.push_back(resultsFilename);
 
  std::ofstream out(resultsFilename, std::ios::binary);
  if (out) {
    out << std::format("{} termination_reason\n", 0);
    out << "GOOD termination_reason_text\n";
    out << "replica_exchange job_type\n";
    out << std::format("{} random_seed\n", params.main_options().randomSeed);
    out << std::format(
        "{} potential_type\n",
        magic_enum::enum_name<PotType>(params.potential_options().potential));
    out << std::format("{} force_calls_sampling\n", forceCalls);
  }
 
  std::string posFilename("pos_out.con");
  returnFiles.push_back(posFilename);
  if (pos) {
    if (!eonc::io::io_ok(pos->matter2con(posFilename))) {
      QUILL_LOG_ERROR(log, "Failed to write {}", posFilename);
    }
  }
}

Member Data Documentation

forceCalls

size_t eonc::ReplicaExchangeJob::forceCalls {0}

private

Definition at line 32 of file ReplicaExchangeJob.h.

{0};

log

eonc::log::Scoped eonc::ReplicaExchangeJob::log

private

Definition at line 35 of file ReplicaExchangeJob.h.

pos

std::shared_ptr<Matter> eonc::ReplicaExchangeJob::pos

private

Definition at line 33 of file ReplicaExchangeJob.h.

returnFiles

std::vector<std::string> eonc::ReplicaExchangeJob::returnFiles

private

Definition at line 34 of file ReplicaExchangeJob.h.

---

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

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