libciomr: The PSI I/O and Math Library

Files
file	add_arr.cc
	Add two arrays.
file	add_mat.cc
	Add two matrices.
file	lib/libciomr/block_matrix.cc
	Allocate a blocked (memory-contiguous) 2D matrix of doubles.
file	lib/libciomr/dot.cc
	Take dot product between two matrices.
file	eigout.cc
	Print eigenvectors and eigenvalues.
file	eigsort.cc
	Sort eigenvalues and eigenvectors in ascending or descending order.
file	eivout.cc
	Print eigenvectors and eigenvalues to output file.
file	ffile.cc
	Open PSI ASCII or small local binary (non-libpsio) files for reading/writing.
file	flin.cc
	Linear equation solver for A * x = b.
file	fndcor.cc
	Get the amount of core memory available from input.
file	init_matrix.cc
	Initialize a matrix of doubles.
file	int_array.cc
	This file includes the integer versions of several psi routines for handling arrays and matrices of doubles.
file	mmult.cc
	Multiply two matrices (superceded by C_DGEMM).
file	mxmb.cc
	Wrapper for the mmult function.
file	print_array.cc
	Print a lower-triangle array of doubles.
file	print_mat.cc
	Print a matrix of doubles.
file	lib/libciomr/psi_start.cc
	Initialize input, output, file prefix, etc.
file	lib/libciomr/psi_stop.cc
	Close input and output, stop input parser.
file	rsp.cc
	Diagonalize a symmetric matrix in packed (lower triangular) form.
file	sq_rsp.cc
	Diagnoalize a symmetrix square matrix.
file	sq_to_tri.cc
	Convert square matrix to lower triangle packing.
file	tqli.cc
	Diagonalizes a tridiagonal matrix output by tred2.
file	tred2.cc
	Converts a symmetric matrix to tridiagonal form for use in tqli.
file	tri_to_sq.cc
	Converts lower triangle to square matrix.
file	tstart.cc
	Controls starting and stopping of timers.
file	zero.cc
	Zero arrays or matrices of doubles.
file	set_memory.cc
	Get the amount of core memory available from input.
Functions
void	psi::add_arr (double *a, double *b, double *c, int n)
void	psi::add_mat (double **a, double **b, double **c, int n, int m)
double **	psi::block_matrix (unsigned long int n, unsigned long int m)
void	psi::free_block (double **array)
double	psi::dot_mat (double **a, double **b, int n)
void	psi::dot_arr (double *a, double *b, int n, double *value)
void	psi::eigout (double **a, double *b, double *c, int m, int n, FILE *out)
void	psi::eigsort (double *d, double **v, int n)
void	psi::mosort (double *d, double **v, int *sym, int nso, int nmo)
void	psi::eivout (double **a, double *b, int m, int n, FILE *out)
void	psi::ffile (FILE **fptr, char *suffix, int code)
void	psi::ffile_noexit (FILE **fptr, char *suffix, int code)
void	psi::ffileb (FILE **fptr, char *suffix, int code)
void	psi::ffileb_noexit (FILE **fptr, char *suffix, int code)
void	psi::flin (double **a, double *b, int in, int im, double *det)
void	psi::fndcor (long int *maxcrb, FILE *infile, FILE *outfile)
double *	psi::init_array (unsigned long int size)
double **	psi::init_matrix (unsigned long int n, unsigned long int m)
void	psi::free_matrix (double **array, unsigned long int size)
int *	psi::init_int_array (int size)
void	psi::zero_int_array (int *a, int size)
int **	psi::init_int_matrix (int rows, int cols)
void	psi::free_int_matrix (int **array)
void	psi::zero_int_matrix (int **array, int rows, int cols)
void	psi::print_int_mat (int **a, int m, int n, FILE *out)
void	psi::mmult (double **AF, int ta, double **BF, int tb, double **CF, int tc, int nr, int nl, int nc, int add)
void	psi::mxmb (double **a, int ia, int ja, double **b, int ib, int jb, double **c, int ic, int jc, int nrow, int nlnk, int ncol)
void	psi::print_array (double *a, int m, FILE *out)
void	psi::print_mat (double **a, int rows, int cols, FILE *out)
int	psi::psi_start (FILE **infile, FILE **outfile, char **psi_file_prefix, int argc, char *argv[], int overwrite_output)
char *	psi::psi_ifname ()
char *	psi::psi_ofname ()
char *	psi::psi_fprefix ()
int	psi::psi_stop (FILE *infile, FILE *outfile, char *psi_file_prefix)
void	psi::rsp (int nm, int n, int nv, double *array, double *evals, int matz, double **evecs, double toler)
void	psi::sq_rsp (int nm, int n, double **array, double *evals, int matz, double **evecs, double toler)
void	psi::sq_to_tri (double **bmat, double *amat, int size)
void	psi::tqli (int n, double *d, double **z, double *e, int matz, double toler)
void	psi::tred2 (int n, double **a, double *d, double *e, int matz)
void	psi::tri_to_sq (double *amat, double **bmat, int size)
void	psi::tstart ()
void	psi::tstop ()
void	psi::zero_arr (double *a, int size)
void	psi::zero_mat (double **a, int rows, int cols)
int	psi::psi_start (int argc, char *argv[])

