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

2.3.0

\n

16th September 2019

\n

2.3 includes multiple new modules, new APIs, and a more powerful console. We have been careful in 2.3 to avoid any major breaking changes, but there are still a few things to be aware of. A change in imports in particular will be a breaking change for most models, and a change in the paquet output config field.

\n

Data output with output channels

\n

More flexible, detailed data can now be output and written to parquet, without having to use annotations and output at every tick. More about how to use this can be seen under Data Output

\n

ModelRunner

\n

The model runner has been updated, allowing users to create different types of multiruns, where previously, only batch runs were possible. More about how to use this can be seen under Multirun Setup

\n

Parquet output

\n

Previously, parquet output was managed via a config flag \"core.parquet-export\". This has now been changed to \"core.parquet-export.enabled\"

\n

Agent context

\n

Agents now have a view onto the model context, which provides information about the current tick and gives access to the output channels.

\n

Import updates

\n

Several classes have been moved, so their imports will have to be updated to reflect that. The easiest way to do that is to remove the old imports which are broken, and with your mouse over the erroring classes, press alt + enter (this only works if using Intelij). Intelij will now be able to find and add the new import for you.

\n

2.2.0

\n

29th March 2019

\n

Immutable Schema

\n

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.

\n

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 = false
\n

Migrating 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:

\n
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}
\n

Additional information is available in the reference on Model Initialisation.

\n

Java 9+ Compatibility

\n

The 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.

\n

Deprecations

\n

SeededRandom.create()

\n

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).

\n

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.

\n

Field Groups

\n

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).

\n

AgentBasedModel#registerAgentType

\n

This method has been deprecated in favour of AgentBasedModel#registerAgentTypes which can take any number of classes.

\n

Console

\n

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

Time Control

\n\n

Network View

\n\n

Charts

\n\n

Sidebar

\n\n

Installation

\n

Global Install Support

\n

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.

\n

License Server Support

\n

The 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.

\n

New Modules

\n

Model Scaffolding

\n

Model 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.

\n

New APIs

\n

Time Series Variables

\n

Agents now support Time Series Variables through windowed values, which are values that track a value through a certain number of ticks.

\n

Empirical Distributions

\n

Empirical 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.

\n

ModelContext

\n

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).

\n

Model.init

\n

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.

\n

Model Sampler

\n

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.

\n

Experimental Modules

\n

In 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.

\n

Financial Tool Kit

\n

This 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.

\n

The full documentation for this module is here on the reference: Financial Tool Kit.

\n

SparkGraph

\n

SparkGraph has been reclassified as an experimental module, with no other changes.

\n

DistributedGraph

\n

DistributedGraph 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.

\n

Other Enhancements

\n

Command Line Interface

\n

The 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.

\n

Parquet Directory Structure

\n

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).

\n

This release adds a new configuration setting to control the output structure, with the default the new query-friendly group-by-type.

\n

Model Health Checks

\n

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.

\n

2.1.0

\n

7th November 2018

\n

This major release of the Simudyne SDK is focused on three main themes:

\n
    \n
  1. Improved data input / output for simulation models.
    2. \n
  2. An enhanced console for better visualisation of agent-based model output.
    3. \n
  3. Better modelling APIs for agent-based models, and the introduction of a new System Dynamics modelling API.
    4. \n
\n

Breaking Changes

\n\n

Licensing

\n

The Simudyne SDK now requires an individually issued license file to operate. This license contains certain characteristics and restrictions, such as validity dates and contractual CPU core limits. This file must be placed and referenced correctly in a Simudyne project for the Simudyne libraries to function. These license files should be requested from Simudyne. Detailed information on licensing restrictions for the SDK can be seen under Licensing Documentation.

\n

Data Import and Export

\n

Data about the current state of a simulation can be retrieved as JSON via the REST API. The Simudyne SDK can also export all simulation data to Parquet files for further analysis.

\n

Console

\n

Network visualisation view

\n

The network visualisation tile has been removed. Network visualisation now has its own tab, which paves the way for enhanced network visualisations and analytics in forthcoming releases.

\n

Agent Attribute Aggregation

\n

Agent attributes can now be aggregated (mean or total) and represented as line charts on the console.

\n

Agent Attribute Time-Series

\n

Agent attributes can be represented as line charts on the console. This allows the user to observe the evolution of an agent attribute (e.g. income) through time.

\n

Tile Search Tool

\n

Tiles are made available through a new search tool, allowing the user to toggle on and off the visualisations they want presented on the console.

\n

Modelling API

\n\n

The default link type BlankLink has been removed. When building links via connectors, link type must always be defined and declared. This has been done to encourage the good modelling practice of naming the defined relationships, as this can become confusing when transitioning from simple models to more complicated ones.

