.TH "sc::Molecule" 3 "Sun Oct 4 2020" "Version 2.3.1" "MPQC" \" -*- nroff -*- .ad l .nh .SH NAME sc::Molecule \- The \fBMolecule\fP class contains information about molecules\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBsc::SavableState\fP\&. .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBMolecule\fP (const \fBMolecule\fP &)" .br .ti -1c .RI "\fBMolecule\fP (\fBStateIn\fP &)" .br .ti -1c .RI "\fBMolecule\fP (const \fBRef\fP< \fBKeyVal\fP > &input)" .br .RI "The \fBMolecule\fP \fBKeyVal\fP constructor is used to generate a \fBMolecule\fP object from the input\&. " .ti -1c .RI "\fBMolecule\fP & \fBoperator=\fP (const \fBMolecule\fP &)" .br .ti -1c .RI "void \fBadd_atom\fP (int Z, double x, double y, double z, const char *=0, double mass=0\&.0, int have_charge=0, double \fBcharge\fP=0\&.0)" .br .RI "Add an AtomicCenter to the \fBMolecule\fP\&. " .ti -1c .RI "virtual void \fBprint\fP (std::ostream &=\fBExEnv::out0\fP()) const" .br .RI "Print information about the molecule\&. " .ti -1c .RI "virtual void \fBprint_parsedkeyval\fP (std::ostream &=\fBExEnv::out0\fP(), int print_pg=1, int print_unit=1, int number_atoms=1) const" .br .ti -1c .RI "int \fBnatom\fP () const" .br .RI "Returns the number of atoms in the molcule\&. " .ti -1c .RI "int \fBZ\fP (int atom) const" .br .ti -1c .RI "double & \fBr\fP (int atom, int xyz)" .br .ti -1c .RI "const double & \fBr\fP (int atom, int xyz) const" .br .ti -1c .RI "double * \fBr\fP (int atom)" .br .ti -1c .RI "const double * \fBr\fP (int atom) const" .br .ti -1c .RI "double \fBmass\fP (int atom) const" .br .ti -1c .RI "const char * \fBlabel\fP (int atom) const" .br .RI "Returns the label explicitly assigned to atom\&. " .ti -1c .RI "int \fBatom_at_position\fP (double *, double tol=0\&.05) const" .br .RI "Takes an (x, y, z) postion and finds an atom within the given tolerance distance\&. " .ti -1c .RI "int \fBatom_label_to_index\fP (const char *\fBlabel\fP) const" .br .RI "Returns the index of the atom with the given label\&. " .ti -1c .RI "double * \fBcharges\fP () const" .br .RI "Returns a double* containing the nuclear charges of the atoms\&. " .ti -1c .RI "double \fBcharge\fP (int iatom) const" .br .RI "Return the charge of the atom\&. " .ti -1c .RI "double \fBnuclear_charge\fP () const" .br .RI "Returns the total nuclear charge\&. " .ti -1c .RI "void \fBset_point_group\fP (const \fBRef\fP< \fBPointGroup\fP > &, double tol=1\&.0e\-7)" .br .RI "Sets the \fBPointGroup\fP of the molecule\&. " .ti -1c .RI "\fBRef\fP< \fBPointGroup\fP > \fBpoint_group\fP () const" .br .RI "Returns the \fBPointGroup\fP of the molecule\&. " .ti -1c .RI "\fBRef\fP< \fBPointGroup\fP > \fBhighest_point_group\fP (double tol=1\&.0e\-8) const" .br .RI "Find this molecules true point group (limited to abelian groups)\&. " .ti -1c .RI "int \fBis_axis\fP (\fBSCVector3\fP &origin, \fBSCVector3\fP &udirection, int order, double tol=1\&.0e\-8) const" .br .RI "Return 1 if this given axis is a symmetry element for the molecule\&. " .ti -1c .RI "int \fBis_plane\fP (\fBSCVector3\fP &origin, \fBSCVector3\fP &uperp, double tol=1\&.0e\-8) const" .br .RI "Return 1 if the given plane is a symmetry element for the molecule\&. " .ti -1c .RI "int \fBhas_inversion\fP (\fBSCVector3\fP &origin, double tol=1\&.0e\-8) const" .br .RI "Return 1 if the molecule has an inversion center\&. " .ti -1c .RI "int \fBis_linear\fP (double tolerance=1\&.0e\-5) const" .br .RI "Returns 1 if the molecule is linear, 0 otherwise\&. " .ti -1c .RI "int \fBis_planar\fP (double tolerance=1\&.0e\-5) const" .br .RI "Returns 1 if the molecule is planar, 0 otherwise\&. " .ti -1c .RI "void \fBis_linear_planar\fP (int &linear, int &planar, double tol=1\&.0e\-5) const" .br .RI "Sets linear to 1 if the molecular is linear, 0 otherwise\&. " .ti -1c .RI "\fBSCVector3\fP \fBcenter_of_mass\fP () const" .br .RI "Returns a \fBSCVector3\fP containing the cartesian coordinates of the center of mass for the molecule\&. " .ti -1c .RI "double \fBnuclear_repulsion_energy\fP ()" .br .RI "Returns the nuclear repulsion energy for the molecule\&. " .ti -1c .RI "void \fBnuclear_repulsion_1der\fP (int center, double xyz[3])" .br .RI "\fBCompute\fP the nuclear repulsion energy first derivative with respect to the given center\&. " .ti -1c .RI "void \fBnuclear_efield\fP (const double *position, double *efield)" .br .RI "\fBCompute\fP the electric field due to the nuclei at the given point\&. " .ti -1c .RI "void \fBnuclear_charge_efield\fP (const double *\fBcharges\fP, const double *position, double *efield)" .br .RI "\fBCompute\fP the electric field due to the given charges at the positions of the nuclei at the given point\&. " .ti -1c .RI "void \fBsymmetrize\fP (double tol=0\&.5)" .br .RI "If the molecule contains only symmetry unique atoms, this function will generate the other, redundant atoms\&. " .ti -1c .RI "void \fBsymmetrize\fP (const \fBRef\fP< \fBPointGroup\fP > &pg, double tol=0\&.5)" .br .RI "Set the point group and then symmetrize\&. " .ti -1c .RI "void \fBcleanup_molecule\fP (double tol=0\&.1)" .br .RI "This will try to carefully correct symmetry errors in molecules\&. " .ti -1c .RI "void \fBtranslate\fP (const double *r)" .br .ti -1c .RI "void \fBmove_to_com\fP ()" .br .ti -1c .RI "void \fBtransform_to_principal_axes\fP (int trans_frame=1)" .br .ti -1c .RI "void \fBtransform_to_symmetry_frame\fP ()" .br .ti -1c .RI "void \fBprint_pdb\fP (std::ostream &=\fBExEnv::out0\fP(), char *title=0) const" .br .ti -1c .RI "void \fBread_pdb\fP (const char *filename)" .br .ti -1c .RI "void \fBprincipal_moments_of_inertia\fP (double *evals, double **evecs=0) const" .br .RI "\fBCompute\fP the principal moments of inertia and, possibly, the principal axes\&. " .ti -1c .RI "int \fBnunique\fP () const" .br .RI "Return information about symmetry unique and equivalent atoms\&. " .ti -1c .RI "int \fBunique\fP (int iuniq) const" .br .RI "Returns the overall number of the iuniq'th unique atom\&. " .ti -1c .RI "int \fBnequivalent\fP (int iuniq) const" .br .RI "Returns the number of atoms equivalent to iuniq\&. " .ti -1c .RI "int \fBequivalent\fP (int iuniq, int j) const" .br .RI "Returns the j'th atom equivalent to iuniq\&. " .ti -1c .RI "int \fBatom_to_unique\fP (int iatom) const" .br .RI "Converts an atom number to the number of its generating unique atom\&. " .ti -1c .RI "int \fBatom_to_unique_offset\fP (int iatom) const" .br .RI "Converts an atom number to the offset of this atom in the list of generated atoms\&. " .ti -1c .RI "int \fBn_core_electrons\fP ()" .br .RI "Return the number of core electrons\&. " .ti -1c .RI "int \fBmax_z\fP ()" .br .RI "Return the maximum atomic number\&. " .ti -1c .RI "\fBRef\fP< \fBAtomInfo\fP > \fBatominfo\fP () const" .br .RI "Return the molecule's \fBAtomInfo\fP object\&. " .ti -1c .RI "std::string \fBatom_name\fP (int iatom) const" .br .RI "Returns the element name of the atom\&. " .ti -1c .RI "std::string \fBatom_symbol\fP (int iatom) const" .br .RI "Returns the element symbol of the atom\&. " .ti -1c .RI "void \fBset_include_q\fP (bool iq)" .br .RI "If include_q is true, then include the 'Q' atoms in the charge and efield routines\&. " .ti -1c .RI "bool \fBinclude_q\fP () const" .br .RI "Returns include_q\&. See set_include_q\&. " .ti -1c .RI "void \fBset_include_qq\fP (bool iqq)" .br .RI "If include_qq is true, include the coupling between pairs of 'Q' atoms when computing nuclear repulsion energy and gradients\&. " .ti -1c .RI "bool \fBinclude_qq\fP () const" .br .RI "Returns include_qq\&. See set_include_qq\&. " .ti -1c .RI "int \fBn_q_atom\fP () const" .br .RI "Retrieve the number of 'Q' atoms\&. " .ti -1c .RI "int \fBq_atom\fP (int i) const" .br .RI "Retrieve the 'Q' atoms\&. " .ti -1c .RI "int \fBn_non_q_atom\fP () const" .br .RI "Retrieve the number of non-'Q' atoms\&. " .ti -1c .RI "int \fBnon_q_atom\fP (int i) const" .br .RI "Retrieve the of non-'Q' atoms\&. " .ti -1c .RI "void \fBsave_data_state\fP (\fBStateOut\fP &)" .br .RI "Save the base classes (with save_data_state) and the members in the same order that the \fBStateIn\fP CTOR initializes them\&. " .in -1c .SS "Protected Member Functions" .in +1c .ti -1c .RI "void \fBinit_symmetry_info\fP (double tol=0\&.5)" .br .ti -1c .RI "void \fBclear_symmetry_info\fP ()" .br .ti -1c .RI "void \fBclear\fP ()" .br .ti -1c .RI "void \fBthrow_if_atom_duplicated\fP (int begin=0, double tol=1e\-3)" .br .in -1c .SS "Protected Attributes" .in +1c .ti -1c .RI "int \fBnatoms_\fP" .br .ti -1c .RI "\fBRef\fP< \fBAtomInfo\fP > \fBatominfo_\fP" .br .ti -1c .RI "\fBRef\fP< \fBPointGroup\fP > \fBpg_\fP" .br .ti -1c .RI "\fBRef\fP< \fBUnits\fP > \fBgeometry_units_\fP" .br .ti -1c .RI "double ** \fBr_\fP" .br .ti -1c .RI "int * \fBZ_\fP" .br .ti -1c .RI "double * \fBcharges_\fP" .br .ti -1c .RI "int \fBnuniq_\fP" .br .ti -1c .RI "int * \fBnequiv_\fP" .br .ti -1c .RI "int ** \fBequiv_\fP" .br .ti -1c .RI "int * \fBatom_to_uniq_\fP" .br .ti -1c .RI "double * \fBmass_\fP" .br .ti -1c .RI "char ** \fBlabels_\fP" .br .ti -1c .RI "int \fBq_Z_\fP" .br .ti -1c .RI "bool \fBinclude_q_\fP" .br .ti -1c .RI "bool \fBinclude_qq_\fP" .br .ti -1c .RI "std::vector< int > \fBq_atoms_\fP" .br .ti -1c .RI "std::vector< int > \fBnon_q_atoms_\fP" .br .in -1c .SS "Additional Inherited Members" .SH "Detailed Description" .PP The \fBMolecule\fP class contains information about molecules\&. It has a \fBKeyVal\fP constructor that can create a new molecule from either a PDB file or from a list of Cartesian coordinates\&. .PP The following \fBParsedKeyVal\fP input reads from the PDB file \fCh2o\&.pdb\fP: .PP .nf molecule: ( pdb_file = 'h2o\&.pdb' ) .fi .PP .PP The following input explicitly gives the atom coordinates, using the \fBParsedKeyVal\fP table notation: .PP .nf 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 ] } ) ) .fi .PP The default units are Bohr which can be overridden with \fCunit=angstrom\fP\&. The \fCatom_labels\fP array can be omitted\&. The \fCatoms\fP and \fCgeometry\fP arrays are required\&. .PP As a special case, an atom can be given with the symbol \fCQ\fP or the name \fCcharge\fP\&. Such centers are treated as point charges and not given basis functions\&. The values of the charges must be specified with a \fCcharge\fP vector in the \fBMolecule\fP input\&. Since the charge vector assign 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: .PP .nf 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 ] } ) ) .fi .PP .PP This feature is designed for doing QM/MM calculations, so, by default, methods will not include interactions between the \fCQ\fP centers when computing the energy or the gradient\&. To include these interactions, set \fCinclude_qq=1\fP\&. .PP The \fBMolecule\fP class has a \fBPointGroup\fP member object, which also has a \fBKeyVal\fP constructor that is called when a \fBMolecule\fP is made\&. The following example constructs a molecule with $C_{2v}$ symmetry: .PP .nf molecule: ( symmetry=c2v unit=angstrom { atoms geometry } = { O [0\&.000000000 0 0\&.369372944 ] H [0\&.783975899 0 -0\&.184686472 ] } ) ) .fi .PP 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\&. .SH "Constructor & Destructor Documentation" .PP .SS "sc::Molecule::Molecule (const \fBRef\fP< \fBKeyVal\fP > & input)" .PP The \fBMolecule\fP \fBKeyVal\fP constructor is used to generate a \fBMolecule\fP object from the input\&. Several examples are given in the \fBMolecule\fP class overview\&. The full list of keywords that are accepted is below\&. .PP KeywordTypeDefaultDescription .PP \fCinclude_q\fPbooleanfalseSome of the atoms can be specified as \fCQ\fP and given a customizable charge\&. Such atoms are a point charge that do not have basis functions\&. If this option is true, then the \fCQ\fP atoms are included when computing the nuclear charge and the electric field due to the nuclear charge\&. .PP \fCinclude_qq\fPbooleanfalseSome of the atoms can be specified as \fCQ\fP and given a customizable charge\&. Such atoms are a point charge that do not have basis functions\&. If this option is true, then the \fCQ\fP atoms are included when computing the nuclear repulsion energy and its derivatives\&. .PP \fCatominfo\fP\fBAtomInfo\fPlibrary valuesThis gives information about each atom, such as the symbol, name, and various atomic radii\&. .PP \fCsymmetry\fPstring\fCC1\fPThe Schoenflies symbol of the point group\&. This is case insensitive\&. It should be a subgroup of D\*<2h\*> \&. If it is \fCauto\fP, then the appropriate subgroup of D\*<2h\*> will be found\&. .PP \fCsymmetry_tolerance\fPdouble1\&.0e-4When 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 a 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\&. .PP \fCsymmetry_frame\fPdouble[3][3][[1 0 0][0 1 0][0 0 1]]The symmetry frame\&. Ignored for \fCsymmetry = auto\fP\&. .PP \fCorigin\fPdouble[3][0 0 0]The origin of the symmetry frame\&. Ignored for \fCsymmetry = auto\fP\&. .PP \fCredundant_atoms\fPbooleanfalseIf 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 \fCsymmetry = auto\fP\&. .PP \fCpdb_file\fPstringundefinedThis 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\&. .PP \fCunit\fPstringbohrThis gives the name of the units used for the geometry\&. See the \fBUnits\fP class for information about the known units\&. This replaces deprecated keywords that are still recognized: \fCangstrom\fP and \fCangstroms\fP\&. This is ignored if \fCpdb_file\fP is given\&. .PP \fCgeometry\fPdouble[][3]noneThis gives the Cartesian coordinates of the molecule\&. This is ignored if \fCpdb_file\fP is given\&. .PP \fCatoms\fPstring[]noneThis gives the Cartesian coordinates of the molecule\&. This is ignored if \fCpdb_file\fP is given\&. .PP \fCghost\fPboolean[]noneIf 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 \fCpdb_file\fP is given\&. .PP \fCcharge\fPdouble[]Z for each atomAllows specification of the charge for each atom\&. This is ignored if \fCpdb_file\fP is given\&. .PP \fCatom_labels\fPstring[]noneThis gives a user defined atom label for each atom\&. This is ignored if \fCpdb_file\fP is given\&. .PP \fCmass\fPdouble[]Taken from \fBAtomInfo\fP given by the \fCatominfo\fP keyword\&. This gives a user defined mass for each atom\&. This is ignored if \fCpdb_file\fP is given\&. .PP .SH "Member Function Documentation" .PP .SS "int sc::Molecule::atom_at_position (double *, double tol = \fC0\&.05\fP) const" .PP Takes an (x, y, z) postion and finds an atom within the given tolerance distance\&. If no atom is found -1 is returned\&. .SS "int sc::Molecule::atom_label_to_index (const char * label) const" .PP Returns the index of the atom with the given label\&. If the label cannot be found -1 is returned\&. .SS "int sc::Molecule::atom_to_unique (int iatom) const\fC [inline]\fP" .PP Converts an atom number to the number of its generating unique atom\&. The return value is in [0, nunique)\&. .SS "int sc::Molecule::atom_to_unique_offset (int iatom) const" .PP Converts an atom number to the offset of this atom in the list of generated atoms\&. The unique atom itself is allows offset 0\&. .br .SS "double* sc::Molecule::charges () const" .PP Returns a double* containing the nuclear charges of the atoms\&. The caller is responsible for freeing the return value\&. .SS "void sc::Molecule::cleanup_molecule (double tol = \fC0\&.1\fP)" .PP This will try to carefully correct symmetry errors in molecules\&. If any atom is out of place by more then tol, abort will be called\&. .SS "\fBRef\fP<\fBPointGroup\fP> sc::Molecule::highest_point_group (double tol = \fC1\&.0e\-8\fP) const" .PP Find this molecules 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\&. .SS "int sc::Molecule::is_axis (\fBSCVector3\fP & origin, \fBSCVector3\fP & udirection, int order, double tol = \fC1\&.0e\-8\fP) const" .PP Return 1 if this given axis is a symmetry element for the molecule\&. The direction vector must be a unit vector\&. .SS "void sc::Molecule::is_linear_planar (int & linear, int & planar, double tol = \fC1\&.0e\-5\fP) const" .PP Sets linear to 1 if the molecular is linear, 0 otherwise\&. Sets planar to 1 if the molecular is planar, 0 otherwise\&. .SS "int sc::Molecule::is_plane (\fBSCVector3\fP & origin, \fBSCVector3\fP & uperp, double tol = \fC1\&.0e\-8\fP) const" .PP Return 1 if the given plane is a symmetry element for the molecule\&. The perpendicular vector must be a unit vector\&. .SS "const char* sc::Molecule::label (int atom) const" .PP Returns the label explicitly assigned to atom\&. If no label has been assigned, then null is returned\&. .SS "void sc::Molecule::save_data_state (\fBStateOut\fP &)\fC [virtual]\fP" .PP Save the base classes (with save_data_state) and the members in the same order that the \fBStateIn\fP CTOR initializes them\&. This must be implemented by the derived class if the class has data\&. .PP Reimplemented from \fBsc::SavableState\fP\&. .SS "void sc::Molecule::symmetrize (double tol = \fC0\&.5\fP)" .PP 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 the is another atom and it is not identical, then abort will be called\&. .SH "Author" .PP Generated automatically by Doxygen for MPQC from the source code\&.