Read Me

DEPENDENCIES

Before proceding with the installation, make sure you have the following 
dependencies installed in your system:

Component			Purpose

C++				general
GNU Make			general
GNU Scientific Library (GSL)	general
ARPACK				sparse matrix decomposition
Fortran				interface with ARPACK
lex				build "date_calc" and "sparse_calc"
yacc					"
readline/history(+dependencies)	"date_calc" and "sparse_calc" interfaces

Take note of where they have been installed as you must modify the makefile
macros with their locations.  See below.

INSTALLATION

To install, download the tarball from Sourceforge and unpack to the desired 
location.  Edit the makefile and type, "make".  You must have the GSL (GNU 
Scientific Library installed.  For a complete list of dependencies, see below.  
To copy the library and include files to the appropriate directories, type, 
"make install".  Or, simply add the installation directory to your path.  
The following macros must be changed to suit your system:

CPP		= name of your C++ compiler
GSL_INCLUDE	= location of GSL include files
INCLUDE_PATH	= desired location of include files
LIB_PATH	= desired location of compiled library
CFLAGS		= compiler options

The level of optimisation can be changed in the usual way by editing the CFLAGS
macro or by setting the OPT_VER macro to the desired flag.  This is to create 
multiple versions with different levels of optimisation--the optimisation flag 
will be appended to all compiled object files and libraries.

There are two satellite libraries included with the distribution: a library for
sparse matrices and a library for specialized "datasets."  To make and install
only the main library (as needed by libagf), type "make petey" and 
"make install_petey." Note that the sparse library, in addition to the GSL,
also requires the Arpack library.  I've found a small bug in
the library, at least when compiled with gfortran/g77: under the "UTIL" 
directory, there is a file/function called, second.f.  Line 24 should be 
changed from, "EXTERNAL ETIME", to "INTRINSIC ETIME".  This is partially 
documented in the "README" instructions, but not this particular fix.

Also particular to the sparse library: you must supply a fortran compiler
and the runtime library that goes with it.  In older versions of GNU, these
would be "g77" and "g2c" respectively.  In newer versions, "gfortran" and
"gfortran".  The make macros are:
F77 = gfortran
FORTRAN_RUNTIME = gfortran

The make macros for the arpack library are:
LIBARPACK = libarpack
ARPATH =/usr/local/lib

To change the leading and trailing underscores in Fortran routines used in
C++ programs:
FLEADING_UNDERSCORES = 
FTRAILING_UNDERSCORES = _

The user should change these to suit his or her system.


SUMMARY

Here is a brief summary of the contents of the library, by include file:

In libpetey.a:

peteys_tmpl_lib.h: A set of template libraries for numerical computation.
			Listed by subroutine, below.

  heapsort_inplace:	Performs a heapsort on arbitary classes (as long as 
			they have the comparison operators defined).  This is 
			done in place with no extra storage required.
  heapsort:		Performs a heapsort.  Returns a set of indices for 
			rearranging a vector while leaving the original vector 
			untouched.  Slightly slower than above.
  treesort:		Treesort routine.  Sorts the data and returns a set of 
			indices.
  reverse:		Reverses the order of an array.
  map_vector:		For use with heapsort routine.  Rearranges a vector 
			from a set of indices.
  invert_mapping:	Inverts an integer permutation map from one array to another.
  bin_search:		Binary search on ordered data.
  interpolate:		Interpolation on ordered data.  Returns a double 
			precision float in which the whole number portion 
			indexes into the array while the fractional value is 
			the interpolation coefficient.
  rk_dumb:		Fourth-order Runge-Kutta integrator with fixed 
			(non-adaptive) stepsize.

kextreme.h:  	Routines for finding a set of k minimum or maximum values in 
		an unsorted array.  Performs this in n log k time using binary 
		trees.

  kleast:	Returns the k minimum values in an array.  Two versions: one 
		returns a set of indices.
  kgreatest:	Returns the k maximum values in an array.  		"

time_class.h:	A class for working with dates and times.  Very useful.

supernewton.h:	Powerful root-finding algorithm.  Brackets the root and fits a 
		third-order polynomial, combining fast convergence with 
		numerical stability.  Function to be zeroed must return its 
		derivatives.

tree_lg:	Binary tree class used to find k- minimum and maximum values.
tree_lgi:	Binary tree class used to find k- minimum and maximum values.  
		Sorts indices simultaneous to actual values.

linked.h:	Templated linked-list class.

tree_tmp.h:	Another binary tree class.  Not well tested.

string_petey.h:	A string class.  Not well tested.

bit_array.h:	For compact storage of bit data.

quicksort.h:	Quicksort routine plus k-least routines based on a quicksort.

parse_command_opts: Subroutine for parsing the optional command arguments
		in far fewer commands than getopt.

petey_pointer.h: "Smart" pointer template class.

symbol_table.h: Templated symbol table class.

full_util.h:	Utilities for working with full matrices stored in primitive
		types.

date_calc:	Command-line calculator for working with dates.  Tests the
		time_class class.


In libsparse.a:

The class hierarchy:

                  matrix_base
                      |
     -----------------------------------
     |                |                |
  sparse          full_matrix    sparse_array

The sparse class stores sparse matrices using 3-tuples consisting of row index,
column index and data value, sorted by row first, then column.
Note that the operations that allow the sparse class to interoperate with the
other classes in the family are stored in the file sparse_cnl.*.

The full_matrix class simply encapsulates the subroutines contained in
full_util -- see above.

The sparse array stores arrays of sparse matrices and treats them as a single
matrix.  Elements must be square and all of the same size.  

A series of virtual methods are defined for the most common matrix operations:
vector multiplication, matrix multiplication and addition.

The class hierarchy is used in an interactive utility called sparse_calc
which allows the user to operate on matrices stored in binary files just as
you might operate on scalars with a pocket calculator.  sparse_calc has a
man page and a generous online help system.


In libdataset.a:

The dataset class hierarchy:

 dataset
    |
    | --  simple_dataset
    |           |
    |           | --  simple<float>
    |           | --  simple<long>
    |           | --  simple<time>
    |           | --  simple<... >
    |
    | --  dependent_dataset
    |           |
    |           | --  dependent<float>
    |           |      | -- dependent_swap<float>
    |           |      
    |           | --  dependent<long>
    |           |      | -- dependent_swap<long>
    |           |
    |           | --  dependent<time>
    |           |      | -- dependent_swap<time>
    |           | 
    |           | --  dependent<... >
    |           |      | -- dependent_swap<... >
    |           |
    |           | --  dependent_intc
    |
    | --  composite_dataset

Simple datasets are meant to represent a set: a list of items with no
ordering or duplication.

Dependent datasets hold one element for each combination of elements in
their dependencies, which are simple datasets.  Thus they represent multi-
dimensional relations.

Composite datasets can hold any number of other datasets, much like a Unix
file system.

This library is not really fully formed but is meant to form the back-bone
of a new scientific database/programming language based on multi-dimensional
data relations.  The most useful elements of the libary are the 
dependent_swap classes which hold dependent datasets swapped from files
and the dependent_intc class which holds no data but can return multi-
dimensional interpolation coefficients.  Note that datasets are currently
limited to only four (4) dimensions.


Questions or comments about this software?  Email me:

Peter Mills
peteymills@hotmail.com