NWChem/doc/prog/basis.tex

\section{The Basis Set Object}
\label{sec:basis}

The basis set object and corresponding API provides access to all
information concerning a basis set from a unique handle.  In this
fashion, multiple distinct basis sets may be manipulated simultanously
on an equal footing.  The internal data structures store only
information for the unique tags in the geometry.

\subsection{Creating, Destroying, Loading and Storing Basis Sets}

Basis set handles must be created with \verb+bas_create+.  Other
routines load and store basis sets from/to the database.

\subsubsection{{\tt bas\_create}}
\begin{verbatim}
  logical function bas_create(basis, name)
  integer basis       ! [output] returned handle
  character*(*)name   ! [input] name of basis set.  
\end{verbatim}
This is the only source of a valid basis set handle.  The input name
is used for output/debug purposes and is not associated with anything
in the database.  An empty basis set is created (in memory only) and
the handle is returned in {\tt basis}.

\subsubsection{{\tt bas\_destroy}}
\begin{verbatim}
  logical function bas_destroy(basis)
  integer basis ![input] handle to basis set to be destroyed
\end{verbatim}
Frees memory and destroys all information about an active in-memory basis
and the associated mapping arrays.

\subsubsection{{\tt bas\_check\_handle}}
\begin{verbatim}
  logical function bas_check_handle(basis,msg)
  integer basis      ! [input] handle
  character*(*) msg  ! [input] error message
\end{verbatim}
Returns \TRUE\ if {\tt basis} is a valid basis set handle.  Otherwise
it returns \FALSE\ and prints the message and a list of known basis
sets on STDOUT.

\subsubsection{{\tt bas\_rtdb\_load}}
\begin{verbatim}
  logical function bas_rtdb_load(rtdb, geom, basis, name)
  integer rtdb        ! [input] rtdb handle      
  integer geom        ! [input] geometry handle with info loaded
  integer basis       ! [input] basis handle
  character*(*) name  ! [input] name of basis in the rtdb
\end{verbatim}
Routine loads a named basis set from the database (specified with the
handle {\tt rtdb}), and using the geometry information builds the
mapping arrays to contractions or shells, basis functions, and
centers.  One level of translation is attempted upon the name --- an
entry with name {\tt name} is searched for in the database and if
located the value of that entry is used as the name of the basis,
rather than {\tt name} itself.

\subsubsection{{\tt bas\_rtdb\_store}}
\begin{verbatim}
  logical function bas_rtdb_store(rtdb, name, basis)
  integer rtdb              ! [input] handle to database
  character*(*) name        ! [input] name to use when storing
  integer basis             ! [input] handle to basis set
\end{verbatim}
Stores the in-memory basis (referenced by the handle {\tt basis}) into
the specified database (referenced by the handle {\tt rtdb}) using the
specified name.  One level of translation is attempted upon the name
--- an entry with name {\tt name} is searched for in the database and
if located the value of that entry is used as the name of the basis,
rather than {\tt name} itself.  The in-memory basis set is unchanged.

\subsection{Information About the Entire Basis}

\subsubsection{{\tt bas\_high\_angular}}
\begin{verbatim}
  logical function bas_high_angular(basis,high_angular)
  integer basis         ! [input] basis set handle
  integer high_angular  ! [output] high angular momentum of basis
\end{verbatim}
Returns the highest angular-momentum present in the basis set.

\subsubsection{{\tt bas\_numbf}}
\begin{verbatim}
  logical function bas_numbf(basis,nbf)
  integer basis   ! [input] basis set handle         
  integer nbf     ! [output] number of basis functions
\end{verbatim}
Returns the total number of functions in the basis set.

\subsubsection{{\tt bas\_name}}
\begin{verbatim}
  logical function bas_name(basis,basis_name,trans_name)
  integer       basis    ! [input] basis set handle
  character*(*) basis_name ! [output] symbolic basis name
  character*(*) trans_name ! [output] actual/translated basis name
