sc::Molecule(3)

📦

version 2.3.1 · 5 versions

💖 `sc::Molecule(3)` — the MPQC manual page 💖

okay bestie, buckle up — this is the sc::Molecule page from MPQC, and it’s a whole main-character moment. it’s long, so this is part 1 of 2. no sign-off yet, we’re just getting started ✨

🌸 NAME 🌸

sc::Molecule — the Molecule class contains information about molecules. literally what it says on the tin, no cap 💅

🦋 SYNOPSIS 🦋

#include <molecule.h>

Inherits sc::SavableState.

✨ Public Member Functions ✨

Molecule (const Molecule &) — signature only, bestie; the original doesn’t give it a description.
Molecule (StateIn &) — same deal, signature only.
Molecule (const Ref< KeyVal > &input) — the Molecule KeyVal constructor is used to generate a Molecule object from the input. keyval girlies rise 🫶
Molecule & operator= (const Molecule &) — assignment operator, signature only.
void add_atom (int Z, double x, double y, double z, const char *=0, double mass=0.0, int have_charge=0, double charge=0.0) — add an AtomicCenter to the Molecule. new atom just dropped 👑
virtual void print (std::ostream &=ExEnv::out0()) const — print information about the molecule. show and tell time ✨
virtual void print_parsedkeyval (std::ostream &=ExEnv::out0(), int print_pg=1, int print_unit=1, int number_atoms=1) const — signature only, no description in the original.
int natom () const — returns the number of atoms in the molecule.
int Z (int atom) const — signature only.
double & r (int atom, int xyz) — signature only.
const double & r (int atom, int xyz) const — signature only.
double * r (int atom) — signature only.
const double * r (int atom) const — signature only.
double mass (int atom) const — signature only.
const char * label (int atom) const — returns the label explicitly assigned to atom.
int atom_at_position (double *, double tol=0.05) const — takes an (x, y, z) position and finds an atom within the given tolerance distance. detective mode 🔍
int atom_label_to_index (const char *label) const — returns the index of the atom with the given label.
double * charges () const — returns a double* containing the nuclear charges of the atoms.
double charge (int iatom) const — return the charge of the atom.
double nuclear_charge () const — returns the total nuclear charge.
void set_point_group (const Ref< PointGroup > &, double tol=1.0e-7) — sets the PointGroup of the molecule. symmetry slay 💫
Ref< PointGroup > point_group () const — returns the PointGroup of the molecule.
Ref< PointGroup > highest_point_group (double tol=1.0e-8) const — find this molecule’s true point group (limited to abelian groups). it’s giving group theory realness 🎀
int is_axis (SCVector3 &origin, SCVector3 &udirection, int order, double tol=1.0e-8) const — return 1 if this given axis is a symmetry element for the molecule.
int is_plane (SCVector3 &origin, SCVector3 &uperp, double tol=1.0e-8) const — return 1 if the given plane is a symmetry element for the molecule.
int has_inversion (SCVector3 &origin, double tol=1.0e-8) const — return 1 if the molecule has an inversion center.
int is_linear (double tolerance=1.0e-5) const — returns 1 if the molecule is linear, 0 otherwise.
int is_planar (double tolerance=1.0e-5) const — returns 1 if the molecule is planar, 0 otherwise.
void is_linear_planar (int &linear, int &planar, double tol=1.0e-5) const — sets linear to 1 if the molecule is linear, 0 otherwise.
SCVector3 center_of_mass () const — returns a SCVector3 containing the cartesian coordinates of the center of mass for the molecule.
double nuclear_repulsion_energy () — returns the nuclear repulsion energy for the molecule.
void nuclear_repulsion_1der (int center, double xyz[3]) — compute the nuclear repulsion energy first derivative with respect to the given center.
void nuclear_efield (const double *position, double *efield) — compute the electric field due to the nuclei at the given point.
void nuclear_charge_efield (const double *charges, const double *position, double *efield) — compute the electric field due to the given charges at the positions of the nuclei at the given point.
void symmetrize (double tol=0.5) — if the molecule contains only symmetry unique atoms, this function will generate the other, redundant atoms. fill in the blanks, bestie ✨
void symmetrize (const Ref< PointGroup > &pg, double tol=0.5) — set the point group and then symmetrize.
void cleanup_molecule (double tol=0.1) — this will try to carefully correct symmetry errors in molecules. gentle cleanup energy 🧹
void translate (const double *r) — signature only.
void move_to_com () — signature only.
void transform_to_principal_axes (int trans_frame=1) — signature only.
void transform_to_symmetry_frame () — signature only.
void print_pdb (std::ostream &=ExEnv::out0(), char *title=0) const — signature only.
void read_pdb (const char *filename) — signature only.
void principal_moments_of_inertia (double *evals, double **evecs=0) const — compute the principal moments of inertia and, possibly, the principal axes.
int nunique () const — return information about symmetry unique and equivalent atoms.
int unique (int iuniq) const — returns the overall number of the iuniq’th unique atom.
int nequivalent (int iuniq) const — returns the number of atoms equivalent to iuniq.
int equivalent (int iuniq, int j) const — returns the j’th atom equivalent to iuniq.
int atom_to_unique (int iatom) const — converts an atom number to the number of its generating unique atom.
int atom_to_unique_offset (int iatom) const — converts an atom number to the offset of this atom in the list of generated atoms.
int n_core_electrons () — return the number of core electrons.
int max_z () — return the maximum atomic number.
Ref< AtomInfo > atominfo () const — return the molecule’s AtomInfo object.
std::string atom_name (int iatom) const — returns the element name of the atom.
std::string atom_symbol (int iatom) const — returns the element symbol of the atom.
void set_include_q (bool iq) — if include_q is true, then include the 'Q' atoms in the charge and efield routines.
bool include_q () const — returns include_q. see set_include_q.
void set_include_qq (bool iqq) — if include_qq is true, include the coupling between pairs of 'Q' atoms when computing nuclear repulsion energy and gradients.
bool include_qq () const — returns include_qq. see set_include_qq.
int n_q_atom () const — retrieve the number of 'Q' atoms.
int q_atom (int i) const — retrieve the 'Q' atoms.
int n_non_q_atom () const — retrieve the number of non-'Q' atoms.
int non_q_atom (int i) const — retrieve the of non-'Q' atoms. (yes, that’s the wording, don’t come for me 💀)
void save_data_state (StateOut &) — save the base classes (with save_data_state) and the members in the same order that the StateIn CTOR initializes them.

