This is the top-level README for PGAPack V0.2


Disclaimer
==========
See the file DISCLAIMER for the official legal disclaimer.  No support of any
kind is implied with this software.  On a time available basis, we will try to
respond to bug reports.  Although it is unlikely we will do so, we reserve
the right to change the calling sequences of PGAPack functions.


Introduction
============
PGAPack is a general-purpose, data-structure-neutral, parallel genetic
algorithm library being developed at Argonne National Laboratory.  This
distribution contains PGAPack V0.2, a sequential beta version that has
the following features:

* Callable from Fortran or C.
* Binary-, integer-, and real-valued native data types
* Object-oriented data structure neutral design. 
* Parameterized population replacement.
* Multiple choices for selection, crossover, and mutation operators
* Easy integration of hill-climbing heuristics. 
* Black-box interface for novice and application users.
* Access to all library calls for expert users.
* Fully extensibile to support custom operators and new data types.
* Extensive debugging facilities
* A large set of example programs.
* A users guide.


Availability
============
PGAPack is available via anonymous ftp from info.mcs.anl.gov in the file
pub/pgapack/pgapack.tar.Z.  Also in this directory are the user guide,
user_guide.ps, in Postscript format, and this README file.  The Web address
for PGAPack is http://www.mcs.anl.gov/home/levine/GA/pgapack.html.


Documentation
=============
* The PGAPack user guide is in ./docs/user_guide.ps.
* Man pages for PGAPack functions are in the ./man directory.
* Installation instructions are in this README file and the user guide.
* Example problems are in the ./examples directory.


Installation Requirements
=========================
To compile you must have an ANSI C compiler that includes a full
implementation of the Standard C library and related header files.  This
version (0.2) of PGAPack has been tested on the 32-bit Unix workstations
mentioned below.  It should also be possible to build PGAPack on other 32-bit
workstations.


Installation Instructions
=========================
1.  Make a directory to install PGAPack in (mkdir /usr/local/pga).
2.  Change directories to the directory created in the last step
    (cd /usr/local/pga).
3.  Obtain the compressed tar file pgapack.tar.Z by anonymous ftp in
    info.mcs.anl.gov from the directory pub/pgapack.
4.  Uncompress the tar file (uncompress pgapack.tar.Z).
5.  Untar the uncompressed tar file (tar xvf ./pgapack.tar).
6.  Run configure to configure the makefiles (configure -arch ARCH_TYPE)
    ARCH_TYPE is one of sun4, NeXT, AIX, IRIX, Linux, or freebsd for Sun
    SparcStations, NeXT workstations, IBM RS6000, Silicon Graphics, or PCs
    running Linux or Free BSD.
    The configure options are configure -arch ARCH TYPE [-f77 FC] [-cc CC] 
    [-optimize] [-help] where all parameters except -arch are optional and
    do the following:
    [-f77] specifies the name of the Fortran 77 compiler
    [-cc] specifies the name of the ANSI C compiler
    [-optimize] disables the debugging features and compiles the
    source code using the    -O  flag.
    [-help] prints a help message
7.  Execute the makefile (make install).
8.  Add PGAPack's man pages to your man page path.
    (setenv MANPATH "$MANPATH"":/home/pgapack/man")
9.  Execute a simple test problem
    a. /usr/local/pga/examples/c/maxbit in C
    b. /usr/local/pga/examples/fortran/maxbit in Fortran.
10. The Unix shell script /usr/local/pga/examples/c/verify_short can
    (optionally) be run to compare the results of several other test
    problems with previous calculations.


Example Installation
====================
Assuming you have the compressed tar file pgapack.tar.Z containing the
distribution in /tmp, and you wish to build for a Sun SparcStation in
/usr/local/pga and test an example, type:

     mkdir /usr/local/pga 
     cd /usr/local/pga 
     uncompress /tmp/pgapack.tar.Z 
     tar xvf /tmp/pgapack.tar 
     configure -arch sun4 
     make install 
     /usr/local/pga/examples/c/maxbit 


PGAPack under MSDOS
===================
PGAPack has not been tested under MS-DOS.  As mentioned earlier, however,
PGAPack is written in ANSI standard C and should compile in an MS-DOS
environment.  Be aware, however, that PGAPack`s random number generator,
PGARandom01, assumes certain machine characteristics for ints and floats that
may not correspond with what your PC and/or compiler support, resulting in
erroneous values.


Structure of the Distribution Directory
=======================================
CHANGES:     Changes new to this release of PGAPack.
DISCLAIMER:  The usage terms.
README:      This file.
Makefile.in: Prototype thats is configured into a makefile by configure.
configure:   Shell script to configure Makefile.in's for target architecture.
docs:        Directory containing documentation.
include:     The PGAPack include directory.
lib:         The directory the library will be installed in.
man:         The directory containing the PGAPack man pages.
source:      The source code for the PGAPack system.


Email Addresses
===============
To join the PGAPack mailing list to receive announcements of new versions,
enhancements, and bug fixes send electronic mail to pgapack@mcs.anl.gov.

Please send bug reports to pgapack-bugs@mcs.anl.gov.  Include as much
information and documentation about the problem as you can.


Contributions
=============
PGAPack was written to be extensible in two ways: adding new operators that
work with existing data types, and defining new data types.  Enhancements of
either type that you wish to share are welcome for possible inclusion in
future versions of PGAPack.  Contact pgapack@mcs.anl.gov.


Acknowledgment
==============
Users of PGAPack are kindly asked to acknowledge its use by referencing the
users guide in the bibliography, and/or by name in the text.



