Functions for reading information from the checkpoint file

This section gives an overview of many of the most widely used functions from libchkpt.a. For more details and descriptions of newer functions that are not yet described here, see the doxygen generated documentation at
http://www.psicode.org/doc/libs/doxygen/html.

Functions that return char*

char *chkpt_rd_corr_lab()
Reads in a label from the checkpoint file which describes the wavefunction used to get the correlated energy which is stored in the checkpoint file (see chkpt_rd_ecorr()).

Arguments:	takes no arguments.
Returns:	a string, like "CISD", or "MCSCF" or some other wavefunction designation.

char *chkpt_rd_label()
Reads the main the checkpoint file label.

Arguments:	takes no arguments.
Returns:	calculation label.

char *chkpt_rd_sym_label()
Reads the label for the point group.

Arguments:	takes no arguments.
Returns:	point group label.

Functions that return char**

char **chkpt_rd_irr_labs()
Read in the symmetry labels for all irreps in the point group in which the molecule is considered.

Arguments:	takes no arguments.
Returns:	an array of labels (strings) which denote the irreps for the point group in which the molecule is considered, _regardless_ of whether there exist any symmetry orbitals which transform as that irrep.

char **chkpt_rd_hfsym_labs()
Read in the symmetry labels only for those irreps which have basis functions.

Arguments:	takes no arguments.
Returns:	an array of labels (strings) which denote the irreps which have basis functions (in Cotton ordering). For DZ or STO-3G water, for example, in $C_{\rm 2v}$ symmetry, this would be an array of three labels: "A1", "B1", and "B2".

Functions that return int

int chkpt_rd_iopen()
Reads in the dimensionality (up to a sign) of ALPHA and BETA vectors of two-electron coupling coefficients for open shells (see chkpt_rd_ccvecs()). Note : iopen = MM * (MM + 1), where MM is the total number of irreps containing singly occupied orbitals.

Arguments:	takes no arguments.
Returns:	the +/- dimensionality of ALPHA and BETA vectors of coupling coefficients for open shells.

int chkpt_rd_max_am()
Reads in the maximum orbital quantum number of AOs in the basis.

Arguments:	takes no arguments.
Returns:	the maximum orbital quantum number of AOs in the basis.

int chkpt_rd_mxcoef()
Reads the value of the constant mxcoef.

Arguments:	takes no arguments.
Returns:	the sum of the squares of the number of symmetry orbitals for each irrep. This gives the number of elements in the non-zero symmetry blocks of the SCF eigenvector. For STO-3G water mxcoef $= (4*4) + (0*0) + (1*1) + (2*2) = 21$.

int chkpt_rd_nao()
Reads in the total number of atomic orbitals (read: Cartesian Gaussian functions).

Arguments:	takes no arguments.
Returns:	total number of atomic orbitals.

int chkpt_rd_natom()
Reads in the total number of atoms.

Arguments:	takes no arguments.
Returns:	total number of atoms.

int chkpt_rd_ncalcs()
Reads in the total number of calculations in the checkpoint file (was always 1 in old libfile30.a, probably still is for now).

Arguments:	takes no arguments.
Returns:	total number of calculations in the checkpoint file.

int chkpt_rd_nirreps()
Reads in the total number of irreducible representations in the point group in which the molecule is being considered.

Arguments:	takes no arguments.
Returns:	total number of irreducible representations.

int chkpt_rd_nmo()
Reads in the total number of molecular orbitals (may be different from the number of basis functions).

Arguments:	takes no arguments.
Returns:	total number of molecular orbitals.

int chkpt_rd_nprim()
Reads in the total number of primitive Gaussian functions (only primitives of _symmetry independent_ atoms are counted!).

Arguments:	takes no arguments.
Returns:	total number of primitive Gaussian functions.

int chkpt_rd_nshell()
Reads in the total number of shells. For example, DZP basis set for carbon atom (contraction scheme $[9s5p1d/4s2p1d]$) has a total of 15 basis functions, 15 primitives, and 7 shells. Shells of _all_ atoms are counted (not only of the symmetry independent; compare chkpt_rd_nprim).

Arguments:	takes no arguments.
Returns:	total number of shells.