🎀 Protected Member Functions 🎀

void init_symmetry_info (double tol=0.5) — signature only.
void clear_symmetry_info () — signature only.
void clear () — signature only.
void throw_if_atom_duplicated (int begin=0, double tol=1e-3) — signature only.

🌈 Protected Attributes 🌈

int natoms_
Ref< AtomInfo > atominfo_
Ref< PointGroup > pg_
Ref< Units > geometry_units_
double ** r_
int * Z_
double * charges_
int nuniq_
int * nequiv_
int ** equiv_
int * atom_to_uniq_
double * mass_
char ** labels_
int q_Z_
bool include_q_
bool include_qq_
std::vector< int > q_atoms_
std::vector< int > non_q_atoms_

⭐ Additional Inherited Members ⭐

there are more inherited members, bestie — they’re inherited, so they live their truth elsewhere 💅

🔥 Detailed Description 🔥

the Molecule class contains information about molecules. iconic, honestly.

it has a KeyVal constructor that can create a new molecule from either a PDB file or from a list of Cartesian coordinates.

the following ParsedKeyVal input reads from the PDB file h2o.pdb:

molecule<Molecule>: (
   pdb_file = 'h2o.pdb'
 )

the following input explicitly gives the atom coordinates, using the ParsedKeyVal table notation:

molecule<Molecule>: (
    unit=angstrom
    { atom_labels atoms           geometry            } = {
          O1         O   [ 0.000000000 0  0.369372944 ]
          H1         H   [ 0.783975899 0 -0.184686472 ]
          H2         H   [-0.783975899 0 -0.184686472 ]
     }
    )
  )

the default units are Bohr, which can be overridden with unit=angstrom. the atom_labels array can be omitted. the atoms and geometry arrays are required. required besties only ✨

as a special case, an atom can be given with the symbol Q or the name charge. such centers are treated as point charges and not given basis functions. the values of the charges must be specified with a charge vector in the Molecule input. since the charge vector assigns charges to all centers, including atoms, it is easiest to place all point charge centers first in the geometry, and then give a charge vector with a number of elements equal to the number of point charges. the following example shows a water molecule interacting with a point charge having value 0.1:

molecule<Molecule>: (
    unit=angstrom
    charge = [ 0.1 ]
    { atom_labels atoms           geometry            } = {
          Q1         Q   [ 0.0         0 10.0         ]
          O1         O   [ 0.000000000 0  0.369372944 ]
          H1         H   [ 0.783975899 0 -0.184686472 ]
          H2         H   [-0.783975899 0 -0.184686472 ]
     }
    )
  )