\end{verbatim}
Returns the name of the basis set.  The ``symbolic'' name used by the
program to load the basis is returned in {\tt name}.  If this name was
used to refer to another basis (i.e., indirection was used) then the
actual name of the basis is returned in {\tt trans} (i.e., the
translated name).  Otherwise {\tt trans} returns the same as name.

\subsubsection{{\tt bas\_numcont}}
\begin{verbatim}
  logical function bas_numcont(basis,numcont)
  integer basis     ! [input] basis set handle
  integer numcont   ! [output] total number of contractions
\end{verbatim}
Returns the total number of mapped general contractions (or shells)
for the given basis set.

\subsubsection{{\tt bas\_nbf\_cn\_max}}
\begin{verbatim}
  logical function bas_nbf_cn_max(basisin,nbf_max)
  integer basisin       ! [input] basis set handle
  integer nbf_max       ! [output] max(nbf in any contraction)
\end{verbatim}
Returns the maximum number of basis functions in any general contraction.

\subsubsection{{\tt bas\_nbf\_ce\_max}}
\begin{verbatim}
  logical function bas_nbf_ce_max(basisin,nbf_max)
  integer basisin       ! [input] basis set handle
  integer nbf_max       ! [output] max(nbf on any center)
\end{verbatim}
Returns the maximum number of basis functions on any single center.

\subsection{Mapping Between Centers, Shells/Contractions and Functions}

\subsubsection{{\tt bas\_cn2ce}}
\begin{verbatim}
  logical function bas_cn2ce(basis,cont,center)
  integer basis     ! [input] basis set handle
  integer cont      ! [input] mapped contraction index
  integer center    ! [output] center index
\end{verbatim}
Returns the center for a given mapped (as opposed to unique)
contraction.

\subsubsection{{\tt bas\_cn2bfr}}
\begin{verbatim}
  logical function bas_cn2bfr(basis,cont,ifirst,ilast)
  integer basis     ! [input] basis set handle
  integer cont      ! [input] mapped contraction index
  integer ifirst    ! [output] first basis function
  integer ilast     ! [output] last basis function     
\end{verbatim}
Returns the first basis function index of a mapped contraction in
{\tt ifirst} and the last basis function index in {\tt ilast}.

\subsubsection{{\tt bas\_ce2bfr}}
\begin{verbatim}
  logical function bas_ce2bfr(basis, icent, ibflo, ibfhi)
  integer basis             ! [input] handle
  integer icent             ! [input] no. of center
  integer ibflo, ibfhi      ! [output] range of functions on center
\end{verbatim}
Returns the range of basis functions on a given center.

\subsubsection{{\tt bas\_ce2cnr}}
\begin{verbatim}
  logical function bas_ce2cnr(basis,center,ifirst,ilast)
  integer basis    ! [input] basis set handle         
  integer center   ! [input] center index 
  integer ifirst   ! [output] first mapped contraction
  integer ilast    ! [output] last mapped contraction
\end{verbatim}
Returns the range of mapped contractions on a given center.

\subsubsection{{\tt bas\_bf2ce}}
\begin{verbatim}
  logical function bas_bf2ce(basis,testbf,center)
  integer basis   ! [input] basis set handle         
  integer testbf  ! [input] basis function index
  integer center  ! [output] center index
\end{verbatim}
Returns the center on which a basis function resides.

\subsubsection{{\tt bas\_bf2cn}}
\begin{verbatim}
  logical function bas_bf2cn(basis,testbf,cont)
  integer basis   ! [input] basis set handle         
  integer testbf  ! [input] basis function index
  integer cont    ! [output] mapped contraction index
\end{verbatim}
Returns the mapped contraction index that contains the given basis
function index.

\subsection{Printing Basis Sets}

\subsubsection{{\tt bas\_print}}
\begin{verbatim}
  logical function bas_print(basis)
  integer basis   ! [input] basis handle
\end{verbatim}
Prints the information about the basis set on unique centers.

\subsubsection{{\tt bas\_print\_all}}
\begin{verbatim}
  logical function bas_print_all()
