The Utils module#

What it does#

This module provides a collection of functions and utilities for processing, interpolating, and exporting simulation data in the Watlab framework.

It handles tasks such as:

  • Extracting values from raster (.tif) files;

  • Interpolating spatial data for meshes;

  • Managing time-stepped outputs and gauge post-processing;

  • Computing derived hydraulic quantities (velocity, Froude number, shear stress, etc.);

  • Creating and exporting results in NetCDF format for visualization or post-processing.

All functions are designed to automate repetitive data preparation and post-processing steps within Watlab workflows.

Documentation#

watlab.utils.create_netcdf_mesh(output_file, nodes_file, cells_file, EPSG_CODE='31370')#

Creates a NetCDF file defining a 2D mesh topology from node and cell files.

This function reads a set of node coordinates and cell connectivity from text files, defines the mesh topology, and writes it to a NetCDF file following CF conventions. The mesh includes node coordinates, elevation (zb), connectivity of faces, and optional EPSG-based spatial reference.

Parameters:

  • output_file (str) – Path to the output NetCDF file to be created.

  • nodes_file (str) – Path to the file containing node coordinates. The file should have at least three columns: x, y, zb, with a header row (number of nodes).

  • cells_file (str) – Path to the file containing cell connectivity. The file should have a header row (number of cells) and at least three columns (node indices).

  • EPSG_CODE (str, optional) – EPSG code for the coordinate reference system. Default is “31370”.

Returns:

NetCDF Dataset object representing the created mesh.

Return type:

netCDF4.Dataset

Example

from watlab.utils import create_netcdf_mesh

ncfile = create_netcdf_mesh(
    output_file="mesh.nc",
    nodes_file="nodes.txt",
    cells_file="cells.txt",
    EPSG_CODE="25831"
)

print(ncfile)  # NetCDF Dataset object
ncfile.close()
watlab.utils.extract_values_from_tif(tif_file)#

Extracts spatial coordinates and corresponding raster values from a GeoTIFF file.

This function opens a GeoTIFF using Rasterio, reads the image band, and computes the (x, y) coordinates of each pixel in the raster grid.

Parameters:

tif_file (str) – Path to the input GeoTIFF file.

Returns:

  • tif_points_coordinates (numpy.ndarray): Array of shape (N, 2) containing the (x, y) coordinates of each pixel.

  • tif_points_data (numpy.ndarray): Array of shape (N,) containing the raster values for each pixel.

Return type:

tuple(numpy.ndarray, numpy.ndarray)

Example

coords, values = extract_values_from_tif("dem.tif")
print(coords.shape, values.shape)
watlab.utils.generate_netcdf_file_from_picture(nodes_file, cells_file, manning_values, pic_path_template, output_file, max_time, time_step, EPSG_CODE='31370', initial_time=0)#

Generate a NetCDF file from mesh and simulation field data over time.

This function reads a mesh (nodes and cells) and a series of simulation output “picture” files, computes derived fields such as velocity and shear stress, and writes all variables into a NetCDF file structured by time and faces.

Parameters:

  • nodes_file (str) – Path to the file containing node coordinates (x, y, zb).

  • cells_file (str) – Path to the file containing cell connectivity (node indices).

  • manning_values (list or numpy.ndarray) – Array or list of Manning’s coefficient ‘n’ values per node.

  • pic_path_template (str) – Template path for the picture file paths, with placeholders for time formatting.

  • output_file (str) – Path to the output NetCDF file to create.

  • max_time (int) – Maximum simulation time in seconds.

  • time_step (int) – Time step interval between simulation outputs, in seconds.

  • EPSG_CODE (str, optional) – EPSG code for the coordinate reference system (default: “31370”).

  • initial_time (int, optional) – Initial time for the simulation in seconds (default: 0).

Returns:

None. The function writes all variables into the NetCDF file specified by output_file.

Return type:

None

Example

nodes_file = "nodes.txt"
cells_file = "cells.txt"
manning_values = np.loadtxt("manning.txt")
pic_template = "results/pic_{:05d}_{:02d}.txt"
output_file = "simulation.nc"
max_time = 3600
time_step = 60

generate_netcdf_file_from_picture(
    nodes_file,
    cells_file,
    manning_values,
    pic_template,
    output_file,
    max_time,
    time_step
)
watlab.utils.generate_sourceterm_id()#

Generates a sequential source term identifier each time it is called.

This function is a generator that yields an incrementing integer value starting from zero. Each iteration provides a unique ID, which can be used to label or index source terms in a model or simulation.

Returns:

Generator that yields an incremental integer ID.

Return type:

generator of int

Example

id_generator = generate_sourceterm_id()

next(id_generator)  # 0
next(id_generator)  # 1
next(id_generator)  # 2
watlab.utils.interpolate_points(known_points_coordinates, known_points_data, desired_points, interpolation_method='nearest')#

Interpolates values at desired spatial points based on known data points.

This function performs spatial interpolation (nearest, linear, or cubic) using the scipy.interpolate.griddata function. It interpolates values at target (x, y) coordinates from a set of known points and associated data.

Parameters:

  • known_points_coordinates (numpy.ndarray) – Coordinates of known data points, of shape (N, 2).

  • known_points_data (numpy.ndarray) – Values corresponding to the known points, of shape (N,).

  • desired_points (numpy.ndarray) – Coordinates where interpolated values should be estimated, of shape (M, 2).

  • interpolation_method (str, optional) – Interpolation method; one of 'nearest', 'linear' or 'cubic'. Defaults to 'nearest'.

Returns:

Interpolated values at the desired points.

Return type:

numpy.ndarray

Example

import numpy as np
from scipy.interpolate import griddata

# Known data points
known_coords = np.array([[0, 0], [1, 0], [0, 1], [1, 1]])
known_values = np.array([1.0, 2.0, 3.0, 4.0])

