An exciting update to the PyTUFLOW Library

from pytuflow import TCF

# Define Roughness Multiplier
mannings_n_multiplier = 1.1

# Define TUFLOW Control File
tuflow_tcf = r"path_to_tuflow_tcf"
tcf = TCF(tuflow_tcf)
roughness = tcf.find_input('Read Materials File')[0] # Find Read Materials File Command
roughness.rhs = fr" ..\model\materials.csv | {mannings_n_multiplier}" # Update Right Hand Side of TUFLOW Command
tcf.write(inc='inplace') # Write the TCF

Once the TUFLOW executables location has been registered, TUFLOW can then be run by specifying the TCF and the version of TUFLOW to be used.

from pytuflow import TCF

# Define TUFLOW Control File
tcf = TCF(r'path_to_tuflow_tcf')
tcf_run = tcf.context()
proc = tcf_run.run('2025.2.0') # Define which TUFLOW Version to use
proc.wait() # Wait for the model to finish running

Accessing TUFLOW 2D Results Example

It is also possible to interrogate the resulting TUFLOW outputs.  This has always been possible with 1D results, including 2D Plot Outputs (2D_PO), within PyTUFLOW (see the example here) but is now extended to interrogating 2D results directly.  For example, the following script will read the water level time series from a NetCDF grid output for a specified TUFLOW TCF for the location 293275.172,6177973.546.

from pytuflow import TCF

tcf = TCF(r'path_to_tuflow_tcf')
nc_path = tcf.context().output_folder_2d() / f'{tcf.context().output_name()}.nc' # Define NetCDF output path
ncgrid = NCGrid(nc_path) # Read the NetCDF output
df = ncgrid.time_series((293241.680, 6178015.150), 'water level') # Read Water Level Time Series

This outputs a dataframe which can be further analysed or plotted.  If GDAL Python bindings are installed, a Shapefile or GPKG (or any other GDAL supported vector format) can be used as the location input rather than an X,Y co-ordinate.

Combining the Above PyTUFLOW Examples

The above 3 examples, set up within their own individual functions, can be combined to create a process for running a Monte Carlo analysis similar to the following.

# Simple Example of a Monte Carlo Analysis for Manning's n sensitivity
# Monte Carlo analysis done on the Roughness Multiplier
# TUFLOW is then run. Results obtained for a single point and recorded to a csv file

from pytuflow import TCF, TPC, NCGrid
import os
import random
import numpy as np
import pandas as pd
import plotly.graph_objs as go

# Define TUFLOW Control File
tuflow_tcf = r"path_to_TUFLOW_TCF"
tcf = TCF(tuflow_tcf)

# Number of Monte Carlo simulations
num_simulations = 100
n_multiplier_min = 0.25
n_multiplier_max = 2.5

# Generate random samples of n
n_values = np.random.uniform(n_multiplier_min, n_multiplier_max, num_simulations)

# Check for existing csv file containing outputs and delete if it exists
file_path = "cumulative_dataframe.csv"
if os.path.exists(file_path):
    os.remove(file_path)

# Function to update Manning's n multiplier
def manning_update(mannings_n_multiplier):
    roughness = tcf.find_input('Read Materials File')[0]
    roughness.rhs = rf" ..\model\materials.csv | {mannings_n_multiplier}"
    tcf.write(inc='inplace')

def run_tuflow_simulation(tcf, version):
    tcf_run = tcf.context()
    proc = tcf_run.run(version)
    proc.wait()

def twod_result_analysis(x_point, y_point, result_parameter):
    nc_path = tcf.context().output_folder_2d() / f'{tcf.context().output_name()}.nc'
    ncgrid = NCGrid(nc_path)
    df = ncgrid.time_series((x_point, y_point), result_parameter)
    return df

# Run simulations
for n in n_values:
    manning_update(n)
    run_tuflow_simulation(tcf, '2025.2.0')
    df = twod_result_analysis((293241.680, 6178015.150), 'water level')
      if os.path.exists(file_path):
        cumulative_df = pd.read_csv(file_path)
        new_column = df.iloc[:, 0].reset_index(drop=True)
        cumulative_df[f"Run_{len(cumulative_df.columns)}"] = new_column
        cumulative_df.to_csv(file_path, index=False)
    else:
        cumulative_df = pd.DataFrame({"Run_1": df.iloc[:, 0]})
        cumulative_df.to_csv(file_path, index=True)

# Reset TCF to original setting
final_roughness = tcf.find_input('Read Materials File')[0]
final_roughness.rhs = rf" ..\model\materials.csv "
tcf.write(inc='inplace')

print(f"Monte Carlo analysis completed. Results saved to {file_path}.")