From aa5be7cb2bd86d8e18bb27ff927614fdb65d0195 Mon Sep 17 00:00:00 2001
From: Kelvin Olaiya <kelvinoluwada.olaiya@studio.unibo.it>
Date: Fri, 3 Feb 2023 12:21:36 +0100
Subject: [PATCH] docs(website): add explanation on batch simulations #1876

---
 site/content/howtos/execution/batch/_index.md | 42 +++++++++++++++++++
 .../batch-pedestrian-simulation.yml           | 37 ++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 site/content/howtos/execution/batch/_index.md
 create mode 100644 src/test/resources/website-snippets/batch-pedestrian-simulation.yml

diff --git a/site/content/howtos/execution/batch/_index.md b/site/content/howtos/execution/batch/_index.md
new file mode 100644
index 0000000000..220f4c7fe1
--- /dev/null
+++ b/site/content/howtos/execution/batch/_index.md
@@ -0,0 +1,42 @@
++++
+title = "Execute simulations batches"
+weight = 1
+tags = ["batch", "variables", "dry"]
+summary = "Execute multiple instances of the same configuration"
++++
+
+In some cases you may need to test the same simulation configuration
+with different *parameters*. Suppose for example that you want to see what
+happens when you place a bunch of pedestrian in a circle 
+(for sake of semplicity we'll ignore their behavior). You may want to 
+observe the scenario with 50 pedestrians placed in a 5 meters radius circle.
+Then you may like to observe it with 100 pedestrian and perhaps by changing 
+the circle radius also. Instead of re-writing the configuration file over-and-over
+for each parameter combination, Alchemist offers the possibility to write the
+configuration once, and it will then derive a batch of simulations.
+
+## Launching batch simulations
+To exploit this mechanism, you must declare what we above called "parameters"
+as **variables**. In our example, they would be the *number of pedestrian* and
+the *radius of the circle* where to place them. Let's write the configuration file,
+specifing that we want to test the simulation with 10, 30, 50, 70, 90 pedestrian
+and a 5, 10, 15 meters circle radius:
+
+{{< code path="src/test/resources/website-snippets/batch-pedestrian-simulation.yml" >}}
+
+{{% notice info %}}
+To understand how variables work refer to [this page](/howtos/simulation/variables/). 
+You may also want to learn how to deal with [data exportation](/howtos/simulation/export/) 
+and [termination criterias](/howtos/execution/termination/).
+{{% /notice %}}
+
+Now we can launch the batch of simulations by yielding the following command:
+
+```bash
+./gradlew run --args="-y <path-to-simulation> -b -hl -var pedestrianNumber - var circleRadius -e <export-path>"
+```
+
+The `-b` option is to tell Alchemist that we want to execute a batch, while the `-hl` stands
+for headless which means we are not interested in starting-up a gui.
+Under the hood the simulator will compute the cartesian product of the variables sets
+specified with the `-var` option.
diff --git a/src/test/resources/website-snippets/batch-pedestrian-simulation.yml b/src/test/resources/website-snippets/batch-pedestrian-simulation.yml
new file mode 100644
index 0000000000..d03cec3f42
--- /dev/null
+++ b/src/test/resources/website-snippets/batch-pedestrian-simulation.yml
@@ -0,0 +1,37 @@
+incarnation: protelis
+
+variables:
+  pedestrianNumber: &pedestrianNumber
+    type: LinearVariable
+    parameters: [10, 10, 100, 10]
+  circleRadius: &cicleRadius
+    type: LinearVariable
+    parameters: [5, 5, 15, 5]
+
+deployments:
+  - type: Circle
+    parameters: [*pedestrianNumber, 0, 0, *cicleRadius]
+    properties:
+      - type: Human
+        parameters: ["adult", "male"]
+      - type: Perceptive2D
+      - type: CognitivePedestrian
+      - type: Cognitive2D
+      - type: CircularArea
+    programs:
+      - time-distribution:
+          type: DiracComb
+          parameters: [ 1.0 ]
+        type: BlendedSteering
+
+export:
+  - type: CSVExporter
+    parameters:
+      fileNameRoot: "time_export"
+      interval: 1.5
+    data:
+      - time
+
+terminate:
+  - type: StableForSteps
+    parameters: [30, 25]