============================================================================== ALGAE - README 12.August 2000 ============================================================================== Contents -------- 1. System requirements 2. How to start the program 2.1 Starting the batch-mode 2.2 Starting the GUI-mode 3. Usage of ALGAE (in GUI-mode) 3.1 Creating a new simulation 3.2 Loading a previously saved simulation preset 4. Changing different settings during a simulation 5. Troubleshooting ============================================================================== 1. System requirements ---------------------- Since ALGAE is fully written in Java, the major requirement to run ALGAE is an installed version of JDK (at least version 1.2.2 recommended, previous version may cause unforeseeable troubles). The system should also have enough RAM installed since this program is very memory consuming. ============================================================================== 2. How to start the program --------------------------- The program can be started either in batch-mode or in GUI-mode. 2.1 Starting the batch-mode --------------------------- To start ALGAE in batch-mode the file "Main.class" has to be executed with the name of the settingsfile to use as parameter. For example (Win9x/WinNT systems) java -classpath ".;algae\simulation\xml.jar" Main demo3.asf If you're using Unix or Linux your command line should look something like this: java -classpath ".:algae/simulation/xml.jar" Main demo3.asf Then the program is started in batch-mode and the simulation (the one specified in the settingsfile given as parameter) is started. During the simulation several statistics are written into a file with extension "stat" (for example: if using settingsfile "demo3.asf", a statisticsfile named "demo3.asf.stat" is created). 2.2 Starting the GUI-mode ------------------------- If the file "Main.class" is called without any parameters, the program ist started in GUI-mode. For example (Win9x/WinNT systems) java -classpath ".;algae\simulation\xml.jar" Main If you're using Unix or Linux your command line should look something like this: java -classpath ".:algae/simulation/xml.jar" Main When the program is started, the settingdialog appears. This dialog is used to set all the different settings of the simulation and to finally start it. ============================================================================== 3. Usage of ALGAE (in GUI-mode) ------------------------------- This section gives you an overview of how to use ALGAE when in GUI-mode. Before a simulation could be initiated a simulation file has to be created or loaded. 3.1 Creating a new simulation ----------------------------- If you want to create a new simulation, you've simply to fill all fields in the settingsdialog. If you're satisfied with your settings you've the possibility now to save your settings to a settingsfile. To do this simply press "Save" and enter the desired filename. To start the simulation press "OK" and the program checks all settings to be valid. If this validation fails the program tells you which settings were entered incorrect and you can correct them. If your press "OK" and all settings are valid the main simulation window appears. 3.2 Loading a previously saved simulation preset ------------------------------------------------ The settingsdialog contains in the right lower corner a combobox, where you can select a simulationfile out of all simulationfiles found at startup (Note: at startup the program searches for all files with extension "asf" in the program's working directory, so it's important to save your settingsfiles with the right extension). If you want to load a settingsfile which isn't located in the progam's working directory, you can do this with the button labeled "Load". To start the simulation press "OK" and the program checks all settings to be valid. If this validation fails the program tells you which settings were entered incorrect and you can correct them. If your press "OK" and all settings are valid the main simulation window appears. ============================================================================== 4. The main simulation window ----------------------------- This is the window where the simulation takes place. In the top left corner a toolbar is located, which is used to control the simulation. Below this toolbar a textfield to change the simulation stepping is placed. In the top right corner there are several checkboxes where you can change several display settings (Note: If you want to change some settings, it's recommended to stop the simulation before doing so). At the bottom of the window there is a status bar, which contains two lines to display some informations about the current simulation. In the center of the window you can see the aquarium, which shows the simulated world. Within this aquarium you can see the following elements: - yellow boxes show the light amount at a certain position - green boxes show the substrate amount at a certain position - blue boxes show the pheromone amount at a certain position - gray filled triangles show the different agents which are shaded according to their current energy level - a red filled triangle shows the currently selected agent If you want to get more informations about a specific agent, you first have to select him. This is done by simply placing the mouse cursor over the desired agent and pressing the left button (Note: It's recommended to do this after stopping the simulation). When an agent is chosen, you may open the information window by choosing the menu-entry "Windows/Info-window". When the simulation is finished, a window pops up, which asks the user, if additional steps yould be simulated. ============================================================================== 5. Troubleshooting ------------------ Q: I'm running a previous version of JDK (older than 1.2.2). May this cause problems ? A: Since this program was developed on platforms using JDK 1.2.2, an older version of JDK may cause unforeseeable problems. It's highly recommended to update to a newer version (at least 1.2.2). Q: After a while of simulation the program throws an outofmemory-error. What can I do to prevent this? A: Seems that you don't have enough memory or Java isn't allocating enough heap-memory at startup. Try the -Xms and -Xmx parameters of Java to give the program more memory.