% intro to this chapter (Molecular Modeling Toolkit)
\label{sec:mmt}

The Molecular Modeling Toolkit provides the basic functionality common to many
chemistry algorithms in NWChem.  These tools include the geometry object,
the basis set object, the integral API, and the linear algebra routines.  
These modules are not strictly
"objects" in the sense usually used in an object oriented language, but
they serve essentially the same purpose in that
they encapsulate specific data and provide access to it through a well-defined
abstract programming interface.  The geometry object specifies the
physical makeup of the chemical system by defining atomic centers, 
spatial location of the centers, and their nuclear charge.  It can include
an applied electric field, the symmetry, and other characteristics of the
system.  The basis set object handles the details of the Gaussian basis sets,
and with the geometry object defines all information required by an 
{\em ab initio} claculation that is not specific to a 
particluar electonic state.  The integral API is a layer between the actual
integral package and the application module.  It allows the developer to 
essentially ignore the details of how the integrals are
computed, which facilitates programming of new modules and allows 
incorporation of new integral
techniques with minimal distruption of applications that use those integrals.
The explicit separation of these objects greatly simplifies the development
of the chemistry modules of NWChem and allows more flexible use of the code
and easier maintenance.
This chapter describes each of the tools in detail,
so that developers can use them correctly when inserting new modules in
the code or modifying existing modules.  

\section{The Geometry Object}

\label{sec:geometry}

The geometry object is used in NWChem to store and manipulate important
information describing the molecular system to be modeled, not all of
which is specifically connected with the geometry of the system.  The
geometry object serves four main purposes; 
\begin{itemize}
\item provides a definition of the coordinate system and positioning in space
  (including lattice vectors for periodic systems)
\item defines an association of names/tags with coordinates in space
\item specifies the external potential (nuclear multipole
  moments, external fields, effective core potentials, \ldots) that
  define the Hamiltonian for all electronic structure methods
\item stores most Hamiltonian related information (but
  not wavefunction related information).
\end{itemize}

The tag associated with a geometric center serves a number of purposes in NWChem.
It provides a convenient and unambiguous way to refer to
\begin{itemize}
\item a specific chemical element (which provides default values for information
such as nuclear charge,
  mass, number of electrons, \ldots)
\item the name of an `atomic' basis set
\item a DFT grid
\end{itemize}

The tag can also serve as a test for symmetry equivalence, since lower symmetry 
can be forced
by specifying different tags for otherwise symmetry equivalent
centers.

The data contained in the geometry object (or information that can be derived from
data in the object) include the following;
\begin{enumerate}
\item A description of the coordinates of all types of centers (e.g.,
      atom, basis function)
\item Charges (or optionally, ECPs, \ldots) associated with those centers
\item Tags (names) of centers
\item Masses associated with centers
\item Variables for optimization (e.g., via constrained cartesians
      or Z-matrix variables)
\item Symmetry information
\item Any other simple scalar/vector attribute associated
      specifically with a center
\end{enumerate}

Specific geometries are referenced through an integer handle.   
Multiple geometries can be defined such that any one of them 
may be accessible at any instant for a given problem.  However,
geometries can consume a large amount of memory, so it is usually
advisable to keep the number of simultaneously
`open' geometries to a minimum.

Logical functions return true on sucess, false on failure.  The following
subsections describe in more detail the functions that return something 
other than the
logical state.

\subsection{Creating, destroying, loading and storing geometries}

The following functions are used to create, destroy, load and store geometries.

\subsubsection{{\tt geom\_create}}
\begin{verbatim}
  logical function geom_create(geom, name)
  integer geom          [output]
  character*(*) name    [input]
\end{verbatim}
This is the only way to get a valid geometry handle.  The user-supplied string
for {\tt name}
is used only for identification in printout and subsequent executions of
the \verb+geom_create+ function.
If the geometry has already been opened, a handle to the existing copy is
returned.

