home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / graphics / megajr13.lha / MegaJitter / README < prev    next >
Text File  |  1994-05-30  |  19KB  |  559 lines
  1. *****************************************************************************
  2. *                                                                           *
  3. *                    PUBLIC DOMAIN SOFTWARE LICENSE                         *
  4. *                                                                           *
  5. *                    ++++++++++++++++++++++++++++++                         *
  6. *                                                                           *
  7. *                                                                           *
  8. * The following program(s) and/or data file(s) are declared Public Domain.  *
  9. *                                                                           *
  10. * Conditions of use:                                                        *
  11. * ------------------                                                        *
  12. *                                                                           *
  13. * 1) No part of this distribution will be omitted (incl. this README file)  *
  14. * 2) None of the Copyright texts will be modified or deleted.               *
  15. * 3) None of the files should be stored and/or converted onto environment-  *
  16. *    ally damaging media. (paper listings, faxes, etc...)                   *
  17. *                                                                           *
  18. * Provided the end user sticks to the above mentioned author's wishes, he   *
  19. * or she is authorized to use, copy, analyze and improve the items.         *
  20. *                                                                           *
  21. *                                                                           *
  22. * The Author,                                                               *
  23. *                                                                           *
  24. * Laurence VanhelsuwΘ                                                       *
  25. *                                                                           *
  26. * Auroville 19/MAY/94 (India)                                               *
  27. *                                                                           *
  28. *                                                                           *
  29. *****************************************************************************
  30.  
  31.                       -------------------------------
  32.                       Program Title: MegaJitter  V1.3
  33.                       -------------------------------
  34.  
  35.                         Author: Laurence VanhelsuwΘ
  36.  
  37.  
  38.  
  39.  
  40.  
  41.             0. Short description
  42.  
  43.             1. Requirements/Installation
  44.  
  45.             2. How to use it
  46.  
  47.             3. Internals
  48.  
  49.               3.1 Command Line Options
  50.  
  51.               3.2 Creature Genes
  52.  
  53.               3.3 AREXX Support
  54.  
  55.               3.4 Speed Optimizations
  56.  
  57.             4. Limitations/Warnings
  58.  
  59.             5. History
  60.  
  61.             6. Future
  62.  
  63.             7. Bibliography
  64.  
  65.             8. Credits
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. 0. Short description:
  73.    ------------------
  74.  
  75. MegaJitter (from now on: MJ) is a biological Evolution simulator.
  76. It tries to simulate a simple ecosystem with creatures which eat, get born,
  77. procreate and die.
  78.  
  79. Believe it or not, but without ANY pressure on the program's part, these
  80. creatures often EVOLVE into new species which are optimally adapted to their
  81. environment !
  82.  
  83. Many different environment scenarios can be configured for MJ, with totally
  84. different species emerging.
  85.  
  86. The main "Laws of Nature" the program codifies are as follows:
  87.  
  88. - if you eat food, you get X energy points
  89. - moving costs energy
  90. - if you run out of energy, you die.
  91. - if you reach a fitness threshold, you're allowed to procreate.
  92. - any offspring get copies of your genes, but in slightly mutated form.
  93.  
  94. MJ Doesn't have miracles, the Fittest Survive, that's the bottom line.
  95.  
  96. On the Amiga, MegaJitter's dual-screen approach offers a full screen of
  97. graphical statistics plus the actual ecosystem with pixels representing food
  98. and creatures.
  99. For research purposes, the animated ecosystem can be disabled for faster
  100. simulations (overnight runs for example).
  101.  
  102.  
  103. 1. Requirements/Installation:
  104.    --------------------------
  105.  
  106. This Release (V1.3) contains the following directories/files which should
  107. be copied into an empty directory called "MegaJitter" (or something like it).
  108.  
  109. ==================================================
  110.      SCENARIOS (dir)
  111.        CHAINREAC                        Clusters
  112.        Hedges                           Oasis
  113.      REXX (dir)
  114.        GOD                              MSC
  115.   .Product-Info                    ja.s
  116.   makefile                         mj
  117.   mj.c                             mj.wth
  118.   README                           SCOPTIONS
  119. ==================================================
  120.  
  121. Required:
  122. ---------
  123.  - V39 of the Amiga OS.
  124.  - a 68020-based Amiga or better.
  125.  - at least 1.5 Mb of RAM to run.
  126.  
  127. Optionally:
  128. -----------
  129.  - AREXX for external program control.
  130.  
  131.  
  132.  
  133.  
  134. 2. How to use it:
  135.    --------------
  136.  
  137. This distribution actually contains 3 programs: MegaJitter (MJ) proper and
  138. two supporting REXX utilities.
  139.  
  140. For MegaJitter itself, 
  141.  
  142. Just type:    "MJ"
  143.  
  144. Or        "RUN MJ"
  145.  
  146. or MJ followed by any of the command line options.
  147. (type "MJ ?" for a list or see below for details)
  148.  
  149.  
  150. The two REXX programs are GOD and MSC and control or configure MJ, respectively.
  151.  
  152. - MSC Stands for "MJ Set Scenario" and takes one argument: a MegaJitter scenario
  153.   file.
  154.  
  155. For example, to configure the "Oasis" scenario you would type:
  156.  
  157.     RX MSC SCENARIOS/OASIS
  158.  
  159. 'RX' Is of course the REXX program dispatcher. You can omit this if you are
  160. using a Shell which allows direct execution of REXX programs.
  161.  
  162. - GOD Is a MegaJitter scenario finder. It generates random sets of starting
  163. parameters and configures MJ to use them.
  164. Then, for about 15 minutes it monitors the running, simulated environment
  165. to see if the parameters result in a stable ecosystem.
  166. If so, it dumps the settings to the screen, otherwise it kills off the failing
  167. ecosystem and generates a new set of parameters, ad infinitum.
  168.  
  169. Use as follows:
  170.  
  171.     RUN RX GOD >godlog        ;capture all output in file 'godlog'
  172.  
  173.  
  174.  
  175. 3. Internals:
  176.    ----------
  177.  
  178. 3.1 Command Line Options
  179.     --------------------
  180.  
  181. The CLI command template for MegaJitter is :
  182.  
  183. AUDIT/S,DATALOG/S,NOANIM/S,VISION/S,SEX/S,SHOWDEFAULTS/S,MAX_BUGS/K,
  184. INIT_BUGS/K,INIT_FOOD/K,INIT_ENERGY/K,INIT_VARIANCE/K,MUTATE_RANGE/K,
  185. FOOD_RATE/K,FOOD_ENERGY/K,X_AND/K,Y_AND/K,OASIS_SIZE/K,NTSC/S
  186.  
  187. For those not yet 100% familiar with the 2.0 DOS template syntax, here's
  188. a quick guide:
  189.  
  190. labels followed by:
  191.  
  192. /S mean that they are used on their own to enable some feature (a |S|witch)
  193. /K mean that they should be followed by a value (a |K|eyword)
  194.  
  195. Note: numerical parameters have lower and upper limits. See section 3.3 for
  196. figures.
  197. -----------------------------------------------------------------------------
  198. AUDIT        Enable full internal audit of creature processing.
  199.         This will show you (in the CLI window) what each particular
  200.         bug is doing, and sometimes, why.
  201.  
  202.         Example: MJ AUDIT NOANIM INIT_BUGS 1
  203.  
  204.         Default: AUDIT is OFF
  205.  
  206. -----------------------------------------------------------------------------
  207. DATALOG        Dumps the statistics in numerical form to STDOUT.
  208.         This is useful if you want to capture the statistics for
  209.         further analysis, like correlation of variables, etc...
  210.  
  211.         Example: MJ DATALOG NOANIM INIT_FOOD 1000 > MJ_RUN043.DAT
  212.  
  213.         Default: DATALOG is OFF
  214.  
  215. -----------------------------------------------------------------------------
  216. NOANIM        Inhibits the opening of the animation screen and lets the
  217.         program use a much more efficient representation for the
  218.         ecosystem, allowing faster simulations.
  219.  
  220.         Example: MJ NOANIM
  221.  
  222.         Default: NOANIM is OFF
  223.  
  224. -----------------------------------------------------------------------------
  225. VISION        Enables the VISION capability (gene) for all creatures.
  226.         With VISION on, creatures can SEE food and override their
  227.         genetic movement pattern somewhat so that they can home in
  228.         on food directly.
  229.  
  230.         Normally creatures are completely blind and rely on bumping
  231.         into food frequently enough to survive.
  232.         Vision gets modulated by the DAY/NIGHT oscillator.
  233.  
  234.         Example: MJ VISION AUDIT INIT_BUGS 35 OASIS_SIZE 20
  235.  
  236.         Default: VISION is OFF
  237.  
  238. -----------------------------------------------------------------------------
  239. SEX        Enables the SEXUAL reproduction gene for all creatures.
  240.         Normally creatures just split asexually when they can,
  241.         producing offspring with slightly mutated copies of the
  242.         "mother" creature.
  243.  
  244.         With SEX on, creatures can be 0..100% sexual creatures.
  245.         100% Sexual means that the creature always needs to find a
  246.         sexual partner to procreate. Only partners which are at
  247.         least as healthy as the originator are chosen.
  248.  
  249.         Example: RUN MJ SEX OASIS_SIZE 20 FOOD_RATE 2
  250.  
  251.         Default: SEX is OFF
  252.  
  253. -----------------------------------------------------------------------------
  254. SHOWDEFAULTS    Dump settings of all internal parameters.
  255.  
  256.         Handy to find out the built-in default scenario settings or
  257.         to see what the resultant settings look like when you
  258.         override some or all of the built-in defaults on the command
  259.         line.
  260.  
  261.         Example: MJ INIT_BUGS 100 MUTATE_RANGE 20 SHOWDEFAULTS
  262.  
  263.         Default: SHOWDEFAULTS is OFF
  264.  
  265. -----------------------------------------------------------------------------
  266. MAX_BUGS    Maximum number of creatures the simulator can handle.
  267.         The program dynamically allocates an array to hold MAX_BUGS
  268.         creature structures.
  269.  
  270.         Example: MJ MAX_BUGS 500
  271.  
  272.         Default: 300
  273.  
  274. -----------------------------------------------------------------------------
  275. INIT_BUGS    Initial number of creatures when program starts.
  276.         The initial population consists of completely random
  277.         creatures.
  278.  
  279.         See also INIT_VARIANCE.
  280.  
  281. -----------------------------------------------------------------------------
  282. INIT_FOOD    Initial amount of food (-pixels) strewn across the plane.
  283.  
  284. -----------------------------------------------------------------------------
  285. INIT_ENERGY    Average starting fitness of creatures.
  286.  
  287. -----------------------------------------------------------------------------
  288. INIT_VARIANCE    Initial genetic variance in the starting creature pool.
  289.         This variance is distributed evenly around middle value (128).
  290.  
  291. -----------------------------------------------------------------------------
  292. MUTATE_RANGE    Allowable aggressiveness of mutations.
  293.  
  294.         If it's too low, then your creatures will not evolve, as
  295.         they won't be able to "jump" the required distance to find
  296.         new, stable genetic configurations.
  297.  
  298.         If it's too high, then genetic inheritance breaks down,
  299.         since offspring now essentially become random creatures
  300.         again, and bear no resemblance to their parents.
  301.  
  302. -----------------------------------------------------------------------------
  303. FOOD_RATE    Rate at which food grows.
  304.         For every N timesteps, the program puts down one food unit.
  305.         Therefore smaller values mean higher food growth rates.
  306.  
  307.         Example: MJ FOOD_RATE 1          ;highest food growth rate!
  308.  
  309. -----------------------------------------------------------------------------
  310. FOOD_ENERGY    How much one food pixel packs in energy.
  311.  
  312. -----------------------------------------------------------------------------
  313. X_AND
  314. Y_AND        These two parameters can affect the way food is distributed
  315.         in normal (non-OASIS, see below) mode.
  316.  
  317.         As random (x,y) coordinates are generated to grow some food,
  318.         the coordinates are always ANDed with X_AND and Y_AND respec-
  319.         tively.
  320.  
  321.         This allows you to grow food in straight "hedges", either
  322.         vertically or horizontally, or even simulate rectangular
  323.         fields of growing food.
  324.  
  325.         Default: 1 (for both)
  326.  
  327. -----------------------------------------------------------------------------
  328. OASIS_SIZE    If this parameter is set, food will grow only within a
  329.         circle in the middle of the screen.
  330.         OASIS_SIZE is the radius of the circle.
  331.         X_AND and Y_AND are not active in this mode.
  332.  
  333. -----------------------------------------------------------------------------
  334. NTSC        This option forces the program to open a shorter statistics
  335.         screen, to support American NTSC monitors/Amigas.
  336.  
  337. -----------------------------------------------------------------------------
  338.  
  339. 3.2 Creature Genes
  340.     --------------
  341.  
  342. Nearly all genes have a numerical meaning which control a PROBABILITY.
  343.  
  344. Internally, genes are encoded as BYTEs (unsigned) so the numerical range
  345. per gene is 0..255.
  346. Some genes use this scaled up (like the age genes) or scaled down (like the
  347. vision gene).
  348.  
  349. Here is the full list of genes implemented so far:
  350.  
  351. right, left    : these two genes control a creature's movement pattern.
  352.           If for example gene 'right' is nearly 100% (ie 255), then
  353.           it is nearly 100% certain that the current bug is going
  354.           to make a CLOCKWISE turn of 45 degrees on his next step.
  355.  
  356.           Gene 'left' similarly controls ANTI-CLOCKWISE turns.
  357.  
  358.           If for example both genes are close to 0% then the bug
  359.           will essentially move in a straight line.
  360.     
  361. speed        : This gene determines a moving DELAY.
  362.           0 Means no delay, 255 means max delay, resulting in a
  363.           very slow creature.
  364.           (scaled down to 0..7)
  365.  
  366. dying_age    : 0..65535. Designed built-in lifespan.
  367.           If a creature is very healthy when he/she reaches this
  368.           age, then his energy level is used to counteract this
  369.           guideline limit.
  370.  
  371. minsexage    : 0..4095. Minimum age before a bug can procreate.
  372.  
  373. maxsexage    : 0..65535. Maximum age for procreation. 
  374.  
  375. procr_energy    : 0..16384. Minimum energy before procreation can begin.
  376.  
  377. foodtype    :   0.. 63: mainly HERBIVORE
  378.            64..191: mainly OMNIVORE
  379.           191..255: mainly CARNIVORE
  380.  
  381.           Since the gene is used probabilistically, a 99% carnivore
  382.           can sometimes be seen to eat grass !
  383.  
  384.  
  385. vision        : 0..63. Vision range in pixels, in the current moving
  386.           direction. Bugs don't have peripheral vision AT ALL.
  387.  
  388.           When many bugs have good vision, the program has to do a
  389.           LOT of work just to support the vision element !
  390.  
  391.  
  392. sexuality    : Like foodtype, probabilistic gene. 0 = ASEXUAL to 255 =
  393.           SEXUAL. Anything inbetween gives you biased mixtures.
  394.  
  395.           Sexual reproduction requires a mate physically touching
  396.           the sexually mature creature ! (Difficult to get in desserts
  397.           with just a few creatures roaming around !).
  398.  
  399.  
  400. 3.3 AREXX Support
  401.     -------------
  402.  
  403. Currently the following AREXX commands are implemented:
  404.  
  405. "MJ_QUIT"            Quits MJ immediately.
  406. "MJ_RESET"            Restarts a simulation with current settings.
  407. "MJ_DUMPDEFAULTS"        Dump settings to CLI window.
  408.  
  409. "MJ_SEX"            Enable Sex Genes.
  410. "MJ_NOSEX"            Disable.
  411. "MJ_VISION"            Enable Vision Genes.
  412. "MJ_NOVISION"            Disable.
  413.  
  414. The following commands are QUERIES, which return information via the RC
  415. special AREXX variable. Use RC to retrieve values.
  416.  
  417. "MJ_BUGS?"            Queries the number of bugs living.
  418. "MJ_RUNS?"            Queries the number of simulation runs so far.
  419. "MJ_TIMESTEPS?"            Queries the age of the current simulation.
  420.  
  421. The following global parameters can be set at any time by using a syntax
  422. like the following:
  423.  
  424.     <PARAMETER_NAME> <value>
  425.  
  426.  
  427. PARAMETER_NAME          LOWEST  HIGHEST
  428. --------------          ------  -------
  429. "INIT_BUGS"          1      100
  430. "INIT_FOOD"          1      30000
  431. "INIT_ENERGY"          10      15000
  432. "INIT_VARIANCE"          1      250
  433. "MUTATE_RANGE"          1      120
  434. "FOOD_RATE"          1      100
  435. "FOOD_ENERGY"          1      5000
  436. "X_AND"              1      260
  437. "Y_AND"              1      260
  438. "OASIS_SIZE"          0      50
  439.  
  440. Note that each parameter has a minimum and maximum acceptable value which
  441. should not be exceeded.
  442. Also note the LACK of the "MJ_" prefix (sorry).
  443.  
  444.  
  445. 3.4 Speed Optimizations
  446.     -------------------
  447.  
  448. Instead of using WritePixel() and ReadPixel() I wrote my own optimized
  449. versions.
  450.  
  451. Since the ecosystem screen is 512x512 (x4), I eliminate the overhead of
  452. having generic code for variable screen dimensions.
  453.  
  454. Also, for the general plot_pixel I have an array of pixel-setting routines,
  455. one for each pen value. This eliminates the typical shift register, then
  456. set or clear the bit-loop.
  457.  
  458. Since most pixels in MegaJitter will have to be erased again because of the
  459. mobility of the creatures, plot_pixel actually caches the end results of
  460. its calculations (the byte offset and the bit number), so that we can have
  461. a very, very fast fastwipe_pixel.
  462.  
  463. Since checking for a food pixel or empty pixels is also very common, I also
  464. wrote custom routines for that.
  465.  
  466. Late in development I converted all the above routines to even faster ones
  467. by having the screen as an INTERLEAVED bitmap.
  468. This allows the use of just one pointer to the bitmap (instead of 4
  469. previously), which simplifies code quite a bit, thus speeding it up again.
  470.  
  471.  
  472. 4. Limitations/Warnings:
  473.    ---------------------
  474.  
  475. Internally, a gene is encoded as a byte having a numeric range of 0..255.
  476.  
  477. The random number generator uses the Amiga video beam x/y position register
  478. to help randomize the numbers; because of this you can't currently replay
  479. EXACTLY a previous simulation, as the random numbers are REALLY random !
  480.  
  481. Occasionally, you might observe some BUG warnings about rogue pointers and
  482. the like... these are harmless in this release.
  483.  
  484. 5. History:
  485.    --------
  486.  
  487. I started writing MegaJitter in 1992 when I had become addicted to watching
  488. a similar program, called "Jitter" (by Don Reble & Chris Gray), for hours and
  489. hours and hours.
  490.  
  491. In the beginning I even tried analyzing Jitter's run-time behaviour (with
  492. homebrew tools like HeartBeat (also PD)) to see if I couldn't optimize the
  493. speed by patching this or that. I was horrified to learn that Jitter used
  494. something like RectFill() to draw its bugs on the screen... obviously a quick
  495. hack !
  496.  
  497. The answer was clear: I would have to write my own, but optimized for speed.
  498.  
  499.  
  500. 6. Future:
  501.    -------
  502.  
  503. I am acutely aware that my simulation is not "open ended", like Nature really
  504. is. By this I mean that, apart from the millions of permutations possible
  505. with the genes and the environmental parameters, MJ is CLOSED. It won't let
  506. new "Laws of Nature" evolve, or let the creatures develop any intelligence.
  507. They can't develop brains... yet.
  508.  
  509. A desirable future change would be to give creatures private, programmable
  510. "program space" so that they can learn, remember, re-program their
  511. behaviour.
  512.  
  513. There should be no distinction between inanimate "grass" food and living
  514. moving grazers.
  515.  
  516. On the Human Computer Interface front (and what a battlefield it is !), I
  517. would like to add a fully interactive control panel with sliders and
  518. switches to control MJ further.
  519. I am thinking of using the REXX interface to implement this.
  520.  
  521. Further speed optimizations are possible.
  522. The handle_bug routine should be the focus of attention as it is the
  523. bottleneck.
  524. The whole program should also be re-compiled with the new register parameters
  525. option.
  526.  
  527.  
  528. 7. Bibliography
  529.    ------------
  530.  
  531. "Artificial Life: The Quest for a New Creation" by Steven Levy
  532. ISBN 00-224-03599-1 (PUBLISHER: Jonathan Cape)
  533.  
  534. This is an INCREDIBLE book. Worth getting a copy if you're remotely
  535. interested in this program.
  536.  
  537. See also:
  538.  
  539.   - the original 'Jitter' (by Don & Chris)
  540.  
  541.   - 'Evolution' on Fish Disk #239 (by Russel Yost)
  542.  
  543.  
  544.  
  545. 8. Credits:
  546.    --------
  547.  
  548. The following address is my home base (where I haven't lived for 8 eight
  549. years now) but where things will bounce off to wherever my real, current
  550. address is (like India for the mo!).
  551.  
  552. Laurence VanhelsuwΘ
  553. Christinastraat 105
  554. B-8400 Oostende
  555. Belgium
  556.  
  557.  
  558. Original stimulus: Don Reble & Chris Gray's "Jitter"
  559.