diff --git a/docs/14.gprmax/1.tutorials/1.quick-start.md b/docs/14.gprmax/1.tutorials/1.quick-start.md index 68b29c8..a6c8669 100644 --- a/docs/14.gprmax/1.tutorials/1.quick-start.md +++ b/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 :: diff --git a/docs/14.gprmax/1.tutorials/2.scaling-with-mpi.md b/docs/14.gprmax/1.tutorials/2.scaling-with-mpi.md new file mode 100644 index 0000000..2936eb6 --- /dev/null +++ b/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 +:: diff --git a/docs/14.gprmax/index.md b/docs/14.gprmax/index.md index c2be3dc..d95f80d 100644 --- a/docs/14.gprmax/index.md +++ b/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.