\subsubsection{{\tt geom\_destroy}}
\begin{verbatim}
  logical function geom_destroy(geom)
  integer geom          [input]
\end{verbatim}
This function deletes the {\em in core} data structures associated with the geometry and
makes the geometry invalid for further use.  (Note that disk resident data is
not deleted.  The runtime database is preserved between calculations.)

\subsubsection{{\tt geom\_check\_handle}}
\begin{verbatim}
  logical function geom_check_handle(geom, msg)
  integer geom          [input]
  character*(*) msg     [input]
\end{verbatim}
If the specified string {\tt geom} is not a valid geometry handle
 this function prints out 
the string {\tt msg}
and returns \FALSE.

\subsubsection{{\tt geom\_rtdb\_load}}
\begin{verbatim}
  logical function geom_rtdb_load(rtdb, geom, name)
  integer rtdb          [input]
  integer geom          [input]
  character*(*) name    [input]
\end{verbatim}
This function loads the named geometry from the data base.  One level of translation is
attempted upon the name.  An entry with the name {\tt name} is searched
for in the database and if located the value of that entry is used as
the name of the geometry, rather than {\tt name} itself.  The string specified
for {\tt geom}
must be a valid handle created by \verb+geom_create+.  The same
geometry in the database may be loaded into distinct in-memory geometry
objects.

\subsubsection{{\tt geom\_rtdb\_store}}
\begin{verbatim}
  logical function geom_rtdb_store(rtdb, geom, name)
  integer rtdb          [input]
  integer geom          [input]
  character*(*) name    [input]
\end{verbatim}  
This function stores the named geometry in the database.  One level of translation is
attempted upon the string supplied for \verb+name+.

\subsubsection{{\tt geom\_rtdb\_delete}}
\begin{verbatim}
  logical function geom_rtdb_delete(rtdb, name)
  integer rtdb          [input]
  character*(*) name    [input]
\end{verbatim}
This function deletes the named geometry from the data base.  One level of
translation is attempted.  Nothing happens to in-core copies of any
geometries.

\subsection{Information About the Geometry}

This section describes functions that are used to define information about specific
geometries. 

\subsubsection{{\tt geom\_ncent}}
\begin{verbatim}
  logical function geom_ncent(geom, ncent)
  integer geom          [input]
  integer ncent         [output]
\end{verbatim}
Returns in {\tt ncent} the number of centers.

\subsubsection{{\tt geom\_nuc\_charge}}
\begin{verbatim}
  logical function geom_nuc_charge(geom, total_charge)
  integer geom                   [input]
  double precision total_charge  [output]
\end{verbatim}
Returns the sum of the nuclear charges.

\subsubsection{{\tt geom\_nuc\_rep\_energy}}
\begin{verbatim}
  logical function geom_nuc_rep_energy(geom, energy)
  integer geom              [input]
  double precision energy   [output]