# Points where we want interpolated values
target_points = np.array([[0.5, 0.5], [0.25, 0.75]])

interpolated = interpolate_points(known_coords, known_values, target_points, interpolation_method='linear')
print(interpolated)
watlab.utils.parse_date(date_string)#

Parses a date string into a pandas Timestamp object.

This function attempts to convert a given date string into a datetime object using pandas.to_datetime with flexible parsing (format='mixed'). If the input string cannot be parsed, a ValueError is raised.

Parameters:

date_string (str) – The date string to parse. It should follow the format 'YYYY-MM-DD HH:MM'.

Returns:

Parsed date as a pandas Timestamp.

Return type:

pandas.Timestamp

Raises:

ValueError – If the date string is not in a recognized or supported format.

Example

from watlab.utils import parse_date

# Valid date string
dt = parse_date("2024-07-15 12:30")
print(dt)  # 2024-07-15 12:30:00

# Invalid format example
parse_date("15/07/2024")  
# Raises: ValueError: The date string is not in the correct format.
watlab.utils.post_processed_gauge(pic_path_template, time_step, variable_names, node_index, output_file_path)#

Extracts and processes time series (gauge) data from simulation output “picture” files.

This function reads a sequence of text or CSV files representing simulation snapshots over time, extracts one or more variables for a specific mesh node, and writes the resulting time series to a CSV file.

Parameters:

  • pic_path_template (str) – Template string for file paths. It should contain placeholders for the time values (e.g., "output_{:05d}_{:02d}.txt").

  • time_step (int) – Time interval (in seconds) between consecutive output files.

  • variable_names (list of str) – List of variable names to extract from each file (e.g., ["h", "V", "zb"]).

  • node_index (int) – Index (zero-based) of the mesh node for which to extract data.

  • output_file_path (str) – Destination path where the extracted gauge data will be saved as a CSV file.

Returns:

None. The function writes the processed gauge data to a CSV file.

Return type:

None

Example

from watlab.utils import post_processed_gauge

pic_path_template = "results/pic_{:05d}_{:02d}.txt"
time_step = 60  # seconds
variable_names = ["h", "V"]
node_index = 42
output_file_path = "output/gauge_node42.csv"

post_processed_gauge(pic_path_template, time_step, variable_names, node_index, output_file_path)

# -> Creates a CSV file with columns: time, h, V
watlab.utils.post_processed_maximal_values(pic_path_template, time_step, output_file_name, variable_names=None, manning_values=None)#

Process a series of simulation output “picture” files and extract the maximal values of specified variables over time.

This function iterates over multiple picture/output files generated by a simulation, extracts specified variables for all nodes, and computes the maximum value of each variable at each node over the entire time series. The results are saved to a CSV file.

Parameters:

  • pic_path_template (str) – Template path to the picture files, with placeholders for time formatting (e.g., “pic_{:05d}_{:02d}.txt”).

  • time_step (int) – Time step increment (in seconds) between consecutive files.

  • output_file_name (str) – Path to save the CSV file containing maximal values.

  • variable_names (list of str, optional) – List of variable names to extract and process. If None, all available variables are used.

  • manning_values (list or numpy.ndarray, optional) – Optional array of Manning’s coefficient ‘n’ values, required if shear stress is computed.

Returns:

Dictionary containing the maximal values for each variable at each node.

Return type:

dict

Raises:

FileNotFoundError – If a file matching pic_path_template does not exist.

Example

pic_template = "results/pic_{:05d}_{:02d}.txt"
time_step = 60
output_file = "max_values.csv"
variables = ["h", "V", "Shear stress"]
manning = np.array([0.03, 0.03, 0.03])

max_vals = post_processed_maximal_values(pic_template, time_step, output_file, variable_names=variables, manning_values=manning)

print(max_vals["h"])  # Maximal water depth over all timesteps
watlab.utils.select_postprocessing_variable(data, variable_name, manning_values=None)#

Selects and computes a variable from simulation data for post-processing or plotting.

Depending on the provided variable_name, this function extracts the corresponding column from the data or computes derived variables such as velocity, Froude number, or shear stress. Supports both pandas DataFrames and numpy structured arrays.

Parameters:

  • data (pandas.DataFrame or numpy.ndarray) – The simulation data from which to extract or compute the variable. Must contain columns like “h”, “zb”, “qx”, “qy”, etc.

  • variable_name (str) –

    Name of the variable to select or compute. Supported values:

    • ”h” or “height”: water depth

    • ”zb”: bed elevation

    • ”zw”: water surface elevation (zb + h)

    • ”V” or “velocity”: flow velocity magnitude

    • ”qx”, “qy”: flow components

    • ”Fr” or “Froude”: Froude number

    • ”Shear stress” or “tau”: bed shear stress (requires manning_values)

    • any column present in data

  • manning_values (numpy.ndarray or list, optional) – Optional array of Manning’s coefficient ‘n’ values, required for “Shear stress” calculation.

Returns:

Array of values corresponding to the selected variable.

Return type:

numpy.ndarray

Raises:

ValueError – If variable_name is unknown or missing in data.

Example

import numpy as np
import pandas as pd
from watlab.utils import select_postprocessing_variable

data = pd.DataFrame({
    "h": [1.0, 2.0],
    "zb": [0.0, 0.0],
    "qx": [0.5, 1.0],
    "qy": [0.0, 0.0]
})
manning = np.array([0.03, 0.03])

# Select water depth
h_values = select_postprocessing_variable(data, "h")

# Compute velocity
velocity = select_postprocessing_variable(data, "V")

# Compute shear stress
tau = select_postprocessing_variable(data, "Shear stress", manning_values=manning)
On this page
Show Source