README
1 This is the README file for
2
3
4 BBBB U U GGGGG SSSSS X X
5 B B U U G S X X
6 BBBB U U G GGG SSSSS X
7 B B U U G G S X X
8 BBBB UUU GGGGG SSSSS X X
9
10
11
121) Author & Copyright
13
14 bugsx was written by
15
16 (C) Copyright 1995-1996 Robert Gasch (Robert_Gasch@peoplesoft.com)
17 http://www.peoplesoft.com/peoplepages/g/robert_gasch/index.htm
18
19 (C) Copyright 1990-1996 Joshua R. Smith (jrs@media.mit.edu)
20 http://physics.www.media.mit.edu/~jrs
21
22 is copyright by the author(s). I (Robert_Gasch@peoplesoft.com) maintain
23 the X11 port and Joshua maintains any other ports. See section 4
24 and 17 for more info.
25
262) Distribution Policy
27
28 Permission to use, copy, modify and distribute this software for
29 any purpose and without fee is hereby granted, provided that this
30 copyright notice appear in all copies as well as supporting
31 documentation. All work developed as a consequence of the use of
32 this program should duly acknowledge such use.
33
34 See the GNU General Public Licence for more information.
35
36 What does this mean?
37 This means that you can pretty much do with it what you want as
38 long as you don't charge substantially more than the distribution
39 costs for it (of course you have to make the source available).
40
41 This makes software distributions like Walnut Creek or Infomagic
42 perfectly acceptable.
43
44 It does NOT matter wether you use it at home or in a comercial
45 environment.
46
47 If you want to include it in a major commercial distribution you
48 need my permission to do so.
49
503) Guarantees
51
52 bugsx should work all right *but*
53
54 No representations are made about the suitability of this software
55 for any purpose. This software is provided "as is" without express
56 or implied warranty.
57
584) What is bugsx?
59
60 bugsx runs under MIT's X11 window system. It was written under
61 UNIX but should be easily portable. It is a program which draws
62 the biomorphs based on parametric plots of Fourier sine and cosine
63 series and let's you play with them using the genetic algorithm.
64
65 The original version which ran under Suntools and XViews was
66 written by Joshua R. Smith sometime 1990. See the 'credits'
67 section for more details.
68
69 For more information about the theoretic backgrounds of
70 bugsx consult Joshua R. Smith's paper distributed with this
71 program in gzip'ed postscript format as bugs.ps.gz. You have
72 to uncompress this file with 'gunzip' before you can print it.
73 Gunzip should be available at an archive near you.
74
75 The paper can also be gotten from:
76 http://physics.www.media.mit.edu/~jrs/biomorphs.ps
77
78 I (Robert_Gasch@peoplesoft.com) maintain the X11 port and
79 Joshua (jrs@media.mit.edu) maintains any other ports.
80 See section 4, and 17 for more info.
81
825) Version Number
83
84 The current version number is 1.08
85
866) Where can I get Bugsx from?
87
88 Bugsx can be gotten from the following FTP sites:
89 media.mit.edu (/physics/dist/bugs)
90 ftp.x.org (/contrib/applications)
91
927) What if you change the program?
93
94 please mail me (Robert_Gasch@peoplesoft.com) the changes(!) as I'd like to
95 act as the central source for bugsx. This will also enable me to
96 include your changes in a future release. If your changes are
97 generic, I'll pass the changes on so that other versions of BUGS
98 can also benefit from your input.
99
1008) Systems currently supported
101
102 Any resonable UNIX-type system running X11 should be able to
103 compile and run bugsx. I've tested it on the following
104 systems:
105
106 Linux
107 AIX
108
1099) How do I get started?
110
111 This section assumes that you have all the necessary files. (The
112 file "Manifest" contains a list of distributed files.)
113
114 a) Customize the Imakefile to suit your system setup. On most systems
115 this should work OK as it is.
116
117 b) Make the Makefile by typing
118 xmkmf
119 If your system does not support generating makefiles from
120 Imakefiles use "Makefile.std" as a template to build your
121 own.
122
123 c) If your X headers do not define APP_DEFAULTS_DIR and your default
124 X Resource file is not
125 /usr/X11R6/lib/X11/app-defaults/
126 edit bugsx.h and modify the definition for APP_DEFAULTS_DIR. On
127 most systems things should be OK the way they are, but this gives
128 you the possibility to customize this.
129
130 d) Once you have a valid Makefile (see step a&b) build bugsx by typing
131 make
132
133 Once you have created the executable, you're ready to go. The
134 executable will be created in the directory in which the source
135 for bugsx resides.
136
13710) Brief users guide
138
139 You can get a list of supported options by typing one of the
140 following:
141 bugsx -?
142 bugsx -help
143 bugsx help
144
145 Once you start bugsx, you get the main window containing
146 the menu options at the top and the evenly distributed drawing
147 windows below the menus.
148
149 The Menus are:
150
151 Initialize - Initializes the gene pool
152 Breed - Breed the selected organisms.
153 Quit - exits bugsx
154
155 Once you have chosen "Initialize" and the first set of drawings
156 is shown, you can select the ones you wish to be included in
157 the cross-breeding by clicking (with the left button) on a
158 drawing window. The selected organisms will be drawn inverse.
159
160 Clicking on Breed will cross breed the selected organisms using
161 the genetic algorithm. If you have not selected at least two
162 organisms, a set of at least two will be randomly chosen and
163 used for the breeding.
164
165 The following keys can be used to control bugsx:
166 q - quit bugsx
167 i - initialize population
168 b - breed
169
170 Interesting/useful sample settings:
171 bugsx -interval 3 -number 4 -batch -nobreed -segments 500
172 bugsx -interval 3 -batch -showbreed
173 bugsx -seed 10
174
175
17610) Command line parameters
177
178 bugsx accepts the following parameters as command line options:
179
180 +rv reverse video (use to override xrdb entry)
181 +synchronous syncronous mode (use to override xrdb entry)
182 -? help
183 -background <arg> backgound color
184 -batch run program in batch mode
185 -bg <arg> same as -background
186 -bordercolor <arg> border color
187 -borderwidth <arg> border width
188 -cycle <arg> re-initialize population after n batch turns
189 -display display
190 -extend_print show extended reproduction info while running
191 -fg <arg> same as -forground
192 -font <arg> font
193 -foreground <arg> forground color (also file system bar color)
194 -geometry <arg> geometry
195 -help help
196 -iconic iconic
197 -interval <arg> interval used per turn
198 -mb show menu border
199 -name <arg> run bugsx under this name
200 -nobreed do not breed when running in batch mode
201 -number <arg> number of biomorphs to draw (must be a square #)
202 -printpop print the population when breeding
203 -rv reverse video
204 -seed <arg> use this seed for random number generator
205 -segments <arg> use this many segments to draw an organism
206 -showbreed show breeding subpopulation when in batch mode
207 -showgenes show a graphic representation of the genes
208 -synchronous synchronous mode
209 -v verbose
210 -xrm make no entry in resrouce database
211 help help
212
213
21411) XResources
215
216 bugsx recognizes the following XResources. Usually bugsx will search
217 for resources under the program name but you can override this with
218 the -name flag. If you do not wish to use a specific application
219 defaults file, you can execute xrdb -merge to merge your resource
220 specifications into the XResource database.
221
222 bugsx first checks in the directory pointed at by the environment
223 variable XAPPLRESDIR. If this doesn't yield any resource definitions
224 it checks the APP_DEFAULTS_DIR. This is defined in your headers or
225 in bugsx.h. If you want to change this you'll have to recompile bugsx.
226
227 background universal backgound color
228 batch run program in batch mode
229 batchbreed do not breed when running in bactch mode
230 borderColor border color
231 borderWidth border width
232 cycle re-initialize population after n batch turns
233 display display
234 extend_print show extended reproduction info while running
235 font font
236 foreground universal foreground color
237 help show help
238 mainWin.geometry main window geometry
239 iconic start program in iconic mode
240 interval interval used per turn
241 minimize minimize window size
242 menuborder draw menu borders
243 name run bugsxunder this name
244 number number of biomorphs to draw (must be a square #)
245 printpop print the population when breeding
246 reverseVideo reverse video
247 seed use this seed for random number generator
248 segments use this many segments to draw an organism
249 showbreed show breeding subpopulation when in batch mode
250 showgenes show a graphic representation of the genes
251 synchronous syncronous mode
252 verbose verbose mode
253
25412) Troubleshooting
255
256 Problem: Compile failes with a problem with the catlist() function
257 definition.
258 Solution: In terms of portability this is the most fragile part
259 of bugsx. I've done my best to make this portable, but
260 there may be systems whose compiler simply throws up once
261 he sees catlist. If you do have problems with catlist(),
262 there are a number of things you can try:
263 1) Try using another compiler (gcc generally accepts the
264 catlist() function as-is).
265 2) Undef/Define __STDC__ in your compiler directives. Most
266 compilers do this via the -U flag.
267 If these fail, you'll have to adapt catlist() for your
268 machine. In that case, accept my apologies for the problems
269 and please send me a mail telling me what you did so that I
270 can integrate your fix into the sources, sparing others of
271 this misery.
272
273 Problem: Bugsx won't find my resource definitions.
274 Solution: Bugsx handles resources as follows:
275 a) bugsx checks in the directory pointed at by the environment
276 variable XAPPLRESDIR. If this doesn't yield any resource
277 definitions we go to step b. If bugsx ignores your personal
278 resrource definitions, make sure you have XAPPLRESDIR
279 set to the proper value and exorted.
280 b) bugsx checks the APP_DEFAULTS_DIR. This is defined in your
281 headers or in bugsx.h. If you want to change this you'll
282 have to recompile bugsx.
283 The reasoning behind this approach is to allow user preferences
284 to take preference over the system preferences.
285
286 Problem: Bugsx seems to start OK but I don't get the window.
287 Solution: Check if your DISPLAY variable is set correctly (you
288 can always use the -v falg to see if it does start up
289 correctly).
290
29113) I've found a bug. What now?
292
293 Read section 11 (Troubeshooting) to see if it falls under one of
294 the problems listed there. If not either fix it yourself or mail
295 me. If my time allows it, I'll try to fix things.
296
29714) I've come up with a feature which I think would be useful.
298
299 Here again you can do 2 things:
300 1) Implement it yourself. If you do this then
301 reread section 5 (What if you change the program?)
302 to get an idea what I would like you to do with the
303 result.
304 2) Mail me. I'll consider it and if I agree with you
305 will implement it whenever I find time.
306
30715) I would like to receive future releases of bugsx.
308
309 Send me mail telling me that. Somewhere in the mail *list*
310 the email address you want to receive future releases at.
311
31216) I'm extatic about this wonderful program. How can I make the author happy?
313
314 If you really feel this way, how about a short mail message
315 telling me that you are happy about using bugsx. If you're
316 really, really extatic, send me a postcard to this address:
317
318 Steneveld 26
319 6715 HB Ede
320 Holland
321
32217) I hate this worthless program. It ruins my day.
323
324 Don't use it. Don't mail me!
325
32618) Credits
327
328 Much (maybe even most) of this program is based on the program
329 BUGS, written by Joshua R. Smith sometime 1990. I've rewritten
330 the code to run under XWindows, fixed some minor things and
331 added some options (both user interface wise as well as in the
332 breeding/mutation possiblities) here and there to make it more
333 fun to play with bugsx, but the basic engine is adapted from
334 the original BUGS version. If you are interested in other
335 BUGS ports, mail Joshua (jrs@media.mit.edu) about this or visit
336 his web page at:
337 http://physics.www.media.mit.edu/~jrs/biomorphs.ps
338