Loading...
Searching...
No Matches
eonc::InstantonJob Class Reference

Ring-polymer instanton ([Instanton]): the tunnelling splitting between two minima beyond one-dimensional WKB (mode splitting), or the thermal rate through a saddle (mode rate): the ring below the crossover temperature, and the parabolic barrier factor times quantum harmonic transition-state theory above it. More...

#include <InstantonJob.h>

Inheritance diagram for eonc::InstantonJob:

Public Member Functions

 InstantonJob (std::unique_ptr< Parameters > parameters, Runtime &rt)
 InstantonJob (std::shared_ptr< Potential > potPassed, const Parameters &parameters)
 ~InstantonJob (void)=default
std::vector< std::string > run (void) override
 Virtual run; used solely for dynamic dispatch.
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
size_t potRegistryForceCalls () const noexcept
 Force calls charged to pot's registry.
void releasePotential ()
 Drop the Potential so on_destroyed is recorded before Runtime dies.

Additional Inherited Members

Protected Member Functions inherited from eonc::Job
 Job (std::unique_ptr< Parameters > parameters, Runtime &rt, ExclusivePotential)
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::unique_ptr< Potential > ownedPot
 Exclusive until a multi-owner job promotes it in the public constructor.
std::shared_ptr< Potential > pot
 Set when one Potential is shared across Matters, images, or a caller.

Detailed Description

Ring-polymer instanton ([Instanton]): the tunnelling splitting between two minima beyond one-dimensional WKB (mode splitting), or the thermal rate through a saddle (mode rate): the ring below the crossover temperature, and the parabolic barrier factor times quantum harmonic transition-state theory above it.

Definition at line 23 of file InstantonJob.h.

Constructor & Destructor Documentation

◆ InstantonJob() [1/2]

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

Definition at line 25 of file InstantonJob.h.

26 : Job(std::move(parameters), rt) {}
Job(std::unique_ptr< Parameters > parameters, Runtime &rt, ExclusivePotential)
Definition Job.h:71

◆ InstantonJob() [2/2]

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

Definition at line 27 of file InstantonJob.h.

29 : Job(std::move(potPassed), parameters) {}

◆ ~InstantonJob()

eonc::InstantonJob::~InstantonJob ( void )
default

Member Function Documentation

◆ run()

std::vector< std::string > eonc::InstantonJob::run ( void )
overridevirtual

Virtual run; used solely for dynamic dispatch.

Implements eonc::Job.

Definition at line 1442 of file InstantonJob.cpp.

