| |
| [ Updated March 2008: |
| -- the original README, minus two references to the now |
| obsolete website and mailing lists, follows below |
| -- PGAPack has also been built successfully against LAM/MPI |
| and Open MPI. ] |
| |
| |
| This is the top-level README for PGAPack V1.0 |
| |
| Copyright |
| ========= |
| See the file COPYRIGHT for Copyright and disclaimer information. |
| |
| Introduction |
| ============ |
| PGAPack is a general-purpose, data-structure-neutral, parallel genetic |
| algorithm library developed at Argonne National Laboratory. |
| Key features are: |
| |
| * Callable from Fortran or C. |
| * Runs on uniprocessors, parallel computers, and workstation networks. |
| * Binary-, integer-, real-, and character-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. |
| * Easy-to-use interface for novice and application users. |
| * Fully extensible to support custom operators and new data types. |
| * Extensive debugging facilities. |
| * A large set of example problems. |
| |
| |
| Availability |
| ============ |
| PGAPack is freely available. The complete distribution is available |
| by anonymous ftp from from ftp.mcs.anl.gov in the file |
| pub/pgapack/pgapack.tar.Z. The distribution contains all source code, |
| installation instructions, users guide, and a collection of examples in C and |
| Fortran. |
| |
| |
| Computational Environment |
| ========================= |
| PGAPack is written in ANSI C and uses the MPI message passing interface |
| and should run on most uniprocessors, parallel computers, and workstation |
| networks. PGAPack has been tested on the workstations and parallel computers |
| specified by the ARCH_TYPE variable below. |
| |
| |
| Documentation |
| ============= |
| * The PGAPack users 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 users 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. To build a |
| *parallel* version of PGAPack you must provide an implementation of MPI |
| (Message Passing Interface) for the parallel computer or workstation network |
| you are running on. |
| |
| Most of our testing and development was done using MPICH, a freely available |
| implementation of MPI. MPICH runs on many parallel computers and |
| workstation networks and is publicly available and free. The complete |
| distribution is available by anonymous ftp from ftp.mcs.anl.gov. Take the |
| file mpich.tar.Z from the directory pub/mpi. Additional information about |
| MPICH is avaliable on the World Wide Web at http://www.mcs.anl.gov/mpi. |
| |
| Installation Instructions |
| ========================= |
| When installing PGAPack you make two choices: whether to build a sequential |
| (the default) or parallel version, and whether to build a debug or optimized |
| (the default) version. In broad outline, the |
| installation steps are as follows. |
| |
| 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 |
| ftp.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) |
| where ARCH_TYPE is one of |
| |
| sun4 for Sun SparcStations workstations, |
| next for NeXT workstations, |
| rs600 for IBM RS6000 workstations, |
| irix for Silicon Graphics workstations, |
| hpux for Hewlett Packard workstations, |
| alpha for DEC Alpha workstations, |
| linux for machines running Linux, |
| freebsd for machines running FreeBSD, |
| generic for generic 32-bit machines, |
| powerchallenge for the Silicon Graphics Power Challenge Array, |
| challenge for the Silicon Graphics Challenge, |
| t3d for the Cray T3D, |
| sp2 for the IBM SP2, |
| paragon for the Intel Paragon, or |
| exemplar for the Convex Exemplar. |
| |
| The full configure options are configure -arch ARCH_TYPE [-cc CC] |
| [-cflags CFLAGS] [-f77 FC] [-fflags FFLAGS] [-debug] |
| [-mpiinc MPI_INCLUDE_DIRECTORY] [-mpilib MPI_LIBRARY] [-help] |
| |
| where all parameters except -arch are optional and do the following: |
| |
| [-cc]: The name of the ANSI C compiler, cc by default. |
| [-cflags]: Options passed to the C compiler. |
| [-f77]: The name of the Fortran 77 compiler, f77 by default. |
| (The Fortran compiler is used only to compile the Fortran |
| examples in the [./examples/] directory.) |
| [-fflags]: Options passed to the Fortran compiler. |
| [-debug]: If specified, enables the debugging features |
| and compiles the source code with the -g flag. |
| [-mpiinc]: The *directory* where MPI include files are located. |
| [-mpilib]: The *full path* to the MPI library. |
| |
| If the [-mpilib] and [-mpiinc] options are specified, a parallel version |
| of PGAPack will be built. If these flags are not specified a sequential |
| version of PGAPack will be built. |
| |
| 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 |
| |
| Sequential version |
| ------------------ |
| C: /usr/local/pga/examples/c/maxbit |
| Fortran: /usr/local/pga/examples/fortran/maxbit |
| |
| Parallel version |
| ------------------ |
| C: mpirun -np 4 /usr/local/pga/examples/c/maxbit |
| Fortran: mpirun -np 4 /usr/local/pga/examples/fortran/maxbit |
| |
| If a parallel version of PGAPack was used, the actual commands to execute |
| a parallel program depend on the particular MPI implementation and |
| parallel computer. If the MPICH implementation was used the "mpirun" |
| command can be used to execute a parallel program on most systems. |
| |
| |
| Example Installation |
| ==================== |
| Assuming you have the compressed tar file, pgapack.tar.Z, containing the |
| distribution in /home/username. To build a sequential version of PGAPack |
| containing debug features for a Sun SparcStation in /usr/local/pga and run a |
| test example, type: |
| |
| uncompress /home/username/pgapack.tar.Z |
| mkdir /usr/local/pga |
| cd /usr/local/pga |
| tar xvf /home/username/pgapack.tar |
| configure -arch sun4 -debug |
| make install |
| /usr/local/pga/examples/c/maxbit |
| |
| To build a parallel version of PGAPack for an IBM SP parallel computer using |
| an MPI implementation with include files in /usr/local/mpi/include and library |
| in /usr/local/mpi/lib, and run a test example, type: |
| |
| uncompress /home/username/pgapack.tar.Z |
| mkdir /usr/local/pga |
| cd /usr/local/pga |
| tar xvf /home/username/pgapack.tar |
| configure -arch rs6000 -mpiinc /usr/local/mpi/include \ |
| -mpilib /usr/local/mpi/lib/libmpi.a |
| make install |
| mpirun -np 4 /usr/local/pga/examples/c/maxbit |
| |
| |
| PGAPack on PCs |
| =================== |
| PGAPack has not been ported to MS-DOS, Windows 3.1, Windows 95, or Apple OS. |
| As mentioned earlier, however, PGAPack is written in ANSI standard C and |
| should compile in these environments. 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. |
| COPYRIGHT: Copyright and disclaimer information. |
| README: This file. |
| configure.in: The ``source code'' for the configure script. |
| configure: Unix shell script to configure Makefile.in for a specific |
| architecture. |
| Makefile.in: Prototype that is configured into ``Makefile'' by configure. |
| docs: Directory containing documentation. |
| examples: A directory containing C and Fortran examples. |
| 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. |
| test: A directory containing programs to verify the installation. |
| |
| |
| 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. |
| |
| |
| Acknowledgment |
| ============== |
| Users of PGAPack are asked to acknowledge its use in any document referencing |
| work based on the program, such as published research. Also, please supply |
| to us a copy of any published research referencing work based on the software. |
| |