Functions available in the library LIBIWL

Documentation created by
C. David Sherrill, October 1995

Updates:
T. Daniel Crawford, December 1995
C. David Sherrill, April 1998

This documentation is now superceded by the automatically generated
doxygen documentation.  
=====================================================================

The library LIBIWL contains functions for reading and writing to files
with the "Integrals With Labels" (IWL) format created by David
Sherrill in 1994, modeled after the format of FILE34.  Most functions
deal with four-index quantitites, but there are also a few which deal
with two-index quantities such as one-electron integrals.  The IWL
format specifies that the 4-index quantities are stored on disk in
several buffers; each buffer has a header segment which gives some
useful info.  Currently, the header is arranged as follows: one
integer word is used as a flag, telling whether the current buffer is
the last buffer in the file.  The next integer gives the number of
integrals (and their associated labels) in the current buffer.  After
this header information, each buffer contains two data segments: one
for labels, and one for the values of the associated integrals.  The
datasize for the labels is defined using typedefs, so it is easy to
change (currently, it is a short int); likewise for the integral
values (currently of type double).  The length of these data segments
is NBUF * 4 * sizeof(Label) and NBUF * sizeof(Value), respectively.
The current use of short ints for Label is really somewhat excessive,
making the files somewhat larger than strictly necessary.  However,
this avoids confusing bit-packing schemes, and instantly allows us to
have up to something like 65,536 basis functions addressable.

Only the most useful few functions are documented at this time.  Other
functions are still experimental and/or of limited use to most PSI
programmers.

=====================================================================
IWL_BUF_INIT

   This function prepares a PSI Buffer according to the IWL format
for reading or writing.  Important to set readflag=1 if opening for 
reading, since other IWL buffer read routines anticipate that there
is already data in the buffer.

void iwl_buf_init(struct iwlbuf *Buf, int intape, double cutoff,
      int readflag)

Parameters:
   Buf      = pointer to IWL buffer
   intape   = file number of binary file to open
   cutoff   = ignore integrals with values below this number
   readflag = set to 1 for reading, and the buffer in memory will  
              be filled with the first buffer of the data in the 
              disk file

Returns:
   none


=====================================================================
IWL_RDONE

   Read one electron ints from the given file.  Assumes that all 
one-electron integrals will fit in core.  The arguments nfzc and nfzv
allow the filtering out of frozen core or frozen virtual orbitals
which will be on disk but may not be desired in core.

void iwl_rdone(int itap, int nbstri, double *onel_ints, double *e_fzc,
      int erase)

Parameters:
   itap       = tape to read ints from
   ints       = buffer (already allocated) to store the integrals
   e_fzc      = pointer to hold the frozen core energy
   ioff       = standard offset array
   norbs      = number of molecular orbitals
   nfzc       = number of frozen core orbs...set to 0 if all ints desired
   nfzv       = number of frozen virt orbs...set to 0 if all ints desired
   erase      = erase itap (1=yes, 0=no)
   printflg   = printing flag.  Set to 1 to print ints; otherwise, set to 0
   outfile    = file pointer for output of ints or error messages

Returns:
   1 if reading was successful, 0 otherwise

Notes: This function takes care of opening and closing the file 
'itap'.  It is not necessary to call iwl_buf_init() etc.


=====================================================================
IWL_RDTWO

   Read two electron ints from the given file.  Assumes that all 
two-electron integrals will fit in core.  The arguments nfzc and nfzv
allow the filtering out of frozen core or frozen virtual orbitals
which may be on disk but are not desired in core.  This is useful
for gradient or MCSCF calculations, where all some frozen orbital 
integrals are required to form the Lagrangian.

void iwl_rdtwo(int itap, double *ints, int *ioff, 
      int norbs, int nfzc, int nfzv, int printflg, FILE *outfile)

Arguments:
   itap     = unit to write to
   ints     = two electron integrals (already allocated)
   ioff     = the old ioff array for lexical ordering
   norbs    = total number of molecular orbitals
   nfzc     = number of frozen core orbitals to be filtered out when reading
   nfzv     = number of frozen virtual orbs to be filtered out when reading
   printflg = print integrals as they're read
   outfile  = output file pointer

Returns:
   none

Notes: This function takes care of opening and closing the file 
'itap'.  It is not necessary to call iwl_buf_init() etc.


=====================================================================

IWL_BUF_CLOSE

   Close an IWL buffer previously opened with iwl_buf_init.
   
void iwl_buf_close(struct iwlbuf *Buf, int keep)

Arguments:
   Buf      = pointer to IWL buffer
   keep     = keep the file?

Returns:
   none


=====================================================================

IWL_BUF_RD

   Read from an IWL buffer.

int iwl_buf_rd(struct iwlbuf *Buf, int target_pq, double *ints,
      int *ioff_lt, int *ioff_rt, int mp2, int printflg, FILE *outfile)

Arguments:
   Buf       = pointer to IWL buffer
   target_pq = the target bra-canonical index desired
   ints      = the destination array for data read
   ioff_lt   = the offset array for the bra indices
   ioff_rt   = the offset array for the ket indices
   mp2       = flag for mp2 calculations only
   printflg  = print the read data with indices
   outfile   = the output text file

Returns:
   0         = all is well
   1         = all is probably not well


=====================================================================