\n

Messaging API

\n

For broadcastMessage, a new fluent API now provides the capability to filter and customise messages sent based on the link the message will be sent along. The capability to broadcast along all link types has been removed, as this was rarely the modeller's intention once multiple link types are defined. Broadcasting along links could cause confusing and unexpected behaviour.

\n
//////\n// 2.0\n//////\ncell.broadcastMessage(new Messages.Aliveness(cell.alive),\n                      Links.Neighbour.class);\n\n// Any message received is inside a wrapper Message type.\nMessage<Messages.Aliveness> m = cell.getMessageOfType(Messages.Aliveness.class);\n\n//////\n// 2.1\n//////\n\n// Using a generic message class.\ncell.getLinks(Links.Neighbour.class)\n    .send(Messages.Aliveness.class, (msg, link) -> msg.alive = cell.alive);\n\n// Using a specialised message class (shown below)\n// Here the value given is assigned into the body\n// of the constructed messages automatically.\ncell.getLinks(Links.Neighbour.class)\n    .send(Messages.Aliveness.class, cell.alive);\n\n// New functionality, customising and filtering messages sent\n// using link information.\ncell.getLinks(Links.Neighbour.class)\n    /* filter messages sent based on link */\n    .filter(link -> link.property < 100)\n    /* can set message body based on link attributes */\n    .send(Messages.Aliveness.class,\n          (msg, link) -> msg.setBody(link.property > some_condition));\n\n// Any message received is now the message type itself\nMessages.Aliveness m = cell.getMessageOfType(Messages.Aliveness.class);
\n

For direct messaging with sendMessage, use the same message construction API based around Agent#send, but use Messaging#to to define the subsequent destination.

\n
//////\n// 2.0\n//////\n\ncell.sendMessage(new Messages.Aliveness(cell.alive), sender);\n\n//////\n// 2.1\n//////\n\ncell.send(Messages.Aliveness.class, cell.alive).to(sender);
\n\n

User-defined message and link types should now extend the built-in Message and Link classes. These classes should not define any constructor that requires parameters. There are also built-in special classes for messages containing a single primitive type, e.g. Message.Boolean, Message.Double, etc. When using these types, there is a convenient shorthand when constructing messages, as shown above.

\n
//////\n// 2.0\n//////\n\npublic class Messages {\n    public static class Aliveness {\n        public boolean alive;\n\n        public Aliveness(boolean alive) {\n            this.alive = alive;\n        }\n    }\n}\n\n//////\n// 2.1\n//////\n\npublic class Messages {\n    // Generic Message\n    public static class Aliveness extends Message {\n        public boolean alive;\n    }\n\n    // Extending the special message class\n    public static class Aliveness extends Message.Boolean {}\n}
\n

Links should similarly extend the Link class. There is currently a single specialisation of link, Link.Empty, that may provide optimisation benefits in the future.

\n

System Dynamics API

\n

System Dynamics is an approach to understand complex nonlinear systems via the creation of stocks, flows, delays, and feedback loops. Originally developed in the 1950's to model industrial or factory processes, it has been used to understand and map large, complex systems to enact policies in the fields of trade, banking, regulation, and more.

\n

A new System Dynamics API has been introduced, allowing users to implement system dynamics models in Simudyne.

\n

Auto-Compilation

\n

The Simudyne auto-compiler allows models to be automatically compiled when changes are made. For now, this must be explicitly enabled via opt-in configuration of the development server.

\n

2.0.5

\n

22nd August 2018

\n

This is a minor improvement release, including a compatibility update for deployment on Spark 2.2.x.

\n

Dependency Changes

\n\n

Module changelogs

\n

core-abm

\n\n

core

\n\n

2.0.4

\n

2nd August 2018

\n

This is a bug-fix release, most importantly fixing issues relating to execution on Spark using YARN.

\n

Dependency Changes

\n\n

Module Changelogs

\n

core-abm

\n\n

nexus-server

\n\n

core-graph-spark

\n\n

2.0.3

\n

26th June 2018

\n

This is a critical bug-fix release relating to deployment on Cloudera Spark clusters.

\n

Dependency Changes

\n\n

console

\n\n

2.0.2

\n

8th June 2018

\n

Breaking Changes

\n

This release is primarily focused on bug fixes but does include a minor API change to be aware of when upgrading. Data injectors for links now receive the agent itself rather than an InitContext. This change allows link attributes to be set based on the agent, and for agents to be altered based on their links. Access to the seeded PRNG and agent ID is then available directly from the agent, e.g. Agent#getPrng().

