Run Your First XBeach Simulation Example with Inductiva

Run Your First XBeach Simulation Example with Inductiva#

Welcome to Inductiva! Now that you’ve completed the onboarding process, it’s time to dive in and see how easy it is to run your first simulation!

In this tutorial, we’ll run a real-world simulation using the XBeach simulator through the Inductiva API. The use case is a study on beach and dune enhancement scenarios for Galveston Island, Texas.

All required input data for this simulation is available here.

By following this step-by-step guide, you will:

  • Learn how to set up and execute a simulation using the Inductiva API.

  • Use and select high-performance cloud machines.

  • Access and manage simulation outputs via CLI and our Web Console.

🎥 Prefer a Visual Guide?

Follow along with our video walkthrough led by our CEO, where key details, features, and step-by-step instructions are explained in depth. It's a quick and engaging way to get started in no time!

Watch Part 1 and Part 2

Let’s go!

Prerequisites#

Before starting, ensure the following:

  • Python Installed: Make sure Python (>=3.9) is installed on your system. Check our System Prep guide for more information.

  • Inductiva API Setup:

Step 1: Prepare Your Project Directory#

Get Your Simulation Artifacts#

  1. Locate the Input Files

    Download the necessary input files from the Galveston Island dataset.

  2. Navigate to the Correct Folder

    Find the files under: Files >> XBeach_Model_Runs >> Beach_Nourish_Only >> Input.

  3. Download all the files into a folder named Beach_Nourish_Only on your local machine.

Adjust Simulation Parameters#

  1. Open params.txtand modify the parameters

    Ensure compatibility with XBeach v10+ by adding the following line after the header:

    single_dir = 0

    Reduce simulation time by changing the tstop value:

    tstop = 34560

Create the Python Script (run.py)#

Open your preferred IDE (e.g., VS Code, PyCharm) and save a new file as run.py in your project directory.

💡 Pro Tip: Quick Creation of run.py

Instead of creating the file manually, you can use a shortcut:

  • On Mac/Linux, type: touch run.py

This will instantly create the run.py file in your current directory.

Organise Your Files#

Ensure your directory structure looks like this:

xbeach/
|-- Beach_Nourish_Only/
    |-- README.txt
    |-- bed.dep
    |-- bedfricfile.txt
    ...
|-- run.py

  • The beach_nourish_only folder contains all simulation artifacts.

  • Therun.py file which will contain your script to execute the simulation.

Step 2: Write the Python Script#

In the empty run.py file you’ve created, add the following code, save, and close!

# Start by importing the required Inductiva library
import inductiva

# Define the machine group
machine_group = inductiva.resources.MachineGroup(
    machine_type="c3d-highcpu-90",
    spot=True, # Enables cost-saving spot mode
    data_disk_gb=20) 

# Specify the input directory
input_dir = "Beach_Nourish_Only"

# Initialize the Simulator
xbeach = inductiva.simulators.XBeach()

# Run simulation with config files in the input directory
task = xbeach.run(
    input_dir=input_dir,
    sim_config_filename="params.txt",
    n_vcpus=90,
    on=machine_group)

task.wait()

# Clean up resources after the simulation
machine_group.terminate()

# Get a small summary of the run
task.print_summary()

The task.wait() command blocks execution and will only return once the simulation is complete.

However, you don’t need to keep your terminal open the entire time!

  • You can safely close your terminal, and the simulation will continue running in the cloud.

  • To check the simulation status from another terminal, use the Inductiva CLI (Command Line Interface) tools.

Step 3: Run the Simulation#

Execute the Script#

Run the script from your terminal:

python3 run.py

Live simulation progress

The script will:

  • Authenticate your API key.

  • Start the specified cloud machine in spot mode.

  • Zip and upload simulation files to Inductiva servers

  • Execute the simulation on the cloud.

  • Terminate the machine once the simulation completes.

View Task Details#

In the Command Line#

Use the inductiva logs command to view simulation logs:

inductiva logs <TASK_ID>

🔎 Understanding the Task ID

Each simulation you run is assigned a unique Task ID.

This is the long alphanumeric sequence visible in the command line output when starting a simulation.

You’ll need this ID to check logs, monitor progress, or retrieve results using the Inductiva API.

In the Web Console#

In the Inductiva Web Console, the Tasks section provides a complete overview of your simulation runs.

Task Details in Inductiva Console

🔹 Task Overview

  • See a list of all your simulation tasks, including their status.

  • Click on any task to access its Task ID and execution details.

🔹 Detailed Task Insights

  • Simulation duration, cost breakdown, machine group details, and much more.

  • Step-by-step timeline of the task lifecycle, from start to completion, with timestamps.

🔹 Task Logs & Debugging

  • Real-time logs to track simulation progress.

  • View error messages for troubleshooting if anything goes wrong.

ℹ️ Good to Know

  • The Auto-Refresh feature updates the simulation status every 15 seconds, ensuring you always have the latest progress.
  • You can terminate a running simulation directly from the Web Console if needed—no need to switch back to the command line.

Step 4: Access Your Simulation Outputs#

All simulation output files are securely stored in your exclusive folder on Inductiva’s cloud platform. If the simulation is interrupted, all progress up to that point is saved, so you can still access and use partial results.

✅ Private & Secure – Only you have access to your simulation results.

✅ Available Anytime – Download your files whenever you need them.

You can retrieve your results via:

  • Web Console → Navigate to your task and download the output files.

  • Command Line → Use Inductiva’s CLI to fetch results directly.

ℹ️ Good To Know

  • 🔁 Reusing Outputs – You can use the results of one simulation as inputs for another, enabling iterative workflows.

Learn more in our documentation on chaining simulations.

Cost Management#

  • Spot mode significantly reduces costs (~85 cents for this example).

  • Idle machines are automatically shut down after 30 minutes to prevent unexpected charges.

Happy Simulating!#

By completing this tutorial, you’ve successfully run an advanced XBeach simulation using the Inductiva API.

🌊 XBeach Simulation Visualization

XBeach Simulation Results

3D visualization of the XBeach simulation results, showcasing coastal dynamics and seabed changes over time.

Now that your simulation is complete, you can choose any visualization tool to process, analyze, and present your results. For our demo, we used ParaView to generate a 3D visualization of the XBeach simulation results.

What’s Next?#

🔹 Discover More Use Cases

Explore other use cases available on the Inductiva Tutorials Page.

🔹 Explore Other Simulators

Inductiva provides a growing range of simulators built into the API, covering coastal dynamics, fluid simulations, physics-based modeling, and more. Check out our Simulators Page to discover more options.

🔹 Browse Powerful Computational Resources

Inductiva gives you access to high-performance cloud computing with optimized machine configurations for various simulation workloads. Explore available computational resources to find the best setup for your needs.

If you encounter issues, refer to the documentation or contact support at support@inductiva.ai.

Happy simulating!