History

2.1.0

7th November 2018

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

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

Breaking Changes

• License files are now required; please see the licensing section below. Existing contract holders will be contacted regarding license provisioning.
• The messaging API has been updated. Please see the migration notes further down these release notes for instructions on upgrading.

Licensing

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.

Data Import and Export

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.

Console

Network visualisation view

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.

Agent Attribute Aggregation

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

Agent Attribute Time-Series

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.

Tile Search Tool

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.

Modelling API

BlankLink Removal

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.

Messaging API

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.

//////
// 2.0
//////
cell.broadcastMessage(new Messages.Aliveness(cell.alive),
                      Links.Neighbour.class);

// Any message received is inside a wrapper Message type.
Message<Messages.Aliveness> m = cell.getMessageOfType(Messages.Aliveness.class);

//////
// 2.1
//////

// Using a generic message class.
cell.getLinks(Links.Neighbour.class)
    .send(Messages.Aliveness.class, (msg, link) -> msg.alive = cell.alive);

// Using a specialised message class (shown below)
// Here the value given is assigned into the body
// of the constructed messages automatically.
cell.getLinks(Links.Neighbour.class)
    .send(Messages.Aliveness.class, cell.alive);

// New functionality, customising and filtering messages sent
// using link information.
cell.getLinks(Links.Neighbour.class)
    /* filter messages sent based on link */
    .filter(link -> link.property < 100)
    /* can set message body based on link attributes */
    .send(Messages.Aliveness.class,
          (msg, link) -> msg.setBody(link.property > some_condition));

// Any message received is now the message type itself
Messages.Aliveness m = cell.getMessageOfType(Messages.Aliveness.class);

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

//////
// 2.0
//////

cell.sendMessage(new Messages.Aliveness(cell.alive), sender);

//////
// 2.1
//////

cell.send(Messages.Aliveness.class, cell.alive).to(sender);

Message and Link Classes

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.

//////
// 2.0
//////

public class Messages {
    public static class Aliveness {
        public boolean alive;

        public Aliveness(boolean alive) {
            this.alive = alive;
        }
    }
}

//////
// 2.1
//////

public class Messages {
    // Generic Message
    public static class Aliveness extends Message {
        public boolean alive;
    }

    // Extending the special message class
    public static class Aliveness extends Message.Boolean {}
}

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.

System Dynamics API

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.

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

Auto-Compilation

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.

2.0.5

22nd August 2018

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

Dependency Changes

• json4s has been downgraded to version 3.2.11 to match Spark 2.2.x.

Module changelogs

core-abm

• Agent#setEnvironment signature has been updated to be consistent with that in Vertex, resolving a warning showing in some IDEs.
• Performance for frequently used LongAccumulator and DoubleAccumulator when running on machines with high core counts has been improved.

core

• Annotating final or effectively final values such as Scala vals as inputs now gives a clearer, eager error detailing the issue.

2.0.4

2nd August 2018

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

Dependency Changes

• akka and akka-http have been updated to their latest versions (2.5.13 and 10.1.3 respectively)
• akka-slf4j is now included as a dependency.
• akka-http-testkit is no longer included as a dependency.

Module Changelogs

core-abm

• When loading links from a Source, ids are now validated to be in the expected range of IDs.

nexus-server

• Timeout for long operations has been increased from 20 seconds to 120 seconds.

core-graph-spark

• Resolved issues with execution on Spark using YARN, related to Kryo ClassLoaders.
• Resolved issues related to serialisation occurring with Spark 2.2.0.

2.0.3

26th June 2018

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

Dependency Changes

• Spark dependency is now properly marked as "provided" scope.
• fastutil library has been downgraded from version 8.1.1 to 6.3, to match commonly deployed ambient libraries.

console

• String input fields should no longer be null when set from the console.

2.0.2

8th June 2018

Breaking Changes

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

Group<MyAgent> = generateGroup(MyAgent.class, 100)

// Before
myGroup.fullyConnected(otherGroup, MyLink.class,
    // receives types InitContext and MyLink
    (initContext, myLink) -> { ... });

// After
myGroup.fullyConnected(otherGroup, MyLink.class,
    // receives types MyAgent and MyLink
    (myAgent, myLink) -> { ... });

Behavioural Changes

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

• For APIs where a class is specified for selection, all subclasses of that type will also be selected. See specific changes in core-abm for further information.
• When loading external data, user data injectors are now run after the external data has been assigned to the instance.

Console

• The network tile is now always shown as the first tile when displayed.
• The network tile can now appropriately display boolean attributes.
• The fan chart shown for multi run results should no longer report NaN as the current value.
• The headings for agent tables should now always align with the corresponding columns.
• Values of type int and long will no longer show decimal places in the agent table.
• Inputs of type String are now supported in the console.
• Exception modals can now be dismissed.

nexus-server

• The default nexus timeout, controlled by nexus-server.nexus-lifetime, has been increased from 30 to 60 minutes.
• Progress for batched model runs is now calculated from the total progress on ticks, rather than the total progress on runs, which should give a smoother progress update when running a high number of ticks.
• Batch runs now use the nexus-server.batchrun-lifetime configuration property to determine how long the server stores the results, and this is now timed from when the results are generated rather than when the batch processing is started.
• Exceptions thrown during a batch run are now caught and reported. This will also include the root PRNG seed for the run that failed.

core-abm

• [Behaviour Change] AgentSelection, as returned by AgentBasedModel#select(Class<AgentType>), now includes subclasses of the given agent type in the selection.
• [Behaviour Change] Messages and Links retrieved from an agent, e.g. from Agent#getMessagesOfType(Class<MessageType>), now include subclasses of the given type.
• [Behaviour Change] The data injector run by loadGroup(Class<AgentType>, Source, SerializableConsumer<T>) now runs after data from the source has been injected, rather than before.
• [Breaking Change] Connector data injectors now are given the Agent instance itself, rather than an InitContext. This allows links to be created based on attributes of the agent, and also for agents to be updated based on link properties.

core-graph

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.

• [Behaviour Change] VertexSelection now includes subclasses of the given agent type in the selection.
• [Breaking Change] Vertex is now an abstract class, rather than an interface. Methods relating to accessing links, such as Environment#getLinks() have moved from the Environment interface to the Vertex class.
• [Breaking Change] Graph#addVertices now receives an InitContext rather than a ConnectionInitializer
• simudyne.core.graph.SerializationLevel and related configuration setting core-abm.serialization-level have been removed.

2.0.1

17th May 2018

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.

Console

• Improved attribute selection UI for network tile.
• Improved display for hovering agents in the network tile.
• Network tile should now reliably update when links in the network change.
• Agent table now shows rounded numbers for floating point values.
• Upgrading console version should no longer require a browser cache clear.

core-abm

• Actions now also run against all subclasses of their defined agent class.

• Added AgentSystem#loadGroup(Class<AgentType>, Source, Consumer<AgentType>) (as well as AgentBasedModel#loadGroup(...) shortcut method).

  • This allows customisation of agent attributes when loaded from a Source, in the same way as generating agents from scratch allows.

2.0.0

April 19th 2018

First major release of the new Simudyne SDK 2.0.