int chkpt_rd_nso()
Reads in the total number of symmetry-adapted basis functions (read: Cartesian or Spherical Harmonic Gaussians).

Arguments:	takes no arguments.
Returns:	total number of SOs.

int chkpt_rd_nsymhf()
Reads in the total number of irreps in the point group in which the molecule is being considered which have non-zero number of basis functions. For STO-3G or DZ water, for example, this is three, even though nirreps is 4 (compare int chkpt_rd_nirreps()).

Arguments:	takes no arguments.
Returns:	total number of irreducible representations with a non-zero number of basis functions.

int chkpt_rd_num_unique_atom()
Reads in the number of symmetry unique atoms.

Arguments:	takes no arguments.
Returns:	number of symmetry unique atoms.

int chkpt_rd_num_unique_shell()
Reads in the number of symmetry unique shells.

Arguments:	takes no arguments.
Returns:	number of symmetry unique shells.

int chkpt_rd_phase_check()
Reads the phase flag, which is 1 if the orbital phases have been checked and is 0 otherwise (phase checking just helps ensure the arbitrary phases of the orbitals are consistent from one geometry to the next, which helps various guessing or extrapolation schemes).

Arguments:	takes no arguments.
Returns:	flag.

int chkpt_rd_ref()
Reads the reference type from the flag in the checkpoint file. 0 = RHF, 1 = UHF, 2 = ROHF, 3 = TCSCF.

Arguments:	takes no arguments.
Returns:	flag indicating the reference.

int chkpt_rd_rottype()
Reads the rigid rotor type the molecule represents. 0 = asymmetric, 1 = symmetric, 2 = spherical, 3 = linear, 6 = atom.

Arguments:	takes no arguments.
Returns:	rigid rotor type.

Functions that return int*

int *chkpt_rd_am2canon_shell_order()
Reads in the the mapping array from the angmom-ordered to the canonical (in the order of appearance) list of shells.

Arguments:	takes no arguments.
Returns:	an array nshell long that maps shells from the angmom-ordered to the canonical (in the order of appearance) order.

chkpt_rd_atom_position()
Reads in symmetry positions of atoms. Allowed values are as follows:

• 1 - atom in a general position
• 2 - atom on the c2z axis
• 4 - atom on the c2y axis
• 8 - atom on the c2x axis
• 16 - atom in the inversion center
• 32 - atom in the sigma_xy plane
• 64 - atom in the sigma_xz plane
• 128 - atom in the sigma_yz plane

This data is sufficient to define stabilizers of the nuclei.

Arguments:	takes no arguments.
Returns:	an array of symmetry positions of atoms.

int *chkpt_rd_clsdpi()
Reads in an array which has an element for each irrep of the point group of the molecule (n.b. not just the ones with a non-zero number of basis functions). Each element contains the number of doubly occupied MOs for that irrep.

Arguments:	takes no arguments.
Returns:	the number of doubly occupied MOs per irrep.

int *chkpt_rd_openpi()
Reads in an array which has an element for each irrep of the point group of the molecule (n.b. not just the ones with a non-zero number of basis functions). Each element contains the number of singly occupied MOs for that irrep.

Arguments:	takes no arguments.
Returns:	the number of singly occupied MOs per irrep.

int *chkpt_rd_orbspi()
Reads in the number of MOs in each irrep.

Arguments:	takes no arguments.
Returns:	the number of MOs in each irrep.

int *chkpt_rd_shells_per_am()
Reads in the number of shells in each angmom block.

Arguments:	takes no arguments.
Returns:	the number of shells in each angmom block.

chkpt_rd_sloc()
Read in an array of pointers to the first AO from each shell.

Arguments:	takes no arguments.
Returns:	Read in an array nshell long of pointers to the first AO from each shell.

chkpt_rd_sloc_new()
Read in an array of pointers to the first basis function (not AO as chkpt_rd_sloc does) from each shell.

Arguments:	takes no arguments.
Returns:	an array nshell long of pointers to the first basis function from each shell.

int *chkpt_rd_snuc()
Reads in an array of pointers to the nuclei on which shells are centered.

Arguments:	takes no arguments.
Returns:	an array nshell long of pointers to the nuclei on which shells are centered.

