Create reusable variables

Declaring variables

The variables section lists variable simulation values. A variable defines some kind of value that can be referenced in the simulation file.

There are two kinds of variables: free and dependent variables. Free variables are meant to provide support for running batches of simulations with varying parameters; dependent variables are either single valued or can be computed from the values of other variables (free or dependent), and they are designed to simplify the simulation code.

Free variables

Free variables define a set of values and a default. Their main scope is enabling Alchemist to run a set of simulations with different parameters (values of variables) without the need to duplicate the simulation code. When used in this mode (called “batch mode”), Alchemist by default produces the cartesian product of all the variables values’ selected for the batch, and runs a simulation for each combination. If the simulation is not executed as batch, then the default value is used.

Linear variables

A variable generating values in a range, starting from a minimum value, and increasing by some step. Represented by LinearVariable.

Examples

Click to show / hide code

incarnation: protelis
variables:
  zoom: &zoom
    formula: 0.1 # Must be a valid Groovy snippet
  image_name: { formula: "'chiaravalle.png'" }
  image_path: &image_path
    language: kotlin # Pick whatever JSR223 language you like and add it to the classpath
    formula: | # The following is pure Kotlin code. Other variables can be referenced!
      import java.io.File
      fun File.findImage(): String? = walkTopDown().find { image_name in it.name }?.absolutePath
      fun File.findImageRecursively(): String = findImage() ?: File(this, "..").findImageRecursively()
      File(".").findImageRecursively()
    timeout: 5000
  # Linear free variable
  walking_speed: &walk-speed { default: 1.4, min: 1, max: 2, step: 0.1 }
  seed: &seed { default: 0, min: 0, max: 99, step: 1 } # 100 samples
  scenario_seed: &scenario_seed { formula: (seed + 31) * seed } # Variable-dependent
  people_count: &people_count
    type: GeometricVariable # A variable scanning a space with geometric segmentation
    parameters: [300, 50, 500, 9] # default 300, minimum 50, maximum 100, 9 samples
seeds: { simulation: *seed, scenario: *scenario_seed}
export:
    type: CSVExporter
    parameters:
      fileNameRoot: "snippet-variables-export"
    data:
      - time
      - molecule: "default_module:default_program"
        aggregators: [ mean, max, min, variance, median ] # From Apache's UnivariateStatistic
        value-filter: onlyfinite # discards NaN and Infinity
environment: { type: ImageEnvironment, parameters: [*image_path, *zoom] }
network-model: { type: ObstaclesBreakConnection, parameters: [50] }
deployments:
  type: Rectangle
  parameters: [*people_count, 62, 15, 95, 200]
  programs:
    - time-distribution: 1
      program: >
        import protelis:coord:spreading
        let source = [110, 325]
        let vector = self.getCoordinates() - source
        let distance = hypot(vector.get(0), vector.get(1))
        distanceTo(distance < 50)        
    - program: send
    - { type: Event, time-distribution: 1, actions: { type: LevyWalk, parameters: [*walk-speed] } }

Click to show / hide code

Geometric variables

A variable generating geometrically-distributed samples across a range. Ideal for exploring non-linear phenomena, or for exploring very large ranges of values whose effect is unknown. Implemented as GeometricVariable.

Examples

Click to show / hide code

incarnation: protelis
variables:
  zoom: &zoom
    formula: 0.1 # Must be a valid Groovy snippet
  image_name: { formula: "'chiaravalle.png'" }
  image_path: &image_path
    language: kotlin # Pick whatever JSR223 language you like and add it to the classpath
    formula: | # The following is pure Kotlin code. Other variables can be referenced!
      import java.io.File
      fun File.findImage(): String? = walkTopDown().find { image_name in it.name }?.absolutePath
      fun File.findImageRecursively(): String = findImage() ?: File(this, "..").findImageRecursively()
      File(".").findImageRecursively()
    timeout: 5000
  # Linear free variable
  walking_speed: &walk-speed { default: 1.4, min: 1, max: 2, step: 0.1 }
  seed: &seed { default: 0, min: 0, max: 99, step: 1 } # 100 samples
  scenario_seed: &scenario_seed { formula: (seed + 31) * seed } # Variable-dependent
  people_count: &people_count
    type: GeometricVariable # A variable scanning a space with geometric segmentation
    parameters: [300, 50, 500, 9] # default 300, minimum 50, maximum 100, 9 samples
