Matter Class Reference

#include <Matter.h>

Public Member Functions
	~Matter ()=default
	Matter (std::shared_ptr< Potential > pot, const Parameters &params)
	Matter (const Matter &matter)
	Matter (Matter &&other) noexcept
	Move: transfers retained movie ConFrames (move-only).
const Matter &	operator= (const Matter &matter)
Matter &	operator= (Matter &&other) noexcept
bool	compare (const Matter &matter, bool indistinguishable=false)
double	distanceTo (const Matter &matter)
double	perAtomNorm (const Matter &matter)
void	setPotential (std::shared_ptr< Potential > pot)
std::shared_ptr< Potential >	getPotential ()
void	resize (long int nAtoms)
long int	numberOfAtoms () const
Matrix3d	getCell () const
void	setCell (const Matrix3d &newCell)
double	getPosition (long int atom, int axis) const
void	setPosition (long int atom, int axis, double position)
void	setVelocity (long int atom, int axis, double velocity)
bool	relax (bool quiet=false, bool writeMovie=false, bool checkpoint=false, std::string prefixMovie=std::string(), std::string prefixCheckpoint=std::string(), bool retainMovieFrames=false)
const std::vector< readcon::ConFrame > &	movieFrames () const
	In-memory minimization movie (same stamps as writeMovie CON).
void	clearMovieFrames ()
std::vector< readcon::ConFrame >	takeMovieFrames ()
	Take ownership of retained frames (leaves storage empty).
AtomMatrix	pbc (const AtomMatrix &diff) const
VectorXd	pbcV (const VectorXd &diff) const
size_t	getPotentialCalls () const
const AtomMatrix &	getPositions () const
AtomMatrix	getPositionsCopy () const
VectorXd	getPositionsV () const
AtomMatrix	getPositionsFree () const
VectorXd	getPositionsFreeV () const
void	setPositions (const AtomMatrix &pos)
void	setPositionsV (const VectorXd &pos)
void	setPositionsFree (const AtomMatrix &pos)
void	setPositionsFreeV (const VectorXd &pos)
AtomMatrix	getVelocities () const
void	setVelocities (const AtomMatrix &v)
void	setBiasForces (const AtomMatrix &bf)
void	setBiasPotential (BondBoost *bondBoost)
void	setForces (const AtomMatrix &f)
AtomMatrix	getAccelerations ()
const AtomMatrix &	getForces () const
const AtomMatrix &	getForcesRaw () const
AtomMatrix	getBiasForces ()
VectorXd	getForcesV () const
AtomMatrix	getForcesFree () const
VectorXd	getForcesFreeV () const
PbcConvention	getPbcConvention () const
void	setPbcConvention (PbcConvention convention)
double	getMass (long int atom) const
void	setMass (long int atom, double mass)
void	setMasses (const VectorXd &massesIn)
long	getAtomicNr (long int atom) const
void	setAtomicNr (long int atom, long atomicNr)
VectorXi	getAtomicNrs () const
VectorXi	getAtomicNrsFree () const
void	setAtomicNrs (const VectorXi &atmnrs)
int	getFixed (long int atom) const
	1 if every Cartesian axis of the atom is fixed, else 0.
int	getFixed (long int atom, int axis) const
	1 if this atom's axis is fixed, else 0. axis is 0=x, 1=y, 2=z.
std::array< bool, 3 >	getFixedMask (long int atom) const
	Per-axis CON column-4 mask (bit0=x, bit1=y, bit2=z).
void	setFixed (long int atom, int isFixed)
	Broadcast a whole-atom flag onto all three axes.
void	setFixed (long int atom, int axis, int isFixed)
	Set one Cartesian axis. axis is 0=x, 1=y, 2=z.
void	setFixedMask (long int atom, std::array< bool, 3 > mask)
double	getEnergyVariance () const
double	getPotentialEnergy () const
bool	needsForceUpdate () const
	Whether forces need recomputation (positions changed since last eval).
double *	forcesData ()
	Mutable access to force storage for batched potential evaluation.
void	setComputedPotential (double energy, double variance)
	Set energy/variance from external batched evaluation and mark forces as up-to-date (recomputePotential = false).
double	getKineticEnergy () const
double	getMechanicalEnergy () const
double	distance (long index1, long index2) const
double	distance (const Matter &matter, long index) const
double	pdistance (long index1, long index2, int axis) const
long int	numberOfFreeAtoms () const
long int	numberOfFixedAtoms () const
long	getForceCalls () const
void	resetForceCalls ()
double	maxForce (void) const
bool	getWriteConForces () const noexcept
	Parameters.main_options.writeConForces for this Matter, if bound.
io::IoStatus	writeTibble (std::string filename)
io::IoStatus	con2matter (std::string filename)
io::IoStatus	con2matter (const readcon::ConFrame &frame, io::ConFrameMetadata *out_metadata=nullptr)
io::IoStatus	convel2matter (std::string filename)
io::IoStatus	matter2con (std::string filename, bool append=false, const io::ConFrameMetadata *metadata=nullptr)
io::IoStatus	matter2convel (std::string filename)
io::IoStatus	matter2xyz (std::string filename, bool append=false)
AtomMatrix	getFree () const
VectorXd	getFreeV () const
Eigen::Matrix< double, Eigen::Dynamic, 1 >	getMasses () const
std::int64_t	getAtomIndex (long int atom) const
	.con column-5 index (pre-grouping); public for I/O / bindings.
void	setAtomIndex (long int atom, std::int64_t index)
const std::array< std::string, 5 > &	getHeaderCon () const
	CON header lines (indices 0..4); public for I/O / bindings.
void	setHeaderCon (const std::array< std::string, 5 > &headers)
void	setHeaderConLine (size_t i, std::string line)
bool	getPeriodic () const noexcept
void	setPeriodic (bool periodic)
void	applyPeriodicBoundaryIfEnabled ()
	Apply MIC wrap when periodic boundaries are enabled (I/O path).

