Chapter 12 The EvoLudo code

For more serious simulations, execution speed is of the essence and that’s where JavaScript is lacking. Fortunately, EvoLudo is written in Java and hence can be compiled and run as a regular java application. In fact, the command ’mvn install’ in section 12.1: Quick start also creates an executable jar-archive in ./EvoLudoJRE/target/EvoLudo.<version>.jar. The jar-archive is a self-contained executable file that includes all the necessary libraries and resources. It can be copied to any location and executed without any further dependencies and accepts all the settings as command line options.

All settings that are passed to the web version of EvoLudo can also be passed to the jar-archive as command line options. In addition, the jar-archive offers a number of options to control simulations that are not available when running in the browser. For a complete list see section 11.2.5: Simulation options or execute ’java -jar EvoLudo.<version>.jar --help’ in the terminal. By default, EvoLudo.<version>.jar runs in headless mode (without GUI) and writes all output to the terminal. The option --gui launches EvoLudo.<version>.jar as a legacy Java application. For example, try ’java -jar EvoLudo.<version>.jar --module 2x2 --gui --geometry R4’ to launch an old-fashioned Java application GUI for a $2\times 2$ game on a random graph with average degree $\overline{k}=4$.

1. 1.

   Reproducible simulations using the command line option --seed[=<seed>] where <seed> is an arbitrary integer number (defaults to zero). For examples, compare Exercise 13.18 and Exercise 13.19 in section 13.12.2: The --export option or Exercise 13.20 in section 13.12.3: The panic file.

2. 2.

   The GWT application produces identical output as the java simulations. In fact, the state of any EvoLudo module/model can be exported in one framework and continued in the other again with identical results. For an example compare the output of Exercise 13.5 in section 13.7: Adding statistics modes and Exercise 13.17 in section 13.12.1: The --data option.

3. 3.

   Prepare for the unexpected: if simulations get inadvertently killed, a panic-<date>.plist file is generated with the <date> replaced by the date and time of the shutdown. The file contains the state of the simulation before it was shutdown and hopefully allows to recover some work that has already been accomplished. For an example, see Exercise 13.20 in section 13.12.3: The panic file.

All code in the maven module EvoLudoCore is shared by both the GWT and JRE environments and must be agnostic of the specific features of GWT or JRE. GWT produces JavaScript code, but JavaScript code is much more lenient than JRE and java.

A notorious example is accessing elements of an array outside the allocated range. For example, the following code snippet

int[] a = new int[3];

int b = a[3];

a[3] = 42;

is perfectly fine in JavaScript (and GWT). The field b is left undefined and the length of the array a is increased to four. In contrast, in java the code compiles fine but throws an ArrayIndexOutOfBoundsException at runtime and exits. In principle, an exception would be thrown on both the second and third line, but execution never gets to the third.

Some edge cases in numerical evaluations are also handled differently. For example, consider the following code snippet

double x = 1.0 / 0.0;

int y = 5 % 0;

is perfectly fine in JavaScript (and GWT) and compiles in java. However, java throws an ArithmeticException at runtime for both lines, while JavaScript assigns Infinity to x and NaN to y.

Most coding errors are already caught and highlighted by the VS Code editor. However, occasionally an error in the code may go unnoticed, which then causes the GWT compiler to fail when reloading the browser window. Instead of the EvoLudo user interface, the Google Chrome browser simply displays an overlay panel with the message failed and a button to Try Again, see Fig. 12.1.

In order to see the actual error, click on the failed message to open another tab with the detailed error message and stack trace. The error message is usually very informative and helps to locate the problem. Once the error in the code is fixed you can click Try Again or reload the browser window once more to see the updated EvoLudo.

Sometimes the java IntelliSense mechanism of VS Code seems to get confused resulting in unreliable code completion or popup info panels. The telltale sign is that the code colouring in the VS Code editor is off. This is easily fixed by the command Java: Restart Java Language Server (Cmd-Shift-P and start typing).

