Package: tilupy
tilupyDescriptionInstallationQuick startPrepare simulationsGet simulation resultsProcess simulation results in python scriptProcess simulation results in command lineModels referencesShaltopr.avaflowDescriptiontilupy(ThIn-Layer Unified Processing in pYthon) package is meant as a top-level tool for processing inputs and outputs of thin-layer geophysical
flow simulations on general topographies.
It contains one submodule per thin-layer model for writing and reading raw inputs and outputs of the model.
Outputs are then easily compared between different simulations / models. The models themselves are not part of this package and must
be installed separately.Note thattilupyis still under development, thus only minimal documentation is available at the moment, and testing is underway.
Contributions are feedback are most welcome. Reading and writing is available for theSHALTOPmodel (most commonly used by the author) andr.avaflow(only partly maintained).InstallationTo installtilupyfrom GitHub or PyPi, you'll need to havepipinstalled on your computer.tilupyis not yet available onconda-forge.It is strongly recommended to installtilupyin a virtual environnement dedicated to this package. This can be done withvirtualenv(see the documentation e.g.here).
Create the environnement with :python-mvenv/path/to/myenvand activate it, on Linux:source/path/to/myenv/bin/activateand on Windows:\path\to\myenv\Scripts\activateAlternatively, if you are more used to Anaconda :condacreate-ntilupypip
condaactivatetilupyor equivalently with Mamba :mambacreate-ntilupypip
mambaactivatetilupyBefore installing withpip, make surepip,steuptoolsandwheelare up to datepython -m pip install --upgrade pip setuptools wheelLatest stable realease from PyPipython -m pip install tilupyDevelopment version on from GitHubDownload the GithHub repositoryhere, or clone it withgit clone https://github.com/marcperuz/tilupy.gitOpen a terminal in the created folder and type:python -m pip install .Quick startWe give here a simple example to prepare simulations for SHALTOP, and process the results. The corresponding scripts can be found inexamples/frankslidePrepare simulationsImport the different required modules :importos# Read an write rastersimporttilupy.raster# Functions to download examples of elevation and initial mass rastersimporttilupy.download_data#Submodule used to prepare Shaltop simulationsimporttilupy.models.shaltop.initsimusasshinitDefine the folder where input data will be downloaded and simulations carried out :FOLDER_BASE='/path/to/myfolder'Import data from GitHub, and create subfolder for simulation resultsfolder_data=os.path.join(FOLDER_BASE,'rasters')os.makedirs(folder_data,exist_ok=True)#raster_topo and raster_mass are the paths to the topography and initial mass rastersraster_topo=tilupy.download_data.import_frankslide_dem(folder_out=folder_data)raster_mass=tilupy.download_data.import_frankslide_pile(folder_out=folder_data)# Create folder for shaltop simulationsfolder_simus=os.path.join(FOLDER_BASE,'shaltop')os.makedirs(folder_simus,exist_ok=True)Convert downloaded rasters to Shaltop input file type, and store the properties of the resulting gridshinit.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'))Initiate simulations parameters. See the SHALTOP documentation for details.params=dict(nx=axes_props['nx'],ny=axes_props['ny'],per=axes_props['nx']*axes_props['dx'],pery=axes_props['ny']*axes_props['dy'],tmax=100,# Simulation maximum time in seconds (not comutation time)dt_im=10,# Time interval (s) between snapshots recordingsfile_z_init='topography.d',# Name of topography input filefile_m_init='init_mass.d',# name of init mass input fileinitz=0,# Topography is read from fileipr=0,# Initial mass is read from filehinit_vert=1,# Initial is given as vertical thicknesses and# must be converted to thicknesses normal to topographyeps0=1e-13,#Minimum value for thicknesses and velocitiesicomp=1,# choice of rheology (Coulomb with constant basal friction)x0=1000,# Min x value (used for plots after simulation is over)y0=2000)# Min y value (used for plots after simulation is over)Finally, prepare simulations for a set of given rheological parameters (here, three basal friction coefficients)deltas=[15,20,25]fordeltaindeltas:params_txt='delta_{:05.2f}'.format(delta).replace('.','p')params['folder_output']=params_txt# Specify folder where outputs are storedparams['delta1']=delta# Specify the friction coefficient#Write parameter fileshinit.write_params_file(params,directory=folder_simus,file_name=params_txt+'.txt')#Create folder for results (not done by shlatop!)os.makedirs(os.path.join(folder_simus,params_txt),exist_ok=True)You must then run the simulations (see Shaltop documentation)Get simulation resultsSimulation results are read from aResultsclass. Main functions are defined in the parent classtilupy.read.Results, and each model has its own inheretied classtilupy.models.[model_name].read.Results. A class instance for a given model can be initiated withres=tilupy.read.get_results([model_name],**kwargs)where `kwargs must be adapted to the considered model. For instance with Shaltop and the example above, the results of the simulation with a friction angle of 25 must be initiated as :res=tilupy.read.get_results('shaltop',folder_base=folder_simus,file_params='delta_25p00.txt)The topography and axes can then directly be read fromres:x,y,z=res.x,res.y,res.zimportmatplotlib.pyplotaspltplt.imshow(z)z[i, j]is the altitude atflip(y[i])andx[j]. Thusz[0, 0]corresponds to the North-West corner of the topography.Specific simulation outputs can be extracted withh_res=res.get_output(res_name)whereres_namemust chosen amongh: Flow thickness in the direction perpendicular to the topographyhvert: Flow thickness in the vertical directionuxanduy: Flow velocity in the X and Y direction (check whether it is in the cartesian reference frame or not)u: Norm of the flow velocityhu: Momentum (thickness * flow velocity)hu2: Kinetic energy (thickness * square flow velocity)It is also possible to extract 2D spatial static characteritics of the flow by using any of the previous states with_[operation], where[operation]is chosen among,max,mean,std,sum,min,final,initial. For instanceh_maxis a 2D array with the
maximum simulated thickness at each point of the grid.h_finalis the simulated thickness at the end of the simulation.tilupywill load these characteristics directly from the simulation output when possible (e.g. Shaltop records a maximum thickness array),
or compute then from the available data. For instance, if the simulation results contains a file whith the maximum thickness,h_maxwill be
read from this file. Otherwise,h_maxis computed from the simulation recorded temporal snapshots (which is supposedly less precise).For instance, to load the recorded thicknesses in the current example :res_name='h'h_res=res.get_output(res_name)# Thicknesses recorded at different times# h_res.d is a 3D numpy array of dimension (len(x) x len(y) x len(h_res.t))plt.imshow(h_res.d[:,:,-1])# Plot final thickness.t=h_res.t# Get times of simulation outputs.And to load the maximum thickness array :res_name='h_max'h_max_res=res.get_output(res_name)#h_max_res is read directly from simulation# results when possible, and is deduced from res.get_output('h') otherwise# h_max_res.d is a 2D numpy array of dimension (len(x) x len(y))plt.imshow(h_max_res.d)Process simulation results in python scripttilupycan be used to plot the results as images, where the flow state (thickness, velocity, ...)
is shown with a colorscale on the underlying topography. Plots can be thouroughly customized (documentation not available yet).For instance, the following code plots the flow thickness at each recorded time step, with a constant colorscale vraying from 0.1 to
100 m. The topography is represented as a shaded relief with thin contour lines every 10 m, and bold contour_lines every 100 m. Plots are saved
in a folder created infolder_out, but not displayed in the terminal (if you work in a developping environnement such asspyder).topo_kwargs=dict(contour_step=10,step_contour_bold=100)# give interval between thin and bold contour linesparams_files='delta_*.txt'tilupy.cmd.plot_results('shaltop','h',params_files,folder_simus,save=True,display_plot=False,figsize=(15/2.54,15/2.54),vmin=0.1,vmax=100,fmt='png',topo_kwargs=topo_kwargs)The following code acts similarly, but plots the maximum thickness instead, and used a segmented colormap given bycmap_intervals.tilupy.cmd.plot_results('shaltop','h_max',params_files,folder_simus,save=True,display_plot=False,figsize=(15/2.54,15/2.54),cmap_intervals=[0.1,5,10,25,50,100],topo_kwargs=topo_kwargs)It is also possible to save outputs back to rasters. The following code save all recorded thicknesses snapshots as tif files in a new folder
created infolder_out.tilupy.cmd.to_raster('shaltop','h_max',params_files,folder_simus,fmt='tif')Process simulation results in command linetilupycomes with command line scripts to allow for quick processing of results. They work similarly as the functionstilupy.cmd.plot_resultsandtilupy.cmd.to_raster,
although there are less options.tilupy_plotwill automatically plot and save results in a new folderplotlocated in the simulation output folder specified in the parameter file :tilupy_plot [-h] [-n RES_NAME] [-p PARAM_FILES] [-f FOLDER] [--fmt FMT] [--vmin VMIN] [--vmax VMAX]
                   [--minval_abs MINVAL_ABS]
                   modelRES_NAMEcan be any of the strings listed in the previous section. For instance, to plot all thicknesses snaphsots from shaltop simulations in the current folder, typetilupy_plot shaltop -n h. If parameters files are located inanother/folder, type,tilupy shaltop -n h -f another/folder. Similarly, to save  thicknesses snapshots as ascii rasters, usetilupy_to_raster shaltop -n h --fmt asc.tilupy_to_raster [-h] [-n RES_NAME] [-p PARAM_FILES] [-f FOLDER] [--fmt {tif,tiff,txt,asc,ascii}] modelWith both commands you can use the-hoption do print help.Models referencesWe provide here a basic descriptions of models compatible withtilupy. The list of references is not exhaustive.Shaltopshaltopmodels gravitational flow models over general topographies with small slope variation (small curvature) and friction. The equations are expressed in a horizontal/vertical reference frame and the shallow approximation is imposed in the direction normal to the slope.shaltopis not yet freely available. If you are interested, contactm.peruzzetto@brgm.frormangeney@ipgp.fr.Bouchut, F., Mangeney-Castelnau, A., Perthame, B., Vilotte, J.-P., 2003. A new model of Saint Venant and Savage–Hutter type for gravity driven shallow water flows. Comptes Rendus Mathématique 336, 531–536.https://doi.org/10.1016/S1631-073X(03)00117-1Bouchut, F., Westdickenberg, M., 2004. Gravity driven shallow water models for arbitrary topography. Communications in Mathematical Sciences 2, 359–389.https://doi.org/10.4310/CMS.2004.v2.n3.a2Mangeney-Castelnau, A., Bouchut, F., Vilotte, J.P., Lajeunesse, E., Aubertin, A., Pirulli, M., 2005. On the use of Saint Venant equations to simulate the spreading of a granular mass: numerical simulation of granular spreading. Journal of Geophysical Research: Solid Earth 110, B09103.https://doi.org/10.1029/2004JB003161Mangeney, A., Bouchut, F., Thomas, N., Vilotte, J.P., Bristeau, M.O., 2007. Numerical modeling of self-channeling granular flows and of their levee-channel deposits. Journal of Geophysical Research 112, F02017.https://doi.org/10.1029/2006JF000469r.avaflowr.avaflow representsa GIS-supported open source software tool for the simulation of complex, cascading mass flows over arbitrary topography. It can be downloaded, along with the associated documentation, on the officielwebsite. Note that the integration ofr.avaflowintilupyis partial and potentially not adapted to new releases ofr.avaflow.Mergili, M., Fischer, J.-T., Krenn, J., Pudasaini, S.P., 2017. r.avaflow v1, an advanced open source computational framework for the propagation and interaction of two-phase mass flows. Geoscientific Model Development Discussions 10, 553–569.https://doi.org/10.5194/gmd-10-553-2017Pudasaini, S.P., Mergili, M., 2019. A Multi-Phase Mass Flow Model. Journal of Geophysical Research: Earth Surface 124, 2920–2942.https://doi.org/10.1029/2019JF005204