\end{verbatim}
Debugging routine.  Prints (using \verb+bas_print+) information about
all active basis sets.

\subsubsection{{\tt gbs\_map\_print}}
\begin{verbatim}
  logical function gbs_map_print(basis)
  integer basis    ! [input] basis set handle
\end{verbatim}
Prints detailed information about the mapping of the unique basis set
information to the centers (using the geometry information).  Mostly
useful only for debugging.


\subsection{Miscellaneous Other Functions for Basis Sets}

The following subsections describe functions that can be used to
obtain detailed contraction information, exponents, coefficients,
and other information on a basis set.

\subsubsection{{\tt bas\_continfo}}
\begin{verbatim}
  logical function bas_continfo(basis,icont,
 &       type,nprimo,ngeno,sphcart)
  integer basis             ! [input] basis handle
  integer icont             ! [input] contraction index
  integer type              ! [output] type (sp/s/p/d/..)
  integer nprimo            ! [output] no. of primitives
  integer ngeno             ! [output] no. of contractions
  integer sphcart           ! [output] 0/1 for cartesian/spherical
\end{verbatim}
Returns information about the specified general contraction or shell.
Type is encoded so that the sequence {\em spd/sp/s/p/d/f\ldots} map
into -2/-1/0/1/2/3/\ldots.  The number of primitives is equivalent to
the number of exponents.  The number of contractions is the number of
radial functions to which the primitives are contracted, or equivalently,
the number of sets of coefficients.

\subsubsection{{\tt bas\_get\_exponent} and {\tt bas\_set\_exponent}}
\begin{verbatim}
  logical function bas_get_exponent(basis,icont,exp)
  integer basis           ! [input] basis set handle
  integer icont           ! [input] mapped contraction index
  double precision exp(*) ! [output] exponents

  logical function bas_set_exponent(basis,icont,exp,nexp) integer
  integer basis        ! [input] basis set handle
  integer icont        ! [input] mapped contraction index
  double precision exp ! [input] "new" exponents for contraction
  integer nexp         ! [input] number of new exponents
\end{verbatim}
Get/set the exponents associated with a contraction.  When setting the
exponents two points must be noted:
\begin{enumerate}
\item the number of new exponents must {\em exactly} match the number
  of old exponents, and
\item since internally exponents are only stored once for atoms of the
  same type, changes effect all atoms of the same type.
\end{enumerate}

\subsubsection{{\tt bas\_get\_coeff} and {\tt bas\_set\_coeff}}
\begin{verbatim}
  logical function bas_get_coeff(basis,icont,coeff)
  integer basis              ! [input] basis set handle
  integer icont              ! [input] mapped contraction index
  double precision coeff(*)  ! [output] mapped contraction coeffs.

  logical function bas_set_coeff(basis,icont,coeff,ncoeff)
  integer basis                   ! [input] basis set handle                   
  integer icont                   ! [input] mapped contraction index           
  integer ncoeff                  ! [input] number of coeffs.
  double precision coeff(ncoeff)  ! [input] "new" coeffs. 
\end{verbatim}
Get/set the contraction coefficients associated with a generally
contracted function.  The coefficients are stored as if the array was
declared as {\tt coeff(nprim,ngen)} where {\tt nprim} is the number of
primitive and {\tt ngen} is the number of sets of coefficients.  When
setting the coefficients two points must be noted:
\begin{enumerate}
\item the number of new coefficients must {\em exactly} match the
  number of old coefficients (i.e., {\tt ncoeff} = {\tt nprim*ngen}, and
\item since internally coefficients are only stored once for atoms of the
  same type, changes effect all atoms of the same type.
\end{enumerate}

\subsection{Other --- unique contraction information and adding
centers}

Routines exist to do all of this stuff, however, it is not anticipated
that this functionality is necessary outside of existing input
routines.  Exceptions might include automatic creation of fitting
basis sets or automatic optimization of an existing basis set.
Rather than confuse most users by documenting this ``private
interface'', anyone seeking additional functionality should contact
Rick or Robert --- the interface you want is probably there.