Occasionally it may happen that the development environment no longer works as expected. In those rare cases it is necessary to quit the GWT DevMode server and run ’mvn clean install gwt:devmode’ to clean the workspace, recompile the code and start the GWT DevMode server again. Usually it is not necessary to also re-start the debugging session and with it the Google Chrome browser.

By default, the DevMode server listens on port $8888$ for http-requests and runs the code server on port $9876$. Shutting down the DevMode server can sometimes take surprisingly long and may require some patience. As long as the server is not fully shutdown, the port $9876$ remains in use for the code server and prevents another instance of the server from starting because access to the port is blocked.

The most frequent and unmistakable sign of trouble is that unexpectedly GWT compilation fails when reloading the browser window. When clicking on failed to display the cause for the error, the first error is

1 [ERROR] Line <N>: No source code is available for type java.awt.Color; did you forget to inherit a required module?

followed by a seemingly never ending cascade of errors. This includes a variety of different errors, but the following two are the most frequent:

1 [ERROR] Line <N>: Color cannot be resolved to a type

2 [ERROR] Line <N>: Color cannot be resolved to a variable

Presumably the cause for the error is that the database underlying the sophisticated incremental building of GWT projects gets out of sync.

As a consequence, recompiling the GWT code by reloading the browser window fails. Quitting and re-starting the DevMode server as outlined above usually resolves the issue.

As a last resort, reset the development environment by quitting the VS Code workspace, which also closes any Google Chrome browser windows from debugging sessions. If the DevMode server is running, shut it down by quitting the DevMode java application. Then, execute ’mvn clean’, ’mvn install’, sequentially and re-launch the DevMode with ’mvn gwt:devmode’. Finally, re-open the VS Code workspace and re-launch the debugging session, which also re-opens the Google Chrome browser. Now everything should be back in a sane state.

The EvoLudo project consists of six maven modules:

EvoLudoCore:

The core java code of EvoLudo shared by GWT as well as JRE. This is the backend that deals with the numerical integration of differential equations (ordinary, stochastic, or partial) as well as individual based simulation and must be agnostic of GWT or JRE specifics.

EvoLudoGWT:

The GWT specific code of EvoLudo. Most notably this includes all the GUI components for visualizations in the web browser as well as handling the asynchronous scheduling of tasks in the browser. This also handles the Jetty server for development using a web browser and includes the .(x)html files for loading the GWT application.

EvoLudoJRE:

The JRE specific code of EvoLudo. This provides the basis for generic as well as customized java simulations. More specifically, in contrast to GWT, JRE can handle multiple threads, which provides a significant performance boost for PDE models and maintains a responsive GUI. In addition, this module also includes GUI components when running as an old-fashioned java application.

.

.

Important: At this point the java GUI components are maintained but are no longer under active development in favour of the GWT counterpart, which is also significantly richer in features.

.

EvoLudoSims:

Handles customized java simulations. The simulations are kept in EvoLudoSims/src/main/org/evoludo/simulator/exec/. By default, the simTBT.jar executable is generated. Other executable can be generated using the option ’-Devoludo.sim=<simulation>’ where <simulation> denotes the class name of the simulation.

EvoLudoTest:

Test suite for the different EvoLudo modules in EvoLudoCore/src/main/java/org/evoludo/simulator/modules (not to be confused with the maven modules). Tests are performed by executing the script ./scripts/runtests.sh in the EvoLudo root directory. All tests must always pass (see section 12.11: Advanced: EvoLudo tests).

java code is organized in packages, classes and interfaces. The most important unit is a class. Each class is defined in a file with the same name as the class and the extension .java. Every class inherits features from a superclass, which is either explicitly specified using the keyword extends, or implicitly extends the Object class. The class contains constructors, fields, methods, and nested classes. Constructors are methods that initialize objects and return a new instance of a class. Fields are variables that store data. Methods are functions that perform operations. Nested (or inner) classes are classes defined within other classes. An inner class can access the fields and methods of the outer class and hence it cannot be instantiated without an instance of the outer class.

