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

@Variable is needed for all data reporting. The Simudyne SDK provides several helper methods and classes that can be used to report more complex data easily.

\n

If using the Simudyne SDK with the console, this reported data will be displayed for you in an appropriate format on the console. If using the Simudyne SDK without the console, the data will be returned in a JSON format.

\n
\nAccumulators are reported by default. They could be present twice in the console if the annotation is used for them.\n
\n

Variable

\n

The most simple way of reporting data is creating a field in the Model and annotating it with @Variable.\nFields annotated with @Variable will be displayed in the console as a line chart.

\n
\n All fields marked as @Variable need to have public access, and must be a data type that can be reported. Accepted data types include primitive types (float, int, double), and any object that extends simudyne.core.JSONValue (see JsonValue below).\n
\n

(Java)

\n
MyAgent agent;\n@Variable public float balance = 0;
\n

Console view

\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n

To set the title of the line chart, set the name in the variable annotation. If not set, it defaults to the name of the field.

\n

(Java)

\n
@Variable(name=\"Balance Header\") public float balance = 0;
\n

Methods that return accepted data types can also be annotated with @Variable. These methods will be called at least once per step, but may be called many more times, so they should not change any values in the model.

\n

Variable methods will only be called after setup, so the model can depend on a state that is initialised as part of the setup (such as AgentSystem).

\n

(Java)

\n
@Variable(name = \"Interest Charge\")\npublic float interestCharge() {\n  return interest * balance;\n}
\n

Fields marked as @Variable (this will be ignored for methods marked as @Variable) can set the parameter \"initialisable\" to true if you want the variable assigned before setup.

\n

(Java)

\n
@Variable(name = \"Balance\", initializable = true)\npublic float balance = 400;
\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n

JSONValue

\n

When reporting complex objects, the Simudyne SDK needs to be able to generate a JSON value and JSON schema of the objects. Therefore, all complex objects need to implement JSONValue and the methods for returning the JSON value.

\n

The Simudyne SDK provides several data types that implement JSONValue, and can be used out of the box to report to the console. These are explained below. Using these provided data types is the recommended way of reporting.

\n
\nAdvanced users can create their own data types that implement JSONValue, and the data returned will be reported as a JSON, but the console will not be able to handle these data types, and will not display the information.\n
\n

Accumulators

\n

Accumulators are variables that are only added to through an associative and commutative operation. They can be used to implement counters or sums.

\n

The two supported accumulators are DoubleAccumulators and LongAccumulators. They are both used in the same way, DoubleAccumulators for storing values of type double, and LongAccumulators for storing values of type long.

\n

Accumulators can be created within an AgentBasedModel.

\n

(Java)

\n
public class MyClass extends AgentBasedModel<GlobalState> {\n\t...\n  {  \n  \t// create accumulator\n  \tcreateLongAccumulator(\"born\");\n\n    // get accumulator and add value\n  \tgetLongAccumulator(\"born\").add(10);\n  }\n}\n// get accumulator and add value from within an Agent\npublic class Cell extends Agent<GlobalState> {\n  public LongAccumulator born = getLongAccumulator(\"born\");\n\n  public void onStart() {\n    born.add(10);\n  }\n}
\n

When running a simulation locally, accumulators are automatically reported to the console. To explicitly turn on or off reporting for accumulators, set the config field core-abm.serialize.accumulators. (See Model Configuration). Accumulators can be created with a second parameter for the display name that will be used when reporting the accumulators on the console.

\n

(Java)

\n
createLongAccumulator(\"born\", \"Amount Born\");
\n

To view the count or mean of the accumulator, use the getCount() or getMean() methods and save the results as a primitive type annotated with @Variable.

\n

(Java)

\n
@Variable(name = \"Born Mean\")\npublic long bornMean = getLongAccumulator(\"born\").mean();
\n

Agent Statistics

\n

Statistics about the values of specific fields in agents can be collected using AgentSystem.stats().

\n

(Java)

\n
// Agent statistics are collected for a specific agent class\npublic AgentStatistics<MyAgent> myAgentStats = stats(MyAgent.class)\n\n// Filters can be used if statistics are only needed for some of the agents.\n// In this case, only get statistics of agents where age is > 100   \nmyAgentStats.filter(x -> x.age)\n\n// Specify which fields to collect statistics for.    \nmyAgentStats.field(\"Age\", x -> x.age).field(\"Balance\", x -> x.balance);  \n\n// Get the statistics results\npublic AgentStatisticsResult<MyAgent> statsResults = myAgentStats.get();
\n

This will collect statistics and save as Apache SummaryStatistics.

\n

Get the SummaryStatistics for a field and get the required statistic to report using the SummaryStatistics methods. Annotate the field with @Variable, so the result will be reported to the console.

\n

(Java)

\n
@Variable public double balanceMean =\n  statsResults.getField(\"Balance\").get Mean();
\n

Agent fields

\n

It is also possible to report the fields inside agents. In order to do so, annotate the fields inside Agents.

\n

(Java)

\n
public class Cell extends Agent<GlobalState> {\n  @Variable public boolean alive;\n}
\n

This will output a table for each Agent type, with the values of the fields annotated with @Variable for each agent in the system.

\n
\n

Agent view

The top-right corner lets you select different views. For the following example, select the Agent view.\n
\nExample output:\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
CellAlive
6565false
4536false
7791false
1209false
\n
\nWhen running models in distributed mode, AgentSystem reporting is muted even if AgentSystem is annotated with @Variable. To report agent fields, core-abm.serialize.agents must be set to true in the config, and to report accumulators, set core-abm.serialize.accumulators must be set to true.\n
\n
\n

Reporting for multirun Simulations

\nWhen running a model as a multirun, Agent tables will not be reported on the console.\n
","headings":[{"value":"Variable","depth":3},{"value":"JSONValue","depth":3},{"value":"Accumulators","depth":3},{"value":"Agent Statistics","depth":3},{"value":"Agent fields","depth":3}],"frontmatter":{"title":"Reporting","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.4/reference/agents/reporting.md","versioned":true,"version":"2.4","kind":"reference","pagePath":"/reference/agents/reporting","chronology":{"prev":{"name":"Actions and Sequencing","path":"/reference/agents/actions-and-sequencing"},"next":{"name":"Global State","path":"/reference/agents/global-state"}},"lastUpdated":"2026-04-21T13:56:54.850Z"}}