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