Private Member Functions
void	assertIsolatedMoleculeLayoutSafe () const
	Throw if pot forbids PBC (isolated molecular QM backends, issue #188).
void	computePotential () const
void	applyPeriodicBoundary ()
void	applyPeriodicBoundary (double &component, int axis)
void	applyPeriodicBoundary (AtomMatrix &diff)

Private Attributes
eonc::log::Scoped	m_log
std::shared_ptr< Potential >	potential
bool	usePeriodicBoundaries
PbcConvention	pbcConvention
bool	recomputePotential
long	forceCalls
std::array< std::string, 5 >	headerCon
bool	removeNetForce {true}
Parameters::structure_comparison_options_t	structComp
const Parameters *	parameters
long	nAtoms
AtomMatrix	positions
AtomMatrix	velocities
AtomMatrix	forces
AtomMatrix	biasForces
BondBoost *	biasPotential {nullptr}
VectorXd	masses
VectorXi	atomicNrs
AtomMatrix	isFixed
Eigen::Matrix< std::int64_t, Eigen::Dynamic, 1 >	atomIndex
AtomMatrix	freeMask
AtomMatrix	maskedForces
std::vector< int >	freeIndices
bool	recomputeFreeMask {true}
bool	recomputeMaskedForces {true}
Matrix3d	cell
Matrix3d	cellInverse
double	energyVariance
std::vector< readcon::ConFrame >	movie_frames_
double	potentialEnergy

Friends
io::IoStatus	io::con2matter (Matter &, const readcon::ConFrame &, io::ConFrameMetadata *)

Detailed Description

Definition at line 92 of file Matter.h.

Constructor & Destructor Documentation

~Matter()

eonc::Matter::~Matter ( )

default

Matter() [1/3]

eonc::Matter::Matter ( std::shared_ptr< Potential > pot, const Parameters & params )

inline

Definition at line 95 of file Matter.h.

      : potential{pot},
        // Isolated molecular QM (NWChem/ORCA) must start with PBC off (#188).
        usePeriodicBoundaries{!(pot && pot->requiresIsolatedMoleculeLayout())},
        pbcConvention{PbcConvention::Legacy},
        recomputePotential{true},
        forceCalls{0},
        removeNetForce{params.main_options.removeNetForce},
        structComp{params.structure_comparison_options},
        parameters{&params},
        nAtoms{0},
        positions{MatrixXd::Zero(0, 3)},
        velocities{MatrixXd::Zero(0, 3)},
        forces{MatrixXd::Zero(0, 3)},
        biasForces{MatrixXd::Zero(0, 3)},
        biasPotential{nullptr},
        masses{Eigen::VectorXd::Zero(0)},
        atomicNrs{Eigen::VectorXi::Zero(0)},
        isFixed{AtomMatrix::Zero(0, 3)},
        cell{Matrix3d::Zero()},
        cellInverse{Matrix3d::Zero()},
        energyVariance{0.0},
        potentialEnergy{0.0} {} // the number of atoms shall be set later

Matter() [2/3]

Matter::Matter

(

const Matter &

matter

)

Definition at line 23 of file Matter.cpp.

{ operator=(matter); }

Matter() [3/3]

Matter::Matter ( Matter && other )

noexcept

Move: transfers retained movie ConFrames (move-only).

User copy suppresses implicit move — without this, relax(inplace=False, retain_frames=True) loses frames when returning the working Matter.

Definition at line 74 of file Matter.cpp.

{ operator=(std::move(other)); }

Member Function Documentation

applyPeriodicBoundary() [1/3]

void Matter::applyPeriodicBoundary ( )

private

Definition at line 543 of file Matter.cpp.

                                   {
  assertIsolatedMoleculeLayoutSafe();
  // Unset / singular cell (default after Matter construct is Zero) — do not
  // wipe coordinates; callers set the cell before wrapping makes sense.
  if (std::abs(cell.determinant()) < 1e-30) {
    return;
  }
  positions =
      eonc::pbc::applyPositions(positions, cell, cellInverse, pbcConvention);
}

applyPeriodicBoundary() [2/3]

void eonc::Matter::applyPeriodicBoundary ( AtomMatrix & diff )

private

applyPeriodicBoundary() [3/3]

void eonc::Matter::applyPeriodicBoundary ( double & component, int axis )

private

applyPeriodicBoundaryIfEnabled()

void eonc::Matter::applyPeriodicBoundaryIfEnabled ( )

inline

Apply MIC wrap when periodic boundaries are enabled (I/O path).

Definition at line 327 of file Matter.h.

                                        {
    if (usePeriodicBoundaries) {
      applyPeriodicBoundary();
    }
  }

assertIsolatedMoleculeLayoutSafe()

void Matter::assertIsolatedMoleculeLayoutSafe ( ) const

private

Throw if pot forbids PBC (isolated molecular QM backends, issue #188).

Definition at line 486 of file Matter.cpp.

                                                    {
  if (!potential || !potential->requiresIsolatedMoleculeLayout()) {
    return;
  }
  if (usePeriodicBoundaries) {
    throw std::runtime_error(
        "Potential requires an isolated (non-periodic) molecular layout "
        "(NWChem/ORCA-class). Disable periodic boundaries before optimizing; "
        "PBC wraps can tear non-centered molecules (issue #188).");
  }
}

clearMovieFrames()

void eonc::Matter::clearMovieFrames ( )

inline

Definition at line 157 of file Matter.h.

{ movie_frames_.clear(); }

compare()

bool Matter::compare	(	const Matter &	matter,
		bool	indistinguishable = false )

Definition at line 129 of file Matter.cpp.

                                                                 {
  if (nAtoms != matter.numberOfAtoms())
    return false;
  if (structComp.check_rotation && indistinguishable) {
    return eonc::helpers::sortedR(*this, matter,
                                  structComp.distance_difference);
  } else if (indistinguishable) {
    if (this->numberOfFixedAtoms() == 0 and structComp.remove_translation)
      eonc::helpers::translationRemove(*this, matter);
    return eonc::helpers::identical(*this, matter,
                                    structComp.distance_difference);
  } else if (structComp.check_rotation) {
    return eonc::helpers::rotationMatch(*this, matter,
                                        structComp.distance_difference);
  } else {
    if (this->numberOfFixedAtoms() == 0 and structComp.remove_translation)
      eonc::helpers::translationRemove(*this, matter);
    return (structComp.distance_difference) > perAtomNorm(matter);
  }
}

computePotential()

void Matter::computePotential ( ) const

private

Definition at line 498 of file Matter.cpp.

                                    {
  if (recomputePotential) {
    if (!potential) {
      throw std::runtime_error(
          "Matter::computePotential called without a potential");
    }
    assertIsolatedMoleculeLayoutSafe();
    if (potential->isSurrogate()) {
      // Surrogate potential case: uses free-atom subset interface
      auto surrogatePotential =
          static_cast<SurrogatePotential *>(potential.get());
      auto [freePE, freeForces, vari] = surrogatePotential->get_ef_var(
          this->getPositionsFree(), this->getAtomicNrsFree(), cell);
      this->potentialEnergy = freePE;
      this->energyVariance = vari;
      for (long idx{0}, jdx{0}; idx < nAtoms; idx++) {
        if (!getFixed(idx)) {
          forces.row(idx) = freeForces.row(jdx);
          jdx++;
        }
      }
    } else {
      // Hot path: call force() directly into member storage.
      // No intermediate allocation, no tuple, no copy.
      double var{0};
      potential->force(nAtoms, positions.data(), atomicNrs.data(),
                       forces.data(), &potentialEnergy, &var, cell.data());
      potential->forceCallCounter++;
      PotRegistry::get().on_force_call(potential->getType());
    }
    forceCalls = forceCalls + 1;
    recomputePotential = false;
 
    if (isFixed.maxCoeff() < 0.5 && removeNetForce) {
      Vector3d tempForce = forces.colwise().sum() / nAtoms;
      for (long int i = 0; i < nAtoms; i++) {
        forces.row(i) -= tempForce.transpose();
      }
    }
  }
}

con2matter() [1/2]

io::IoStatus eonc::Matter::con2matter ( const readcon::ConFrame & frame, io::ConFrameMetadata * out_metadata = nullptr )

inlinenodiscard

Definition at line 273 of file Matter.h.

                                                       {
    return io::con2matter(*this, frame, out_metadata);
  }

con2matter() [2/2]

io::IoStatus eonc::Matter::con2matter ( std::string filename )

inlinenodiscard

Definition at line 269 of file Matter.h.

                                                          {
    return io::con2matter(*this, filename);
  }

convel2matter()

io::IoStatus eonc::Matter::convel2matter ( std::string filename )

inlinenodiscard

Definition at line 277 of file Matter.h.

                                                             {
    return io::convel2matter(*this, filename);
  }

distance() [1/2]

double Matter::distance	(	const Matter &	matter,
		long	index ) const

Definition at line 376 of file Matter.cpp.

                                                              {
  return pbc(positions.row(index) - matter.getPositions().row(index)).norm();
}

distance() [2/2]

double Matter::distance	(	long	index1,
		long	index2 ) const

Definition at line 360 of file Matter.cpp.

                                                      {
  return pbc(positions.row(index1) - positions.row(index2)).norm();
}

distanceTo()

double Matter::distanceTo

(

const Matter &

matter

)

Definition at line 155 of file Matter.cpp.

                                              {
  return pbc(positions - matter.positions).norm();
}

forcesData()

double * eonc::Matter::forcesData ( )

inline

Mutable access to force storage for batched potential evaluation.

Caller must also call setComputedPotential() after writing forces.

Definition at line 236 of file Matter.h.

{ return forces.data(); }

getAccelerations()

AtomMatrix Matter::getAccelerations

(

)

Definition at line 612 of file Matter.cpp.

                                    {
  AtomMatrix totF = getForces() + getBiasForces();
  AtomMatrix ret = totF.array() * getFree().array();
  // Single reciprocal mass computation, replicated across 3 columns
  auto invMass = masses.array().inverse();
  ret.col(0).array() *= invMass;
  ret.col(1).array() *= invMass;
  ret.col(2).array() *= invMass;
  return ret;
}

getAtomicNr()

long Matter::getAtomicNr

(

long int

atom

)

const

Definition at line 392 of file Matter.cpp.

                                                 {
  return (atomicNrs[indexAtom]);
}

getAtomicNrs()

VectorXi Matter::getAtomicNrs

(

)

const

Definition at line 569 of file Matter.cpp.

{ return this->atomicNrs; }

getAtomicNrsFree()

VectorXi Matter::getAtomicNrsFree

(

)

const

Definition at line 253 of file Matter.cpp.

                                        {
  return this->atomicNrs.array() * getFreeV().cast<int>().array();
}

getAtomIndex()

std::int64_t eonc::Matter::getAtomIndex ( long int atom ) const

inlinenodiscard

.con column-5 index (pre-grouping); public for I/O / bindings.

Held 64-bit wide: readcon carries the column as a uint64_t, and a 32-bit slot drops the high half of any id past 2^31.

Definition at line 300 of file Matter.h.

                                                             {
    return atomIndex(atom);
  }

getBiasForces()

AtomMatrix Matter::getBiasForces

(

)

Definition at line 305 of file Matter.cpp.

                                 {
  if (biasPotential != nullptr) {
    // Evaluate the current bias only. The MD job advances the bond-boost
    // schedule once per step via BondBoost::advance().
    biasPotential->boost();
  }
  return biasForces.array() * getFree().array();
}

getCell()

Matrix3d Matter::getCell

(

)

const

Definition at line 211 of file Matter.cpp.

{ return cell; }

getEnergyVariance()

double Matter::getEnergyVariance

(

)

const

Definition at line 663 of file Matter.cpp.

{ return this->energyVariance; }

getFixed() [1/2]

int Matter::getFixed

(

long int

atom

)

const

1 if every Cartesian axis of the atom is fixed, else 0.

Definition at line 402 of file Matter.cpp.

                                             {
  return (isFixed(indexAtom, 0) > 0.5 && isFixed(indexAtom, 1) > 0.5 &&
          isFixed(indexAtom, 2) > 0.5)
             ? 1
             : 0;
}

getFixed() [2/2]

int Matter::getFixed	(	long int	atom,
		int	axis ) const

1 if this atom's axis is fixed, else 0. axis is 0=x, 1=y, 2=z.

Definition at line 409 of file Matter.cpp.

                                                       {
  return isFixed(indexAtom, axis) > 0.5 ? 1 : 0;
}

getFixedMask()

std::array< bool, 3 > Matter::getFixedMask ( long int atom ) const

nodiscard

Per-axis CON column-4 mask (bit0=x, bit1=y, bit2=z).

Definition at line 413 of file Matter.cpp.

                                                               {
  return {isFixed(indexAtom, 0) > 0.5, isFixed(indexAtom, 1) > 0.5,
          isFixed(indexAtom, 2) > 0.5};
}

getForceCalls()

long Matter::getForceCalls

(

)

const

Definition at line 479 of file Matter.cpp.

{ return (forceCalls); }

getForces()

const AtomMatrix & Matter::getForces

(

)

const

Definition at line 324 of file Matter.cpp.

                                          {
  computePotential();
  if (recomputeMaskedForces) {
    // Use the cached freeMask (Nx3, 1.0 for free / 0.0 for fixed) to zero
    // fixed-atom forces in a single vectorized Eigen operation.
    maskedForces = forces.array() * getFree().array();
    recomputeMaskedForces = false;
  }
  return maskedForces;
}

getForcesFree()

AtomMatrix Matter::getForcesFree

(

)

const

Definition at line 344 of file Matter.cpp.

                                       {
  AtomMatrix allForces = getForces();
  getFree(); // ensure freeIndices is up to date (mutable cache)
  AtomMatrix ret(static_cast<long>(freeIndices.size()), 3);
  for (size_t j = 0; j < freeIndices.size(); j++) {
    ret.row(static_cast<long>(j)) = allForces.row(freeIndices[j]);
  }
  return ret;
}

getForcesFreeV()

VectorXd Matter::getForcesFreeV

(

)

const

Definition at line 354 of file Matter.cpp.

                                      {
  AtomMatrix freeForces = getForcesFree();
  return VectorXd::Map(freeForces.data(), 3 * numberOfFreeAtoms());
}

getForcesRaw()

const AtomMatrix & Matter::getForcesRaw

(

)

const

Definition at line 335 of file Matter.cpp.

                                             {
  computePotential();
  return forces;
}

getForcesV()

VectorXd Matter::getForcesV

(

)

const

Definition at line 340 of file Matter.cpp.

                                  {
  return VectorXd::Map(getForces().data(), 3 * numberOfAtoms());
}

getFree()

AtomMatrix Matter::getFree

(

)

const

Definition at line 580 of file Matter.cpp.

                                 {
  if (recomputeFreeMask) {
    freeMask.resize(nAtoms, 3);
    freeMask = 1.0 - isFixed.array();
    freeIndices.clear();
    freeIndices.reserve(static_cast<size_t>(nAtoms));
    for (long i = 0; i < nAtoms; i++) {
      if (freeMask.row(i).sum() > 0.5) {
        freeIndices.push_back(static_cast<int>(i));
      }
    }
    recomputeFreeMask = false;
  }
  return freeMask;
}

getFreeV()

VectorXd Matter::getFreeV

(

)

const

Definition at line 596 of file Matter.cpp.

                                {
  return VectorXd::Map(getFree().data(), 3 * numberOfAtoms());
}

getHeaderCon()

const std::array< std::string, 5 > & eonc::Matter::getHeaderCon ( ) const

inlinenodiscard

CON header lines (indices 0..4); public for I/O / bindings.

Definition at line 308 of file Matter.h.

                                                                   {
    return headerCon;
  }

getKineticEnergy()

double Matter::getKineticEnergy

(

)

const

Definition at line 454 of file Matter.cpp.

                                      {
  // 0.5 * sum(mass_i * |v_i,free|^2); a constrained axis does not contribute.
  AtomMatrix vfree = velocities.array() * getFree().array();
  Eigen::VectorXd speed2 = vfree.rowwise().squaredNorm();
  return 0.5 * (masses.array() * speed2.array()).sum();
}

getMass()

double Matter::getMass

(

long int

atom

)

const

Definition at line 380 of file Matter.cpp.

{ return (masses[indexAtom]); }

getMasses()

Matrix< double, Eigen::Dynamic, 1 > Matter::getMasses

(

)

const

Definition at line 623 of file Matter.cpp.

{ return masses; }

getMechanicalEnergy()

double Matter::getMechanicalEnergy

(

)

const

Definition at line 461 of file Matter.cpp.

                                         {
  return getPotentialEnergy() + getKineticEnergy();
}

getPbcConvention()

PbcConvention eonc::Matter::getPbcConvention ( ) const

inline

Definition at line 201 of file Matter.h.

{ return pbcConvention; }

getPeriodic()

bool eonc::Matter::getPeriodic ( ) const

inlinenodiscardnoexcept

Definition at line 318 of file Matter.h.

                                                  {
    return usePeriodicBoundaries;
  }

getPosition()

double Matter::getPosition	(	long int	atom,
		int	axis ) const

Definition at line 218 of file Matter.cpp.

                                                             {
  return positions(indexAtom, axis);
}

getPositions()

const AtomMatrix & Matter::getPositions

(

)

const

Definition at line 236 of file Matter.cpp.

{ return positions; }

getPositionsCopy()

AtomMatrix Matter::getPositionsCopy

(

)

const

Definition at line 238 of file Matter.cpp.

{ return positions; }

getPositionsFree()

AtomMatrix Matter::getPositionsFree

(

)

const

Definition at line 244 of file Matter.cpp.

                                          {
  getFree(); // ensure freeIndices is up to date
  AtomMatrix ret(static_cast<long>(freeIndices.size()), 3);
  for (size_t j = 0; j < freeIndices.size(); j++) {
    ret.row(static_cast<long>(j)) = positions.row(freeIndices[j]);
  }
  return ret;
}

getPositionsFreeV()

VectorXd Matter::getPositionsFreeV

(

)

const

Definition at line 268 of file Matter.cpp.

                                         {
  return VectorXd::Map(getPositionsFree().data(), 3 * numberOfFreeAtoms());
}

getPositionsV()

VectorXd Matter::getPositionsV

(

)

const

Definition at line 240 of file Matter.cpp.

                                     {
  return VectorXd::Map(positions.data(), 3 * numberOfAtoms());
}

getPotential()

std::shared_ptr< Potential > Matter::getPotential

(

)

Definition at line 671 of file Matter.cpp.

{ return this->potential; }

getPotentialCalls()

size_t Matter::getPotentialCalls

(

)

const

Definition at line 659 of file Matter.cpp.

                                       {
  return this->potential->forceCallCounter;
}

getPotentialEnergy()

double Matter::getPotentialEnergy

(

)

const

Definition at line 446 of file Matter.cpp.

                                        {
  if (nAtoms > 0) {
    computePotential();
    return potentialEnergy;
  } else
    return 0.0;
}

getVelocities()

AtomMatrix Matter::getVelocities

(

)

const

Definition at line 600 of file Matter.cpp.

                                       {
  return velocities.array() * getFree().array();
}

getWriteConForces()

bool eonc::Matter::getWriteConForces ( ) const

inlinenodiscardnoexcept

Parameters.main_options.writeConForces for this Matter, if bound.

Definition at line 261 of file Matter.h.

                                                        {
    return parameters != nullptr && parameters->main_options.writeConForces;
  }

matter2con()

io::IoStatus eonc::Matter::matter2con ( std::string filename, bool append = false, const io::ConFrameMetadata * metadata = nullptr )

inlinenodiscard

Definition at line 281 of file Matter.h.

                                                         {
    return io::matter2con(*this, filename, append, metadata);
  }

matter2convel()

io::IoStatus eonc::Matter::matter2convel ( std::string filename )

inlinenodiscard

Definition at line 285 of file Matter.h.

                                                             {
    return io::matter2convel(*this, filename);
  }

matter2xyz()

io::IoStatus eonc::Matter::matter2xyz ( std::string filename, bool append = false )

inlinenodiscard

Definition at line 288 of file Matter.h.

                                                           {
    return io::matter2xyz(*this, filename, append);
  }

maxForce()

double Matter::maxForce

(

void

)

const

Definition at line 554 of file Matter.cpp.

                              {
  // Ensures that the forces are up to date
  computePotential();
 
  const AtomMatrix &f = getForces();
  double maxForce = 0.0;
  for (int i = 0; i < nAtoms; i++) {
    if (getFixed(i)) {
      continue;
    }
    maxForce = std::max(f.row(i).norm(), maxForce);
  }
  return maxForce;
}

movieFrames()

const std::vector< readcon::ConFrame > & eonc::Matter::movieFrames ( ) const

inlinenodiscard

In-memory minimization movie (same stamps as writeMovie CON).

Cleared when retainMovieFrames=false on the next relax, or via clearMovieFrames().

Definition at line 154 of file Matter.h.

                                                                      {
    return movie_frames_;
  }

needsForceUpdate()

bool eonc::Matter::needsForceUpdate ( ) const

inlinenodiscard

Whether forces need recomputation (positions changed since last eval).

Definition at line 232 of file Matter.h.

{ return recomputePotential; }

numberOfAtoms()

long int Matter::numberOfAtoms

(

)

const

Definition at line 209 of file Matter.cpp.

{ return (nAtoms); }

numberOfFixedAtoms()

long int Matter::numberOfFixedAtoms

(

)

const

Definition at line 465 of file Matter.cpp.

                                          {
  long n = 0;
  for (long i = 0; i < nAtoms; ++i) {
    if (getFixed(i)) {
      ++n;
    }
  }
  return n;
}

numberOfFreeAtoms()

long int Matter::numberOfFreeAtoms

(

)

const

Definition at line 475 of file Matter.cpp.

                                         {
  return nAtoms - numberOfFixedAtoms();
}

operator=() [1/2]

const Matter & Matter::operator=

(

const Matter &

matter

)

Definition at line 25 of file Matter.cpp.

                                                  {
  if (this == &matter) {
    return *this;
  }
  nAtoms = matter.nAtoms;
  resize(nAtoms);
 
  positions = matter.positions;
  forces = matter.forces;
  masses = matter.masses;
  atomicNrs = matter.atomicNrs;
  isFixed = matter.isFixed;
  atomIndex = matter.atomIndex;
  cell = matter.cell;
  cellInverse = matter.cellInverse;
  velocities = matter.velocities;
 
  removeNetForce = matter.removeNetForce;
  structComp = matter.structComp;
  parameters = matter.parameters;
 
  usePeriodicBoundaries = matter.usePeriodicBoundaries;
  pbcConvention = matter.pbcConvention;
 
  potential = matter.potential;
  potentialEnergy = matter.potentialEnergy;
  energyVariance = matter.energyVariance;
  forceCalls = matter.forceCalls;
  recomputePotential = matter.recomputePotential;
  // Both caches describe the forces this object held before the assignment.
  // resize() above already raises them; state it here alongside the members
  // this function owns.
  recomputeFreeMask = true;
  recomputeMaskedForces = true;
 
  // A BondBoost binds to one Matter (BondBoost.h:32 takes a Matter *), so a
  // copy cannot share the source's: boosting through it would drive the
  // original. The copy starts without one and re-establishes it through
  // setBiasPotential. biasForces is zeroed by the resize above, which is the
  // state that matches having no bias potential.
  biasPotential = nullptr;
 
  headerCon = matter.headerCon;
  // ConFrame is move-only; copy does not retain movie trajectory.
  movie_frames_.clear();
 
  return *this;
}

operator=() [2/2]

Matter & Matter::operator= ( Matter && other )

noexcept

Definition at line 76 of file Matter.cpp.

                                               {
  if (this == &other) {
    return *this;
  }
  potential = std::move(other.potential);
  usePeriodicBoundaries = other.usePeriodicBoundaries;
  pbcConvention = other.pbcConvention;
  recomputePotential = other.recomputePotential;
  forceCalls = other.forceCalls;
  headerCon = std::move(other.headerCon);
  removeNetForce = other.removeNetForce;
  structComp = other.structComp;
  parameters = other.parameters;
  nAtoms = other.nAtoms;
  positions = std::move(other.positions);
  velocities = std::move(other.velocities);
  forces = std::move(other.forces);
  biasForces = std::move(other.biasForces);
  biasPotential = other.biasPotential;
  other.biasPotential = nullptr;
  masses = std::move(other.masses);
  atomicNrs = std::move(other.atomicNrs);
  isFixed = std::move(other.isFixed);
  atomIndex = std::move(other.atomIndex);
  freeMask = std::move(other.freeMask);
  maskedForces = std::move(other.maskedForces);
  freeIndices = std::move(other.freeIndices);
  recomputeFreeMask = other.recomputeFreeMask;
  recomputeMaskedForces = other.recomputeMaskedForces;
  cell = std::move(other.cell);
  cellInverse = std::move(other.cellInverse);
  energyVariance = other.energyVariance;
  movie_frames_ = std::move(other.movie_frames_);
  potentialEnergy = other.potentialEnergy;
 
  other.nAtoms = 0;
  other.recomputePotential = true;
  other.recomputeFreeMask = true;
  other.recomputeMaskedForces = true;
  return *this;
}

pbc()

AtomMatrix eonc::Matter::pbc ( const AtomMatrix & diff ) const

inline

Definition at line 163 of file Matter.h.

                                               {
    return eonc::pbc::apply(diff, cell, cellInverse);
  }

pbcV()

VectorXd eonc::Matter::pbcV ( const VectorXd & diff ) const

inline

Definition at line 166 of file Matter.h.

                                            {
    return eonc::pbc::applyV(diff, cell, cellInverse);
  }

pdistance()

double Matter::pdistance	(	long	index1,
		long	index2,
		int	axis ) const

Definition at line 366 of file Matter.cpp.

                                                                 {
  Matrix<double, 1, 3> ret;
  ret.setZero();
  ret(0, axis) = positions(index1, axis) - positions(index2, axis);
  ret = pbc(ret);
  return ret(0, axis);
}

perAtomNorm()

double Matter::perAtomNorm

(

const Matter &

matter

)

Definition at line 160 of file Matter.cpp.

                                               {
  long i = 0;
  double max_distance = 0.0;
 
  if (matter.numberOfAtoms() == nAtoms) {
    AtomMatrix diff = pbc(positions - matter.positions);
    for (i = 0; i < nAtoms; i++) {
      max_distance = std::max(diff.row(i).norm(), max_distance);
    }
  }
  return max_distance;
}

relax()

bool Matter::relax	(	bool	quiet = false,
		bool	writeMovie = false,
		bool	checkpoint = false,
		std::string	prefixMovie = std::string(),
		std::string	prefixCheckpoint = std::string(),
		bool	retainMovieFrames = false )

Definition at line 257 of file Matter.cpp.

                                           {
  if (retainMovieFrames) {
    movie_frames_.clear();
  }
  return eonc::helpers::relaxMatter(
      *this, *parameters, quiet, writeMovie, checkpoint, prefixMovie,
      prefixCheckpoint, retainMovieFrames ? &movie_frames_ : nullptr);
}

resetForceCalls()

void Matter::resetForceCalls

(

)

Definition at line 481 of file Matter.cpp.

                             {
  forceCalls = 0;
  return;
}

resize()

void Matter::resize

(

long int

nAtoms

)

Definition at line 173 of file Matter.cpp.

                                         {
  if (length < 0) {
    throw std::invalid_argument("Matter::resize: negative atom count");
  }
  // Zero is a real size: leaving nAtoms at the old value there sends
  // setMasses and every other nAtoms loop off the end of an empty array.
  nAtoms = length;
  positions.resize(length, 3);
  positions.setZero();
 
  velocities.resize(length, 3);
  velocities.setZero();
 
  biasForces.resize(length, 3);
  biasForces.setZero();
 
  forces.resize(length, 3);
  forces.setZero();
 
  masses.resize(length);
  masses.setZero();
 
  atomicNrs.resize(length);
  atomicNrs.setZero();
 
  isFixed.resize(length, 3);
  isFixed.setZero();
 
  atomIndex.resize(length);
  for (long i = 0; i < length; i++)
    atomIndex(i) = static_cast<std::int64_t>(i); // default: sequential
  recomputePotential = true;
  recomputeMaskedForces = true;
  recomputeFreeMask = true;
}

setAtomicNr()

void Matter::setAtomicNr	(	long int	atom,
		long	atomicNr )

Definition at line 396 of file Matter.cpp.

                                                          {
  atomicNrs[indexAtom] = atomicNr;
  recomputePotential = true;
  recomputeMaskedForces = true;
}

setAtomicNrs()

void Matter::setAtomicNrs

(

const VectorXi &

atmnrs

)

Definition at line 571 of file Matter.cpp.

                                                {
  if (atmnrs.size() != this->nAtoms) {
    throw std::invalid_argument(
        "Vector of atomic numbers not equal to the number of atoms");
  } else {
    this->atomicNrs = atmnrs;
  }
}

setAtomIndex()

void eonc::Matter::setAtomIndex ( long int atom, std::int64_t index )

inline

Definition at line 303 of file Matter.h.

                                                     {
    atomIndex(atom) = index;
  }

setBiasForces()

void Matter::setBiasForces

(

const AtomMatrix &

bf

)

Definition at line 318 of file Matter.cpp.

                                               {
  biasForces = bf.array() * getFree().array();
}

setBiasPotential()

void Matter::setBiasPotential

(

BondBoost *

bondBoost

)

Definition at line 314 of file Matter.cpp.

                                                  {
  biasPotential = bondBoost;
}

setCell()

void Matter::setCell

(

const Matrix3d &

newCell

)

Definition at line 213 of file Matter.cpp.

                                            {
  cell = newCell;
  cellInverse = cell.inverse();
}

setComputedPotential()

void Matter::setComputedPotential	(	double	energy,
		double	variance )

Set energy/variance from external batched evaluation and mark forces as up-to-date (recomputePotential = false).

Definition at line 643 of file Matter.cpp.

                                                                {
  potentialEnergy = energy;
  energyVariance = variance;
  recomputePotential = false;
  recomputeMaskedForces = true;
  forceCalls++;
 
  // Apply the same net force removal as computePotential()
  if (isFixed.maxCoeff() < 0.5 && removeNetForce) {
    Vector3d tempForce = forces.colwise().sum() / nAtoms;
    for (long int i = 0; i < nAtoms; i++) {
      forces.row(i) -= tempForce.transpose();
    }
  }
}

setFixed() [1/2]

void Matter::setFixed	(	long int	atom,
		int	axis,
		int	isFixed )

Set one Cartesian axis. axis is 0=x, 1=y, 2=z.

Definition at line 427 of file Matter.cpp.

                                                                      {
  isFixed(indexAtom, axis) = isFixed_passed ? 1.0 : 0.0;
  recomputeFreeMask = true;
  recomputeMaskedForces = true;
}

setFixed() [2/2]

void Matter::setFixed	(	long int	atom,
		int	isFixed )

Broadcast a whole-atom flag onto all three axes.

Definition at line 418 of file Matter.cpp.

                                                            {
  const double v = isFixed_passed ? 1.0 : 0.0;
  isFixed(indexAtom, 0) = v;
  isFixed(indexAtom, 1) = v;
  isFixed(indexAtom, 2) = v;
  recomputeFreeMask = true;
  recomputeMaskedForces = true;
}

setFixedMask()

void Matter::setFixedMask	(	long int	atom,
		std::array< bool, 3 >	mask )

Definition at line 433 of file Matter.cpp.

                                                                    {
  isFixed(indexAtom, 0) = mask[0] ? 1.0 : 0.0;
  isFixed(indexAtom, 1) = mask[1] ? 1.0 : 0.0;
  isFixed(indexAtom, 2) = mask[2] ? 1.0 : 0.0;
  recomputeFreeMask = true;
  recomputeMaskedForces = true;
}

setForces()

void Matter::setForces

(

const AtomMatrix &

f

)

Definition at line 608 of file Matter.cpp.

                                          {
  forces = f.array() * getFree().array();
}

setHeaderCon()

void eonc::Matter::setHeaderCon ( const std::array< std::string, 5 > & headers )

inline

Definition at line 311 of file Matter.h.

                                                           {
    headerCon = headers;
  }

setHeaderConLine()

void eonc::Matter::setHeaderConLine ( size_t i, std::string line )

inline

Definition at line 314 of file Matter.h.

                                                  {
    headerCon.at(i) = std::move(line);
  }

setMass()

void Matter::setMass	(	long int	atom,
		double	mass )

Definition at line 382 of file Matter.cpp.

                                                    {
  masses[indexAtom] = mass;
}

setMasses()

void Matter::setMasses

(

const VectorXd &

massesIn

)

Definition at line 386 of file Matter.cpp.

                                               {
  for (int i = 0; i < nAtoms; i++) {
    masses[i] = massesIn[i];
  }
}

setPbcConvention()

void eonc::Matter::setPbcConvention ( PbcConvention convention )

inline

Definition at line 202 of file Matter.h.

                                                  {
    pbcConvention = convention;
  }

setPeriodic()

void eonc::Matter::setPeriodic ( bool periodic )

inline

Definition at line 321 of file Matter.h.

                                  {
    usePeriodicBoundaries = periodic;
    recomputePotential = true;
    recomputeMaskedForces = true;
  }

setPosition()

void Matter::setPosition	(	long int	atom,
		int	axis,
		double	position )

Definition at line 222 of file Matter.cpp.

                                                                      {
  positions(indexAtom, axis) = position;
  if (usePeriodicBoundaries) {
    applyPeriodicBoundary();
  }
  recomputePotential = true;
  recomputeMaskedForces = true;
}

setPositions()

void Matter::setPositions

(

const AtomMatrix &

pos

)

Definition at line 273 of file Matter.cpp.

                                               {
  positions = pos;
  if (usePeriodicBoundaries) {
    applyPeriodicBoundary();
  }
  recomputePotential = true;
  recomputeMaskedForces = true;
}

setPositionsFree()

void Matter::setPositionsFree

(

const AtomMatrix &

pos

)

Definition at line 287 of file Matter.cpp.

                                                   {
  getFree(); // ensure freeIndices is up to date
  for (size_t j = 0; j < freeIndices.size(); j++) {
    positions.row(freeIndices[j]) = pos.row(static_cast<long>(j));
  }
  // Optimizers write free-atom coords only (TIP4P/SPCE and any PBC pot).
  // Match setPositions: wrap the full configuration when PBC is on (#171).
  if (usePeriodicBoundaries) {
    applyPeriodicBoundary();
  }
  recomputePotential = true;
  recomputeMaskedForces = true;
}

setPositionsFreeV()

void Matter::setPositionsFreeV

(

const VectorXd &

pos

)

Definition at line 301 of file Matter.cpp.

                                                  {
  setPositionsFree(AtomMatrix::Map(pos.data(), numberOfFreeAtoms(), 3));
}

setPositionsV()

void Matter::setPositionsV

(

const VectorXd &

pos

)

Definition at line 283 of file Matter.cpp.

                                              {
  setPositions(AtomMatrix::Map(pos.data(), numberOfAtoms(), 3));
}

setPotential()

void Matter::setPotential

(

std::shared_ptr< Potential >

pot

)

Definition at line 625 of file Matter.cpp.

                                                      {
  this->potential = pot;
  // Molecular QM backends (NWChem/ORCA) must not use PBC wraps (#188). Auto-off
  // with a hard fail if code later forces PBC while this pot is attached.
  if (potential && potential->requiresIsolatedMoleculeLayout() &&
      usePeriodicBoundaries) {
    usePeriodicBoundaries = false;
    // Use EONC_LOG_* (not bare QUILL_LOG_* with eonc::log::get() as arg): the
    // quill macros expand logger->… and choke on a call expression as the first
    // macro argument on some GCC versions (CI: expected primary-expression).
    EONC_LOG_WARNING(
        "Disabled PBC for isolated-molecule potential (NWChem/ORCA-class); "
        "re-enabling PBC will throw (issue #188)");
  }
  recomputePotential = true;
  recomputeMaskedForces = true;
}

setVelocities()

void Matter::setVelocities

(

const AtomMatrix &

v

)

Definition at line 604 of file Matter.cpp.

                                              {
  velocities = v.array() * getFree().array();
}

setVelocity()

void Matter::setVelocity	(	long int	atom,
		int	axis,
		double	velocity )

Definition at line 231 of file Matter.cpp.

                                                                 {
  velocities(indexAtom, axis) = vel;
}

takeMovieFrames()

std::vector< readcon::ConFrame > eonc::Matter::takeMovieFrames ( )

inlinenodiscard

Take ownership of retained frames (leaves storage empty).

Definition at line 159 of file Matter.h.

                                                             {
    return std::move(movie_frames_);
  }

writeTibble()

io::IoStatus eonc::Matter::writeTibble ( std::string filename )

inlinenodiscard

Definition at line 266 of file Matter.h.

                                                           {
    return io::writeTibble(*this, filename);
  }

Friends And Related Symbol Documentation

io::con2matter

io::IoStatus io::con2matter ( Matter & , const readcon::ConFrame & , io::ConFrameMetadata *  )

friend

Member Data Documentation

atomicNrs

VectorXi eonc::Matter::atomicNrs

private

Definition at line 373 of file Matter.h.

atomIndex

Eigen::Matrix<std::int64_t, Eigen::Dynamic, 1> eonc::Matter::atomIndex

private

Definition at line 376 of file Matter.h.

biasForces

AtomMatrix eonc::Matter::biasForces

private

Definition at line 370 of file Matter.h.

biasPotential

BondBoost* eonc::Matter::biasPotential {nullptr}

private

Definition at line 371 of file Matter.h.

{nullptr};

cell

Matrix3d eonc::Matter::cell

private

Definition at line 382 of file Matter.h.

cellInverse

Matrix3d eonc::Matter::cellInverse

private

Definition at line 383 of file Matter.h.

energyVariance

double eonc::Matter::energyVariance

mutableprivate

Definition at line 384 of file Matter.h.

forceCalls

long eonc::Matter::forceCalls

mutableprivate

Definition at line 351 of file Matter.h.

forces

AtomMatrix eonc::Matter::forces

mutableprivate

Definition at line 369 of file Matter.h.

freeIndices

std::vector<int> eonc::Matter::freeIndices

mutableprivate

Definition at line 379 of file Matter.h.

freeMask

AtomMatrix eonc::Matter::freeMask

mutableprivate

Definition at line 377 of file Matter.h.

headerCon

std::array<std::string, 5> eonc::Matter::headerCon

private

Definition at line 354 of file Matter.h.

isFixed

AtomMatrix eonc::Matter::isFixed

private

Definition at line 374 of file Matter.h.

m_log

eonc::log::Scoped eonc::Matter::m_log

private

Definition at line 340 of file Matter.h.

maskedForces

AtomMatrix eonc::Matter::maskedForces

mutableprivate

Definition at line 378 of file Matter.h.

masses

VectorXd eonc::Matter::masses

private

Definition at line 372 of file Matter.h.

movie_frames_

std::vector<readcon::ConFrame> eonc::Matter::movie_frames_

private

Definition at line 385 of file Matter.h.

nAtoms

long eonc::Matter::nAtoms

private

Definition at line 366 of file Matter.h.

parameters

const Parameters* eonc::Matter::parameters

private

Definition at line 365 of file Matter.h.

pbcConvention

PbcConvention eonc::Matter::pbcConvention

private

Definition at line 347 of file Matter.h.

positions

AtomMatrix eonc::Matter::positions

private

Definition at line 367 of file Matter.h.

potential

std::shared_ptr<Potential> eonc::Matter::potential

private

Definition at line 342 of file Matter.h.

potentialEnergy

double eonc::Matter::potentialEnergy

mutableprivate

Definition at line 386 of file Matter.h.

recomputeFreeMask

bool eonc::Matter::recomputeFreeMask {true}

mutableprivate

Definition at line 380 of file Matter.h.

{true};

recomputeMaskedForces

bool eonc::Matter::recomputeMaskedForces {true}

mutableprivate

Definition at line 381 of file Matter.h.

{true};

recomputePotential

bool eonc::Matter::recomputePotential

mutableprivate

Definition at line 348 of file Matter.h.

removeNetForce

bool eonc::Matter::removeNetForce {true}

private

Definition at line 362 of file Matter.h.

{true};

structComp

Parameters::structure_comparison_options_t eonc::Matter::structComp

private

Definition at line 363 of file Matter.h.

usePeriodicBoundaries

bool eonc::Matter::usePeriodicBoundaries

private

Definition at line 343 of file Matter.h.

velocities

AtomMatrix eonc::Matter::velocities

private

Definition at line 368 of file Matter.h.

---

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

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