TUFLOW FV Python Toolbox

Jump to navigation Jump to search
Wiki Links Help Downloads
TUFLOW FV Wiki Main Page Products Support/Contact TUFLOW FV Downloads
TUFLOW FV Tutorials Requesting a Licence Tutorial Module Data
TUFLOW Classic/HPC Wiki TUFLOW FV Glossary Manuals


This introductory tutorial provides a guide to get you setup with the TUFLOW FV Python Toolbox using Conda and Jupyter Notebooks.

We will complete these steps:

  1. Download and install Miniconda.
  2. Setup a TUFLOW FV Python development environment.
  3. Run a Jupyter Notebook in your web browser.
  4. You can then work through the example notebooks and try out and test your own code.

Assumed Knowledge

This tutorial doesn't require any existing Python knowledge. However, it is recommended to try out some introductory courses on Python, particularly use of:

  • Navigating and using Jupyter Notebooks
  • The numpy, xarray, pandas and matplotlib Python modules

Download Example Datasets and Scripts

Download the TUFLOW FV Python Toolbox Data Package.

Unzip the download and save to your preferred location. For example, D:\Tutorial_Models\TUFLOWFV_Python_Toolbox\.

Within the download package are the following folders and files:

File or Directory Description
.\Readme.txt Short description of the contents of each folder and basic metadata.
.\examples Tutorial and example Jupyter Notebooks to guide you through post-processing with the tfv python package.
.\examples\data Existing results and data required to run the demonstration notebooks.
.\examples\tutorial_01 Introduction to using the tfv xarray tools.
.\examples\tutorial_02 Introduction to plotting with tfv.
.\examples\tutorial_02 Working with gridded boundary data.
.\examples\gallery Series of sub-folders with example plots.
.\tfv_workspace.yaml Conda Python configuration for TUFLOW FV workspace. We'll use it to install conda forge packages.

You can preview the notebooks on our tfv Readthedocs page.

Setup Python Environment

Create The TUFLOW FV Python Environment

To install miniconda and setup the working environment, please follow: Setup TUFLOW FV Python Environment.

Open Jupyter Lab

1. In Anaconda prompt (which is installed with Miniconda), navigate to where you have downloaded and unzipped the TUFLOW FV Python Toolbox data package. Stay at the top level folder, for example D:\Tutorial_Models\TUFLOWFV_Python_Toolbox\. Do not cd down into the sub-folders, otherwise we will not be able to access everything we need when we open Jupyter Lab. To navigate, use the cd command as shown below:

Cd jupyter.png

In this example, as we've started on the C drive, we need to add the command D: to move from the C drive to our TUFLOWFV_Python_Toolbox folder on the D drive.

2. Once you've navigated to your TUFLOWFV_Python_Toolbox directory, type the command: jupyter-lab

Open jupyter.png

A Jupyter Lab instance should open in your web browser. Note the folders available to the workspace are based on the file location from which you opened jupyter-lab. In this example, this is D:\Tutorial_Models\TUFLOWFV_Python_Toolbox\TUFLOWFV_Python_Toolbox.


Tutorials And Examples

To learn more about navigating Jupyter Notebooks, including commands and shortcuts, please check out the Jupyter Lab online interactive documentation.

You can open each of the notebooks (they have the extension .ipynb) in your Jupyter Lab environment and run them. If you would like to preview the contents of each notebook, the full suite of them can be viewed on our tfv Readthedocs page.

We recommend working through the Tutorial 1 and Tutorial 2 notebooks first prior to working your way through the gallery notebooks.

The figure below is an example of the outputs available. You can view the Gallery 5 Combined Plots available in our download package within .\examples\gallery\5.combined_plots.

Salinity a salty tale.png

Using Alternative Integrated Development Environments

If you prefer to use an alternative IDE to Jupyter Labs, then please do. You can find tfv available via PyPi or Conda Forge. For more information, please check out the tfv documentation page: https://tfv.readthedocs.io/en/latest/.

Going Further - Creating Boundary Conditions Using The TUFLOW FV Get Tools

The TUFLOW FV Python Toolbox can be used to help generate astronomical tide, meteorological and ocean boundary conditions for your TUFLOW FV model. These tools make it easy for you to download global model datasets and write TUFLOW FV boundary condition files for you that are directly ready for you to start modelling. When you install the tuflowfv-workspace python environment the following three command line interface tools are also installed and the following wiki tutorial pages will walk you through step by step how to use them:

  1. TUFLOW FV Get Tide: Tools to generate astronomical tidal boundary condition from FES2014.
  2. TUFLOW FV Get Atmos : Tools to download ERA5, CFSR/CSFv2 and BARRA model data and generate meteorological boundary conditions.
  3. TUFLOW FV Get Ocean: Tools to download HYCOM model data and generate oceanic boundary conditions.


For comments, requests and feedback contact support@tuflow.com.

Archive Dataset And Tutorial

Historic Python tutorial model datasets can be accessed via the following link: TUFLOW_FV_Python_Toolbox_Archive.


Thank you for working through the TUFLOW FV Python Toolbox Wiki Page. For more TUFLOW FV guidance, examples and tutorials, please return to the TUFLOW FV Wiki Home Page.