---

Detailed Description

---

Function Documentation

void psi::add_arr	(	double *	a,
		double *	b,
		double *	c,
		int	n
	)

add_arr(): Add arrays a and b and put the result in array c. Adds the first n elements

Parameters:

	a	= first array to add
	b	= second array to add
	c	= array to hold the result of a+b
	n	= number of elements to add

Returns: none

void psi::add_mat	(	double **	a,
		double **	b,
		double **	c,
		int	n,
		int	m
	)

add_mat(): Add matrices a and b into c for n rows and m columns

Parameters:

	a	= double star pointer to first matrix to add
	b	= double star pointer to second matrix to add
	c	= double star pointer to matrix to hold the result of a+b
	n	= number of rows in a,b,c
	m	= number of columns in a,b,c

double ** psi::block_matrix	(	unsigned long int	n,
		unsigned long int	m
	)

block_matrix(): Allocate a 2D array of doubles using contiguous memory

Allocates a contiguous block of memory for an array of doubles, allocates an array of pointers to the beginning of each row and returns the pointer to the first row pointer. This allows transparent 2d-array style access, but keeps memory together such that the matrix could be used in conjunction with FORTRAN matrix routines.

Allocates memory for an n x m matrix and returns a pointer to the first row.

Parameters:

	n	= number of rows (unsigned long to allow large matrices)
	m	= number of columns (unsigned long to allow large matrices)

Returns: double star pointer to newly allocated matrix

T. Daniel Crawford Sometime in 1994

Based on init_matrix() from libciomr

void psi::dot_arr	(	double *	a,
		double *	b,
		int	n,
		double *	value
	)

dot_arr(): Take the dot product of the first n elements of two arrays a and b and return the result

Parameters:

	a	= first array to take dot product of
	b	= second array to take dot product of
	n	= number of elements in array
	value	= pointer to hold dot product result

Returns: none

double psi::dot_mat	(	double **	a,
		double **	b,
		int	n
	)

dot_mat(): Takes the dot product between two 2D matrices a and b with dimensions n x n and returns the value

Parameters:

	a	= first matrix for dot product
	b	= second matrix for dot product
	n	= number of rows/columns for matrices a and b

Returns: value of dot product

void psi::eigout	(	double **	a,
		double *	b,
		double *	c,
		int	m,
		int	n,
		FILE *	out
	)

eigout(): Print out eigenvectors and eigenvalues.

Prints an n x m matrix of eigenvectors. Under each eigenvector, the corresponding elements of two arrays, b and c, will also be printed. This is useful for printing, for example, the SCF eigenvectors with their associated eigenvalues (orbital energies) and also the population.

