source: trunk/optimizer/src/pgapack/pgapack/README @ 986

Last change on this file since 986 was 816, checked in by liveletlive, 17 years ago

Committing the newer version of PGAPack.

File size: 9.7 KB
1This is the top-level README for PGAPack V1.0
5See the file COPYRIGHT for Copyright and disclaimer information.
9PGAPack is a general-purpose, data-structure-neutral, parallel genetic
10algorithm library being developed at Argonne National Laboratory. 
11Key features are:
13* Callable from Fortran or C.
14* Runs on uniprocessors, parallel computers, and workstation networks.
15* Binary-, integer-, real-, and character-valued native data types.
16* Object-oriented data structure neutral design.
17* Parameterized population replacement.
18* Multiple choices for selection, crossover, and mutation operators.
19* Easy integration of hill-climbing heuristics.
20* Easy-to-use interface for novice and application users.
21* Fully extensible to support custom operators and new data types.
22* Extensive debugging facilities.
23* A large set of example problems.
28PGAPack is freely available.  The complete distribution is available
29by anonymous ftp from from in the file
30pub/pgapack/pgapack.tar.Z.  The distribution contains all source code,
31installation instructions, users guide, and a collection of examples in C and
32Fortran. Additional information is available on the World Wide Web at
36Computational Environment
38PGAPack is written in ANSI C and uses the MPI message passing interface
39and should run on most uniprocessors, parallel computers, and workstation
40networks.  PGAPack has been tested on the workstations and parallel computers
41specified by the ARCH_TYPE variable below.
46* The PGAPack users guide is in ./docs/
47* Man pages for PGAPack functions are in the ./man directory.
48* Installation instructions are in this README file and the users guide.
49* Example problems are in the ./examples directory.
52Installation Requirements
54To compile you must have an ANSI C compiler that includes a full
55implementation of the Standard C library and related header files.  To build a
56*parallel* version of PGAPack you must provide an implementation of MPI
57(Message Passing Interface) for the parallel computer or workstation network
58you are running on.
60Most of our testing and development was done using MPICH, a freely available
61implementation of MPI.  MPICH runs on many parallel computers and
62workstation networks and is publicly available and free.  The complete
63distribution is available by anonymous ftp from  Take the
64file mpich.tar.Z from the directory pub/mpi.  Additional information about
65MPICH is avaliable on the World Wide Web at
67Installation Instructions
69When installing PGAPack you make two choices: whether to build a sequential
70(the default) or parallel version, and whether to build a debug or optimized
71(the default) version.  In broad outline, the
72installation steps are as follows.
741.  Make a directory to install PGAPack in (mkdir /usr/local/pga).
752.  Change directories to the directory created in the last step
76    (cd /usr/local/pga).
773.  Obtain the compressed tar file pgapack.tar.Z by anonymous ftp in
78 from the directory pub/pgapack.
794.  Uncompress the tar file (uncompress pgapack.tar.Z).
805.  Untar the uncompressed tar file (tar xvf ./pgapack.tar).
816.  Run configure to configure the makefiles (configure -arch ARCH_TYPE)
82    where ARCH_TYPE is one of
84    sun4           for Sun SparcStations workstations,
85    next           for NeXT workstations,
86    rs600          for IBM RS6000 workstations,
87    irix           for Silicon Graphics workstations,
88    hpux           for Hewlett Packard workstations,
89    alpha          for DEC Alpha workstations,
90    linux          for machines running Linux,
91    freebsd        for machines running FreeBSD,
92    generic        for generic 32-bit machines,
93    powerchallenge for the Silicon Graphics Power Challenge Array,
94    challenge      for the Silicon Graphics Challenge,
95    t3d            for the Cray T3D,
96    sp2            for the IBM SP2,
97    paragon        for the Intel Paragon, or
98    exemplar       for the Convex  Exemplar.
100    The full configure options are configure -arch ARCH_TYPE [-cc CC]
101    [-cflags CFLAGS] [-f77 FC] [-fflags FFLAGS] [-debug]
102    [-mpiinc MPI_INCLUDE_DIRECTORY] [-mpilib MPI_LIBRARY]  [-help]
104    where all parameters except -arch are optional and do the following:
106    [-cc]:       The name of the ANSI C compiler, cc by default.
107    [-cflags]:   Options passed to the C compiler.
108    [-f77]:      The name of the Fortran 77 compiler, f77 by default.
109                 (The Fortran compiler is used only to compile the Fortran
110                 examples in the [./examples/] directory.)
111    [-fflags]:   Options passed to the Fortran compiler.
112    [-debug]:    If specified, enables the debugging features
113                 and compiles the source code with the -g flag.
114    [-mpiinc]:   The *directory* where MPI include files are located.
115    [-mpilib]:   The *full path* to the MPI library. 
117    If the [-mpilib] and [-mpiinc] options are specified, a parallel version
118    of PGAPack will be built.  If these flags are not specified a sequential
119    version of PGAPack will be built.
1217.  Execute the makefile (make install).
1228.  Add PGAPack's man pages to your man page path.
123    (setenv MANPATH "$MANPATH"":/home/pgapack/man")
1249.  Execute a simple test problem
126    Sequential version
127    ------------------
128    C:        /usr/local/pga/examples/c/maxbit
129    Fortran:  /usr/local/pga/examples/fortran/maxbit
131    Parallel version
132    ------------------
133    C:        mpirun -np 4 /usr/local/pga/examples/c/maxbit
134    Fortran:  mpirun -np 4 /usr/local/pga/examples/fortran/maxbit
136    If a parallel version of PGAPack was used, the actual commands to execute
137    a parallel program depend on the particular MPI implementation and
138    parallel computer.  If the MPICH implementation was used the "mpirun"
139    command can be used to execute a parallel program on most systems.
142Example Installation
144Assuming you have the compressed tar file, pgapack.tar.Z, containing the
145distribution in /home/username.  To build a sequential version of PGAPack
146containing debug features for a Sun SparcStation in /usr/local/pga and run a
147test example, type:
149    uncompress /home/username/pgapack.tar.Z
150    mkdir /usr/local/pga
151    cd /usr/local/pga
152    tar xvf /home/username/pgapack.tar
153    configure -arch sun4 -debug
154    make install
155    /usr/local/pga/examples/c/maxbit
157To build a parallel version of PGAPack for an IBM SP parallel computer using
158an MPI implementation with include files in /usr/local/mpi/include and library
159in /usr/local/mpi/lib, and run a test example, type:
161   uncompress /home/username/pgapack.tar.Z
162   mkdir /usr/local/pga
163   cd /usr/local/pga
164   tar xvf /home/username/pgapack.tar
165   configure -arch rs6000 -mpiinc /usr/local/mpi/include \
166             -mpilib /usr/local/mpi/lib/libmpi.a
167   make install
168   mpirun -np 4 /usr/local/pga/examples/c/maxbit
171PGAPack on PCs
173PGAPack has not been ported to MS-DOS, Windows 3.1, Windows 95, or Apple OS.
174As mentioned earlier, however, PGAPack is written in ANSI standard C and
175should compile in these environments.  Be aware, however, that PGAPack's
176random number generator, PGARandom01, assumes certain machine characteristics
177for ints and floats that may not correspond with what your PC and/or compiler
178support, resulting in erroneous values.
181Structure of the Distribution Directory
183CHANGES:      Changes new to this release of PGAPack.
184COPYRIGHT:    Copyright and disclaimer information.
185README:       This file. The ``source code'' for the configure script.
187configure:    Unix shell script to configure for a specific
188              architecture.  Prototype that is configured into ``Makefile'' by configure.
190docs:         Directory containing documentation.
191examples:     A directory containing C and Fortran examples.
192include:      The PGAPack include directory.
193lib:          The directory the library will be installed in.
194man:          The directory containing the PGAPack man pages.
195source:       The source code for the PGAPack system.
196test:         A directory containing programs to verify the installation.
199Email Addresses
201To join the PGAPack mailing list to receive announcements of new versions,
202enhancements, and bug fixes, send electronic mail to  Bug
203reports should be sent to  The World Wide Web page
204for PGAPack is and contains up-to-date
205news and a list of outstanding bug reports.
208When reporting a bug please include as much information and documentation as
209possible.  Helpful information would include PGAPack version number, MPI
210implementation and version used (if any), configuration options, type of
211computer system, problem description and error message output.  It is helpful
212if you put a PGAPrintContextVariable call before and after the PGASetUp call.
213Additionally, if possible, build a debug version of PGAPack and send
214``high-level'' output from running your program with the trace facility
220PGAPack was written to be extensible in two ways: adding new operators that
221work with existing data types, and defining new data types.  Enhancements of
222either type that you wish to share are welcome for possible inclusion in
223future versions of PGAPack.
228Users of PGAPack are asked to acknowledge its use in any document referencing
229work based on the program, such as published research.  Also, please supply
230to us a copy of any published research referencing work based on the software.
Note: See TracBrowser for help on using the repository browser.