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. diff --git a/docs/31.swmm/1.tutorials/0.setup-test.md b/docs/31.swmm/1.tutorials/0.setup-test.md index c334083..1e4e67c 100644 --- a/docs/31.swmm/1.tutorials/0.setup-test.md +++ b/docs/31.swmm/1.tutorials/0.setup-test.md @@ -71,21 +71,21 @@ After the simulation completes, a task summary will be displayed in your termina Task status: Success Timeline: - Waiting for Input at 02/12, 10:32:31 0.845 s - In Queue at 02/12, 10:32:32 37.366 s - Preparing to Compute at 02/12, 10:33:09 1.375 s - In Progress at 02/12, 10:33:10 65.312 s - └> 65.135 s runswmm model.inp model.rpt - Finalizing at 02/12, 10:34:16 3.772 s - Success at 02/12, 10:34:19 + Waiting for Input at 18/12, 16:39:26 1.051 s + In Queue at 18/12, 16:39:27 34.749 s + Preparing to Compute at 18/12, 16:40:01 1.953 s + In Progress at 18/12, 16:40:03 67.368 s + └> 67.155 s runswmm model.inp model.rpt + Finalizing at 18/12, 16:41:11 3.819 s + Success at 18/12, 16:41:15 Data: Size of zipped output: 39.28 MB Size of unzipped output: 808.37 MB Number of output files: 5 -Total estimated cost (US$): 0.01045 US$ - Estimated computation cost (US$): 0.00045 US$ +Total estimated cost (US$): 0.01028 US$ + Estimated computation cost (US$): 0.00028 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. @@ -94,10 +94,6 @@ Learn more about costs at: https://inductiva.ai/guides/how-it-works/basics/how-m If the task status shows **Success**, congratulations! You've successfully run an SWMM simulation. -This simple example tested your installation on a small machine with just 4 virtual CPUs. Inductiva offers far more powerful options to supercharge your simulations. - -Start running simulations seamlessly! - ::docsbannersmall :: diff --git a/docs/31.swmm/1.tutorials/1.quick-start.md b/docs/31.swmm/1.tutorials/1.quick-start.md index 762b8e6..5a9db1d 100644 --- a/docs/31.swmm/1.tutorials/1.quick-start.md +++ b/docs/31.swmm/1.tutorials/1.quick-start.md @@ -26,7 +26,7 @@ import inductiva # Allocate cloud machine on Google Cloud Platform cloud_machine = inductiva.resources.MachineGroup( \ provider="GCP", - machine_type="c2d-highcpu-4", + machine_type="c2d-highcpu-2", spot=True) # Initialize the Simulator @@ -52,9 +52,7 @@ task.download_outputs() task.print_summary() ``` -In this basic example, we're using a cloud machine (`c2d-highcpu-4`) equipped with 4 virtual CPUs. -For larger or more compute-intensive simulations, consider adjusting the `machine_type` parameter to select -a machine with more virtual CPUs and increased memory capacity. You can explore the full range of available machines [here](https://console.inductiva.ai/machine-groups/instance-types). +In this basic example, we're using a cloud machine (`c2d-highcpu-2`) equipped with 2 virtual CPUs.Since SWMM runs in a single thread, increasing the number of vCPUs won’t speed up a single simulation. You may consider switching machine families via the `machine_type` parameter, as newer CPU generations can improve single-core performance. You can explore the full range of available machines [here](https://console.inductiva.ai/machine-groups/instance-types). > **Note**: Setting `spot=True` enables the use of [spot machines](/guides/machines/spot-machines), which are available at substantial discounts. > However, your simulation may be interrupted if the cloud provider reclaims the machine. @@ -68,21 +66,21 @@ When the simulation is complete, we terminate the machine, download the results Task status: Success Timeline: - Waiting for Input at 02/12, 11:29:08 1.21 s - In Queue at 02/12, 11:29:09 35.567 s - Preparing to Compute at 02/12, 11:29:45 1.342 s - In Progress at 02/12, 11:29:46 2.173 s - └> 1.977 s runswmm Example8.inp model.rpt - Finalizing at 02/12, 11:29:48 0.63 s - Success at 02/12, 11:29:49 + Waiting for Input at 18/12, 16:37:03 1.115 s + In Queue at 18/12, 16:37:04 36.949 s + Preparing to Compute at 18/12, 16:37:41 1.514 s + In Progress at 18/12, 16:37:42 1.444 s + └> 1.183 s runswmm Example8.inp model.rpt + Finalizing at 18/12, 16:37:44 0.934 s + Success at 18/12, 16:37:44 Data: - Size of zipped output: 253.95 KB + Size of zipped output: 253.98 KB Size of unzipped output: 3.37 MB Number of output files: 3 -Total estimated cost (US$): 0.010038 US$ - Estimated computation cost (US$): 0.000038 US$ +Total estimated cost (US$): 0.010019 US$ + Estimated computation cost (US$): 0.000019 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. diff --git a/docs/32.wavewatch3/1.tutorials/0.setup-test.md b/docs/32.wavewatch3/1.tutorials/0.setup-test.md index f946ba6..c33d0e4 100644 --- a/docs/32.wavewatch3/1.tutorials/0.setup-test.md +++ b/docs/32.wavewatch3/1.tutorials/0.setup-test.md @@ -106,6 +106,5 @@ This simple example tested your installation on a small machine with just 4 virt ::docsbannersmall :: - ## Need Help? If you encounter any issues or need further assistance, don't hesitate to [**Contact Us**](mailto:support@inductiva.ai). We're here to help!