All fields and methods have four different visibilities: private, protected, public, or package-private (no keyword). The visibility determines whether the field or method can be accessed from other classes and from which ones. private restricts access to the class, package-private allows access from subclasses in the same package, while protected allows access from any subclass, and public allows access from any class. The access restrictions are summarized in Table 12.1.

The keyword static makes a field or method belong to the class rather than to an instance of the class. When applied to an inner class the static inner class can be instantiated on its own – without an instance of the outer class. As a consequence, a static inner class cannot directly access the fields and methods of the outer class (apart from static ones).

The keyword final prevents fields from being modified, methods from being overridden, and classes from being subclassed. The keyword abstract indicates that a class or method is incomplete and must be implemented by a subclass.

Interfaces are similar to classes but only contain method signatures, constants and nested interfaces. Method signatures in interfaces may provide default implementations of the methods, marked by the keyword default. A class can only inherit from one superclass but may implement multiple interfaces, listed after the keyword implements.

All classes are organized in packages. The package of a class is specified as the first line of code in a class, for example package org.evoludo.simulator.modules;. The package name actually doubles as a path to the location of the class file starting at the src folder of the java code. That is, a class in the aforementioned package must reside in the folder src/org/evoludo/simulator/modules.

All modules implement the MilestoneListener interface and are notified of the following events:

moduleLoaded():

Called after the EvoLudo module finished loading.

moduleUnloaded():

Called after the EvoLudo module has unloaded.

moduleRestored():

Called after the state of the EvoLudo module has been restored.

modelLoaded():

Called after EvoLudo model finished loading.

modelUnloaded():

Called after the EvoLudo model has unloaded.

modelRunning():

Called before the EvoLudo model starts running.

modelRelaxed():

Called after the initial configuration has relaxed.

modelStopped():

Called after a running EvoLudo model stopped because the model converged (or reached an absorbing state). Not called when the model is stopped by the user (through the GUI).

modelSettings():

Called after the settings of the EvoLudo model have changed. If the changes required resetting the model, modelDidReset() is called instead.

modelDidInit():

Called after the EvoLudo model got re-initialized. Initialization generates a new initial configuration, i.e. trait distribution, but does not regenerate the geometry of the population.

modelDidReset():

Called after the EvoLudo model was reset. Resetting the model first re-generates the geometry of the population and then generates a new initial configuration. For fixed population geometries, for example lattices, resetting and initializing the model are equivalent. This is not the case for geometries that include a random element, for example random regular graphs.

Overriding any of the methods is optional.

In contrast to the milestone events, modules are not notified of change events by default. Modules that wish to be informed about all state changes of the EvoLudo model need to explicitly implement the ChangeListener interface. This requires implementing the method modelChanged(PendingAction action). After every state change of the model, the modelChanged(...) method is called. Such a state change can be triggered by user actions through the GUI or by the model itself. A running model calls modelChanged(...) every time an update is available. The frequency of those calls depends on the --timestep settings. The reason and type of state change is given by the PendingAction argument. It’s called a pending action item because any running model may not immediately attend to external request. A ChangeListener may decide to process any or all of the following actions:

NONE:

State changed. No action requested.

SHUTDOWN:

Unload EvoLudo. Stop running models and initiate clean shutdown of the EvoLudo engine when the GWT application gets unloaded.

RESET:

Reset model. Stop running models, re-initialize geometry and strategies.

INIT:

Initialize model. Stop running models and re-initialize strategies.

STOP:

Stop running models.

CHANGE_MODE:

Change execution mode of model.

STATISTIC_READY:

Statistics sample is ready.

STATISTIC_FAILED:

Statistics sample has failed.

Any of these actions can be requested by calling the method requestAction(PendingAction action) of the EvoLudo engine, see section 12.9: EvoLudo engine.