YAML simulation specification

Warning

This reference guide assumes that the reader knows the basics of YAML. A good resource to learn it quickly is Learn X in Y minutes where X = YAML

Reading this document

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Simulation document structure

The document MUST be YAML map. The map MUST contain all the mandatory Alchemist keys, MAY contain any subset of the optional Alchemist keys, MAY contain any key whose name begins with underscore (_), and MUST NOT contain any other key.

The sets of valid cobinations of mandatory and optional keys for each section of the document is specified in form of Kotlin code as follows:

Types of entries

Type Description
Any Any YAML type
Int YAML integer number, or other type that can be parsed into an integer
List Any YAML List
Map Any YAML Map
MultiSpec A list of Spec. A Map matches a MultiSpec if it matches one and only one of its Spec.
Number YAML number
Spec Pair of lists of strings. The first list contains mandatory keys, the second optional keys. A map matches a Spec if it contains all its mandatory keys, any of the optional keys, and no other key
SpecMap A YAML Map matching a MultiSpec
String YAML String
Traversable One of: A SpecMap, a List of Traversable, a Map of Traversable

Arbitrary class loading system

Type: SpecMap

Alchemist is able to load arbitrary types conforming to the expected interface (or Scala trait). The expected type depends on where the class is requested. This section describes how the system works independently of the specific target type.

(Multi)Spec

Mandatory keys Optional keys
type parameters

type

Type: String

The name of an instanceable class compatible with the expected interface. It can be either the qualified name or a simple name, in the latter case the class SHOULD be located in the same package where the default alchemist implementations of the same interface live.

If a name includes a ., it is interpreted as a fully qualified name. Otherwise, it is interpreted as a simple name. Provided types SHOULD NOT be located in the default package.

For instance, if the expected type is an Action and the concrete type FooAction, FooAction SHOULD be located into package it.unibo.alchemist.model.actions.

parameters

Type: List or Map

The list of parameters the constructor of type should be passed. Alchemist automatically provides contextual information to the constructors: for instance, if an Action is being built, the loading system is aware of the current RandomGenerator, Incarnation, Environment, Deployment, Node, TimeDistribution, and Reaction, as the action requires all of them. Consequently, all parameters of these types SHOULD NOT be manually specified (on the other hand, the syntax is built to make it very difficult to do by mistake). The constructor MAY fail if they are provided.

If a Map is provided instead of a List, then the keys are interpred as the parameter names, and their associated values as the corresponding parameter values. Since Java 11 does not support named arguments, this special invocation type is built around the Kotlin reflection, thus, the concrete class whose constructor is being invoked MUST be written in Kotlin.

When using named arguments, if at least one optional parameter is specified, then all the previous optional parameters MUST be specified as well. This limitation is due to the fact that Alchemist supports loading of JVM classes regardless of their origin language, and, thus, the simulator must leverage constructor overloading to emulate optional parameters. In the case of Kotlin classes, because of the way @JvmOverloads works, only a (reasonable) subset of all possible overloads gets generated, and they differ by parameter count.

Instantiation is delegated to the Java Implicit Reflective Factory.

Examples

  • Construction of a Point
    Click to show / hide code
  • Construction of variables with named parameters
    Click to show / hide code

Counter-examples

  • The following simulation fails on loading, as BidimensionalGaussianLayer has the first and last parameters marked as optional: in order to provide the latter, the designer must also provide the former.
    Click to show / hide code

Document root

Type: SpecMap

The document contents at the root of the file. Contains all the information required to buld a Loader, which, in turn, is able to spawn Simulations through a Launcher.

(Multi)Spec

Mandatory keys Optional keys
incarnation deployments, environment, export, layers, launcher, network-model, remote-dependencies, seeds, terminate, variables

Examples

  • Minimal Biochemistry specification
    Click to show / hide code
  • Minimal Protelis specification
    Click to show / hide code
  • Minimal SAPERE specification
    Click to show / hide code

incarnation

Type: String

Valid incarnation types in the full distribution:

  • biochemistry
  • protelis
  • sapere
  • scafi

Examples

  • Minimal Biochemistry specification
    Click to show / hide code
  • Minimal Protelis specification
    Click to show / hide code
  • Minimal SAPERE specification
    Click to show / hide code

action

Builds an Action using the arbitrary class loading system.


condition

Builds a Condition using the arbitrary class loading system.


deployments

Type: Traversable

