add-MPI-tutorial

docs/14.gprmax/1.tutorials/1.quick-start.md

@@ -13,7 +13,7 @@ We will cover the `Bowtie antenna model` case from the gprMax examples to help y
 This example shows how to use a built-in antenna model in a simulation. Using a realistic antenna, like a MALA 1.2 GHz model, instead of a simple source improves accuracy, especially for near-field targets and complex antenna-environment interactions.
 
 ## Prerequisites
-Download the required files [here](https://docs.gprmax.com/en/latest/examples_antennas.html) and save them to a folder named `SimulationFiles`. Then, you’ll be ready to send your simulation to the Cloud.
+Download the required files [here](https://docs.gprmax.com/en/latest/examples_antennas.html#bowtie-antenna-model) and save them to a folder named `SimulationFiles`. Then, you’ll be ready to send your simulation to the Cloud.
 
 ## Running an gprMax Simulation
 Here is the code required to run a gprMax simulation using the Inductiva API:
@@ -65,28 +65,28 @@ and print a summary of the simulation as shown below.
 Task status: Success
 
 Timeline:
-	Waiting for Input         at 12/11, 14:39:27      0.816 s
-	In Queue                  at 12/11, 14:39:28      57.399 s
-	Preparing to Compute      at 12/11, 14:40:26      4.071 s
-	In Progress               at 12/11, 14:40:30      164.437 s
-		└> 164.254 s       python -m gprMax antenna_like_MALA_1200_fs.in
-	Finalizing                at 12/11, 14:43:14      0.559 s
-	Success                   at 12/11, 14:43:15      
+	Waiting for Input         at 18/12, 12:29:34      0.919 s
+	In Queue                  at 18/12, 12:29:35      36.426 s
+	Preparing to Compute      at 18/12, 12:30:11      2.012 s
+	In Progress               at 18/12, 12:30:13      98.182 s
+		└> 98.0 s          python -m gprMax antenna_like_MALA_1200_fs.in
+	Finalizing                at 18/12, 12:31:51      0.554 s
+	Success                   at 18/12, 12:31:52      
 
 Data:
-	Size of zipped output:    29.70 KB
-	Size of unzipped output:  185.09 KB
+	Size of zipped output:    25.41 KB
+	Size of unzipped output:  125.44 KB
 	Number of output files:   5
 
-Total estimated cost (US$): 0.0037 US$
-	Estimated computation cost (US$): 0.0037 US$
-	Task orchestration fee (US$): 0 US$
+Total estimated cost (US$): 0.0122 US$
+	Estimated computation cost (US$): 0.0022 US$
+	Task orchestration fee (US$): 0.010 US$
 
 Note: A per-run orchestration fee (0.010 US$) applies to tasks run from 01 Dec 2025, in addition to the computation costs.
 Learn more about costs at: https://inductiva.ai/guides/how-it-works/basics/how-much-does-it-cost
 ```
 
-As you can see in the "In Progress" line, the part of the timeline that represents the actual execution of the simulation, the core computation time of this simulation was approximately 3 minutes.
+As you can see in the "In Progress" line, the part of the timeline that represents the actual execution of the simulation, the core computation time of this simulation was approximately 2 minutes.
 
 ::docsbannersmall
 ::

docs/14.gprmax/1.tutorials/2.scaling-with-mpi.md

@@ -0,0 +1,134 @@
+---
+title: Scale gprMax with MPI
+description: A step-by-step guide to running gprMax simulations with MPI
+seo:
+ title: Scale gprMax simulations with MPI on Inductiva.AI
+ description: Step-by-step guide to running gprMax simulations with MPI on Inductiva.AI
+---
+
+gprMax supports parallelism through **MPI** and **OpenMP**. For a deeper dive into how parallelism works in gprMax, refer to the [official documentation](https://docs.gprmax.com/en/latest/openmp_mpi.html).
+
+In this tutorial, you will learn how to configure and run gprMax simulations sequentially and using MPI. We will use the `B-scan with a bowtie antenna model` from the gprMax example cases as our demonstration.
+
+This example creates a B-scan using an antenna model. The setup includes a metal cylinder with a diameter of 20 mm buried in a dielectric half-space with a relative permittivity of 6. The simulation uses an antenna similar to the GSSI 1.5 GHz antenna.
+
+For a B-scan, the antenna must be repositioned for each A-scan (trace). In this case, the B-scan covers a distance of 270 mm with traces every 5 mm, resulting in **54 separate model runs**.
+
+## Prerequisites
+Download the required files [here](https://docs.gprmax.com/en/latest/examples_antennas.html#b-scan-with-a-bowtie-antenna-model) and save them to a folder named `b-scan-case`.
+
+## Sequential Processing
+First, let's run the 54 models **sequentially**. This means the simulation will process the A-scans one after another: model 1, then model 2, and so on.
+
+You can do this using the following command:
+
+```
+python -m gprMax cylinder_Bscan_GSSI_1500.in -n 54
+```
+
+Here, `-n` specifies the number of runs.
+
+Each run produces a separate output file. To merge them into a single result file, run:
+
+```
+python -m tools.outputfiles_merge cylinder_Bscan_GSSI_1500.in
+```
+
+The required Python script to run this case sequentially on Inductiva is shown below:
+
+```python
+import inductiva
+
+# Instantiate machine group
+cloud_machine = inductiva.resources.MachineGroup(
+    machine_type="c2d-highcpu-16",
+    provider="GCP",
+    spot=True)
+
+input_dir = "/Path/to/b-scan-case"
+
+# Initialize the Simulator
+gprmax = inductiva.simulators.GprMax(version="3.1.7")
+
+commands_sequential = [
+    "python -m gprMax cylinder_Bscan_GSSI_1500.in -n 54",
+    "python -m tools.outputfiles_merge cylinder_Bscan_GSSI_1500.in"
+]
+
+# Start sequential simulation
+task_sequential = gprmax.run(\
+    input_dir=input_dir,
+    commands=commands_sequential,
+    on=cloud_machine,
+    n_vcpus=16)
+
+# Wait for the simulations to finish
+task_sequential.wait()
+cloud_machine.terminate()
+```
+
+Running these 54 simulations sequentially took approximately **1 hour and 55 minutes**.
+
+Next, we will explore MPI-based parallel execution, which will significantly speed up this case.
+
+## MPI Processing
+gprMax supports MPI, allowing each of the 54 runs to be executed **in parallel**. This requires a machine with enough vCPUs to support all the runs. Hence, we'll be running the case on a `c2d-highcpu-112`, which has 112 vCPUs, providing ample resources for all 54 simulations to run concurrently.
+
+> ⚠️ **Note on vCPUs and Hyperthreading**: In most cloud environments (e.g., Google Cloud), a vCPU represents a single thread rather than a full physical core. By default, Google Cloud VMs provide 2 vCPUs per physical core, so a `c2d-standard-112` machine with 112 vCPUs typically has 56 physical cores with hyperthreading enabled.
+
+Wrap the Python command with `mpirun` as follows:
+
+```
+mpirun -n 55 python -m gprMax cylinder_Bscan_GSSI_1500.in -n 54 --mpi-no-spawn
+```
+
+- `-n 55` specifies the number of processes, which should be one more than the number of runs (`-n 54 + 1`) to account for the master process
+- `--mpi-no-spawn` is recommended according to the [gprMax documentation](https://docs.gprmax.com/en/latest/openmp_mpi.html#mpi)
+
+Here’s the Python script to run the case with MPI:
+
+```python
+import inductiva
+
+# Instantiate machine group
+cloud_machine = inductiva.resources.MachineGroup(
+    machine_type="c2d-highcpu-112",
+    provider="GCP",
+    spot=True)
+
+input_dir = "/Path/to/b-scan-case"
+
+# Initialize the Simulator
+gprmax = inductiva.simulators.GprMax(version="3.1.7")
+
+commands_mpi = [
+    "mpirun -n 55 python -m gprMax cylinder_Bscan_GSSI_1500.in -n 54 --mpi-no-spawn",
+    "python -m tools.outputfiles_merge cylinder_Bscan_GSSI_1500.in"
+]
+
+# Start MPI simulation
+task_mpi = gprmax.run(\
+    input_dir=input_dir,
+    commands=commands_mpi,
+    on=cloud_machine,
+    n_vcpus=112)
+
+# Wait for the simulations to finish
+task_mpi.wait()
+cloud_machine.terminate()
+```
+
+This MPI-based simulation significantly reduces the runtime compared to sequential execution, taking approximately **23 minutes**.
+
+## Results
+The following table summarizes the performance and cost of sequential versus MPI-based execution for the `B-scan with a bowtie antenna model` case on Inductiva:
+
+| Processing Type | Machine Type      | Total Time   | Estimated Cost (USD) |
+|-----------------|-------------------|--------------|----------------------|
+| Sequential      | c2d-highcpu-16    | 1h, 55 min   | 0.15                 |
+| MPI             | c2d-highcpu-112   | 23 min       | 0.21                 |
+
+Running the simulations on **Inductiva** using MPI-based parallel execution drastically reduces the runtime compared to sequential processing, from nearly **2 hours down to under 25 minutes**. Although the estimated cost for the larger machine is slightly higher, the time savings are significant, making MPI a highly efficient option for large-scale gprMax simulations.
+
+::docsbannersmall
+::

docs/14.gprmax/index.md

@@ -20,6 +20,9 @@ Step-by-step guides to help you learn how to run gprMax through the Inductiva AP
     - [Test Your Inductiva Setup](/guides/gprmax/tutorials/setup-test)
     - [Run Your First Simulation](/guides/gprmax/tutorials/quick-start)
 
+* **Advanced Tutorials**
+    - [Scale gprMax with MPI](/guides/gprmax/tutorials/scaling-with-mpi)
+
 ### Benchmarks
 A trusted guide to selecting the right simulation hardware for your needs. These benchmarks, conducted using the Inductiva platform, provide insight into how gprMax performs on different hardware configurations.