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 from the TUFLOW Website Utilities Download Section (look for the TUFLOW FV Python Toolbox).

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\xarray_basic_use Introduction to using the tfv xarray tools.
.\examples\plot_composition Introduction to plotting with tfv.
.\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.

Previous Downloads

Looking for the previous Pycharm workflow and .py scripts? You can still find these via the TUFLOW FV Python Toolbox Archive.

Setup Python Environment

Miniconda Installation

1. Go to https://docs.conda.io/en/latest/miniconda.html and download the latest Miniconda Windows 64-bit installer.

Conda install 1.png

2. Once downloaded, please install and follow the prompts. Select the default options as you are guided through the install wizard.

Create The TUFLOW FV Python Environment

Once Miniconda is installed we will create a Python working environment. In this environment we will install the tfv Python package and the modules required to complete common post-processing tasks on TUFLOW FV results.

To setup the working environment please follow: Setup TUFLOW FV Python Environment.

Open Jupyter Lab

1. In Anaconda prompt 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 you opened the jupyter-lab from. In this example 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 notebooks the full suite of them can be viewed on our tfv Readthedocs page.

The figure below is an output from Gallery 5 Combined Plots available in our download package within .\examples\gallery\5.combined_plots.

Salinity a salty tale.png

Upgrading the TUFLOW FV Python Toolbox

If you are encountering issues with accessing functionality described in our documentation, it is possible that your TUFLOW FV Python Toolbox version requires upgrading. To upgrade:

1. Open Anaconda prompt, and activate your TUFLOW FV Python environment with the command:

  conda activate tfv-workspace

Activate tfv-workspace.png

2. To view the details of all packages installed as part of this environment, enter the command:

  conda list

GetAtmos conda list.png

3. Identify the version of your tfv package.

Get tfv package.png

4. To view all existing versions of the tfv module, enter the command:

  conda search -c conda-forge -f tfv

Get tfv existing packages.png

5. If the version of the tfv module in your environment is not the most recent, you will need to upgrade. To upgrade the tfv module to the current version, enter the command:

  conda update tfv

Get update tfv 1.png

Get update tfv 2.png

6. To verify that Get Atmos has now been reinstalled, you can again check the list of all environment packages by entering the command:

  conda list

GetAtmos conda list.png

You will now find the most recent version of Get Atmos within your environment packages list.

Get tfv package.png

Using Alternative Integrated Development Environments

If you prefer to use an alternative IDE to Jupyter Labs than 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/.


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.


Thanks 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.