Provided by: libsc-doc_2.3.1-22build2_all bug

NAME

       sc::Molecule - The Molecule class contains information about molecules.

SYNOPSIS

       #include <molecule.h>

       Inherits sc::SavableState.

   Public Member Functions
       Molecule (const Molecule &)
       Molecule (StateIn &)
       Molecule (const Ref< KeyVal > &input)
           The Molecule KeyVal constructor is used to generate a Molecule object from the input.
       Molecule & operator= (const Molecule &)
       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.
       virtual void print (std::ostream &=ExEnv::out0()) const
           Print information about the molecule.
       virtual void print_parsedkeyval (std::ostream &=ExEnv::out0(), int print_pg=1, int
           print_unit=1, int number_atoms=1) const
       int natom () const
           Returns the number of atoms in the molcule.
       int Z (int atom) const
       double & r (int atom, int xyz)
       const double & r (int atom, int xyz) const
       double * r (int atom)
       const double * r (int atom) const
       double mass (int atom) const
       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) postion and finds an atom within the given tolerance distance.
       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.
       Ref< PointGroup > point_group () const
           Returns the PointGroup of the molecule.
       Ref< PointGroup > highest_point_group (double tol=1.0e-8) const
           Find this molecules true point group (limited to abelian groups).
       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 molecular 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.
       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.
       void translate (const double *r)
       void move_to_com ()
       void transform_to_principal_axes (int trans_frame=1)
       void transform_to_symmetry_frame ()
       void print_pdb (std::ostream &=ExEnv::out0(), char *title=0) const
       void read_pdb (const char *filename)
       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.
       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.

       Public Member Functions inherited from sc::SavableState
       SavableState & operator= (const SavableState &)
       void save_state (StateOut &)
           Save the state of the object as specified by the StateOut object.
       void save_object_state (StateOut &)
           This can be used for saving state when the exact type of the object is known for both
           the save and the restore.
       virtual void save_vbase_state (StateOut &)
           Save the virtual bases for the object.

       Public Member Functions inherited from sc::DescribedClass
       DescribedClass (const DescribedClass &)
       DescribedClass & operator= (const DescribedClass &)
       ClassDesc * class_desc () const  throw ()
           This returns the unique pointer to the ClassDesc corresponding to the given type_info
           object.
       const char * class_name () const
           Return the name of the object's exact type.
       int class_version () const
           Return the version of the class.

       Public Member Functions inherited from sc::RefCount
       int lock_ptr () const
           Lock this object.
       int unlock_ptr () const
           Unlock this object.
       void use_locks (bool inVal)
           start and stop using locks on this object
       refcount_t nreference () const
           Return the reference count.
       refcount_t reference ()
           Increment the reference count and return the new count.
       refcount_t dereference ()
           Decrement the reference count and return the new count.
       int managed () const
       void unmanage ()
           Turn off the reference counting mechanism for this object.
       int managed () const
           Return 1 if the object is managed. Otherwise return 0.

       Public Member Functions inherited from sc::Identity
       Identifier identifier ()
           Return the Identifier for this argument.

   Protected Member Functions
       void init_symmetry_info (double tol=0.5)
       void clear_symmetry_info ()
       void clear ()
       void throw_if_atom_duplicated (int begin=0, double tol=1e-3)

       Protected Member Functions inherited from sc::SavableState
       SavableState (const SavableState &)
       SavableState (StateIn &)
           Each derived class StateIn CTOR handles the restore corresponding to calling
           save_object_state, save_vbase_state, and save_data_state listed above.

       Protected Member Functions inherited from sc::RefCount
       RefCount (const RefCount &)
       RefCount & operator= (const RefCount &)

   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
       Static Public Member Functions inherited from sc::SavableState
       static void save_state (SavableState *s, StateOut &)
       static SavableState * restore_state (StateIn &si)
           Restores objects saved with save_state.
       static SavableState * key_restore_state (StateIn &si, const char *keyword)
           Like restore_state, but keyword is used to override values while restoring.
       static SavableState * dir_restore_state (StateIn &si, const char *objectname, const char
           *keyword=0)

Detailed Description

       The Molecule class contains information about molecules.

       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.

       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 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:

       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.

       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.

Constructor & Destructor Documentation

   sc::Molecule::Molecule (const Ref< KeyVal > & input)
       The Molecule KeyVal constructor is used 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.

       KeywordTypeDefaultDescription

       include_qbooleanfalseSome 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_qqbooleanfalseSome 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.

       atominfoAtomInfolibrary valuesThis gives information about each atom, such as the symbol,
       name, and various atomic radii.

       symmetrystring<td>C1The 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_tolerancedouble1.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.

       symmetry_framedouble[3][3][[1 0 0][0 1 0][0 0 1]]The symmetry frame. Ignored for symmetry
       = auto.

       origindouble[3][0 0 0]The origin of the symmetry frame. Ignored for symmetry = auto.

       redundant_atomsbooleanfalseIf 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_filestringundefinedThis 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.

       unitstringbohrThis 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.

       geometrydouble[][3]noneThis gives the Cartesian coordinates of the molecule. This is
       ignored if pdb_file is given.

       atomsstring[]noneThis gives the Cartesian coordinates of the molecule. This is ignored if
       pdb_file is given.

       ghostboolean[]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 pdb_file is given.

       chargedouble[]Z for each atomAllows specification of the charge for each atom. This is
       ignored if pdb_file is given.

       atom_labelsstring[]noneThis gives a user defined atom label for each atom. This is ignored
       if pdb_file is given.

       massdouble[]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

   int sc::Molecule::atom_at_position (double *, double tol = 0.05) const
       Takes an (x, y, z) postion and finds an atom within the given tolerance distance. If no
       atom is found -1 is returned.

   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.

   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).

   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 is allows offset 0.

   double * sc::Molecule::charges () const
       Returns a double* containing the nuclear charges of the atoms. The caller is responsible
       for freeing the return value.

   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 then tol, abort will be called.

   Ref< PointGroup > sc::Molecule::highest_point_group (double tol = 1.0e-8) const
       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.

   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.

   void sc::Molecule::is_linear_planar (int & linear, int & planar, double tol = 1.0e-5) const
       Sets linear to 1 if the molecular is linear, 0 otherwise. Sets planar to 1 if the
       molecular is planar, 0 otherwise.

   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.

   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.

   virtual void sc::Molecule::print (std::ostream & = ExEnv::out0()) const [virtual]
       Print information about the molecule.

       Reimplemented from sc::DescribedClass.

   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.

   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 the is another atom and it is not identical, then abort
       will be called.

Author

       Generated automatically by Doxygen for MPQC from the source code.