Parameters:

	a	= matrix of eigenvectors (eigenvectors are columns)
	b	= first array to print under eigenvectors (e.g., eigenvalues)
	c	= second array to print under eigenvectors (e.g., populations)
	m	= number of rows in matrix a
	n	= number of columns in matrix a (and length of b and c)
	out	= file pointer for output

Returns: none

void psi::eigsort	(	double *	d,
		double **	v,
		int	n
	)

eigsort(): Sort the eigenvalues in d and eigenvectors in v in ascending (n>0) or descending (n<0) order. abs(n) is the number of eigenvalues.

Parameters:

	d	= array of eigenvalues
	v	= matrix of eigenvectors (each column is an eigenvector) Note: seems to assume v is a square matrix, could be a problem if, e.g., nmo != nso.
	n	= abs(n) is the number of eigenvalues/cols of v. Use n>0 to sort in ascending order, n<0 to sort in descending order

Returns: none

void psi::eivout	(	double **	a,
		double *	b,
		int	m,
		int	n,
		FILE *	out
	)

eivout: Print out eigenvectors and eigenvalues to the output file

Parameters:

	a	= eigenvectors
	b	= eigenvalues
	m	= rows of a
	n	= columns of a
	out	= output file pointer

Returns: none

void psi::ffile	(	FILE **	fptr,
		char *	suffix,
		int	code
	)

ffile(): Open a PSI3 ASCII file for reading/writing. Returns a pointer to the new file.

Parameters:

	suffix	= name of the file, not including automatic prefix
	code	= 0 (write), 1 (write/append), 2 (read)

Returns: none

void psi::ffile_noexit	(	FILE **	fptr,
		char *	suffix,
		int	code
	)

ffile_noexit(): Open a PSI3 ASCII file for reading/writing. Returns a pointer to the new file via an argument. This function is the same as ffile(), but will not exit if fopen() fails.

Parameters:

	suffix	= name of the file, not including automatic prefix
	code	= 0 (write), 1 (write/append), 2 (read)

Returns: none

void psi::ffileb	(	FILE **	fptr,
		char *	suffix,
		int	code
	)

ffileb(): Open a PSI3 binary file for reading/writing. Returns a pointer to the new file.

Parameters:

	suffix	= name of the file, not including automatic prefix
	code	= 0 (write), 1 (write/append), 2 (read)

Returns: none

void psi::ffileb_noexit	(	FILE **	fptr,
		char *	suffix,
		int	code
	)

ffileb_noexit(): Open a PSI3 binary file for reading/writing. Returns a pointer to the new file via an argument. This function is the same as ffileb(), but will not exit if fopen() fails.

Parameters:

	suffix	= name of the file, not including automatic prefix
	code	= 0 (write), 1 (write/append), 2 (read)

Returns: none

void psi::flin	(	double **	a,
		double *	b,
		int	in,
		int	im,
		double *	det
	)

flin(): solves linear equations A * x = b.

Parameters:

	a	= coefficient matrix
	b	= known vectors
	in	= dimension of a(in*in)
	im	= number of b vectors
	det	= pointer to hold determinant of matrix a

Returns: none

void psi::fndcor	(	long int *	maxcrb,
		FILE *	infile,
		FILE *	outfile
	)

fndcor(): C translation of the Fortran version, to remove the need to link the library alloc, which also requires the linking of libparse, etc, etc...

This routine looks for the MEMORY keyword from input

Parameters:

	maxcrb	= long int ptr to hold size of maxcore in bytes
	infile	= file pointer to input file (eg input.dat)
	outfile	= file pointer to output file (eg output.dat)

Returns: none

David Sherrill, February 1994 Revised to handle more than 2GB of memory by Ed Valeev, October 2000

Revised to return the default if memory keyword is missing and raised the default to 256 MB. TDC, January 2003

void psi::free_block

