Processing Thin-Layer Geophysical Flow Simulations with tilupy

December 22, 2023

Thin-layer geophysical flow simulations are an important tool in understanding and predicting natural disasters such as landslides, avalanches, and debris flows. The tilupy package provides a convenient and efficient way to process the inputs and outputs of such simulations on general topographies. In this article, we will explore how to install tilupy, get started with processing simulations, and discuss several examples of how to utilize the package in Python scripts and the command line.

Installation

Before we can start using tilupy, we need to install it. The package is currently not available on conda-forge, so we need to install it from either PyPi or the GitHub repository. To install tilupy from PyPi, run the following command:

python -m pip install tilupy

If you prefer to install the development version from the GitHub repository, you can download the repository here or clone it using the following command:

git clone https://github.com/marcperuz/tilupy.git

Once you have downloaded the repository, navigate to its folder and run the following command to install tilupy:

python -m pip install .

Quick Start

To get started with tilupy, let’s walk through a simple example of preparing simulations for the SHALTOP model and processing the results. In this example, we will import necessary modules, download example data, create simulation folders, convert rasters to SHALTOP input files, initialize simulation parameters, and prepare simulations for different rheological parameters.

import os
import tilupy.raster
import tilupy.download_data
import tilupy.models.shaltop.initsimus as shinit

# Define folder paths
FOLDER_BASE = '/path/to/myfolder'
folder_data = os.path.join(FOLDER_BASE, 'rasters')
folder_simus = os.path.join(FOLDER_BASE, 'shaltop')

# Import example data
raster_topo = tilupy.download_data.import_frankslide_dem(folder_out=folder_data)
raster_mass = tilupy.download_data.import_frankslide_pile(folder_out=folder_data)

# Convert rasters to SHALTOP input files
shinit.raster_to_shaltop_txtfile(raster_topo, os.path.join(folder_simus, 'topography.d'))
axes_props = shinit.raster_to_shaltop_txtfile(raster_mass, os.path.join(folder_simus, 'init_mass.d'))

# Initialize simulation parameters
params = dict(nx=axes_props['nx'], ny=axes_props['ny'], per=axes_props['nx']*axes_props['dx'], ..., y0=2000)

# Prepare simulations for different rheological parameters
deltas = [15, 20, 25]
for delta in deltas:
params_txt = 'delta_{:05.2f}'.format(delta).replace('.', 'p')
params['folder_output'] = params_txt
params['delta1'] = delta
shinit.write_params_file(params, directory=folder_simus, file_name=params_txt + '.txt')
os.makedirs(os.path.join(folder_simus, params_txt), exist_ok=True)

After preparing the simulations, you can run them using the Shaltop documentation. To retrieve the simulation results, you can use the tilupy.read.get_results function, specifying the model name and the folder containing the simulation outputs. From the results, you can access various output variables such as flow thickness, velocity, momentum, and kinetic energy. You can also process the results by plotting them on top of the underlying topography or saving them as raster files.

Implementation 1: Plotting Simulation Results

One implementation example is to plot the flow thickness at each recorded time step, using the tilupy.cmd.plot_results function. This function allows you to customize the plot settings such as the color scale, contour lines, and plot size. You can save the plots in a specified folder and choose whether to display the plots in the terminal or not.

import tilupy.cmd

# Plot flow thickness
tilupy.cmd.plot_results('shaltop', 'h', 'delta_*.txt', folder_simus, save=True, display_plot=False, figsize=(15/2.54, 15/2.54), vmin=0.1, vmax=100, fmt='png')

Implementation 2: Saving Simulation Results as Rasters

If you prefer to save the simulation results as raster files, you can use the tilupy.cmd.to_raster function. This function allows you to specify the output format, such as TIFF or ASCII, and saves each recorded output variable as a separate raster file in a new folder created in the specified output folder.

tilupy.cmd.to_raster('shaltop', 'h_max', 'delta_*.txt', folder_simus, fmt='tif')

Implementation 3: Command Line Processing

tilupy also provides command line scripts that allow for quick processing of simulation results. For example, you can use the tilupy_plot command to automatically plot and save simulation results in a new folder within the simulation output folder. Similarly, the tilupy_to_raster command allows you to save simulation results as raster files in various formats.

tilupy_plot shaltop -n h -p delta_*.txt -f folder_simus
tilupy_to_raster shaltop -n h_max -p delta_*.txt -f folder_simus --fmt tif

Conclusion

In this article, we have explored the tilupy package and learned how to process thin-layer geophysical flow simulations using Python scripts and the command line. We have discussed the installation process, provided a quick start guide, and presented several examples of implementing tilupy for data processing and analysis. With its convenient features for handling input and output files, tilupy is a powerful tool for researchers and practitioners in the field of geophysics.

Category: Data Processing and Analysis

Tags: tilupy, geophysical flow simulations, thin layer, Python, data processing, command line, Python packages

Group Sum