int *chkpt_rd_snumg()
Reads in array of the numbers of the primitive Gaussians in the shells.

Arguments:	takes no arguments.
Returns:	an array nshell long of the numbers of the primitive Gaussians in shells.

int *chkpt_rd_sprim()
Reads in pointers to the first primitive from each shell.

Arguments:	takes no arguments.
Returns:	an array nshell long of pointers to the first primitive from each shells.

chkpt_rd_sopi()
Read in the number of symmetry-adapted basis functions in each symmetry block.

Arguments:	takes no arguments.
Returns:	an array nirreps long of the numbers of symmetry orbitals in symmetry blocks.

int *chkpt_rd_stype()
Reads in angular momentum numbers of the shells.

Arguments:	takes no arguments.
Returns:	Returns an array nshell long of the angular momentum numbers of the shells.

int *chkpt_rd_symoper()
Read in the mapping array between "canonical" ordering of the symmetry operations of the point group and the one defined in symmetry.h.

Arguments:	takes no arguments.
Returns:	a mapping array nirrep long

int *chkpt_rd_ua2a()
Read in the mapping array from the symmetry-unique atom list to the full atom list.

Arguments:	takes no arguments.
Returns:	a mapping array num_unique_atom long

int *chkpt_rd_us2s()
Read in the mapping array from the symmetry-unique shell list to the full shell list.

Arguments:	takes no arguments.
Returns:	a mapping array num_unique_shell long

Functions that return int**

int **chkpt_rd_ict()
Reads the transformation properties of the nuclei under the operations allowed for the particular symmetry point group in which the molecule is considered.

Arguments:	takes no arguments.
Returns:	a matrix of integers. Each row corresponds to a particular symmetry operation, while each column corresponds to a particular atom. The value of ict[2][1], then, should be interpreted in the following manner: application of the third symmetry operation of the relavant point group, the second atom is placed in the location originally occupied by the atom number ict[2][1].

int **chkpt_rd_shell_transm()
Reads in the transformation matrix for the shells. Each row of the matrix is the orbit of the shell under symmetry operations of the point group.

Arguments:	takes no arguments.
Returns:	a matrix of nshell*nirreps integers.

Functions that return double

double chkpt_rd_ecorr()
Reads in the correlation energy stored in the checkpoint file. To get some information (a label) on the type of correlated wavefunction used to get this energy, see chkpt_rd_corr_lab().

Arguments:	takes no arguments.
Returns:	the correlation energy.

double chkpt_rd_enuc()
Reads in the nuclear repulsion energy

Arguments:	takes no arguments.
Returns:	the nuclear repulsion energy.

double chkpt_rd_eref()
Reads in the reference energy (may be different from HF energy).

Arguments:	takes no arguments.
Returns:	the reference energy.

double chkpt_rd_escf()
Reads in the SCF HF energy.

Arguments:	takes no arguments.
Returns:	the SCF HF energy.

double chkpt_rd_etot()
The total energy, be it HF, CISD, CCSD, or whatever! This is the preferred function to use for geometry optimization via energies, printing energies in analysis, etc., since this value is valid whatever the calculation type.

Arguments:	takes no arguments.
Returns:	The total energy.

Functions that return double*

double *chkpt_rd_evals()
double *chkpt_rd_alpha_evals()
double *chkpt_rd_beta_evals()
Reads in the (spin-restricted HF, $\alpha$ UHF, and $\beta$ UHF) eigenvalues: the orbital energies.

Arguments:	take no arguments.
Returns:	an array of _all_ of the SCF eigenvalues, ordered by irrep, and by increasing energy within each irrep. (i.e. for STO-3G water, the four $a_1$ eigenvalues all come first, and those four are ordered from lowest energy to highest energy, followed by the single $b_1$ eigenvalue, etc. -- Pitzer ordering)

double *chkpt_rd_exps()
Reads in the exponents of the primitive Gaussian functions.

Arguments:	takes no arguments.
Returns:	an array of doubles.

double *chkpt_rd_zvals()
Reads in nuclear charges.

Arguments:	takes no arguments.
Returns:	an array natom long of nuclear charges (as doubles).

