RTS3 Mini User's Guide

The RTS3 software belongs to a research project. It is not intended to be run as a stand alone application.

However, interested users may want to try it, or to try their own parameters. To get the executable download the file execv2400.zip (1044 Kb). Decompress this file in a directory where RTS3-XP will be run. The zip file contains:

-RTS3-XP.CFG (note the hyphen): should be in the same directory as RTS3_XP.EXE (note the underscore).

rts3_xp.exe is compiled on my own machine (a Pentium 4 2.80 GHz with 1 Gb memory, a graphic card NVidia GeForce4 MX440 with AGP 8X, operating system Windows XP Professional). RTS3-XP should work on any PC with the following characteristics:

500 MHz or more processor, OS Windows 2000 or XP Prof., RAM1024 Mb, graphic board with 8/16 Mb on board, monitor set to a resolution of 1280 x 1024, 256 colors (RTS3-XP can work on 640 x 480, 16 colors, but some code adjustments may be necessary).

Look first at the paper in Marine Ecol. Progr. Ser., 154 (1997) where CALIFE, the ancestor of RTS3, is explained. Most of it still applies to RTS3-XP.

Ver. 14.1 has major changes. Now it is possible to create 2 salp populations with different parameters values in the same environment. The simulation results can be viewed by clicking with the mouse on a menu item. The Help menu has a submenu "Creatures Codes". Ver. 14.2 has some improvements and corrections.

From ver. 17.00 on, a major restructuration of the graphic interface has been devised, and the simulation code corrected on important points.

When the program is run, a 'console window' appears first, asking "**Debug** Command? ('H' for help) :"
Do not answer by hitting <Return>, this is for advanced users, see below under "Debugging help". Press the 'i' key, and then <Return> (or Enter).

The parameters values are then read in RTS3-XP.CFG or any other conformant configuration file. By clicking on Edit and its submenus you may see or change many parameters .
When you are satisfied with the parameters values, click <Simulation> and then <GO>. Two questions are asked during 1.5 seconds. If you don't hit a key during this lapse, a screen appears asking "Press <Esc>, <Return> or <Space> to start the simulation". When one of those keys is pressed , the simulation begins.

I tried to use most of the screen surface for displaying the creatures. As a consequence only 2 lines at the bottom are not used to display the zooids and Vibilia: the Status line and the Message line. Once a simulation is started, it can be aborted by pressing the Delete key or the End key.

If in Edit> General parameters>" Presence of Vibilia" is checked (and in Vibilia parameters Infestation lag is made equal to Simulation duration (the default)), the left mouse button can be used (once) to create a Vibilia at any location. This is useful to create the first Vibilia near a group of zooids to increase the probability of starting an infestation. Otherwise the female will have no chance to deposit her larvae.

When Simulation duration is elapsed, the numbers of zooids created, etc. are displayed. The last time <Esc> is hit, the End of simulation window is displayed (the one with a yellow background). You can save the results (with a 'comma delimited' format which can be read by many spreadsheet or plotting programs), and also you can save the current parameters values (back in RTS3-XP.CFG or in any other file).

When it is done, click anywhere and you are back in the introductory window (the one with a blue background).
(Note: to run again a simulation, it is necessary to re-start the program).

