Jump to notes for a specific release with the following links:
\n29th March 2019
\nThis is a major relase of the software, including multiple new modules, new APIs, and a more powerful console.
\nUpgrading can be done by changing the simudyne.version setting in your pom.xml to 2.2.0. We have been careful in 2.2 to avoid any major breaking changes, but there are still a few things to be aware of. Immutable Schema in particular will be a breaking change for most models, but can be opted out of for the 2.2 release cycle if so desired, details below.
2.2 is beginning preparations for future improvements for data integration. As part of this, models will need to have a fixed type once they are initialised. We have introduced a new method, init() that can be implemented for models, which is called just as the model is created. After this method has been called, all agent and link types should be registered, and all accumulators created. Demonstrations of this and other improvements can be found in the new Trading Tutorial.
To ease upgrading you can disable this restriction for this release, by disabling the feature in your configuration. Note that this flag is planned for removal in a future release, and so you will be warned when it is disabled.
\n# In your simudyneSDK.properties file\n\nfeature.immutable-schema = falseMigrating for this involves moving any accumulator creation to an init() method on your model, as well as registering agent and link types. For example, in the Trading tutorial model, this is done as so:
public void init() {\n createLongAccumulator(\"buys\", \"Number of buy orders\");\n createLongAccumulator(\"sells\", \"Number of sell orders\");\n createDoubleAccumulator(\"price\", \"Price\");\n\n registerAgentTypes(Market.class, Trader.class);\n registerLinkTypes(Links.TradeLink.class);\n}Additional information is available in the reference on Model Initialisation.
\nThe Simudyne SDK has been made warning free for versions of Java 9 and above. As part of the restrictions this introduces, annotated fields and methods (e.g. your @Variable and @Input fields) must now be marked as public. Users of Java 8 will be unaffected by this change.
Calling SeededRandom.create() without any arguments is now deprecated. The behaviour of this method is to return a new SeededRandom instance, using the seed configured in your project, or a random seed if there is no seed configured. However, this method was easy to use incorrectly, as calling it twice is almost certainly an error (returning two separate PRNG with the same seed, and so generating the same sequences of outputs independently).
The advised replacement is to use ModelContext.getPrng(). Within your AgentBasedModel class, you can get the context by calling getContext(). This has identical behaviour to SeededRandom.create(), except that multiple calls will return the same instance of SeededRandom. If you want to keep the previous behaviour, you can call SeededRandom.create(long seed) explicitly with the same seed.
Field groupings set through field annotations are no longer used on the console. These annotation properties have been deprecated to maintain compatibility, and will be removed in a future version. Specifically this related to the @ModelSettings(groups = {}) setting, and field level annotation settings such as @Variable(group = 0).
This method has been deprecated in favour of AgentBasedModel#registerAgentTypes which can take any number of classes.
The console has been given a visual update, providing a more polished interface and better indication of types of data through colouring. Along with this there are a large number of improvements and new features, here are the highlights:
\n@ModelSettings annotations on the Model class.License files can now be placed in a users home directory, allowing all Simudyne SDK projects for that user to find the license. This eases installation to be a once-per-machine task, rather than once per project. Existing installations will continue to work, but it is advised for everyone to update to the new approach, detailed in the updated installation documentation.
\nThe SDK now supports a remote licensing server. This allows the license placed on a users machine to contain only simple user identification, with the server controlling aspects such as expiration. This removes the need for rotating license files on expiry, as they can be extended by the server independently. This approach will be rolled out first to academic users of Simudyne. The existing licenses, which requires no network connection, will continue to function and are not planned to be removed, in support of enterprise environments.
\nModel Scaffolding is a tool for generating the initial skeleton of an ABM, using a definition of the model in the JSON data format. This is a step towards simplifying the initial creation of an ABM, making it easier to declare agents and links quickly. It is distributed within the new simudyne-maven-plugin module, which is a plugin for the Maven build system. We will be looking to roll out new tooling at the build stage in the future, to continue improving the modeling experience.
Agents now support Time Series Variables through windowed values, which are values that track a value through a certain number of ticks.
\nEmpirical distributions can now be loaded from a Source, using the new SeededRandom.empiricalFromSource(Source source) API. This allows you to easily construct distributions from source data, structured as a histogram, and then use them in your model.
A new API object is available in all models, called ModelContext. In AgentBasedModel this is available by calling getContext(), and returns the context of the current model. Through this context you can access additional APIs relating to the model, including the current tick (through getTick) and the root PRNG (through getPrng).
Model.init() is a new lifecycle method available on all Models. This acts similarly to a constructor, however contextual APIs such as ModelContext will be available. This interacts with the new Immutable Schema restrictions, as after init() has been called, methods affecting the data structure of the model can no longer be called.
The Model Sampler is a new interface onto multi-run, allowing more declarative execution of collecting samples from a model over a given parameter space. Currently this is only available through the REST API.
\nIn the pursuit of newer features to end users, but clear communication of stability and readiness for production, we have a new classification of modules: experimental. These are modules that are not guaranteed to be stable, either in the implementation or their API, and so are not suitable for production use. They have however been tested internally by us, and are at the point where external users should be able to usefully try and test them, and provide feedback on whether these modules are suitable.
\nThis module provides two new APIs for defining domain specific agent-based models. The first API allows the definition of a system of traders and markets, where the markets hold an internal order book which is executed on via messages from traders. The second is a lending model, where a system of borrowers and lenders take out loans and make repayments, tracked through balance sheets.
\nThe full documentation for this module is here on the reference: Financial Tool Kit.
\nSparkGraph has been reclassified as an experimental module, with no other changes.
\nDistributedGraph is a new implementation of a distributed execution engine for very large networks of agents. It is designed to be more performant than SparkGraph, and is available for initial testing.
\nThe CLI mode is a new addition that allows models to be run from the command line, rather than using the webserver. While the server is still used to run the task, once it is finished it will exit. Enabling this new mode is striaghtforward, as you just need to pass program arguments through to the existing Server.run call. If any arguments are passed, the server will try and execute them, otherwise if no arguments are passed the server will start as usual.
For parquet output on batch and multi-run, the SDK needs to output into a set of directories containing all of the results. In previous versions this was done by grouping results into separate directories per run. This was friendly to humans, as it was clear where the results for a given run are located, but in practice these results are often used from query engines such as SparkSQL. For these systems, files should be grouped by their data structure (columns).
\nThis release adds a new configuration setting to control the output structure, with the default the new query-friendly group-by-type.
The server is now able to perform a set of health checks on models when it is starting up, to advise on potential problems. With this release there exists a check for Repeatable Models which attempts to detect if your model is deterministic with respect to the configured seed. If it is not, then it will log a warning advising that the model fails the test.
","headings":[{"value":"2.2.0","depth":1},{"value":"Upgrading","depth":2},{"value":"Immutable Schema","depth":3},{"value":"Java 9+ Compatibility","depth":3},{"value":"Deprecations","depth":2},{"value":"SeededRandom.create()","depth":3},{"value":"Field Groups","depth":3},{"value":"AgentBasedModel#registerAgentType","depth":3},{"value":"Improvements","depth":1},{"value":"Console","depth":2},{"value":"Time Control","depth":3},{"value":"Network View","depth":3},{"value":"Charts","depth":3},{"value":"Sidebar","depth":3},{"value":"Installation","depth":2},{"value":"Global Install Support","depth":3},{"value":"License Server Support","depth":3},{"value":"New Modules","depth":2},{"value":"Model Scaffolding","depth":3},{"value":"New APIs","depth":2},{"value":"Time Series Variables","depth":3},{"value":"Empirical Distributions","depth":3},{"value":"ModelContext","depth":3},{"value":"Model.init","depth":3},{"value":"Model Sampler","depth":3},{"value":"Experimental Modules","depth":2},{"value":"Financial Tool Kit","depth":3},{"value":"SparkGraph","depth":3},{"value":"DistributedGraph","depth":3},{"value":"Other Enhancements","depth":2},{"value":"Command Line Interface","depth":3},{"value":"Parquet Directory Structure","depth":3},{"value":"Model Health Checks","depth":3}],"frontmatter":{"title":"Release Notes","toc":false,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.2/docs/release-notes.md","versioned":true,"version":"2.2","kind":"docs","pagePath":"/release-notes","chronology":{"prev":{"name":"Repeatable Models","path":"/practices/repeatable-models"},"next":{"name":"History","path":"/release-notes/release-history"}},"lastUpdated":"2026-04-21T13:56:54.834Z"}}