Traversable of deployment

deployment

Type: SpecMap

Definition of the positions of a set of nodes. Builds a Deployment using the same syntax of arbitrary class loading system, with additional keys.

(Multi)Spec

Mandatory keys Optional keys
type parameters, contents, nodes, programs

Examples

  • Deployment of a single node in a point
    Click to show / hide code
  • Deployment of three nodes
    Click to show / hide code
  • Deployment of three nodes, but nesting the traversable
    Click to show / hide code
  • Deployment of three nodes through SpecificPositions.
    Click to show / hide code
  • Grid centered in (0, 0), with nodes distanced of 0.25 both horizontally and vertically.
    Click to show / hide code
  • Irregular Grid centered in (0, 0), with nodes distanced of 0.25 both horizontally and vertically, randomly perturbed of (±0.1 distance units).
    Click to show / hide code
  • Nodes located randomly inside a Circle
    Click to show / hide code
  • Nodes located randomly inside a Rectangle
    Click to show / hide code
  • Nodes located randomly inside a Polygon delimiting the Venice Lagoon
    Click to show / hide code

deployment.type

Same as type

deployment.parameters

Same as parameters

deployment.contents

Type: Traversable of content

deployment.nodes

Type: SpecMap

Forces the type of Node, building concrete types through the arbitrary class loading system. If left unspecified, nodes get created through Incarnation.createNode.

Examples

  • Creation of heterogeneous pedestrians
    Click to show / hide code

deployment.properties

Type: Traversable of property

deployment.programs

Type: Traversable of program


content

Type: SpecMap

Definition of the contents (Molecules and Concentrations) of a group of nodes.

(Multi)Spec

Mandatory keys Optional keys
molecule, concentration in

Examples

  • Three molecules injected into all nodes deployed in the scenario
    Click to show / hide code
  • Injection of a molecule only in those nodes located inside a Rectangle
    Click to show / hide code

content.molecule

Type: String or SpecMap

The name of the molecule to be injected. If a String is provided, then it is created via Incarnation.createMolecule. Otherwise, the arbitrary class loading system SHOULD be used.

content.concentration

Type: String

The concentration of the molecule to be injected. If a String is provided, then it is created via Incarnation.createConcentration. Otherwise, the arbitrary class loading system SHOULD be used.

content.in

Type: Traversable of shapeFilter

property

Type: SpecMap

(Multi)Spec

Mandatory keys Optional keys
type parameters, in

property.type

Same as type

property.parameters

Same as parameters

property.in

Type: Traversable of shapeFilter


environment

Type: SpecMap

Builds an Environment using the same syntax of arbitrary class loading system.

If left unspecified, defaults to a bidimensional Euclidean manifold: Continuous2DEnvironment.

Type: SpecMap

Examples

  • Default environment, omitted specification
    Click to show / hide code
  • Explicitly builds a Continuous2DEnvironment solely with the contextual parameters
    Click to show / hide code
  • Explicitly builds a Continuous2DEnvironment using the qualified type name using only the contextual parameters
    Click to show / hide code
  • Explicitly builds a Continuous2DEnvironment explicitly specifying that no parameters but the contextual ones should be used
    Click to show / hide code

export

Type: Traversable of exporter


exporter

Type: SpecMap

Definition of the contents (Molecules and Concentrations) of a group of nodes.

(Multi)Spec

Mandatory keys Optional keys
type, data parameters

exporter.type

Same as type

exporter.data

Type: Traversable of extractor

exporter.parameters

Same as parameters


extractor

Type: String or SpecMap

The only supported String is "time". Otherwise, a SpecMap MUST be provided.

Creates instances of Extractor.

(Multi)Spec

Mandatory keys Optional keys
type parameters
molecule property, aggregators, value-filter

extractor.type

Same as type

extractor.parameters

Same as parameters

extractor.molecule

Type: String

Name of a Molecule to be read from nodes and exported. The String is passed down to Incarnation.createMolecule. The created molecule is read from every node.

extractor.property

Type: String

Name of a property to be extracted from the selected Molecule. The Molecule and the String are passed down to Incarnation.getProperty. The obtained value is added to the exports.

extractor.aggregators

Type: String or List of Strings

Name of any valid UnivariateStatistic, case insensitive. All those provided with Apache Commons Math are available by default. New statistics can be defined, they get loaded transparently as far as their package matches the one of Apache Commons Math.