this feature is designed for doing QM/MM calculations, so, by default, methods will not include interactions between the Q centers when computing the energy or the gradient. to include these interactions, set include_qq=1. periodt.

the Molecule class has a PointGroup member object, which also has a KeyVal constructor that is called when a Molecule is made. the following example constructs a molecule with $C_{2v}$ symmetry:

molecule<Molecule>: (
    symmetry=c2v
    unit=angstrom
    { atoms         geometry            } = {
        O   [0.000000000 0  0.369372944 ]
        H   [0.783975899 0 -0.184686472 ]
     }
    )
  )

only the symmetry unique atoms need to be specified. nonunique atoms can be given too, however, numerical errors in the geometry specification can result in the generation of extra atoms, so be careful. like, actually be careful — extra atoms are not the vibe 😭

part 2 is coming, bestie — don’t touch that dial 💖

💖 Constructor & Destructor Documentation 💖

✨ `sc::Molecule::Molecule (const Ref< KeyVal > & input)`

sc::Molecule::Molecule (const Ref< KeyVal > & input)

okay so bestie, the Molecule KeyVal constructor is what you use to generate a Molecule object from the input 💅 Several examples are given in the Molecule class overview. The full list of keywords that are accepted is below — no cap, this is the whole roster.

Keyword · Type · Default · Description

include_q — boolean, default false — some of the atoms can be specified as Q and given a customizable charge. Such atoms are a point charge that do not have basis functions. If this option is true, then the Q atoms are included when computing the nuclear charge and the electric field due to the nuclear charge. ⚡
include_qq — boolean, default false — some of the atoms can be specified as Q and given a customizable charge. Such atoms are a point charge that do not have basis functions. If this option is true, then the Q atoms are included when computing the nuclear repulsion energy and its derivatives. 🔥
atominfo — AtomInfo, default library values — this gives information about each atom, such as the symbol, name, and various atomic radii. 🧚
symmetry — string, default C1 — the Schoenflies symbol of the point group. This is case insensitive. It should be a subgroup of D2h. If it is auto, then the appropriate subgroup of D2h will be found. 🌈
symmetry_tolerance — double, default 1.0e-4 — when a molecule has symmetry, some atoms may be related by symmetry operations. The distance between given atoms and atoms generated by symmetry operations is compared to this threshold to determine if they are the same. If they are the same, then the coordinates are cleaned up to make them exactly symmetry equivalent. If the given molecule was produced by an optimization that started in C1 symmetry, but produced a roughly symmetric structure and you would like to begin using symmetry, then this may need to be increased a bit to properly symmetrize the molecule. 🔍
symmetry_frame — double[3][3], default [[1 0 0][0 1 0][0 0 1]] — the symmetry frame. Ignored for symmetry = auto. 🎀
origin — double[3], default [0 0 0] — the origin of the symmetry frame. Ignored for symmetry = auto. ✨
redundant_atoms — boolean, default false — if true, do not generate symmetry equivalent atoms; they are already given in the input. It should not be necessary to specify this option, since, by default, if a symmetry operation duplicates an atom, the generated atom will not be added to the list of atoms. Ignored for symmetry = auto. 💫
pdb_file — string, default undefined — this gives the name of a PDB file, from which the nuclear coordinates will be read. If this is given, the following options will be ignored. 📁

⚠️ when pdb_file is set, the options listed after it in this roster are ignored — so don't expect them to do anything, bestie.

unit — string, default bohr — this gives the name of the units used for the geometry. See the Units class for information about the known units. This replaces deprecated keywords that are still recognized: angstrom and angstroms. This is ignored if pdb_file is given. 📏
geometry — double[][3], default none — this gives the Cartesian coordinates of the molecule. This is ignored if pdb_file is given. 🧊
atoms — string[], default none — this gives the Cartesian coordinates of the molecule. This is ignored if pdb_file is given. 🧬
ghost — boolean[], default none — if true, the atom will be given zero charge. It will still have basis functions, however. This is used to estimate basis set superposition error. This is ignored if pdb_file is given. 👻
charge — double[], default Z for each atom — allows specification of the charge for each atom. This is ignored if pdb_file is given. ⚡
atom_labels — string[], default none — this gives a user defined atom label for each atom. This is ignored if pdb_file is given. 🏷️
mass — double[], default Taken from AtomInfo given by the atominfo keyword. — this gives a user defined mass for each atom. This is ignored if pdb_file is given. ⚖️