(

double **

array

)

free_block(): Free a block matrix

Parameters:

array

= pointer to matrix to be freed

Returns: none

void psi::free_int_matrix

(

int **

array

)

free_int_matrix(): Free a matrix of integers. Pass a pointer to the matrix.

Parameters:

array

= pointer to integer matrix

void psi::free_matrix	(	double **	array,
		unsigned long int	size
	)

free_matrix(): Free a 2D matrix allocated with init_matrix().

Parameters:

	array	= matrix to free
	size	= number of rows (unsigned long to allow large matrices)

Returns: none

double * psi::init_array

(

unsigned long int

size

)

init_array(): This function initializes an array of doubles of length 'size' and returns a pointer to the first element

Parameters:

size

= length of array (unsigned long to allow large arrays)

Returns: pointer to new array

int * psi::init_int_array

(

int

size

)

init_int_array(): Allocates memory for one-D array of ints of dimension 'size' and returns pointer to 1st element. Zeroes all elements.

Just modified the init_array() routine to do int's instead. This will avoid the temptation to allocate 5 integers by p = (int *) init_array(5/2), which is bad.

Parameters:

size

= length of array to allocate

Returns: pointer to new array

C. David Sherrill

int ** psi::init_int_matrix	(	int	rows,
		int	cols
	)

init_int_matrix(): Function initializes (allocates and clears) a matrix of integers with dimensions 'rows' by 'cols' and returns a pointer to it (ptr to first row ptr). The matrix layout is blocked, i.e. like produced by block_matrix()

Parameters:

	rows	= number of rows
	cols	= number of columns

Returns: pointer to first row of newly-allocated integer block matrix

double ** psi::init_matrix	(	unsigned long int	n,
		unsigned long int	m
	)

init_matrix(): Initialize an nxm matrix of doubles and return a pointer to the first row. Note that this does not form a matrix which is necessarily contiguous in memory. Use block_matrix() for that.

Parameters:

	n	= number of rows (unsigned long to allow large matrices)
	m	= number of columns (unsigned long to allow large matrices)

Returns: pointer to first row

void psi::mmult	(	double **	AF,
		int	ta,
		double **	BF,
		int	tb,
		double **	CF,
		int	tc,
		int	nr,
		int	nl,
		int	nc,
		int	add
	)

mmult(): a reasonably fast matrix multiply (at least on the DEC3100) written by ETS

Parameters:

	AF	= first matrix to multiply
	ta	= if 1, transpose AF before multiplying; otherwise, 0
	BF	= second matrix to multiply
	tb	= if 1, transpose BF before multiplying; otherwise 0
	CF	= matrix to hold result of AF*BF
	tc	= if 1, transpose CF after the multiplication; otherwise 0
	nr	= number of rows of AF
	nl	= number of cols of AF and rows of BF
	nc	= number of cols of BF
	add	= if 1, add AF*BF to the matrix passed in as CF; else 0

Returns: none

nr,nl,nc are the number of rows,links,and columns in the final matrices to be multiplied together if ta=0 AF should have the dimensions nr x nl if ta=1 AF should have the dimensions nl x nr if tb=0 BF should have the dimensions nl x nc if tb=1 BF should have the dimensions nc x nl if tc=0 CF should have the dimensions nr x nc if tc=1 CF should have the dimensions nc x nr

void psi::mosort	(	double *	d,
		double **	v,
		int *	sym,
		int	nso,
		int	nmo
	)

mosort(): Minor modification of eigsort() to also sort a series of irrep labels.

Parameters:

	d	= array of eigenvalues
	v	= matrix of eigenvectors (each column is an eigenvector)
	sym	= array of symmetry ID's (irreps)
	nso	= number of rows in v
	nmo	= abs(nmo) is the number of eigenvalues/cols of v. Use nmo>0 to sort in ascending order, nmo<0 to sort in descending order

Returns:none

TDC, 6/03