Functions that return double**

double **chkpt_rd_blk_scf(int irrep)
double **chkpt_rd_alpha_blk_scf(int irrep)
double **chkpt_rd_beta_blk_scf(int irrep)
Reads in a symmetry block of the (RHF, $\alpha$ UHF, $\beta$ UHF) eigenvector.

Arguments:	int irrep, designates the desired symmetry block
Returns:	a square matrix has orbspi[irrep] rows. The eigenvectors are stored with the column index denoting MOs and the row index denoting SOs: this means that scf_vector[i][j] is the contribution of the $i$th SO to the $j$th MO.

double **chkpt_rd_ccvecs()
Reads in a matrix rows of which are ALPHA (ccvecs[0]) and BETA (ccvecs[1]) matrices of coupling coefficients for open shells stored in lower triangular form. Coupling coefficients are defined NOT as in C.C.J.Roothaan Rev. Mod. Phys. 32, 179 (1960) as it is stated in the manual pages for CSCF, but according to Pitzer (no reference yet) and are **different** from those in Yamaguchi, Osamura, Goddard, and Schaefer's book "Analytic Derivative Methods in Ab Initio Molecular Electronic Structure Theory".
The relationship between the Pitzer's and Yamaguchi's conventions is as follows : ALPHA = 1-2*a , BETA = 1+4*b , where a and b are alpha's and beta's for open shells defined on pp. 69-70 of Dr. Yamaguchi's book.

Arguments:	takes no arguments.
Returns:	double **ccvecs, a matrix 2 by abs(iopen) rows of which are coupling coefficient matrices for open-shells in packed form. For definition of iopen see chkpt_rd_iopen().

chkpt_rd_contr_full()
Reads in the normalized contraction coefficients.

Arguments:	takes no arguments.
Returns:	a matrix MAXANGMOM (a constant defined in ???) by the total number of primitives nprim; each primitive Gaussian contributes to only one shell (and one basis function, of course), so most of these values are zero.

double **chkpt_rd_geom()
Reads in the cartesian geometry.

Arguments:	takes no arguments.
Returns:	The cartesian geometry is returned as a matrix of doubles. The row index is the atomic index, and the column is the cartesian direction index (x=0, y=1, z=2). Therefore, geom[2][0] would be the x-coordinate of the third atom.

chkpt_rd_lagr()
chkpt_rd_alpha_lagr()
chkpt_rd_beta_lagr()
Reads in an (RHF, $\alpha$ UHF, $\beta$ UHF) Lagrangian matrix in MO basis.

Arguments:	takes no arguments.
Returns:	a matrix nmo by nmo.

double **chkpt_rd_scf()
double **chkpt_rd_alpha_scf()
double **chkpt_rd_beta_scf()
Reads in the (RHF, $\alpha$ UHF, $\beta$ UHF) eigenvector.

Arguments:	takes no arguments.
Returns:	a square matrix of dimensions nmo by nmo (see: chkpt_rd_nmo()). The symmetry blocks of the SCF vector appear on the diagonal of this matrix.

chkpt_rd_schwartz()
Reads in the table of maxima of Schwartz integrals (ij|ij) for each shell doublet.

Arguments:	takes no arguments.
Returns:	NULL if no table is present in the checkpoint file, a matrix nshell by nshell otherwise.

chkpt_rd_usotao_new()
Reads in an AO to SO transformation matrix.

Arguments:	takes no arguments.
Returns:	a nso by nao matrix of doubles.

chkpt_rd_usotbf()
Reads in a basis function to SO transformation matrix.

Arguments:	takes no arguments.
Returns:	a nso by nso matrix of doubles.

Functions that return struct *z_entry

The z-matrix is read from the checkpoint file as an array of z_entry structs which are declared in chkpt.h. This structure contains the reference atom, an optimization flag, the coordinate value, and any label used for each internal coordinate. When not applicable (such as the first few lines of a z-matrix) atom variables are given values of -1, opt variables are given values of -1, val variables are given values of -999.9, and label strings are left empty.

chkpt_rd_zmat()
Reads in the z-matrix

Arguments:	takes no arguments.
Returns:	struct *z_entry natom long.