\n
Group<MyAgent> = generateGroup(MyAgent.class, 100)\n\n// Before\nmyGroup.fullyConnected(otherGroup, MyLink.class,\n    // receives types InitContext and MyLink\n    (initContext, myLink) -> { ... });\n\n// After\nmyGroup.fullyConnected(otherGroup, MyLink.class,\n    // receives types MyAgent and MyLink\n    (myAgent, myLink) -> { ... });
\n

Behavioural Changes

\n

This release includes some improvements which can affect the behaviour of models.

\n\n

Console

\n\n

nexus-server

\n\n

core-abm

\n\n

core-graph

\n

Note that changes within this module should not directly affect any users of the API unless noted under core-abm, unless you are using this lower level implementation directly.

\n\n

2.0.1

\n

17th May 2018

\n

This is a minor bug fix release, primarily resolving issues with the network tile display. Improvements have also been made to the ABM API, allowing more flexible definition of actions, as well as injection of attributes to agents loaded from external sources.

\n

Console

\n\n

core-abm

\n\n

2.0.0

\n

April 19th 2018

\n

First major release of the new Simudyne SDK 2.0.

","headings":[{"value":"2.3.0","depth":2},{"value":"Data output with output channels","depth":3},{"value":"ModelRunner","depth":3},{"value":"Parquet output","depth":3},{"value":"Agent context","depth":3},{"value":"Import updates","depth":3},{"value":"2.2.0","depth":2},{"value":"Immutable Schema","depth":4},{"value":"Java 9+ Compatibility","depth":4},{"value":"Deprecations","depth":3},{"value":"SeededRandom.create()","depth":4},{"value":"Field Groups","depth":4},{"value":"AgentBasedModel#registerAgentType","depth":4},{"value":"Console","depth":3},{"value":"Time Control","depth":4},{"value":"Network View","depth":4},{"value":"Charts","depth":4},{"value":"Sidebar","depth":4},{"value":"Installation","depth":3},{"value":"Global Install Support","depth":4},{"value":"License Server Support","depth":4},{"value":"New Modules","depth":3},{"value":"Model Scaffolding","depth":4},{"value":"New APIs","depth":3},{"value":"Time Series Variables","depth":4},{"value":"Empirical Distributions","depth":4},{"value":"ModelContext","depth":4},{"value":"Model.init","depth":4},{"value":"Model Sampler","depth":4},{"value":"Experimental Modules","depth":3},{"value":"Financial Tool Kit","depth":4},{"value":"SparkGraph","depth":4},{"value":"DistributedGraph","depth":4},{"value":"Other Enhancements","depth":3},{"value":"Command Line Interface","depth":4},{"value":"Parquet Directory Structure","depth":4},{"value":"Model Health Checks","depth":4},{"value":"2.1.0","depth":2},{"value":"Breaking Changes","depth":3},{"value":"Licensing","depth":3},{"value":"Data Import and Export","depth":3},{"value":"Console","depth":3},{"value":"Network visualisation view","depth":4},{"value":"Agent Attribute Aggregation","depth":4},{"value":"Agent Attribute Time-Series","depth":4},{"value":"Tile Search Tool","depth":4},{"value":"Modelling API","depth":3},{"value":"BlankLink Removal","depth":4},{"value":"Messaging API","depth":4},{"value":"Message and Link Classes","depth":4},{"value":"System Dynamics API","depth":4},{"value":"Auto-Compilation","depth":3},{"value":"2.0.5","depth":2},{"value":"Dependency Changes","depth":3},{"value":"Module changelogs","depth":3},{"value":"core-abm","depth":4},{"value":"core","depth":4},{"value":"2.0.4","depth":2},{"value":"Dependency Changes","depth":3},{"value":"Module Changelogs","depth":3},{"value":"core-abm","depth":4},{"value":"nexus-server","depth":4},{"value":"core-graph-spark","depth":4},{"value":"2.0.3","depth":2},{"value":"Dependency Changes","depth":3},{"value":"console","depth":3},{"value":"2.0.2","depth":2},{"value":"Breaking Changes","depth":3},{"value":"Behavioural Changes","depth":3},{"value":"Console","depth":4},{"value":"nexus-server","depth":4},{"value":"core-abm","depth":4},{"value":"core-graph","depth":4},{"value":"2.0.1","depth":2},{"value":"Console","depth":3},{"value":"core-abm","depth":3},{"value":"2.0.0","depth":2}],"frontmatter":{"title":"History","toc":true,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.3/docs/release-notes/release-history.md","versioned":true,"version":"2.3","kind":"docs","pagePath":"/release-notes/release-history","chronology":{"prev":{"name":"Release Notes","path":"/release-notes"},"next":{"name":"Libraries","path":"/release-notes/libraries"}},"lastUpdated":"2026-04-21T13:56:54.841Z"}}