TUFLOW FV Python Toolbox

USEFUL LINKS
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

Introduction

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 TUFLOW FV Python Toolbox xarray extensions.
.\examples\tutorial_02	Introduction to plotting with the TUFLOW FV Python Toolbox
.\examples\tutorial_03	Working with gridded boundary condition 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. To run them yourself you will need to setup the TUFLOW FV Python Environment.

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

Create The TUFLOW FV Python Environment

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:

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

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.

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

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

  conda list

3. Identify the version of your tfv package.

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

  conda search -c conda-forge -f tfv

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

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

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

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

Contact

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.

Conclusion

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.