Commit 8dcf11e3 authored by Christian Meyer's avatar Christian Meyer
Browse files

added Readme.md

added example/: example project used in Readme
parent 00122a70
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.
ext.simClassName = 'MySim'
buildscript {
repositories {
jcenter()
maven {
// zmt maven repository - public
url 'https://dochost.leibniz-zmt.de/maven2/'
}
}
dependencies {
classpath 'de.zmt:zmt-build:2+'
}
}
apply plugin: 'de.zmt.simulation'
dependencies {
compile 'de.zmt:zmt-core:latest.release'
}
<AutoParams>
<simTime>1000.0</simTime>
<AutoDefinition>
<locator>
<field>
<name>seed</name>
<clazz>sim.engine.MySim$MyParams</clazz>
</field>
</locator>
<long>0</long>
</AutoDefinition>
</AutoParams>
<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>
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;
}
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment