Scripting

This scripting reference is for researchers 🧪 and developers 💻 learning how to write custom JavaScript experiments for AmoebotSim.

Instead of simply using the user interface controls to run a single algorithm instance, AmoebotSim also exposes a JavaScript interface that enables more programmatic and granular control of the simulator. The scripting interface can be used to run large numbers of algorithm instances automatically and consecutively, adjust algorithm parameters more fluidly, capture metrics data for repeated runs, and lower runtime by streamlining graphics.

Writing Scripts

Writing custom JavaScript experiments for AmoebotSim uses standard JavaScript syntax, while additionally making use of custom commands specific to AmoebotSim (listed below in the JavaScript API). Here is an example of a simple JavaScript experiment:

for (var run = 0; run < 25; run++) {
  shapeformation(100, 0.2, "h");
  runUntilTermination();
  writeToFile('shapeformation_data.txt', getMetric("# Rounds") + '\n');
}

In the above script, AmoebotSim runs 25 instances of the Basic Shape Formation algorithm (with given parameters), appending the value of the “# Rounds” metric at the end of each run to a text file. This data could then be used, for example, to compute average runtime.

The simple scripting above can be expanded to carry out much more complex experiments.

Running Scripts

To run your JavaScript experiment, press the Run Script button in the sidebar and select the desired JavaScript file. AmoebotSim will then begin executing your script, temporarily disabling graphics updates for faster execution. When the script execution completes, graphics are reenabled and the following message will be logged to the simulator: Ran script: path_to_file/your_script.js.

Warning

All JavaScript experiment files must be saved within the directory containing AmoebotSim’s executable. Otherwise, AmoebotSim’s JavaScript engine will not be able to locate or execute the script.

Note

AmoebotSim may temporarily hang (i.e., “Not Responding” on Windows or the faded window and rainbow pinwheel on macOS) while the script is executing. This is expected behavior, and is simply acknowledging that graphics are not currently being updating.

The following animation illustrates the process of loading and running a script in AmoebotSim:

../_images/scriptinganimation.gif

Scripting API

The following is a list of all recognized commands.

Note

All file path parameters for the JavaScript API are relative to the directory containing AmoebotSim’s executable.

Algorithm Instantiation Commands

All algorithms are instantiated based on their signatures and parameters defined when registering the algorithm.

discodemo(numParticles, counterMax)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • counterMax (int()) – The maximum counter value for the color changes.

Instantiates a system running the DiscoDemo algorithm with the given parameters.

metricsdemo(numParticles, counterMax)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • counterMax (int()) – The maximum counter value for the color changes.

Instantiates a system running the MetricsDemo algorithm with the given parameters.

ballroomdemo(numParticles)
Arguments

  • numParticles (int()) – The number of particles in the system.

Instantiates a system running the BallroomDemo algorithm with the given parameter.

tokendemo(numParticles, lifetime)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • lifetime (int()) – The total number of times a token should be passed.

Instantiates a system running the TokenDemo algorithm with the given parameters.

dynamicdemo(numParticles, growProb, dieProb)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • growProb (float()) – The probability of adding a new particle on activation.

  • dieProb (float()) – The probability of removing this particle on activation.

Instantiates a system running the DynamicDemo algorithm with the given parameters.

aggregation(numParticles, lambda)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • mode (string()) – The noise mode: "d" for deadlock perturbation, "e" for error probability.

  • noiseVal (float()) – The noise magnitude, which is either an integer number of steps to wait before rotating in place (deadlock perturbation) or a float probability of receiving the wrong signal from the sight sensor (error probability).

Instantiates a system running the Swarm Aggregation algorithm (Daymude et al., SSS 2021) with the given parameters.

compression(numParticles, lambda)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • lambda (int()) – The bias parameter.

Instantiates a system running the Compression algorithm (Cannon et al., PODC 2016) with the given parameters.

edfhexagonformation(numParticles, numEnergySources, holeProb, capacity, transferRate, demand)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • numEnergySources (int()) – The number of particles with access to external energy sources.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

  • capacity (float()) – The capacity of each particle’s battery.

  • transferRate (float()) – The maximum amount of energy a particle can transfer to a neighbor.

  • demand (float()) – The energy cost for each particle’s actions.

Instantiates a system running the energy-constrained version of the Hexagon Formation algorithm produced by the Energy Distribution Framework (Weber et al., Under Review, 2023) with the given parameters.

edfleaderelectionbyerosion(numParticles, numEnergySources, capacity, transferRate, demand)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • numEnergySources (int()) – The number of particles with access to external energy sources.

  • capacity (float()) – The capacity of each particle’s battery.

  • transferRate (float()) – The maximum amount of energy a particle can transfer to a neighbor.

  • demand (float()) – The energy cost for each particle’s actions.

Instantiates a system running the energy-constrained version of the Leader Election by Erosion algorithm produced by the Energy Distribution Framework (Weber et al., Under Review, 2023) with the given parameters.

