{"data":{"markdownRemark":{"html":"

Overview

\n

In order to create a model with the Simudyne SDK, you must generate the java files yourself, which can be time-consuming and is prone to small errors if you are not familiar with java.

\n

The model scaffolding allows you to avoid having to create those files manually. This plugin can turn correct JSON files into a basic model structure.\nThe simudyne-maven-plugin is the only component you need to make it work. This is currently only supported for models built with maven.

\n

Installation

\n

The plugin should be added to the POM in the build section:

\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<project xmlns=\"http://maven.apache.org/POM/4.0.0\"\n         xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd\">\n... Model properties here...\n    <dependencies>\n        ... dependencies here ...\n    </dependencies>\n    <build>\n        <plugins>\n            ... other plugins here ...\n            <plugin>\n                <groupId>simudyne</groupId>\n                <artifactId>simudyne-maven-plugin</artifactId>\n                <version>1.0-SNAPSHOT</version>\n                <configuration>\n                    <overwrite>false</overwrite>\n                </configuration>\n            </plugin>\n        </plugins>\n    </build>\n</project>
\n

Defining a correct JSON representation

\n

In order to work, a correct JSON representation of a model must be provided to the plugin.\nEach representation must be held in one JSON file, but the plugin can be called to generate the models from several files at the same time.

\n

The default location the plugin will look for JSON files is in the src/main/json/models (inside the current directory). You can manually set the input directory by passing the input parameter to the plugin.

\n
<configuration>\n    <input>my/new/path</input>\n</configuration>
\n

Defining a model in JSON

\n

Inside the input directory, put the JSON files you want to use to generate models.\nEach file will generate a different model and must therefore contain all the necessary information to the creation of a model. The name of the json file will be the package name in which the generated files are put.

\n

General structure

\n
{\n    \"name\": \"myModel\",\n    \"variables\": {},\n    \"constants\": {},\n    \"inputs\": {},\n    \"fields\": {},\n    \"longAccumulators\": {},\n    \"doubleAccumulators\": {},\n    \"globals\": {},\n    \"agents\": {},\n    \"messages\": {},\n    \"links\": {}\n}
\n

A JSON file representing a model must provide the name of the model. It can also define accumulators, model fields, the global states fields, inputs, constants, variables, the agents of the model, the links and the messages that will be used in the model.\nThe name of the JSON file will be the name of the model package.

\n

Variables, constants, inputs and fields structures

\n
{\n    \"variables\": {},\n    \"constants\": {},\n    \"inputs\": {},\n    \"fields\": {}\n}
\n

The keys variables, constants, inputs, fields all represent java variables in the model. The only difference is their annotation.\nA variable defined in inputs will have the annotation @Input, those in variables will have @Variable, those in constants will have @Constant\nand the ones in fields will have no annotations.

\n

Required fields for a java variable are

\nOptional fields for a java variable are .

\n
{\n  \"inputs\": {\n    \"fieldWithDefault\": \"int = 1\",\n    \"basicField\": \"String\",\n    \"fieldWithDisplayName\": \"long = 2 , myField\"\n  }\n}
\n

The code above will generate the following java code inside your model:

\n
    @Input\n    int fieldWithDefault = 1;\n\n    @Input\n    String basicField;\n\n    @Input(name = \"myField\")\n    long fieldWithDisplayName = 2;
\n

The member in the JSON can also be defined in a more explicit way as follow :

\n
{\n  \"inputs\": {\n      \"fieldName\": {\n          \"type\": \"int\",\n          \"default\": 5,\n          \"displayName\": \" this will be displayed\"\n      }\n  }\n}
\n

Note that a member of fields does not have any annotation and therefore cannot have a display name.

\n

Globals structure

\n

The globals key in the model allows you to define the variables, constants, inputs and fields that will be in the GlobalState of the model.

\n
{\n  \"globals\" : {\n      \"variables\": {},\n      \"constants\": {},\n      \"inputs\": {},\n      \"fields\": {}\n  }\n}
\n

The code above will output the correct fields with the right annotations inside the GlobalState object on your model.

\n

Accumulators structure

\n

Accumulators must be defined separately in the JSON file depending on their type (Double or Long accumulator).\nAn accumulator only needs a name, but will also accept a display name if provided.\nThe keys doubleAccumulators and longAccumulators are used to define the accumulators.

\n

To generate accumulators without display names:

\n
{\n  \"longAccumulators\": [\"name1\", \"name2\", \"name3\"],\n  \"doubleAccumulators\": [\"name4\", \"name5\"]\n}
\n

To use with the display names :

\n
{\n  \"longAccumulators\": {\n      \"name1\": \"display name1\",\n      \"name2\": \"display name2\",\n      \"name3\": \"display name3\"\n  },\n  \"doubleAccumulators\": {\n      \"name4\": \"display name4\",\n      \"name5\": \"display name5\"\n  }\n}
\n\n

The messages and links must be defined on the same JSON file as the model, but they will be output as different files.\nA message/link only needs a name, but it can also have a type and fields.

\n

There are 3 ways to define a message/link.

\n\n

For instance, the following code :

\n
{\n \"messages\": {\n       \"Mg1\": {\n             \"fields\": {},\n             \"type\": \"Empty\"\n       },\n       \"Msg2\": \"Long\",\n       \"Msg3\": {}\n   },\n \"links\": {\n       \"MyLink\": {}\n   }\n}
\n

will output the Messages.java file:

\n
import simudyne.core.graph.Message;\n\npublic class Messages {\n  public static class Msg1 extends Message.Empty {\n  }\n  public static class Msg2 extends Message.Long {\n  }\n  public static class Msg3 extends Message {\n  }\n}
\n

and the Links.java file:

\n
import simudyne.core.graph.Link;\n\npublic class Links {\n  public static class MyLink extends Link {\n  }\n}
\n

Agents structure

\n

Agents are defined with their fields and the names of their actions. The actions generated will not contain any logic, they must be completed before running the code.

\n
{\n  \"agents\": {\n      \"Agent1\": {\n          \"fields\": {},\n          \"actions\": [\"action1_name\", \"action2_name\"]\n      }\n  }\n}
\n

The JSON above will for instance output the following java file agent1.java:

\n
package myImports;\nimport simudyne.core.abm.Action;\nimport simudyne.core.abm.Agent;\n\npublic class Agent1 extends Agent<myModel.Globals> {\n  public static Action<agent1> action1_name =\n    Action.create(\n      Agent1.class,\n      agent1 -> {\n        // enter the action's body here\n    });\n  public static Action<agent1> action2_name =\n    Action.create(\n      Agent1.class,\n      agent1 -> {\n        // enter the action's body here\n    });\n}
\n

Generation of the model files

\n

Once the JSON files representing models are placed at the right location, the generation of the java files can begin.

\n

In order to generate the java files from the JSON, run

\n
mvn simudyne:jsonGen
\n

This will fetch the JSON into the specified input directory and extract the information.

\n

The java files will be generated into the directory src/main/java/models inside the Simudyne project.

\n

The files corresponding to a model will be output in a subfolder with the same name as the input JSON file.

\n

Troubleshooting

\n

When running the mvn simudyne:jsonGen, you may encounter issues.

\n

If some fields, actions, classes or files were not generated, please check the syntax and make sure the JSON file does not contain spelling errors.

\n

If the plugin finds duplicate names in your model, an exception will be thrown and the conflicting names will be displayed, as well as their location.

\n

If the plugin tries to create a file that already exists and the overwrite flag is not set on true, the plugin will throw an exception.\nThe overwrite flag must be set to true to enable the old files to be replaced. This can be done in the POM :

\n
<configuration>\n    <overwrite>true</overwrite>\n</configuration>
","headings":[{"value":"Overview","depth":2},{"value":"Installation","depth":2},{"value":"Defining a correct JSON representation","depth":2},{"value":"Defining a model in JSON","depth":2},{"value":"General structure","depth":4},{"value":"Variables, constants, inputs and fields structures","depth":4},{"value":"Globals structure","depth":4},{"value":"Accumulators structure","depth":4},{"value":"Messages and Links structures","depth":4},{"value":"Agents structure","depth":4},{"value":"Generation of the model files","depth":2},{"value":"Troubleshooting","depth":4}],"frontmatter":{"title":"Model Scaffolding","toc":null,"experimental":true}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.6/reference/experimental/scaffolding.md","versioned":false,"version":"2.6","kind":"reference","pagePath":"/reference/experimental/scaffolding","chronology":{"prev":{"name":"Auto-compiler","path":"/reference/experimental/auto-compiler"},"next":{"name":"System Messaging","path":"/reference/experimental/system_messaging"}},"lastUpdated":"2026-04-21T13:56:54.869Z"}}