\end{verbatim}
Returns the effective nuclear repulsion energy.  (Refer also to functions
\verb+geom_incude_bqbq()+  and
\verb+geom_set_bqbq()+.

\subsubsection{{\tt geom\_include\_bqbq}}
\label{sec:incbqbq}
\begin{verbatim}
  logical function geom_include_bqbq(geom)
  integer geom          [input]
\end{verbatim}
By default the nuclear repulsion energy returned by
\verb+geom_nuc_rep_energy+ does not include the interactions between
point-charges (i.e., centers which tag begins with \verb+bq+).  This
is so that it is easy for QM-MM programs to generate effective
Hamiltonians based on point charges and avoid double counting of
contributions.  This routine returns \TRUE or \FALSE
if the BQ-BQ contributions are or are not being computed.  The default
(don't include BQ-BQ interactions) thus corresponds to a return value
of \FALSE.

\subsubsection{{\tt geom\_set\_bqbq}}
\label{sec:setbqbq}
\begin{verbatim}
  logical function geom_set_bqbq(geom, value)
  integer geom          [input]
  logical value         [input]
\end{verbatim}
Sets the logical variable that determines if BQ-BQ interactions are
included to {\tt value}.

\subsection{Information About Centers and Coordinates}

This section describes functions that define information about the
centers and coordinate system for the geometry object.

\subsubsection{{\tt geom\_cart\_set}}
\begin{verbatim}
  logical function geom_cart_set(geom, ncent, t, c, q)
  integer geom                [input]
  integer ncent               [input]
  character*16 t(ncent)       [input]
  double precision c(3,ncent) [input]
  double precision q(ncent)   [input]
\end{verbatim}
This function is a simple interface for setting tags ({\tt t}), 
cartesian coordinates ({\tt
  c}) and charges ({\tt q}) for the geometry.

\subsubsection{{\tt geom\_cart\_get}}
\begin{verbatim}
  logical function geom_cart_get(geom, ncent, t, c, q)
  integer geom                [input]
  integer ncent               [output]
  character*16 t(ncent)       [output]
  double precision c(3,ncent) [output]
  double precision q(ncent)   [output]
\end{verbatim}
This function extracts information from the geometry.  (It performs
essentially the opposite action to that of the \verb+set+ functions
described above.)  The user must ensure 
that the arrays are of sufficient
dimension to hold the output.

\subsubsection{{\tt geom\_cent\_get}}
\begin{verbatim}  
  logical function geom_cent_get(geom, icent, t, c, q)
  integer geom          [input]
  integer icent         [input]
  character*16 t        [output]
  double precision c(3) [output]
  double precision q    [output]
\end{verbatim}
Returns tag/coordinates/charge about the center {\tt icent}.

\subsubsection{{\tt geom\_cent\_set}}
\begin{verbatim}
  logical function geom_cent_set(geom, icent, t, c, q)
  integer geom          [input]
  integer icent         [input]
  character*16 t        [input]
  double precision c(3) [input]
  double precision q    [input]
\end{verbatim}
This function sets values for center {\tt icent} inside the geometry.  It
is
essentially the opposite of the function
\verb+geom_cent_get+.

\subsubsection{{\tt geom\_cent\_tag}}
\begin{verbatim}
  logical function geom_cent_tag(geom, icent, tag)
  integer geom          [input]
  integer icent         [input]
  character*16 tag      [output]
\end{verbatim}
Returns just the tag of the center {\tt icent}.

\subsubsection{{\tt geom\_check\_cent}}
\begin{verbatim}
  logical function geom_check_cent(geom, msg, icent)
  integer geom          [input]
  character*(*) msg     [input]
  integer icent         [input]
\end{verbatim}
This function returns \verb+.true.+ if center \verb+icent+ is a valid center.
Otherwise it returns \verb+.false.+ and prints out the message and other
information. 

\subsection{Support for Periodic Systems}


This section describes functions that are applicable only to periodic systems.

\subsubsection{{\tt geom\_systype\_get}}
\begin{verbatim}
  logical function geom_systype_get(geom, itype)
  integer geom          [input]
  integer itype         [input]
\end{verbatim}
This function returns an integer flag corresponding to
the system type in {\tt itype}.  Valid entries include
the following
\begin{itemize}
\item 0 = Molecule
\item 1 = Polymer
\item 2 = Slab
\item 3 = Crystal
\end{itemize}

\subsubsection{{\tt geom\_latvec\_get}}
\begin{verbatim}
  logical function geom_latvec_get(geom, vectors)
  integer geom                [input]
  double precision vectors(3) [output]
\end{verbatim}
For periodic systems, this function returns the lattice constants.

\subsubsection{{\tt geom\_latang\_get}}
\begin{verbatim}
  logical function geom_latang_get(geom, angles)
  integer geom                [input]
  double precision angles(3)  [output]
\end{verbatim}
For periodic systems, this function returns the angles defining the lattice.

\subsubsection{{\tt geom\_recipvec\_get}}
\begin{verbatim}
  logical function geom_recipvec_get(geom,rvectors)
  integer geom                [input]
  double precision rvectors(3)[output]
\end{verbatim}
For periodic systems, this function returns the constants of 
the reciprocal lattice.

\subsubsection{{\tt geom\_recipang\_get}}
\begin{verbatim}
  logical function geom_recipang_get(geom, rangles)
  integer geom                [input]
  double precision rangles(3) [output]
\end{verbatim}
For periodic systems, this function returns the angles defining the reciprocal
lattice ({\bf units?}).

\subsubsection{{\tt geom\_volume\_get}}
\begin{verbatim}
  logical function geom_volume_get(geom,volume)
  integer geom            [input]
  double precision volume [output]
\end{verbatim}
For periodic systems, this function returns the volume of the unit cell ({\bf units?}).

\subsubsection{{\tt geom\_amatrix\_get} and {\tt geom\_amatinv\_get}}
\begin{verbatim}
  logical function geom_amatrix_get(geom,amat)
  integer geom                  [input]
  double precision amat(3,3)    [output]

  logical function geom_amatinv_get(geom,amatinv)
  integer geom                  [input]
  double precision amatinv(3,3) [output]
\end{verbatim}
For periodic systems, this function returns the `A-matrix' or its inverse.  This is
the matrix that transforms fractional coordinates to a Cartesian
system in atomic units (???).  This matrix is the unit matrix for
molecular systems.

\subsection{Printing and Miscellaneous Routines}

This section describes various useful functions that can be called upon to
manipulate data in the geometry object.

\subsubsection{{\tt geom\_print} and {\tt geom\_print\_xyz}}
\begin{verbatim}
  logical function geom_print(geom)
  integer geom          [input]

  logical function geom_print_xyz(geom, unit)
  integer geom          [input]
  integer unit          [input]
\end{verbatim}
This function prints out the geometry to standard output.  The {\tt XYZ} form prints
the geometry out to the specified Fortran unit in the XYZ format of 
the molecular viewer {\em Xmol}.

\subsubsection{{\tt geom\_set\_user\_units}}
\begin{verbatim}
  logical function geom_set_user_units(geom, units)
  integer geom          [input]
  character*(*) units   [input]
\end{verbatim}
This function sets the coordinates that the user expects for input/output.  It
currently understands either `a.u.' or `angstrom'.  Note that
geometries are always internally stored as cartesians in atomic units.

\subsubsection{{\tt geom\_tag\_to\_element}}
\begin{verbatim}
  logical function geom_tag_to_element(tag, symbol, element, atn)
  character*16 tag      [input]
  character*(*) symbol  [output]
  character*(*) element [output]
  integer atn           [output]
\end{verbatim}
This function attempts to interpret a tag as the name of a chemical element.  If successful,
it return the symbol, full name and atomic number of the element.

\subsubsection{{\tt geom\_charge\_center}}
\begin{verbatim}
  logical function geom_charge_center(geom)
  integer geom          [input]
\end{verbatim}
This function adjusts the cartesian coordinates so that the nuclear dipole moment is
zero (i.e., defines the origin of the coordinate system at the center of
charge.)

\subsubsection{{\tt geom\_num\_core}}
\begin{verbatim}
  logical function geom_num_core(rtdb, geom, module, ncore)
  integer rtdb          [input]
  integer geom          [input]
  character*(*)         [input]
  integer ncore         [output]
\end{verbatim}
This function determines the number of core orbitals in a system based on the user defining
the number of orbitals per atom.  If there is no user input, the number of core orbitals in a system
is determined by constituent atoms and the standard general chemistry concepts of core and
valance.

\subsubsection{{\tt geom\_freeze}}
\begin{verbatim}
  logical function geom_freeze(rtdb, geom, module, ncore)
  integer rtdb          [input]
  integer geom          [input]
  character*(*) module  [input]
  integer ncore         [output]
\end{verbatim}
This function determines the number of frozen core orbitals in a system.  If successful,
it returns the number of frozen core orbitals, as well as a logical true value.

