| Aquatic research and simulation software

User manual

Open a model

Menu File→ Open project… then choose the project to open in the dialog. An Uglylab project is recognizable by the Uglylab icon.

Prepare initialization scenarios

In the right panel, there are three tabs: Initializers, Observers and Meta rules

In order to create new initial conditions, i.e. what you will have at time 0, in menu Initializers→ New… or right click in the Initializers panel and choose Add Initializer…

Give a name to your new scenario and if you want, a short description. Click OK.

In the Initializers tab, you have three sub panels: Agent groups, World elements and Rules.

Define Agent groups

Define populations or groups of agent that you want to have at time 0.

In the tab Agent groups, in the list of group, right click and choose Add a group… in context menu.

Choose the agent class and the number of individuals you want to have for this group.

An agent group is a set of agents of the same type (the same class) who share some common property values at the beginning. The notion of group will disappear as soon as the time runs. It is only a convenient way to populate the world at the beginning.

Define the property values for the new created Agent group. I use the term property or parameter interchangeably.

Per default, the properties are set with their default value from the model (i.e. values from the Java class made by the modeler).

When you click on a property row, a dialog appears where you can change the value. This value can be a constant or in some cases, for compatible types (like numeric value) you can affect a distribution. Imagine that you create a group of 100 individuals and you want the values of property “age” to be uniformly distributed between 0 and 30. To accomplish this, choose UniformDistribution and enter 0 for Lower and 30 for Upper. (For now, there is only one distribution type: uniform. In a next version of the software, you will be able to choose other distribution types, like Gaussian or Poisson)

Define Rules

In the Initializers panel, click now on the tab Rules.

As you create a new initializer, Uglylab instanciates and activates all the rules defined by the model with their default parameter values. You can change a parameter value double clicking on it and entering a new value. For each rule you can define the frequency of execution, that is to say how many steps between two executions. For example, if the frequency is 1, then the rule executes every time step. If this value is set to 5, the rule will execute every 5th time step and so on. If you want the rule to be executed during 2 consecutive time steps every 5th time step, then set the frequency to 5 and the duration to 2.

The neighborhood concept

A rule defining an interaction between agent uses the neighborhood concept. It is a central concept of Uglylab enhancing greatly the computational speed. A neighborhood definition tells the program with which agent class(es) a given agent class (to which the rule applies on) interacts, the distance of interaction (radius) and the distance definition (euclidean, Manhattan distance,…) as well as the agent parameters used to calculate the distance.

Normally, default distance definitions (defined by the modeler in Rule Java Classes) are fine and you will only want to play with the radius parameter.

Note that a rule will have several distance definitions if the given agent type interacts with several other agent types.

Other things about rules

Sometimes the order of execution of rules within a time step is of importance. In the rule list you can change the priority of execution right clicking a rule in the rule list and choose Move up or Move down. The rules will be executed starting from the beginning of the list.

You can also activate/deactivate a rule clicking on the check-box before the rule.

You can also have several instances of the same rule but with different parameters. To add a rule instance, right click the rule list and choose Add a rule instance…

Create the world

Now you defined your Initializer with its agent groups and rules it is time to run your scenario. But before let us save the new created Initializer: menu Initializers → Save or Save all if you have created several scenarios. Creation or modification on Initializer are not automatically saved!

In the tool bar below the menu and above the 3D world representation, click on the second button (the one with the Erlenmeyer containing microbes). This will put all the active agent groups for the selected Initializer into your world, set the active rules who will govern this world and reset the time to zero. At this stage you are able to see the agents in the 3D window (if not, click one time anywhere in the 3D window to make it gain the focus).

Navigate the 3D world

Navigating means moving the camera. There are two modes (two cameras): a navigation mode and an observer mode. Per default you are in navigation mode. To switch between the modes click ‘S’ on your keyboard.

In navigation mode: Mouse left click rotate the camera. Arrows to move left, right, forward and backward. + and – to move up and down. Mouse wheel to zoom in and out.

In observer mode: Mouse left click rotate the camera around the selected object (origin per default).

Press ‘I’ to open the information panel. Pointing an agent will display his information (actual parameter values). Press I again to hide this panel.

Start the clock

In the toolbar you will find 4 different stopwatches: run, run 1 step, run n steps (n is defined in the option menu) and pause.

You can also set the speed of the simulation, if too fast, with the help of the slider on the left of the stopwatches in the toolbar. Slide to right will slow down the simulation. The simulation is full speed if the slider is at its leftmost position.


In the right panel, tab Observers, you can define Observers and plot them.

By default, there is one observer per agent type, giving the abundance for this type.

In order to plot this abundance over time, just right click on an observer and choose Plot this observer.

A second method is: in menu Plots → Add a plot and then drag and drop an observer from the observer panel to the new created plot. You can add several observers to one plot per drag and drop.

In addition to the plots, you can add a histogram in order to look at a distribution. For that, in the menu Plots, choose add histogram… In the add histogram dialog, choose which agent parameter you want to see the distribution over time, set the min and max value, as well as the number of bins. Two bins will be add automatically to show values greater than max and less than min.

If you have the jdk installed, you can also define custom observer (I will explain this later).

In order to remove a plot or histogram just right click on it and choose remove in the context menu.

You have also the possibility to output the observer values to a csv file (the location of this file is defined in the menu Options). To achieve that, click on the icon csv in the tool bar.

To relaunch/reset the simulation, create the world again (see section create the world).

During a simulation you can decide to change a rule, activate or deactivate one or several rules. Anytime during the simulation (time have only to be paused) make your changes in the rule panel and when you are finish click the icon looking like a ruler to tell the world rules have changed.