seeds: { simulation: *seed, scenario: *scenario_seed}
export:
    type: CSVExporter
    parameters:
      fileNameRoot: "snippet-variables-export"
    data:
      - time
      - molecule: "default_module:default_program"
        aggregators: [ mean, max, min, variance, median ] # From Apache's UnivariateStatistic
        value-filter: onlyfinite # discards NaN and Infinity
environment: { type: ImageEnvironment, parameters: [*image_path, *zoom] }
network-model: { type: ObstaclesBreakConnection, parameters: [50] }
deployments:
  type: Rectangle
  parameters: [*people_count, 62, 15, 95, 200]
  programs:
    - time-distribution: 1
      program: >
        import protelis:coord:spreading
        let source = [110, 325]
        let vector = self.getCoordinates() - source
        let distance = hypot(vector.get(0), vector.get(1))
        distanceTo(distance < 50)        
    - program: send
    - { type: Event, time-distribution: 1, actions: { type: LevyWalk, parameters: [*walk-speed] } }

Click to show / hide code

Arbitrary-valued variables

Generates an ArbitraryVariable spanning on an arbitrary set of values.

Examples

Click to show / hide code

Dependent variables

Some variables are combination of other variables. Let’s suppose that we want to deploy on a circle, but for some reason (e.g. because it is required by the constructor of some Action) we need to compute and have available radius and perimeter. We don’t need to control both of them: the perimeter can be computed from the radius (or vice versa).

To favor reusability and apply the DRY principle, the simulator allows defining variables whose values possibly depend on values of other variables through JSR223Variable. Their values can be expressed, by default, in Groovy, but any JSR-223-compatible language can be used, in principle. If a compatible JSR-223 implementation of the language is available in the classpath, Alchemist will load and use it transparently. By default, groovy, kotlin (or kts), and scala are available as scripting languages for dependent variables.

Info

The JSR-223 specification defines mechanisms allowing scripting language programs to access information developed in the Java Platform.

Many languages (including Groovy, Python (Jython), Kotlin, and Scala provide bindings for JSR-223).

Variables can be defined in any order. Alchemist figures out the dependencies automatically, as far as there are no cyclic dependencies (e.g. variable a requires b, and b requires a). Please note that the simulator variable dependency resolution system is not designed to solve mathematical systems, so even though the problem has a well-formed mathematical solution, the actual variable resolution may fail; e.g. if a is defined as 2 * b + 1, and b is defined as 4 - a, the system won’t bind a to 3 and b to 1, but will simply fail complaining about circular dependencies.

Multiline programs

Sometimes data manipulation can get tricky and trivial scripting may no longer be enough. In such cases, and especially with modern languages that allow for a reduced usage of cerimonial semicolons (such as Kotlin and Scala), it can be useful to write multiline programs. This can be achieved in YAML by using the pipe | operator, as exemplified in the following snippet:

multiline-string: |
  note that the string
  needs to be indented.
  Newlines will be preserved!

Examples

Click to show / hide code