If things go wrong, click the "gexecute" icone in the task bar to shut down the program (don't leave one of them running).

The first parameter, Simulation mode, in RTS3-XP.CFG governs the way the creatures are displayed on screen. The normal mode is PIX. In this mode the grid is the largest possible (312 x 230 cells), allowing the creatures to stay within the frame. As there is food only in a centered square area 1/8 the surface of the grid, zooids reaching the outer area do not develop much.

The CHAR mode is preferred for debugging. In this mode creatures are displayed as alphanumeric characters, allowing a better identification of their state. This obliges to have a smaller grid, and as the frame boundaries are 'reflecting boundaries', the zooids return where they have already fed, so that any ecological conclusion would be biased.

The screen represents a rectangular grid with discrete locations on which the creatures stay and move: this is the "swimming area". From vers. 7.0 on, the swimming area is considered viewed from above, i.e. there is no depth dimension. This was done because each location represents the average stay of a zooid during a 'mean day' -- thus buffering any diel vertical migration. Cadavers no longer sink as in the previous versions: they are just seen shortly in place before they disappear below the surface (but they remain under program control until they are completely decomposed).

Food can be present in the central part of the swimming area (called the food area). In the current version the food area represents 1/8 of the swimming area (this proportion is hard_coded, this can easily be changed but then the program needs to be recompiled). This was chosen in order to observe the increase and subsequent extinction of the population. Parameters in RTS3-XP.CFG allow to distribute initially the food in every location of the food area, or according to a checkerboard pattern with different pavement sizes. As it is not possible to show the food and the creatures, only the initial and final food distribution can be displayed.

On each 'mean day', each creature moves (in parallel) to occupy the next adjacent empty location on the underlying bidimensional grid. A location is "empty" if it is not occupied by another creature (zooid orVibilia) or by an obstacle like the frame. (The creatures should not encounter the frame, at least in PIX mode; there is no such thing in the open ocean). The "next" adjacent location is one of the eight (or four) locations around the current position, in a direction chosen randomly clockwise or counterclockwise. Food is peridodically renewed, but not where it has been exhausted. If all the 8 (4) locations are occupied (this may happen in a dense bloom) or devoid of food, the move tentatives are postponed until the next 'day', where the situation may have changed. If it did not after 10 such cycles, the zooid is "suppressed", i.e. it dies from overpopulation (or from starvation).

Vibilia moves are somewhat different from zooids. To be able to attack zooid preys or hosts, a Vibilia must swim faster than zooids. During a Vibilia dayly cycle several moves (called 'jumps') are performed in straight line. At the beginning of each jump the Vibilia explores its environment in all allowed directions (8 or 4) over a distance of Search_Radius. If during this search a n attackable zooid (this depends on the Vibilia state) is found, the jump is interrupted and the Vibilia leaps directly on the zooid location, devours the zooid or put its larvae on it. If no attackable zooid is found at the end of the search, the Vibilia changes randomly its swimming direction.

In RTS3 all creatures have a nominal longevity, which is the maximum age they may reach if they find enough food. Zooids may also die prematurely if they are attacked or infested by a Vibilia. Besides this "natural" mortality, it is possible to add an "accidental" mortality, to mimic other mortality factors such as being eaten by a predator or being killed by a micro-organism. This accidental mortality is defined as the percentage of individuals which die from unknown factors before being able to reproduce. These individuals are not suddenly eliminated, but die at an age randomly set between birth and maturity.

Note that to compute mortality the random generator is used twice: first to see if the individual will die prematurely and then to determine at what age before maturity.

In the case of a zooid parasited by a Vibilia, if either of the two partners dies, the other one also dies.

The meaning of 'Time constriction'

Ideally, to get true parallelism each creature task should execute on its own processor. With only one processor, pseudoparallelism is obtained by the GNAT runtime by giving only a very small amount of CPU to each task in turn. For each daily cycle, the computations demand only a few milliseconds of CPU, the rest being spent in a 'delay' statement until the Internal_Pace duration is elapsed. In Ada a delay statement is a "synchronization point"; at this point the CPU can be given to the other tasks.

However, when several hundred creatures are active there may be not enough time left, because of the total duration of hundreds of 'context switches' to allow the creature, when it regains the CPU, to finish its daily cycle. There is no solution to this problem other than running the program on a faster processor. In RTS3-XP, if the creature cannot finish its cycle in time, a warning is emitted ("Time constriction in a zooid" or "in a Vibilia") and an extra "mean day" is alloted to the creature.

With the Constant Food option set to Yes, any food amount consumed by a zooid is put again at the same location in the environment. The zooid uses it to make reserves, but the environment is never depleted: each zooid always find what it needs (up to the initial food value). This option, together with Pavement Size = 0 (no empty locations), allows to eliminate the influence of food heterogeneity: whatever the path followed, each zooid finds the same amount of food. This option may be useful to tune a metabolic parameter.

If set to Yes, a moving zooid swims in only one of 4 directions (Moore neighborhood): N, E, S, or W. No gives a von Neumann neighborhood: 8 directions, N, NE, E, SE, S, SW, W, or NW. This choice was programmed when I realized that a zooid moving in a diagonal direction in a von Neumann neighborhood could, with an inadequate starting location, never encounter food. But this can only lead to extinction at the beginning of the simulation. Later on, zooids randomly change their swimming direction. Eight directions permit to better exploit space. It is the preferred option.

If all the zooids reproduce at exactly the same age, the simulation resemble a cellular automaton. Moreover, when hundreds zooids reproduce at the same time, there are scheduling problems: as only one zooid may allocate computer memory to reproduce, the others are queued waiting to receive the control from the scheduler. These problems are lessened when a small variability is added. This is obtained by making the embryonic phase slightly variable (the other development phases, depending on the reserves level, are by themselves already variable). Unless specially needed, the preferred value is thus Yes.

In Vers. 10.0 a lot of attention has been paid to the development of the Vibilia population. The problem was challenging because zooids and Vibilia live asynchronously. When a Vibilia attacks a zooid, the zooid cannot respond immediately to the attack because of scheduling problems when simulating concurrent processes on a monoprocessor. When the Vibilia attacks, the processor is not executing a part of the zooid code: when zooids are numerous the zooid will regain control many 'time slices' later. The attacking Vibilia must suspend its computations until the zooid acknowledges it was attacked.

A satisfactory treatment of the zooids infestation by Vibilia was only attained in Vers. 17.04.

In addition Vibilia have more stages than zooids, with often a different behavior. This results in a great number of combinations, making testing difficult.

Each simulation run is slightly different from the previous one. Two hundreds runs made with the same parameters show for the number of oozooids produced a coefficient of variation of 12.7 % (8.0 % for the chains). The pseudorandom generator uses exactly the same seed for each run, and only one pseudorandom sequence (protected from concurrent access) is used throughout the simulation. It is possible to eliminate the variability by setting in RTS3-XP.CFG Constant Food to Yes and Pavement Size to 0, (see above for these options). Slight differences when the oozooids emitted by a chain are created, exaggerated by the exponential mode of reproduction, explain the remaining small differences, if any. The only means to obtain a confidence interval is to run the simulation with exactly the same parameters a great number of times.

IMPORTANT: The outcome of RTS3 is hardware-dependent. It is not valid to compare the results obtained on a given machine with those obtained on another machine, even with exactly the same parameter values. However, it is valid to statistically compare a number of simulation runs made with a certain parameter value, with another number of runs made with a different value, provided the comparison is made on the same machine (with no other CPU-demanding application running in the background).

Note that if Internal_Pace is too short for the processor, a message "Warning: Time constriction in a Vibilia" or "-- in a zooid" is displayed. If this does not occur often, just exclude the run(s) from any statistical test. If the number of 'time constrictions' (displayed in the results screens) is too large, it is necessary to increase Internal_Pace (or to run the simulation on a faster CPU).

The categories are: 1 non-mature oozooid, 2 mature ooz., 3 non-mature aggregate, 4 mature aggr., 5 ooz. cadaver, 6 chain cadaver.

Similarly, if Vibilia_Present = Yes in General parameters, the coordinates of the Vibilia are recorded in another text-file. The symbol for the live Vibilia category is *, forVibilia cadavers +.

Note that if it is necessary to catenate these two text-files in a single file, this may be done with the DOS Copy command (using "+").

The numbers of zooids created each 'day' during the simulation, may be recorded in a text-file whose name is asked to the user. The numbers ouput on each line (ending with a comma) are, in this order:

Interval #,
Number of live oozooids,
Nb of live chains,
Nb of oozooid cadavers,
Nb of ooz. killed (by Vibilia),
Nb of chain cadavers,
Nb of chains killed,

From vers. 6.3 on, RTS3 includes a Random_Sampling task, used to simulate the sampling of the salp population. This task writes a SAMPLES.TXT file in the Exec directory. Its parameters are currently hard-coded, the user cannot change them unless the program code is modified and recompiled. This was intended for a punctual experiment, but I leaved it here as it does not harm.

Because in RTS3-XP tasks are generated in a recursive manner, I found debugging this program difficult until J.P. Rosen from ADALOG pointed out that his Debug program could be useful in this case. It was, so I incorporated his utility in RTS3. I could remove it before making the code available on the web, but I cannot claim that there are no more bugs, so I left it. It is also useful if you want to understand what happened to a creature, why it died, and so on. If you don't want to use it when just running the program, enter 'i' (ignore) when a window pops up at the beginning, prompting for "Command? (H for help)".
Otherwise If the user anwers by pressing 'Enter' instead of 'i' [Enter], a file named trace will be written in the executable directory. Depending on the setting of the parameters Debug_Zooids or Debug_Vibilia in the configuration file, 0 or more zooid or Vibilia tasks will be traced in this file. If there are several tasks, their ouputs are interlaced. To cope with this situation, proceed as follows:

1. Rename trace as trace-xxx.txt (xxx being the date or anything you want to identify the run).
2. View the file in Wordpad or any text editor, and search for the string 'Zooid No' or 'Vibilia No'. To find the ID of the creature you want to debug, look for a line like (if you want to trace the Vibilia # 5):
**Debug** (S61b_00EBAF00) : Vibilia No. 5
S61b_00EBAF00 is the ID of the Vibilia # 5. Then in a DOS Windows use findstr (similar to Unix grep) to find all lines with this ID and redirect the output to a file:
findstr /c:"S61b_00EBAF0" trace-xxx.txt > [filename].txt

ERROR conditions:

If during the creation of zooids the exception Storage_Error is raised, the simulation is stopped with the message ">MEMORY in a zooid !" or "in a Vibilia". >MEMORY stands for Memory Allocation Error (it is sometimes not possible to regain the control after this exception, which may occur if there is too much food or if the simulation is too long).
If the program is frozen: with Windows NT/2000 click on RTS3_XP.EXE or "gexecute" on the task bar, and close the window with the 'X' in the upper right corner.
If too many context switches occur and the processor is not fast enough, the message "Time constriction in a zooid" (or "in a Vibilia") shows up. The value of the parameter Internal_Pace (normal value about 1000) should then be increased; but the simulation will last longer (for the user). With a 450 MHz processor, do not set Internal_Pace below 1000).