void psi::mxmb	(	double **	a,
		int	ia,
		int	ja,
		double **	b,
		int	ib,
		int	jb,
		double **	c,
		int	ic,
		int	jc,
		int	nrow,
		int	nlnk,
		int	ncol
	)

mxmb: multiplies two rectangular matrices together (wrapper for mmult). Deprecated; use C_DGEMM instead.

Parameters:

	a	= first matrix to multiply
	ia	= if 1, normal multiplication of a
	ja	= if 1, transpose a before multiplication
	b	= second matrix to multiply
	ib	= if 1, normal multiplication of b
	jb	= if 1, transpose b before multiplication
	c	= matrix to store the result
	ic	= if 1, normal multiplication into c
	jb	= if 1, transpose c after multiplication
	nrow	= number of rows of a
	nlnk	= number of columns of a and rows of b
	ncol	= number of columns of b

Returns: none

void psi::print_array	(	double *	a,
		int	m,
		FILE *	out
	)

print_array(): Prints a lower-triangle of a symmetric matrix packed as an array of doubles.

Parameters:

	a	= array (packed lower triangle of matrix) to print
	m	= dimension of matrix (mxm)
	out	= file pointer for output

Returns: none

void psi::print_int_mat	(	int **	a,
		int	m,
		int	n,
		FILE *	out
	)

print_int_mat(): Print a matrix of integers. Pass the matrix, the number of rows and columns, and the output file pointer.

Parameters:

	a	= integer matrix to print
	m	= number of rows in matrix
	n	= number of columns in matrix
	out	= FILE pointer to output file

Returns: none

void psi::print_mat	(	double **	a,
		int	m,
		int	n,
		FILE *	out
	)

print_mat: Print a matrix a of dimensions mxn to file pointer out.

Parameters:

	a	= matrix to print
	m	= number of rows in matrix
	n	= number of columns in matrix
	out	= file pointer for output

Returns: none

char * psi::psi_fprefix

(

)

psi_fprefix()

This function returns the PSI file prefix

Arguments: none

Returns: the pointer to the string containing the PSI file prefix if it has been determined, NULL otherwise

char * psi::psi_ifname

(

)

psi_ifname()

This function returns the input file name

Arguments: none

Returns: the pointer to the string containing the input file name if it has been determined, NULL otherwise

char * psi::psi_ofname

(

)

psi_ofname()

This function returns the output file name

Arguments: none

Returns: the pointer to the string containing the output file name if it has been determined, NULL otherwise

int psi::psi_start	(	int	argc,
		char *	argv[]
	)

psi_start(): This function initializes the input, output files, file prefix, etc., by checking command line arguments and environmental variables. It also initializes the input parsing library.

Parameters:

	argc	= number of command-line arguments passed
	argv	= command-line arguments

Returns: one of standard PSI error codes

int psi::psi_start	(	FILE **	infile,
		FILE **	outfile,
		char **	psi_file_prefix,
		int	argc,
		char *	argv[],
		int	overwrite_output
	)

psi_start(): This function initializes the input, output files, file prefix, etc., by checking command line arguments and environmental variables. It also initializes the Input Parsing library.

Parameters:

	argc	= number of command-line arguments passed
	argv	= command-line arguments
	overwrite	= whether to overwrite output file (1) or append to it (0). Most PSI modules will want to append.

Returns: one of standard PSI error codes

int psi::psi_stop	(	FILE *	infile,
		FILE *	outfile,
		char *	psi_file_prefix
	)

psi_stop(): This function closes input and output files and deinitializes Input Parsing library.

Arguments: none

Returns: one of standard PSI error codes

void psi::rsp	(	int	nm,
		int	n,
		int	nv,
		double *	array,
		double *	e_vals,
		int	matz,
		double **	e_vecs,
		double	toler
	)

rsp(): diagonalize a symmetric matrix in packed (lower triangular) form in 'array'. For square symmetric matrices, see sq_rsp().