🧚 Member Function Documentation 🧚

🔹 `atom_at_position`

int sc::Molecule::atom_at_position (double *, double tol = 0.05) const

Takes an (x, y, z) position and finds an atom within the given tolerance distance. If no atom is found, -1 is returned. 🕵️‍♀️

🔹 `atom_label_to_index`

int sc::Molecule::atom_label_to_index (const char * label) const

Returns the index of the atom with the given label. If the label cannot be found, -1 is returned. 🏷️

🔹 `atom_to_unique`

int sc::Molecule::atom_to_unique (int iatom) const [inline]

Converts an atom number to the number of its generating unique atom. The return value is in [0, nunique). 🔁

🔹 `atom_to_unique_offset`

int sc::Molecule::atom_to_unique_offset (int iatom) const

Converts an atom number to the offset of this atom in the list of generated atoms. The unique atom itself gets offset 0. 🎯

🔹 `charges`

double* sc::Molecule::charges () const

Returns a double* containing the nuclear charges of the atoms. The caller is responsible for freeing the return value. 🧾

🔹 `cleanup_molecule`

void sc::Molecule::cleanup_molecule (double tol = 0.1)

This will try to carefully correct symmetry errors in molecules. If any atom is out of place by more than tol, abort will be called. 🚨

⚠️ yes bestie, that's a real abort — keep an eye on your tol.

🔹 `highest_point_group`

Ref<PointGroup> sc::Molecule::highest_point_group (double tol = 1.0e-8) const

Find this molecule's true point group (limited to abelian groups). If the point group of this molecule is set to the highest point group, then the origin must first be set to the center of mass. 🌸

🔹 `is_axis`

int sc::Molecule::is_axis (SCVector3 & origin, SCVector3 & udirection, int order, double tol = 1.0e-8) const

Return 1 if this given axis is a symmetry element for the molecule. The direction vector must be a unit vector. 🧭

🔹 `is_linear_planar`

void sc::Molecule::is_linear_planar (int & linear, int & planar, double tol = 1.0e-5) const

Sets linear to 1 if the molecule is linear, 0 otherwise. Sets planar to 1 if the molecule is planar, 0 otherwise. 📐

🔹 `is_plane`

int sc::Molecule::is_plane (SCVector3 & origin, SCVector3 & uperp, double tol = 1.0e-8) const

Return 1 if the given plane is a symmetry element for the molecule. The perpendicular vector must be a unit vector. 🪞

🔹 `label`

const char* sc::Molecule::label (int atom) const

Returns the label explicitly assigned to atom. If no label has been assigned, then null is returned. 🏷️

🔹 `save_data_state`

void sc::Molecule::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. 💾

Reimplemented from sc::SavableState.

🔹 `symmetrize`

void sc::Molecule::symmetrize (double tol = 0.5)

If the molecule contains only symmetry unique atoms, this function will generate the other, redundant atoms. The redundant atom will only be generated if there is no other atoms within a distance of tol. If there is another atom and it is not identical, then abort will be called. 🌀

🚨 another abort moment — if the atom overlap isn't identical, it's not gonna quietly fix it for you.

🌸 Author 🌸

Generated automatically by Doxygen for MPQC from the source code.

💖 and that's a wrap, bestie — this iconic little page is from version 2.3.1, dated Sun Oct 4 2020, and yeah, Doxygen generated it for MPQC from the source code. mwah 💋✨

📦 where this page comes from

ubuntu jammy: libsc-doc 2.3.1-21
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

sc::Molecule(3)

💖 sc::Molecule(3) — the MPQC manual page 💖

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

✨ Public Member Functions ✨

🎀 Protected Member Functions 🎀

🌈 Protected Attributes 🌈

⭐ Additional Inherited Members ⭐

🔥 Detailed Description 🔥

💖 Constructor & Destructor Documentation 💖

✨ sc::Molecule::Molecule (const Ref< KeyVal > & input)

🧚 Member Function Documentation 🧚

🔹 atom_at_position

🔹 atom_label_to_index

🔹 atom_to_unique

🔹 atom_to_unique_offset

🔹 charges

🔹 cleanup_molecule

🔹 highest_point_group

🔹 is_axis

🔹 is_linear_planar

🔹 is_plane

🔹 label

🔹 save_data_state

🔹 symmetrize