If the aggregators are specified, only one value per aggregator gets exported, instead of one value for each node.

extractor.value-filter

Type: String or SpecMap

Builds a ExportFilter, to be applied to raw data before being processed by the aggregators(#extractoraggregators), if present. If a String is provided, then it is used to load a policy from CommonFilters. Otherwise, the arbitrary class loading system MUST be used.

Mandatory keys Optional keys
type parameters

extractor.value-filter.type

Same as type

extractor.value-filter.parameters

Same as parameters


launcher

Type: SpecMap

Builds a Launcher using the arbitrary class loading system. If unspecified, defaults to DefaultLauncher, which runs the default simulation, unless the variable set on which the batch should be executed is specified.

Customizing the launcher can be useful for implementing custom batch execution strategies, or “simulations of simulations”, if the process requires multiple simulation “stages” (e.g., running a batch to train a neural network, then running another batch to test it).


layer

Type: SpecMap

Builds a Layer using the arbitrary class loading system.

Examples

  • Creation of two Layers
    Click to show / hide code
  • Creation of two BidimensionalGaussianLayers:
    Click to show / hide code

layers

Type: Traversable of layer

Examples

  • Creation of two Layers
    Click to show / hide code
  • Creation of two BidimensionalGaussianLayers:
    Click to show / hide code

monitor

Type: SpecMap Builds a OutputMonitor using the arbitrary class loading system.

Examples

  • Creation of one OutputMonitors
    Click to show / hide code

monitors

Type: Traversable of monitor

Examples

  • Creation of one OutputMonitors
    Click to show / hide code

network-model

Type: SpecMap

Builds a LinkingRule using the arbitrary class loading system. If unspecified, defaults to NoLinks, and no node will have any neighbor.

Examples

  • Nodes connected when closer than some range
    Click to show / hide code

program

Type: SpecMap

Definition of the contents (Molecules and Concentrations) of a group of nodes.

(Multi)Spec

Mandatory keys Optional keys
type parameters, conditions, time-distribution actions
program time-distribution

program.type

Same as type

program.program

Type: String

Passed to Incarnation.createReaction to be interepreted and

program.in

Type: Traversable of shapeFilter

program.actions

Type: Traversable of action

program.conditions

Type: Traversable of condition

program.parameters

Same as parameters

program.time-distribution

Type: String or SpecMap

Builds a TimeDistribution. If a String is provided, then it is created via Incarnation.createTimeDistribution. Otherwise, the arbitrary class loading system SHOULD be used.


remote-dependencies


shapeFilter

Type: SpecMap

Builds a PositionBasedFilter using the arbitrary class loading system.

Examples

  • Injection of a molecule only in those nodes located inside a Rectangle
    Click to show / hide code

seeds

Type: SpecMap

Selection of the seed for the RandomGenerators.

(Multi)Spec

Mandatory keys Optional keys
scenario, simulation

seeds.scenario

Type: Int

Selection of the seed for the RandomGenerator controlling the position of random displacements.

seeds.simulation

Type: Int

Selection of the seed for the RandomGenerator controlling the evolution of the events of the simulation.


terminate

Type: Traversable of terminator


terminator

Type: SpecMap

Builds a Predicate using the arbitrary class loading system.

Examples

  • Termination after some time
    Click to show / hide code
    Click to show / hide code
    Click to show / hide code

variable

Type: SpecMap

Definition of free and dependent variables.

(Multi)Spec

Mandatory keys Optional keys
type parameters
min, max, step, default
formula language, timeout

Variables can be created in three ways:

variable.type

Same as type

variable.parameters

Same as parameters

variable.default

Type: Number

Default value for a LinearVariable, to be selected if the variable is not among those generating the batch.

variable.max

Type: Number

Maximum value for a LinearVariable

variable.min

Type: Number

Minimum value for a LinearVariable

variable.step

Type: Number

Size of the incremental step of a LinearVariable

variable.formula

Type: String

Code that can be interpreted by a JSR223Variable.

variable.language

Type: String

Language to be used by a JSR223Variable. The language must be available in the classpath. Groovy (default), Kotlin (kotlin or kts), and Scala (scala) are supported natively.

variable.timeout

Type: Int

Time in milliseconds after which the interpreter of the JSR223Variable is considered stuck or in livelock. The interpreter gets interrupted and the simulation loading fails to prevent unresponsive simulations. Defaults to 1000ms.


variables

Type: Traversable of variable