Readme.md 3.99 KB
Newer Older
Christian Meyer's avatar
Christian Meyer committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
Library for launching ZMT simulations. Recent javadoc can be found here: https://dochost.leibniz-zmt.de/javadoc/zmt-launcher/

## Minimal Setup
[zmt-core](https://gitlab.leibniz-zmt.de/ecomod/zmt-core) provides an interface for zmt-launcher to launch simulations. The minimal setup for that consists of the following:

* Add zmt-core to the classpath of your simulation, i.e. add a dependency for it in build.gradle:
```
compile 'de.zmt:zmt-core:latest.release'
```
* Create a parameters class implementing `de.zmt.params.SimParams`.
* Let your main simulation class extend `sim.engine.BaseZmtSimState` and place it in package `sim.engine`. Use your parameters class for the type parameter and supply the class via `getParamsClass()` method.
* If you want to customize the GUI, let your class extend `sim.display.ZmtGuiState` and place it in package `sim.display`.

With this setup, you can launch your simulation via zmt-launcher. For an example, consult [test files](https://gitlab.leibniz-zmt.de/ecomod/zmt-launcher/tree/master/src/test/java) of zmt-launcher.

### Example
You can find the whole example project in the `example/` sub directory.
```java
package sim.engine;

import de.zmt.params.SimParams;
import sim.engine.MySim.MyParams;

public class MySim extends BaseZmtSimState<MyParams> {
    private static final long serialVersionUID = 1L;

    @Override
    public Class<? extends MyParams> getParamsClass() {
        return MyParams.class;
    }

    public static class MyParams implements SimParams {
        private static final long serialVersionUID = 1L;

        private long seed;

        @Override
        public long getSeed() {
            return seed;
        }

        public void setSeed(long seed) {
            this.seed = seed;
        }
    }
}
```

## The Launcher Application
The launcher is a command-line application that will be distributed together with your simulation when using [zmt-build](https://gitlab.leibniz-zmt.de/ecomod/zmt-build). You can use the `run-launcher` shortcut in your distribution's root directory to access it. Use option `--help` to display all available options.

### Launch Modes
Simulations can be launched in 3 different modes:
* **GUI**: Opens the GUI of the simulation.
* **SINGLE**: Launches a single run of the simulation.
* **BATCH**: Launches a parallel batch run of simulations.

For example, to launch the [example](#example) simulation MySim in GUI mode, enter:
```shell
./run-launcher MySim gui
```
The package of the simulation can be omitted, if `sim.engine`.
    
### Batch Runs
Batch runs require an automation parameters XML file. To create one, you can use the option `--export-auto-params <FILE>` to export all available automation parameters to a file. Use this file to create your own set of automation parameters. Several parameter iterations can be specified after the locator tag ending with `</locator>`.

To export the [example simulation](#example)'s automation parameters, enter:
```shell
./run-launcher MySim --export-auto-params exported-auto-params.xml
```
and the file exported-auto-params.xml will contain:
```
<AutoParams>
  <simTime>1000.0</simTime>
  <AutoDefinition>
    <locator>
      <field>
        <name>seed</name>
        <clazz>sim.engine.MySim$MyParams</clazz>
      </field>
    </locator>
    <long>0</long>
  </AutoDefinition>
</AutoParams>
```

If you want to automate with seeds 21, 22, 23, change the file to:
```
<AutoParams>
  <simTime>1000.0</simTime>
  <AutoDefinition>
    <locator>
      <field>
        <name>seed</name>
        <clazz>sim.engine.MySim$MyParams</clazz>
      </field>
    </locator>
    <long>21</long>
    <long>22</long>
    <long>23</long>
  </AutoDefinition>
</AutoParams>
```

At last, do not forget to adjust the simulation time as needed via the `<simTime>` tag and save the file. `parameters/autoParams.xml` is used in the example. Then start your batch run with:
```shell
./run-launcher MySim batch --auto-params parameters/autoParams.xml
```
The batch will consists of all combinations of parameters defined in the automation file.