1 | This is the top-level README for PGAPack V1.0 |
---|
2 | |
---|
3 | Copyright |
---|
4 | ========= |
---|
5 | See the file COPYRIGHT for Copyright and disclaimer information. |
---|
6 | |
---|
7 | Introduction |
---|
8 | ============ |
---|
9 | PGAPack is a general-purpose, data-structure-neutral, parallel genetic |
---|
10 | algorithm library being developed at Argonne National Laboratory. |
---|
11 | Key features are: |
---|
12 | |
---|
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. |
---|
24 | |
---|
25 | |
---|
26 | Availability |
---|
27 | ============ |
---|
28 | PGAPack is freely available. The complete distribution is available |
---|
29 | by anonymous ftp from from ftp.mcs.anl.gov in the file |
---|
30 | pub/pgapack/pgapack.tar.Z. The distribution contains all source code, |
---|
31 | installation instructions, users guide, and a collection of examples in C and |
---|
32 | Fortran. Additional information is available on the World Wide Web at |
---|
33 | http://www.mcs.anl.gov/pgapack.html. |
---|
34 | |
---|
35 | |
---|
36 | Computational Environment |
---|
37 | ========================= |
---|
38 | PGAPack is written in ANSI C and uses the MPI message passing interface |
---|
39 | and should run on most uniprocessors, parallel computers, and workstation |
---|
40 | networks. PGAPack has been tested on the workstations and parallel computers |
---|
41 | specified by the ARCH_TYPE variable below. |
---|
42 | |
---|
43 | |
---|
44 | Documentation |
---|
45 | ============= |
---|
46 | * The PGAPack users guide is in ./docs/user_guide.ps. |
---|
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. |
---|
50 | |
---|
51 | |
---|
52 | Installation Requirements |
---|
53 | ========================= |
---|
54 | To compile you must have an ANSI C compiler that includes a full |
---|
55 | implementation 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 |
---|
58 | you are running on. |
---|
59 | |
---|
60 | Most of our testing and development was done using MPICH, a freely available |
---|
61 | implementation of MPI. MPICH runs on many parallel computers and |
---|
62 | workstation networks and is publicly available and free. The complete |
---|
63 | distribution is available by anonymous ftp from ftp.mcs.anl.gov. Take the |
---|
64 | file mpich.tar.Z from the directory pub/mpi. Additional information about |
---|
65 | MPICH is avaliable on the World Wide Web at http://www.mcs.anl.gov/mpi. |
---|
66 | |
---|
67 | Installation Instructions |
---|
68 | ========================= |
---|
69 | When 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 |
---|
72 | installation steps are as follows. |
---|
73 | |
---|
74 | 1. Make a directory to install PGAPack in (mkdir /usr/local/pga). |
---|
75 | 2. Change directories to the directory created in the last step |
---|
76 | (cd /usr/local/pga). |
---|
77 | 3. Obtain the compressed tar file pgapack.tar.Z by anonymous ftp in |
---|
78 | ftp.mcs.anl.gov from the directory pub/pgapack. |
---|
79 | 4. Uncompress the tar file (uncompress pgapack.tar.Z). |
---|
80 | 5. Untar the uncompressed tar file (tar xvf ./pgapack.tar). |
---|
81 | 6. Run configure to configure the makefiles (configure -arch ARCH_TYPE) |
---|
82 | where ARCH_TYPE is one of |
---|
83 | |
---|
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. |
---|
99 | |
---|
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] |
---|
103 | |
---|
104 | where all parameters except -arch are optional and do the following: |
---|
105 | |
---|
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. |
---|
116 | |
---|
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. |
---|
120 | |
---|
121 | 7. Execute the makefile (make install). |
---|
122 | 8. Add PGAPack's man pages to your man page path. |
---|
123 | (setenv MANPATH "$MANPATH"":/home/pgapack/man") |
---|
124 | 9. Execute a simple test problem |
---|
125 | |
---|
126 | Sequential version |
---|
127 | ------------------ |
---|
128 | C: /usr/local/pga/examples/c/maxbit |
---|
129 | Fortran: /usr/local/pga/examples/fortran/maxbit |
---|
130 | |
---|
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 |
---|
135 | |
---|
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. |
---|
140 | |
---|
141 | |
---|
142 | Example Installation |
---|
143 | ==================== |
---|
144 | Assuming you have the compressed tar file, pgapack.tar.Z, containing the |
---|
145 | distribution in /home/username. To build a sequential version of PGAPack |
---|
146 | containing debug features for a Sun SparcStation in /usr/local/pga and run a |
---|
147 | test example, type: |
---|
148 | |
---|
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 |
---|
156 | |
---|
157 | To build a parallel version of PGAPack for an IBM SP parallel computer using |
---|
158 | an MPI implementation with include files in /usr/local/mpi/include and library |
---|
159 | in /usr/local/mpi/lib, and run a test example, type: |
---|
160 | |
---|
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 |
---|
169 | |
---|
170 | |
---|
171 | PGAPack on PCs |
---|
172 | =================== |
---|
173 | PGAPack has not been ported to MS-DOS, Windows 3.1, Windows 95, or Apple OS. |
---|
174 | As mentioned earlier, however, PGAPack is written in ANSI standard C and |
---|
175 | should compile in these environments. Be aware, however, that PGAPack's |
---|
176 | random number generator, PGARandom01, assumes certain machine characteristics |
---|
177 | for ints and floats that may not correspond with what your PC and/or compiler |
---|
178 | support, resulting in erroneous values. |
---|
179 | |
---|
180 | |
---|
181 | Structure of the Distribution Directory |
---|
182 | ======================================= |
---|
183 | CHANGES: Changes new to this release of PGAPack. |
---|
184 | COPYRIGHT: Copyright and disclaimer information. |
---|
185 | README: This file. |
---|
186 | configure.in: The ``source code'' for the configure script. |
---|
187 | configure: Unix shell script to configure Makefile.in for a specific |
---|
188 | architecture. |
---|
189 | Makefile.in: Prototype that is configured into ``Makefile'' by configure. |
---|
190 | docs: Directory containing documentation. |
---|
191 | examples: A directory containing C and Fortran examples. |
---|
192 | include: The PGAPack include directory. |
---|
193 | lib: The directory the library will be installed in. |
---|
194 | man: The directory containing the PGAPack man pages. |
---|
195 | source: The source code for the PGAPack system. |
---|
196 | test: A directory containing programs to verify the installation. |
---|
197 | |
---|
198 | |
---|
199 | Email Addresses |
---|
200 | =============== |
---|
201 | To join the PGAPack mailing list to receive announcements of new versions, |
---|
202 | enhancements, and bug fixes, send electronic mail to pgapack@mcs.anl.gov. Bug |
---|
203 | reports should be sent to pgapack-bugs@mcs.anl.gov. The World Wide Web page |
---|
204 | for PGAPack is http://www.mcs.anl.gov/pgapack.html and contains up-to-date |
---|
205 | news and a list of outstanding bug reports. |
---|
206 | |
---|
207 | |
---|
208 | When reporting a bug please include as much information and documentation as |
---|
209 | possible. Helpful information would include PGAPack version number, MPI |
---|
210 | implementation and version used (if any), configuration options, type of |
---|
211 | computer system, problem description and error message output. It is helpful |
---|
212 | if you put a PGAPrintContextVariable call before and after the PGASetUp call. |
---|
213 | Additionally, if possible, build a debug version of PGAPack and send |
---|
214 | ``high-level'' output from running your program with the trace facility |
---|
215 | enabled. |
---|
216 | |
---|
217 | |
---|
218 | Contributions |
---|
219 | ============= |
---|
220 | PGAPack was written to be extensible in two ways: adding new operators that |
---|
221 | work with existing data types, and defining new data types. Enhancements of |
---|
222 | either type that you wish to share are welcome for possible inclusion in |
---|
223 | future versions of PGAPack. |
---|
224 | |
---|
225 | |
---|
226 | Acknowledgment |
---|
227 | ============== |
---|
228 | Users of PGAPack are asked to acknowledge its use in any document referencing |
---|
229 | work based on the program, such as published research. Also, please supply |
---|
230 | to us a copy of any published research referencing work based on the software. |
---|
231 | |
---|