energyshape(numParticles, numEnergyRoots, holeProb, capacity, demand, transferRate)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • numEnergyRoots (int()) – The number of particles with access to external energy sources.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

  • capacity (float()) – The capacity of each particle’s battery.

  • demand (float()) – The energy cost for each particle’s actions.

  • transferRate (float()) – The maximum amount of energy a particle can transfer to a neighbor.

Instantiates a system running the Energy Sharing algorithm (Daymude et al., ICDCN 2021) composed with Hexagon Formation with the given parameters.

energysharing(numParticles, numEnergyRoots, usage, capacity, demand, transferRate)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • numEnergyRoots (int()) – The number of particles with access to external energy sources.

  • usage (int()) – Whether the system uses energy for “invisible” actions (usage = 0) or for reproduction (usage = 1).

  • capacity (float()) – The capacity of each particle’s battery.

  • demand (float()) – The energy cost for each particle’s actions.

  • transferRate (float()) – The maximum amount of energy a particle can transfer to a neighbor.

Instantiates a system running the Energy Sharing algorithm (Daymude et al., ICDCN 2021) with the given parameters.

hexagonformation(numParticles, holeProb)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

Instantiates a system running the canonical version of the Hexagon Formation algorithm (Daymude et al., Distributed Computing 2023) with the given parameters.

infobjcoating(numParticles, holeProb)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

Instantiates a system running the Infinite Object Coating algorithm (Derakhshandeh et al., arXiv 2014) with the given parameters.

leaderelection(numParticles, holeProb)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

Instantiates a system running the Leader Election (Daymude et al., arXiv 2015) algorithm with the given parameters.

leaderelectionbyerosion(numParticles)
Arguments

  • numParticles (int()) – The number of particles in the system.

Instantiates a system running the Leader Election by Erosion (Briones et al., ICDCN 2023) algorithm with the given parameters.

shapeformation(numParticles, holeProb, mode)
Arguments

  • numParticles (int()) – The number of particles in the system.

  • holeProb (float()) – The system’s hole probability capturing how spread out the initial configuration is.

  • mode (string()) – The desired shape to form: "h" for hexagon, "s" for square, "t1" for vertex triangle, "t2" for centered triangle, and "l" for line.

Instantiates a system running the Basic Shape Formation algorithm (Derakhshandeh et al., NANOCOM 2015) with the given parameters.

Scripting Commands

log(msg, error)
Arguments

  • msg (string()) – A message to log to AmoebotSim’s interface.

  • error (boolean()) – true if and only if this is an error message; false by default.

Emits the message msg to the status bar. Can be denoted as an error message (red background) by setting error to true.

runScript(scriptFilePath)
Arguments

  • scriptFilePath (string()) – The file path (relative to AmoebotSim’s executable directory) of a JavaScript script.

Loads a JavaScript script from scriptFilePath and executes it.

writeToFile(filePath, text)
Arguments

  • filePath (string()) – The path of a file to write text to.

  • text (string()) – The string to append to the specified file.

Appends the specified text to a file at the given location filePath.

Simulation Flow Commands

step()

Executes a single particle activation. Equivalent to pressing the Step button or using Ctrl+D/Cmd+D.

setStepDuration(ms)
Arguments

  • ms (int()) – The number of milliseconds (positive integer) between individual particle activations.

Sets the simulator’s delay between particle activations to the given value ms.

runUntilTermination()

Runs the current algorithm instance until its hasTerminated function returns true.

Metrics Commands

getNumParticles()
Returns

The number of particles in the system in the given instance.

getNumObjects()
Returns

The number of objects in the system in the given instance.

getMetric(name, history)
Arguments

  • name (string()) – The name of a metric.

  • history (boolean()) – true to return the metric’s history or false to return the metric’s current value; false by default.

Returns

An array of the metric’s value(s).

For a metric with specified name, returns either its current value (history = false) or historical data (history = true).

exportMetrics()

Writes all metrics data to JSON as metrics/metrics_<secs_since_epoch>.json. Equivalent to pressing the Metrics button or using Ctrl+E/Cmd+E.

Visualization Commands

setWindowSize(width, height)
Arguments

  • width (int()) – The width in pixels; 800 by default.

  • height (int()) – The height in pixels; 600 by default.

Sets the size of the application window to the specified width and height.

focusOn(x, y)
Arguments

  • x (int()) – An x-coordinate on the triangular lattice.

  • y (int()) – A y-coordinate on the triangular lattice.

Sets the window’s center of focus to the given (x, y) node. Zoom level is unaffected.

setZoom(zoom)
Arguments

  • zoom (float()) – A value defining the level/amount of zoom.

Sets the zoom level of the window to the given value zoom.

saveScreenshot(filePath)
Arguments

  • filePath (string()) – The file path/name to save the captured image; amoebotsim_<secs_since_epoch>.png by default.

Saves the current window as a .png at file location filePath.

filmSimulation(filePath, stepLimit)
Arguments

  • filePath (string()) – The file path location to save captured images.

  • stepLimit (int()) – The number of simulation steps to run and capture.

Saves a series of screenshots to the specified location filePath, up to the specified number of steps stepLimit.