Creating a console application

Intro

A simulation model in a form of a console application can be used to run scenario analysis, when it is more important to get the results of the simulation quickly than to observe the intermediate state of the model.

A console application can then be turned into a web service to let multiple users run simulations remotely.

Download and run the sample project

Clone the sample console application: https://github.com/amalgama-llc/basic-console-app

Use its 'README.md' instructions to build and run the application.

The program should print the following to the console:

engine time is 5.0

What is going on in the sample program (and how to create one yourself)

First of all, we need to add the Amalgama Platform dependencies into our project.

In the pom.xml file, the repositories section refers to the Maven repository with Amalgama Platform dependencies:

<repository>
  <id>amalgama-platform-maven</id>
  <url>https://nexus.am-sim.com/repository/amalgama-platform-mvn/</url>
</repository>

The dependencies section mentions the 'engine' dependency - it contains the simulation engine that executes the events that happen during simulation:

<dependency>
  <groupId>com.amalgamasimulation</groupId>
  <artifactId>com.amalgamasimulation.engine</artifactId>
  <version>1.12.0</version>
</dependency>

Now that the application can use the simulation engine, we create an instance of Engine in class Main and schedule an event to happen at model time 5:

public static void main(String[] args) {
  Engine engine = new Engine();
  engine.scheduleAbsolute(5, () -> System.out.println("engine time is " + engine.time()));
  engine.scheduleStop(10, "Engine stop");
  engine.setFastMode(true);
  engine.run(true);
}

Let’s skim through the code of the sample application.

First, we create a new Engine instance.

In the next line we schedule an event to happen at model time 5. By default, the model time is measured in seconds. We can also use the setTemporal() method of the Engine instance to change this behavior. In this case we use 'absolute scheduling': on the 5th second of model time an action will be performed. Engine also supports 'relative scheduling' when an event is scheduled to fire after a period of time from the current model time, for example, 'in two hours from now'.

The action that we have just scheduled will print a short message to the console with the current 'model time' (the Engine.time() method). The value returned by the Engine.time() method is the (non-negative) number of 'model time units' (seconds by default) that have passed since the beginning of the simulation.

The next line schedules the engine to stop at model time 10 (i.e., on the 10th 'model second'). So, the overall duration of the simulated period of time will be 10 seconds (of model time).

Do we have to wait 10 'real' seconds for the simulation to finish? No. Instead, we instruct the engine to run the simulation in 'fast mode', i.e., as fast as the computer hardware allows.

The last line starts the engine, and the simulation begins in a separate Java thread. The only parameter to the run() method is set to 'true', which means that the engine is started in synchronous mode: the method call will block until the simulation is over.