CLI Model Runner

The CLI (command line interface) Runner allows users to run models for a specified duration with specified inputs from the command line. This could be useful for users who wish to run the model but do not need to run the server or view the output on the console.

Preparing the model

To run a Model using the CLI, you first need to update your Main.java class so that it runs the server with the array of String arguments passed from the java main method. This allows you to pass your CLI parameters to the Simudyne SDK so the model can be run with your CLI parameters.

Main.Java

public class Main {
  public static void main(String[] args) {
    Server.register("My Model", MyModel.class);
    // Pass args as parameter to Server.run
    Server.run(args);
  }
}

You then need to package, you will need to build a fat jar which will carry your model, the Simudyne SDK and all the necessary dependencies. In this example, we will use the maven-shade-plugin to build this fat jar.

To do this, add the following code to the plugins section in the pom.xml file.

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    ... properties and dependencies ...
    <build>
        <plugins>
            ... other plugins ...
            <plugin>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <transformers>
                        <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
                            <resource>reference.conf</resource>
                        </transformer>
                        <transformer
                                implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                            <mainClass>Main</mainClass>
                        </transformer>
                    </transformers>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

You can then run the maven command to create the fatJar:

Maven

mvn -s settings.xml clean compile package

Maven will create the jar and place it in the target directory (unless you have specified otherwise in your pom settings). Unless you have given it a specific name, the generated jar will be named <some-artifact-id>-<some-version>-jar.

Running the model

The CLI runner can be used to run any model that has been registerd using Server.register("name", model). It is run by running the generated jar with arguments specifying which model to run and how to run the model.

• --help This parameter can be used to list all the CLI options with an explaination of how they are used.

Running the CLI help option

java -jar target/sample-artifact-1.1.0.jar --help

Expected output

Usage: <main class> [options]
  Options:
    --model-class
      Full canonical class name to run.
...      

Required parameters

• --model-class , --model-name -> One of these options must be passed with the full java class name to run, or the name the model was registed with respectively.

Example:

Model Registration

    Server.register("Mortgage Tutorial", org.example.models.MortgageModel.class);

Running the model

# Running using the registered model name
java -jar target/simudyne-maven-java-2.1.0-SNAPSHOT.jar --model-name "Morgage Tutorial" ...Additional parameters...

# Running using the model class
java -jar target/simudyne-maven-java-2.1.0-SNAPSHOT.jar --model-class "org.example.models.MortgageModel.class" ...Additional parameters...   

• --input-path -> In order to run a CLI runner, a directory must be passed containing files which specify the input fields to be set for some or all ticks. Each file in the specified directory will be used to run the model according to its configuration. If the directory does not contain any input files, the model will not run. Input files can be either csv or json format, and have to follow a specified structure to be run.

JSON input files

ExampleInput.json

{
  "runs": 23,
  "seeds": [123,234], // 123 and 234 will be used as the seeds for the first two runs
  "scenarioData": {
    "2": {
      "nbHouseholds": 50 // nbHouseholds will be set to 50 at the second tick
    },
    "100" : {} // run 100 ticks (without setting any inputs after the second tick)
  }
}

CSV input files

CSV input files can only be used to run single runs. The first column in the csv can be used to specify ticks, and the subsequent columns are input fields, so the values in those columns are the values to set for input fields at specific ticks.

ExampleInput.csv

tick,nbHouseholds
1,200 // nbHouseholds will be set to 200 at the first tick
2,250 // nbHouseholds will be set to 250 at the second tick
100 // run 100 ticks (without setting any inputs after the second tick)

Optional parameters

• --run-ID -> A unique ID to identify this run. This ID will be used as a directory for output data.
• --output-path -> The directory that data generated by these runs should be written to. If not specified, this will be the current directory.
• --output-format -> The format that data generated by these runs to should be written in. (Excepted formats are json and parquet). If not specified, data will be output as json. (Read the Data Output section for more details on the parquet output structure.)
• --custom-export-metadata -> Custom JSON object that will be included in the metadata.json file as part of the data output. If not specified, no custom metadata will be added.