Run your First Simulation

Run your First Simulation#

In this first example, you will use the open-source hydrodynamics REEF3D simulator to simulate a 2D dam break scenario. This involves a block of fluid released to flow under the influence of gravity, as shown in the video below. As the simulation progresses, you’ll find that running simulations through the Inductiva API is not much different from running them in your local machine.

REEF3D 2D dambreak simulation

To run a simulation via the API, you first need to prepare a Python script with the following steps:

  1. Prepare and gather all the necessary configuration files for the simulation into one input folder. To simplify our example, we will provide you with an input folder containing all the necessary configuration files for the dam break simulation, slightly modified from the original REEF3D tutorials found on their GitHub repository to reduce the simulation run time;

  2. Instantiate a simulator object that identifies the simulator you want to use, here exemplified by instantiating a REEF3D simulator object;

  3. Launch the simulation using the run method of the simulator object, passing a reference to the input folder. This folder gets uploaded to your remote storage and accessed by the worker machine executing the simulation;

  4. After the simulation completes, download the results back to your local machine.

Following the steps outlined above, here is the Python script you’ll use to run the dam break simulation via the Inductiva API. Give it a go:

import inductiva

# 1 - Download the configuration files for a REEF3D simulation. This folder
# contains the control.txt and ctrl.txt files that configure the parameters of
# the mesh and the simulation, respectively.
input_dir = inductiva.utils.download_from_url(
    "", unzip=True)

# 2 - Initialize the REEF3D simulator object
simulator = inductiva.simulators.REEF3D()

# 3 - Launch the simulation with the downloaded input folder. This will return
# a task object that can be used to monitor the task and download the outputs.
task =

# 4 - Wait for the simulation to finish and download the outputs to a default
# folder in your local machine named `example_simulation`.

As the simulation progresses, you’ll receive updates on its status. When it finishes, you should find the following folder on your local machine:

|- DIVEMesh_Decomp
|- DIVEMesh_Log
|- DIVEMesh_Paraview 
|- REEF3D_Log
|- control.txt
|- ctrl.txt
|- grid-000001.dat
|- grid-000002.dat
|- stderr.txt
|- stdout.txt

Once the simulation data is on your local machine, you’re ready to proceed with post-processing just as you normally would. For example, you can visualize the contents of the files in REEF3D_CFD_VTU using open-source visualization tools such as Paraview.