1442 {
1443 const auto &o = params.instanton_options();
1444 if (o.mode != "rate" && !o.initial_ring.empty()) {
1445 throw std::invalid_argument("instanton: initial_ring requires mode rate");
1446 }
1447 pathintegral::requireTrotterSprings(o.springs, "instanton");
1448 std::vector<std::string> returnFiles;
1449 const std::string resultsFile = "results.dat";
1450 const std::string pathFile = "instanton.con";
1451 returnFiles.push_back(resultsFile);
1452
1453 auto reactant = std::make_unique<Matter>(pot, params);
1454 if (!io::io_ok(reactant->con2matter(o.reactant_filename))) {
1455 throw std::runtime_error("instanton: cannot read " + o.reactant_filename);
1456 }
1457 const MassWeighted mw(*reactant);
1458 const long n = mw.dimension();
1459 const VectorXd qStart = VectorXd::Zero(n);
1460
1461 // Bead evaluations: one batch per call, through forceBatch when the
1462 // potential spreads a batch over calculators.
1463 std::vector<std::unique_ptr<Matter>> pool;
1464 tunneling::OwnedBatchPotential evaluateOwned =
1465 [&](const std::vector<VectorXd> &q, std::vector<double> &v,
1466 std::vector<VectorXd> &grad, const std::vector<long> &owners) {
1467 if (owners.size() != q.size())
1468 throw std::invalid_argument(
1469 "instanton: potential owner count mismatch");
1470 while (pool.size() < q.size()) {
1471 pool.push_back(std::make_unique<Matter>(*reactant));
1472 }
1473 for (size_t j = 0; j < q.size(); ++j) {
1474 mw.place(q[j], *pool[j]);
1475 }
1476 v.resize(q.size());
1477 grad.resize(q.size());
1478 if (pot->supportsBatchEvaluation() && !q.empty()) {
1479 const long atoms = reactant->numberOfAtoms();
1480 std::vector<VectorXi> nrs(q.size());
1481 std::vector<Matrix3d> boxes(q.size());
1482 std::vector<const double *> posPtr, boxPtr;
1483 std::vector<const int *> nrsPtr;
1484 std::vector<double *> frcPtr;
1485 for (size_t j = 0; j < q.size(); ++j) {
1486 nrs[j] = pool[j]->getAtomicNrs();
1487 boxes[j] = pool[j]->getPeriodic() ? pool[j]->getCell()
1488 : Matrix3d::Zero().eval();
1489 }
1490 for (size_t j = 0; j < q.size(); ++j) {
1491 posPtr.push_back(pool[j]->getPositions().data());
1492 nrsPtr.push_back(nrs[j].data());
1493 frcPtr.push_back(pool[j]->forcesData());
1494 boxPtr.push_back(boxes[j].data());
1495 }
1496 std::vector<double> energies(q.size()), variances(q.size());
1497 pot->forceBatchOwned(static_cast<long>(q.size()), atoms,
1498 posPtr.data(), nrsPtr.data(), frcPtr.data(),
1499 energies.data(), variances.data(), boxPtr.data(),
1500 owners.data());
1501 for (size_t j = 0; j < q.size(); ++j) {
1502 pool[j]->setComputedPotential(energies[j], variances[j]);
1503 }
1504 }
1505 for (size_t j = 0; j < q.size(); ++j) {
1506 v[j] = pool[j]->getPotentialEnergy();
1507 grad[j] = mw.gradient(pool[j]->getForces());
1508 }
1509 };
1510
1511 tunneling::BatchPotential evaluate = [&](const std::vector<VectorXd> &q,
1512 std::vector<double> &v,
1513 std::vector<VectorXd> &grad) {
1514 evaluateOwned(q, v, grad,
1515 std::vector<long>(q.size(), potential_owner::auxiliary));
1516 };
1517
1518 // The first call is the reactant. Its Hessian decides which rotations
1519 // are zero modes; later beads reuse that decision.
1520 std::array<bool, 3> rotationZero{{false, false, false}};
1521 std::array<double, 3> rotationResidual{{0.0, 0.0, 0.0}};
1522 bool rotationsKnown = false;
1523 auto hessianWith = [&](const VectorXd &q, bool projectRotations,
1524 const std::string &filename = std::string{}) {
1525 Matter m(*reactant);
1526 mw.place(q, m);
1527 MatrixXd out;
1528 if (filename.empty()) {
1529 Hessian h(params, &m);
1530 h.writeHessianFile(false);
1531 out = h.getHessian(&m, mw.freeAtoms());
1532 } else {
1533 out = tunneling::readReferenceHessian(filename, m, n);
1534 EONC_LOG_INFO("[Instanton] reference Hessian read from {} with matching "
1535 "geometry and mass metric",
1536 filename);
1537 }
1538 if (out.rows() != n) {
1539 throw std::runtime_error("instanton: a bead Hessian failed");
1540 }
1541 if (!rotationsKnown) {
1542 mw.markRotationZeroModes(
1543 out, mw.rigidGenerators(m),
1544 params.instanton_options().rotation_zero_fraction, rotationZero,
1545 rotationResidual);
1546 rotationsKnown = true;
1547 }
1548 // A finite-difference Hessian of a free structure has small nonzero
1549 // rigid eigenvalues of either sign; project them to zero. At a point
1550 // that is not stationary, H r for a rotation r is the rotated gradient,
1551 // which on a ring bead balances the springs; ring beads keep it and
1552 // lose only their translations.
1553 const std::array<bool, 3> none{{false, false, false}};
1554 const MatrixXd rigid =
1555 mw.rigidBasis(m, projectRotations ? rotationZero : none);
1556 if (rigid.cols() > 0) {
1557 const MatrixXd p = MatrixXd::Identity(n, n) - rigid * rigid.transpose();
1558 out = p * out * p;
1559 }
1560 return out;
1561 };
1562 auto hessianAt = [&](const VectorXd &q) { return hessianWith(q, true); };
1563 auto beadHessianAt = [&](const VectorXd &q) {
1564 if (!rotationsKnown) {
1565 hessianWith(VectorXd::Zero(n), true);
1566 }
1567 return hessianWith(q, false);
1568 };
1569
1570 if (o.mode == "rate") {
1571 auto referenceHessianAt = [&](const VectorXd &q,
1572 const std::string &filename) {
1573 return hessianWith(q, true, filename);
1574 };
1575 return runRate(params, pot, *reactant, mw, evaluate, evaluateOwned,
1576 referenceHessianAt, beadHessianAt, rotationZero,
1577 rotationResidual);
1578 }
1579
1580 auto product = std::make_unique<Matter>(pot, params);
1581 if (!io::io_ok(product->con2matter(o.product_filename))) {
1582 throw std::runtime_error("instanton: cannot read " + o.product_filename);
1583 }
1584 if (reactant->numberOfAtoms() != product->numberOfAtoms()) {
1585 throw std::runtime_error("instanton: the minima differ in atom count");
1586 }
1587 requireMatchingReferenceSurface(*reactant, *product);
1588 const MatrixXd hStart = hessianAt(qStart);
1589 const bool rotate = rotationZero[0] || rotationZero[1] || rotationZero[2];
1590 alignRigid(*reactant, *product, rotate);
1591 const VectorXd qEnd = mw.toQ(*product);
1592
1593 // Starting path: a band from file, else the straight line.
1594 std::vector<VectorXd> guess;
1595 if (!o.initial_path.empty()) {
1596 const auto frames = readcon::read_all_frames(o.initial_path);
1597 for (const auto &frame : frames) {
1598 Matter m(*reactant);
1599 if (!io::io_ok(io::con2matter(m, frame))) {
1600 throw std::runtime_error("instanton: cannot read " + o.initial_path);
1601 }
1602 alignRigid(*reactant, m, rotate);
1603 guess.push_back(mw.toQ(m));
1604 }
1605 if (guess.size() >= 2) {
1606 guess.front() = qStart;
1607 guess.back() = qEnd;
1608 }
1609 }
1610
1611 const MatrixXd hEnd = hessianAt(qEnd);
1612 // Both Hessians lost the same rigid motions. The zero-point energy the
1613 // product well holds above the reactant's belongs in the asymmetry.
1614 const double zeroPoint = tunneling::zeroPointDifference(
1615 hStart, hEnd, mw.rigidBasis(*reactant, rotationZero).cols());
1616 const double omega = tunneling::pathOmega(hStart, hEnd, qStart, qEnd);
1617 const double betaHbar = o.beta_hbar_omega / omega;
1618 tunneling::InstantonOptions opt;
1619 opt.beads = o.beads;
1620 opt.betaHbarOmega = o.beta_hbar_omega;
1621 opt.maxIterations = o.max_iterations;
1622 opt.forceTolerance = o.force_tolerance;
1623 EONC_LOG_INFO("[Instanton] {} beads over beta hbar = {:.4f} fs, {} degrees "
1624 "of freedom",
1625 o.beads, betaHbar * kTimeUnitFs, n);
1626
1627 // Minima of different energy tunnel on the surface with that difference
1628 // switched off along the path; the bias leaves both minima and their
1629 // Hessians alone.
1630 std::vector<double> vEnds;
1631 std::vector<VectorXd> gEnds;
1632 evaluate({qStart, qEnd}, vEnds, gEnds);
1633 const double dV = vEnds.at(1) - vEnds.at(0);
1634 const bool symmetrized = o.symmetrize && dV != 0.0;
1635 const tunneling::EnergyBias bias(qStart, qEnd, symmetrized ? dV : 0.0);
1636 const tunneling::BatchPotential surface = [&](const std::vector<VectorXd> &q,
1637 std::vector<double> &v,
1638 std::vector<VectorXd> &grad) {
1639 evaluate(q, v, grad);
1640 for (size_t j = 0; symmetrized && j < q.size(); ++j) {
1641 v[j] -= bias.value(q[j]);
1642 grad[j] -= bias.gradient(q[j]);
1643 }
1644 };
1645 tunneling::Instanton inst =
1646 tunneling::optimizeInstanton(qStart, qEnd, betaHbar, guess, surface, opt);
1647 inst.asymmetry = dV;
1648 for (size_t j = 0; j < inst.path.size(); ++j) {
1649 inst.energies[j] += bias.value(inst.path[j]);
1650 }
1651 EONC_LOG_INFO("[Instanton] action {:.6f} after {} iterations{}{}",
1652 inst.action, inst.iterations,
1653 inst.converged ? "" : " (not converged)",
1654 symmetrized ? ", wells levelled" : "");
1655
1656 bool splitOk = false;
1657 std::string failure;
1658 // beta |delta|: without the levelled surface, the propagator ratio reads
1659 // delta0 only when the wells lie within a small fraction of kB T of each
1660 // other.
1661 const double betaAsymmetry = std::abs(dV) * betaHbar / tunneling::kHbar;
1662 inst.symmetricEnough = betaAsymmetry < 0.1;
1663 const bool splittable = symmetrized || inst.symmetricEnough;
1664 if (inst.converged && !splittable) {
1665 EONC_LOG_WARNING("[Instanton] beta |delta| = {:.3g}: the wells differ by "
1666 "{:.4g} eV, too far for the splitting; the path and "
1667 "action are written, the splitting is not",
1668 betaAsymmetry, inst.asymmetry);
1669 }
1670 if (inst.converged && splittable) {
1671 const long stride = std::max<long>(1, o.hessian_stride);
1672 const long P = o.beads;
1673 std::map<long, MatrixXd> anchors;
1674 // The splitting is the J = 0 one: every bead loses its rotations, as the
1675 // two minima do. A closed rate ring keeps them on its beads, because
1676 // there a rotation of every bead at once is the zero mode it lifts.
1677 auto anchor = [&](long j) -> const MatrixXd & {
1678 auto it = anchors.find(j);
1679 if (it == anchors.end()) {
1680 const VectorXd &q = inst.path[static_cast<size_t>(j)];
1681 it = anchors.emplace(j, hessianAt(q) - bias.hessian(q)).first;
1682 }
1683 return it->second;
1684 };
1685 auto beadHessian = [&](long j, const VectorXd &) -> MatrixXd {
1686 if (stride == 1) {
1687 return anchor(j);
1688 }
1689 const long lo = 1 + ((j - 1) / stride) * stride;
1690 const long hi = std::min(lo + stride, P - 1);
1691 if (j == lo || hi == lo) {
1692 return anchor(lo);
1693 }
1694 const double t =
1695 static_cast<double>(j - lo) / static_cast<double>(hi - lo);
1696 return (1.0 - t) * anchor(lo) + t * anchor(hi);
1697 };
1698 try {
1699 tunneling::instantonSplitting(inst, beadHessian, hStart, hEnd);
1700 splitOk = std::isfinite(inst.delta0);
1701 } catch (const std::runtime_error &ex) {
1702 failure = ex.what();
1703 EONC_LOG_ERROR("[Instanton] {}", failure);
1704 }
1705 }
1706
1707 // The path, one frame per bead; the splitting on the first frame.
1708 const double kelvin = tunneling::kHbar / (tunneling::kBoltzmann * betaHbar);
1709 const double asymmetryZpe = inst.asymmetry + zeroPoint;
1710 Matter frame(*reactant);
1711 for (size_t j = 0; j < inst.path.size(); ++j) {
1712 mw.place(inst.path[j], frame);
1713 io::ConFrameMetadata meta;
1714 meta.frame_index = static_cast<uint64_t>(j);
1715 meta.energy = inst.energies[j];
1716 meta.write_con_forces = false;
1717 meta.scalars = {{"imaginary_time_fs",
1718 static_cast<double>(j) * inst.dtau * kTimeUnitFs}};
1719 if (j == 0) {
1720 meta.scalars.push_back({"instanton_action", inst.action});
1721 meta.scalars.push_back(
1722 {"instanton_beta_hbar_fs", betaHbar * kTimeUnitFs});
1723 meta.scalars.push_back({"instanton_temperature_K", kelvin});
1724 meta.scalars.push_back(
1725 {"instanton_converged", inst.converged ? 1.0 : 0.0});
1726 meta.scalars.push_back({"tunnel_asymmetry", inst.asymmetry});
1727 meta.scalars.push_back({"tunnel_asymmetry_zpe", asymmetryZpe});
1728 meta.scalars.push_back(
1729 {"instanton_symmetrized", symmetrized ? 1.0 : 0.0});
1730 meta.scalars.push_back(
1731 {"instanton_symmetric", inst.symmetricEnough ? 1.0 : 0.0});
1732 meta.scalars.push_back({"instanton_beta_asymmetry", betaAsymmetry});
1733 if (splitOk) {
1734 meta.scalars.push_back({"tunnel_splitting_instanton", inst.delta0});
1735 meta.scalars.push_back(
1736 {"tls_energy_instanton", std::hypot(asymmetryZpe, inst.delta0)});
1737 meta.scalars.push_back({"instanton_zero_mode", inst.zeroMode});
1738 meta.scalars.push_back(
1739 {"instanton_mode_separation", inst.modeSeparation});
1740 }
1741 }
1742 if (!io::io_ok(frame.matter2con(pathFile, j > 0, &meta))) {
1743 throw std::runtime_error("instanton: cannot write " + pathFile);
1744 }
1745 }
1746 returnFiles.push_back(pathFile);
1747 writeCentroid("instanton_centroid.con", inst.path, mw, *reactant,
1748 {{"instanton_temperature_K", kelvin},
1749 {"instanton_converged", inst.converged ? 1.0 : 0.0}});
1750 returnFiles.push_back("instanton_centroid.con");
1751
1752 // A converged path between wells too far apart is a result, not a
1753 // failure: the flags say why no splitting was written.
1754 const bool good = splitOk || (inst.converged && !splittable);
1755 const auto status = good ? RunStatus::GOOD
1756 : (inst.converged ? RunStatus::FAIL_POTENTIAL_FAILED
1759 status, params.potential_options().potential,
1760 pot->forceCallCounter.load(), false, 0.0);
1761 env.provenance = provenanceForJob(params);
1762 env.job_type = "instanton";
1763 env.extras.emplace_back("force_calls", static_cast<double>(env.force_calls));
1764 env.extras.emplace_back("instanton_iterations",
1765 static_cast<double>(inst.iterations));
1766 env.extras.emplace_back("instanton_action", inst.action);
1767 env.extras.emplace_back("instanton_temperature_K", kelvin);
1768 env.extras.emplace_back("tunnel_asymmetry", inst.asymmetry);
1769 env.extras.emplace_back("tunnel_asymmetry_zpe", asymmetryZpe);
1770 env.extras.emplace_back("instanton_beta_asymmetry", betaAsymmetry);
1771 env.extras.emplace_back("instanton_symmetric",
1772 inst.symmetricEnough ? 1.0 : 0.0);
1773 env.extras.emplace_back("instanton_symmetrized", symmetrized ? 1.0 : 0.0);
1774 if (splitOk) {
1775 env.extras.emplace_back("tunnel_splitting_instanton", inst.delta0);
1776 env.extras.emplace_back("tls_energy_instanton",
1777 std::hypot(asymmetryZpe, inst.delta0));
1778 env.extras.emplace_back("instanton_mode_separation", inst.modeSeparation);
1779 }
1780 env.writeResultsDat(resultsFile);
1781 return returnFiles;
1782}
Eigen::Matrix< double, Eigen::Dynamic, Eigen::Dynamic, eOnStorageOrder > MatrixXd
Definition Eigen.h:33
#define EONC_LOG_ERROR(...)
Definition EonLogger.h:328
#define EONC_LOG_WARNING(...)
Definition EonLogger.h:322
#define EONC_LOG_INFO(...)
Definition EonLogger.h:316
std::shared_ptr< Potential > pot
Set when one Potential is shared across Matters, images, or a caller.
Definition Job.h:66
Parameters params
Definition Job.h:58
IoStatus con2matter(Matter &m, std::string filename)
constexpr bool io_ok(IoStatus s) noexcept
Definition ConFileIO.h:38
void requireTrotterSprings(const std::string &springs, const char *use)
Economised springs and a normal-mode GLE are refused.
constexpr long reactant
constexpr long auxiliary
double zeroPointDifference(const MatrixXd &hessStart, const MatrixXd &hessEnd, long rigidModes)
Harmonic zero-point energy of the end minimum minus that of the start, in eV: (hbar / 2) times the di...
void instantonSplitting(Instanton &inst, const BeadHessian &hessian, const MatrixXd &hessStart, const MatrixXd &hessEnd)
Fills delta0, zeroMode and modeSeparation from the bead Hessians and the Hessians of the two minima.
double pathOmega(const MatrixXd &hessStart, const MatrixXd &hessEnd, const VectorXd &start, const VectorXd &end)
omega along the straight line between the minima from the curvature of each well there,...
constexpr double kHbar
hbar in eV^0.5 amu^0.5 Angstrom, correctly rounded from the exact SI values (h = 6....
Definition Tunneling.h:39
std::function< void(const std::vector< VectorXd > &q, std::vector< double > &v, std::vector< VectorXd > &grad)> BatchPotential
V (eV) and dV/dq (eV / (amu^0.5 Angstrom)) at every point of q, all in one call so a potential can sp...
Definition Tunneling.h:238
MatrixXd readReferenceHessian(const std::string &filename, const Matter &reference, long dimension)
Read a mass-weighted reference matrix bound to filename + ".con".
std::function< void( const std::vector< VectorXd > &q, std::vector< double > &v, std::vector< VectorXd > &grad, const std::vector< long > &owners)> OwnedBatchPotential
Explicit electronic-state owners for each evaluated geometry.
Definition Tunneling.h:243
Instanton optimizeInstanton(const VectorXd &start, const VectorXd &end, double betaHbar, std::vector< VectorXd > guess, const BatchPotential &potential, const InstantonOptions &options)
Minimises the action from guess (P + 1 beads, ends at the minima, or empty for a tanh kink along the ...
constexpr double kBoltzmann
Boltzmann constant in eV / K, correctly rounded from the exact 1.380649e-23 J / K.
Definition Tunneling.h:43
JobResultProvenance provenanceForJob(const Parameters &params)
Optimizer backend, engine identity, rgpot pin, and xts ABI from a job.
static JobResultEnvelope fromMinimization(RunStatus status, PotType pot, std::uint64_t fcalls, bool hasE, double energy)
Definition JobResult.h:251

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