incarnation: protelis
variables:
  zoom: &zoom
    formula: 0.1 # Must be a valid Groovy snippet
  image_name: { formula: "'chiaravalle.png'" }
  image_path: &image_path
    language: kotlin # Pick whatever JSR223 language you like and add it to the classpath
    formula: | # The following is pure Kotlin code. Other variables can be referenced!
      import java.io.File
      fun File.findImage(): String? = walkTopDown().find { image_name in it.name }?.absolutePath
      fun File.findImageRecursively(): String = findImage() ?: File(this, "..").findImageRecursively()
      File(".").findImageRecursively()
    timeout: 5000
  # Linear free variable
  walking_speed: &walk-speed { default: 1.4, min: 1, max: 2, step: 0.1 }
  seed: &seed { default: 0, min: 0, max: 99, step: 1 } # 100 samples
  scenario_seed: &scenario_seed { formula: (seed + 31) * seed } # Variable-dependent
  people_count: &people_count
    type: GeometricVariable # A variable scanning a space with geometric segmentation
    parameters: [300, 50, 500, 9] # default 300, minimum 50, maximum 100, 9 samples
seeds: { simulation: *seed, scenario: *scenario_seed}
export:
    type: CSVExporter
    parameters:
      fileNameRoot: "snippet-variables-export"
    data:
      - time
      - molecule: "default_module:default_program"
        aggregators: [ mean, max, min, variance, median ] # From Apache's UnivariateStatistic
        value-filter: onlyfinite # discards NaN and Infinity
environment: { type: ImageEnvironment, parameters: [*image_path, *zoom] }
network-model: { type: ObstaclesBreakConnection, parameters: [50] }
deployments:
  type: Rectangle
  parameters: [*people_count, 62, 15, 95, 200]
  programs:
    - time-distribution: 1
      program: >
        import protelis:coord:spreading
        let source = [110, 325]
        let vector = self.getCoordinates() - source
        let distance = hypot(vector.get(0), vector.get(1))
        distanceTo(distance < 50)        
    - program: send
    - { type: Event, time-distribution: 1, actions: { type: LevyWalk, parameters: [*walk-speed] } }

Click to show / hide code

incarnation: protelis
variables:
  zoom: &zoom
    formula: 0.1 # Must be a valid Groovy snippet
  image_name: { formula: "'chiaravalle.png'" }
  image_path: &image_path
    language: kotlin # Pick whatever JSR223 language you like and add it to the classpath
    formula: | # The following is pure Kotlin code. Other variables can be referenced!
      import java.io.File
      fun File.findImage(): String? = walkTopDown().find { image_name in it.name }?.absolutePath
      fun File.findImageRecursively(): String = findImage() ?: File(this, "..").findImageRecursively()
      File(".").findImageRecursively()
    timeout: 5000
  # Linear free variable
  walking_speed: &walk-speed { default: 1.4, min: 1, max: 2, step: 0.1 }
  seed: &seed { default: 0, min: 0, max: 99, step: 1 } # 100 samples
  scenario_seed: &scenario_seed { formula: (seed + 31) * seed } # Variable-dependent
  people_count: &people_count
    type: GeometricVariable # A variable scanning a space with geometric segmentation
    parameters: [300, 50, 500, 9] # default 300, minimum 50, maximum 100, 9 samples
seeds: { simulation: *seed, scenario: *scenario_seed}
export:
    type: CSVExporter
    parameters:
      fileNameRoot: "snippet-variables-export"
    data:
      - time
      - molecule: "default_module:default_program"
        aggregators: [ mean, max, min, variance, median ] # From Apache's UnivariateStatistic
        value-filter: onlyfinite # discards NaN and Infinity
environment: { type: ImageEnvironment, parameters: [*image_path, *zoom] }
network-model: { type: ObstaclesBreakConnection, parameters: [50] }
deployments:
  type: Rectangle
  parameters: [*people_count, 62, 15, 95, 200]
  programs:
    - time-distribution: 1
      program: >
        import protelis:coord:spreading
        let source = [110, 325]
        let vector = self.getCoordinates() - source
        let distance = hypot(vector.get(0), vector.get(1))
        distanceTo(distance < 50)        
    - program: send
    - { type: Event, time-distribution: 1, actions: { type: LevyWalk, parameters: [*walk-speed] } }