sc::MolecularCoor(3)

📦

version 2.3.1 · 5 versions

✨ `sc::MolecularCoor(3)` ✨ — the manual for the MPQC vibes

Okay so bestie, welcome to the sc::MolecularCoor(3) page 💅 this is the MPQC manual, and we're about to get into the abstract class that literally describes the coordinate system used to describe a molecule. No cap, it's giving main character energy for all your molecular geometry needs 🧚

🦋 SYNOPSIS 🦋

#include <coor.h>

It inherits from sc::SavableState (so it's savable, periodt 💾). And it gets inherited by sc::CartMolecularCoor and sc::IntMolecularCoor — slay, the family tree is thriving 👑

🌸 DESCRIPTION 🌸

The sc::MolecularCoor abstract class describes the coordinate system used to describe a molecule. That's the whole vibe. It's used to convert a molecule's cartesian coordinates to and from this coordinate system — so it's like the translator between your fave coordinate world and cartesian reality, and honestly? We love a bilingual icon 🫶

🎀 OPTIONS 🎀

Okay so these are the KeyVal constructor keywords — the little settings you can pass in via const Ref< KeyVal > &, iykwim 😌

molecule — a Molecule object. There is no default — so you literally have to give it one, bestie, no skipping 🙈
debug — an integer which, if nonzero, will cause extra output. So if you're nosy like me, set it and watch the tea spill ☕
matrixkit — a SCMatrixKit object. It is usually unnecessary to give this keyword — so like, don't stress about it 💅
natom3 — an SCDimension object for the dimension of the vector of cartesian coordinates. It is usually unnecessary to give this keyword — again, optional, no pressure 🦋

🌈 PUBLIC MEMBER FUNCTIONS 🌈

Here's the full roster, bestie — every single one, no skips ✨

MolecularCoor (Ref< Molecule > &) — constructor energy, let's go 💖
MolecularCoor (StateIn &) — the StateIn constructor, for when you're restoring from saved state 🎀
MolecularCoor (const Ref< KeyVal > &) — the KeyVal constructor (the one with the keywords above, iykyk) 🔑
void save_data_state (StateOut &) — saves the base classes (with save_data_state) and the members in the same order that the StateIn CTOR initializes them. It's giving "keep the order, don't mess it up" energy 📦
RefSCDimension dim_natom3 () — returns a smart reference to an SCDimension equal to the number of atoms in the molecule times 3. So like, atoms × 3 = the dimension, math is mathing 🔢
Ref< Molecule > molecule () const — returns the molecule. That's it, that's the function — short and iconic 👑
virtual void print (std::ostream &=ExEnv::out0()) const =0 — print the coordinate. Pure virtual, so the derived classes have to bring it to life 🖨️
virtual void print_simples (std::ostream &=ExEnv::out0()) const =0 — also pure virtual, no default body — the derived classes better handle it 💀
virtual RefSCDimension dim ()=0 — returns a smart reference to an SCDimension equal to the number of coordinates (be they Cartesian, internal, or whatever) that are being optimized. Whatever the vibe, it counts them 🌟
int to_cartesian (const RefSCVector &internal) — given a set of displaced internal coordinates, updates the cartesian coordinates of the Molecule contained herein. Note: it does not change the vector internal — so don't expect it to mutate your input, bestie 🙅‍♀️
virtual int to_cartesian (const Ref< Molecule > &mol, const RefSCVector &internal)=0 — pure virtual, no body, the derived classes take the wheel 🛞
virtual int to_internal (RefSCVector &internal)=0 — fill in the vector internal with the current internal coordinates. Heads up: this member will update the values of the variable internal coordinates ⚠️
virtual int to_cartesian (RefSCVector &cartesian, RefSCVector &internal)=0 — convert the internal coordinate gradients in internal to Cartesian coordinates and copy these Cartesian coordinate gradients to cartesian. Only the variable internal coordinate gradients are transformed — so not everything, just the variable ones, periodt 💅
virtual int to_internal (RefSCVector &internal, RefSCVector &cartesian)=0 — convert the Cartesian coordinate gradients in cartesian to internal coordinates and copy these internal coordinate gradients to internal. Only the variable internal coordinate gradients are calculated 🔁
virtual int to_cartesian (RefSymmSCMatrix &cartesian, RefSymmSCMatrix &internal)=0 — convert the internal coordinate Hessian internal to Cartesian coordinates and copy the result to cartesian. Only the variable internal coordinate force constants are transformed — again, just the variable ones 🧮
virtual int to_internal (RefSymmSCMatrix &internal, RefSymmSCMatrix &cartesian)=0 — convert the Cartesian coordinate Hessian cartesian to internal coordinates and copy the result to internal. Only the variable internal coordinate force constants are calculated 🔄
virtual void guess_hessian (RefSymmSCMatrix &hessian)=0 — calculate an approximate hessian and place the result in hessian. It's a guess, but make it a good one 🤞
virtual RefSymmSCMatrix inverse_hessian (RefSymmSCMatrix &)=0 — given a Hessian, return the inverse of that hessian. For singular matrices this should return the generalized inverse — so like, even when it's singular, it's still got you 🫶
virtual int nconstrained () — returns the number of constrained coordinates. Count them, bestie 🔢
virtual Ref< NonlinearTransform > change_coordinates () — when this is called, MoleculeCoor may select a new internal coordinate system and return a transform to it. The default action is to not change anything and return an IdentityTransform — so it's giving "no changes, I'm comfy" energy 😌
Ref< SCMatrixKit > matrixkit () const — returns the matrix kit, cute and simple 🎀

👑 PROTECTED ATTRIBUTES 👑

These are the protected besties — not for everyone, just the class and its derivatives 💜

Ref< Molecule > molecule_
RefSCDimension dnatom3_
Ref< SCMatrixKit > matrixkit_
int debug_

💅 MEMBER FUNCTION DETAILS (the deep lore) 💅

Okay so now we're getting into the detailed descriptions — this is where the real tea is ☕

🦋 `virtual Ref<NonlinearTransform> sc::MolecularCoor::change_coordinates ()` [virtual]

When this is called, MoleculeCoor may select a new internal coordinate system and return a transform to it. The default action is to not change anything and return an IdentityTransform — so yeah, it's the "I'm not changing, I'm iconic as I am" function 👑

Reimplemented in sc::SymmMolecularCoor — so that one's got its own take on it 💫

🌸 `virtual RefSymmSCMatrix sc::MolecularCoor::inverse_hessian (RefSymmSCMatrix &)` [pure virtual]

Given a Hessian, return the inverse of that hessian. For singular matrices this should return the generalized inverse — so even when the math says "nope, singular", it's still got a generalized inverse for you, bestie 🫶

Implemented in sc::CartMolecularCoor, sc::RedundMolecularCoor, and sc::SymmMolecularCoor — the whole squad showed up 💅

🎀 `void sc::MolecularCoor::save_data_state (StateOut &)` [virtual]

Save the base classes (with save_data_state) and the members in the same order that the StateIn CTOR initializes them. This must be implemented by the derived class if the class has data — so like, no skipping, it's mandatory 🙅‍♀️

Reimplemented from sc::SavableState.

Reimplemented in sc::CartMolecularCoor, sc::RedundMolecularCoor, sc::SymmMolecularCoor, and sc::IntMolecularCoor — slay, the whole crew 🌈

🧚 `int sc::MolecularCoor::to_cartesian (const RefSCVector & internal)`

Given a set of displaced internal coordinates, update the cartesian coordinates of the Molecule contained herein. This function does not change the vector internal — so your input stays untouched, periodt 🙅‍♀️

🔥 `virtual int sc::MolecularCoor::to_cartesian (RefSCVector & cartesian, RefSCVector & internal)` [pure virtual]

Convert the internal coordinate gradients in internal to Cartesian coordinates and copy these Cartesian coordinate gradients to cartesian. Only the variable internal coordinate gradients are transformed — so not all of them, just the variable ones, iykyk 💅