Parameters:

	nm	= rows of matrix
	n	= columns of matrix
	nv	= number of elements in lower triangle (n*(n+1)/2)
	array	= matrix to diagonalize (packed as linear array)
	e_vals	= array to hold eigenvalues
	matz	= 0 (no eigenvectors, eigenvals in ascending order) = 1 (eigenvectors and eigenvalues in ascending order) = 2 (no eigenvectors, eigenvalues in descending order) = 3 (eigenvectors and eigenvalues in descending order)
	e_vecs	= matrix of eigenvectors (one column for each eigvector)
	toler	= tolerance for eigenvalues? Often 1.0E-14.

Returns: none

void psi::sq_rsp	(	int	nm,
		int	n,
		double **	array,
		double *	e_vals,
		int	matz,
		double **	e_vecs,
		double	toler
	)

sq_rsp(): diagomalize a symmetric square matrix ('array').

Parameters:

	nm	= rows of matrix
	n	= columns of matrix
	nv	= number of elements in lower triangle (n*(n+1)/2)
	array	= matrix to diagonalize
	e_vals	= array to hold eigenvalues
	matz	= 0 (no eigenvectors, eigenvals in ascending order) = 1 (eigenvectors and eigenvalues in ascending order) = 2 (no eigenvectors, eigenvalues in descending order) = 3 (eigenvectors and eigenvalues in descending order)
	e_vecs	= matrix of eigenvectors (one column for each eigvector)
	toler	= tolerance for eigenvalues? Often 1.0E-14.

void psi::sq_to_tri	(	double **	bmat,
		double *	amat,
		int	size
	)

sq_to_tri(): converts square matrix to lower triangle

Parameters:

	bmat	= matrix to convert
	amat	= array to put lower triangle of bmat into
	size	= number of rows/columns of bmat

Returns: none

void psi::tqli	(	int	n,
		double *	d,
		double **	z,
		double *	e,
		int	matz,
		double	toler
	)

tqli(): diagonalizes tridiagonal matrix output by tred2. Gives only eigenvalues if matz=0, both eigenvalues and eigenvectors if matz=1

void psi::tred2	(	int	n,
		double **	a,
		double *	d,
		double *	e,
		int	matz
	)

tred2(): converts symmetric matrix to a tridagonal form for use in tqli

if matz = 0, only find eigenvalues, else find both eigenvalues and eigenvectors

Returns: none

void psi::tri_to_sq	(	double *	amat,
		double **	bmat,
		int	size
	)

tri_to_sq(): converts lower triangle to square matrix

Parameters:

	amat	= lower triangle matrix
	bmat	= square matrix
	size	= number of rows/cols of matrix

Returns: none

void psi::tstart

(

)

tstart(): Starts a timer

Parameters:

outfile

= output file pointer

void psi::tstop

(

)

tstop(): Stop timer

Parameters:

outfile

= output file pointer.

void psi::zero_arr	(	double *	a,
		int	size
	)

zero_arr(): zero out an array of length 'size'

Parameters:

	a	= array to zero out
	size	= how many elements of a to zero

Returns: none

void psi::zero_int_array	(	int *	a,
		int	size
	)

zero_int_array() Zeroes out an array of integers 'size' integers long

Parameters:

	a	= integer array to zero out
	size	= number of elements in a to zero

Returns: none

void psi::zero_int_matrix	(	int **	array,
		int	rows,
		int	cols
	)

zero_int_matrix(): Zero a matrix of integers. Pass the matrix, the number of rows, and the number of columns.

Parameters:

	array	= pointer to integer matrix
	rows	= number of rows in matrix
	cols	= number of columns in matrix

Returns: none

void psi::zero_mat	(	double **	a,
		int	n,
		int	m
	)

zero_mat(): zero out a matrix 'a' with n rows and m columns

Parameters:

	a	= matrix of doubles to zero out
	n	= number of rows in a
	m	= number of columns in a