Jump to notes for a specific release with the following links:

2.2.0

29th March 2019

This is a major relase of the software, including multiple new modules, new APIs, and a more powerful console.

Upgrading

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

Immutable Schema

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.

# In your simudyneSDK.properties file

feature.immutable-schema = false

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:

public void init() {
  createLongAccumulator("buys", "Number of buy orders");
  createLongAccumulator("sells", "Number of sell orders");
  createDoubleAccumulator("price", "Price");

  registerAgentTypes(Market.class, Trader.class);
  registerLinkTypes(Links.TradeLink.class);
}

Additional information is available in the reference on Model Initialisation.

Java 9+ Compatibility

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.

Deprecations

SeededRandom.create()

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 Groups

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

AgentBasedModel#registerAgentType

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

Improvements

Console

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:

Time Control

• The new time bar at the top of the side panel can be moved to a point in the models past. This syncs with all point-in-time visualisations such as the network, so you can see these more detailed visualisations at any point in the models timeline.
• Time series charts can now be zoomed, and a new time bar beneath each time series chart allows the zoomed view to be panned through time.

Network View

• Network visualisation has been rebuilt to use hardware acceleration, allowing much larger networks of agents to be visualised.
• A circular layout option has also been added, which is much faster to layout, and better for visualising some types of networks.

Charts

• Time series charts can now be toggled between bar and line chart views, with bar chart view being the default.
• Agent attributes can now be aggregated as histograms, showing the distribution of the attribute across the agents at a point in time. Combined with the time bar control, you can now see how distributions evolve as your model runs.
• Balance sheet and order book visualisations for the new experimental Financial Tool kit.
• Charts can now show real time value, rather than tick numbers. The mapping from tick to time can be controlled through the @ModelSettings annotations on the Model class.

Sidebar

• Sidebar can now be collapsed, giving more space for visualisations.
• Inputs now better indicate when they are read only.

Installation

Global Install Support

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.

License Server Support

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.

New Modules

Model Scaffolding

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.

New APIs

Time Series Variables

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

Empirical Distributions

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.

ModelContext

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

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.

Model Sampler

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.

Experimental Modules

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.

Financial Tool Kit

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.

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

SparkGraph

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

DistributedGraph

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.

Other Enhancements

Command Line Interface

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.

Parquet Directory Structure

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

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

Model Health Checks

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.