FV Python Tools

From TUFLOW FV Wiki
Jump to: navigation, search

This online guide is designed to be a brief overview of the suite of Python tools for visualising model results.

Introduction

This page provides you with an overview of the TUFLOW FV Python Package and uses example scripts to showcase it's functionality.
The Python examples presented herein use Tutorial Module 5 as the example dataset. The provided scripts can be easily modified for use with your own datasets, however we encourage you to start out with the pre-defined examples provided with Tutorial Module 5.

Python Install and Toolbox Setup

Python Install

Please refer to the Python Installation page for installation guidance.

TUFLOW FV Python Package

The TUFLOW FV (tfv) package is available via Python Package Index PyPi.

From command prompt install and update using pip:

python -m pip install tfv

The tfv package depends on the following packages and versions:

cftime >= 1.0.3.4
cycler >= 0.10.0
imagecodecs >= 2019.5.22
kiwisolver >= 1.1.0
matplotlib >= 3.1.1
netCDF4 >= 1.5.1.2
numpy >= 1.17.0
pyparsing >= 2.4.2
PyQt5 >= 5.13.0
six >= 1.12.0

IDE Setup

The IDE you choose is completely up to your preference. Below you will find instructions on how to setup the TUFLOW FV Python Toolbox with two common IDEs:

  • PyScripter Setup
  • PyCharm Setup

    Visualising Tutorial Module 5 results

    This page is used in combination with the datasets produced by Tutorial Module 05 that demonstrates the development of a 3D estuary model. Before completing the following exercises please ensure you have downloaded the data package for the tutorial from the TUFLOW FV Tutorial / Demo Models page:www.tuflow.com.

    Timeseries Plot

    A timeseries plot allows you to view the timeseries data of a single variable at a single location. In order to produce timeseries plots, a profile NetCDF (nc) file must be written using the results NetCDF file from TUFLOW FV. To write a profile file, please navigate to the \tutorial\Basic folder and open the script ‘000_create_profile_file.py’ in your preferred IDE. Verify that the following lines of code are set to process data from the HYD_000, HYD_001, HYD_002, WQ_000, WQ_001 and WQ_002 models.

    000 create profile script b.png

    This script will generate NetCDF profile files with the simulation results located at the 9 output sites specified above.

    Run the script. The files ‘HYD_000_profiles.nc’, ‘HYD_001_profiles.nc’, ‘HYD_002_profiles.nc’, ‘WQ_000_profiles.nc’, ‘WQ_001_profiles.nc’ and ‘WQ_002_profiles.nc’ will now be generated in the output folder.

    If you are currently completing Tutorial Module 5 you can return to the Initial 2D model HYD_000.

    To produce a timeseries plot, please open the script ‘001_plot_2D_variable_timeseries.py’ in your preferred IDE. This script will create a timeseries plot of elevation vs. a variable selected from a profile file. Make the appropriate changes shown below to plot temperature at point 4 for HYD_001.

    001 temp timeseries script.PNG

    As shown above, the path to the results and profile files must be provided. Additionally, depending on which point you would like to plot a profile for, you will have to enter the point name and coordinates as provided in the comment lines. Finally, depending on which variable you wish to plot, you may have to alter the var, y_lim, and y_label lines of code.

    A timeseries plot produced in python is shown below:

    001 temp timeseries plot.PNG

    Profile Plot

    To view the results of the HYD_000 and HYD_001 simulations we will produce profile plots for salinity. A profile plot will allow you to view a variable through the vertical as a timeseries (with time slider bar). To plot the profile, open the script ‘002_plot_profile.py’ in your preferred IDE. This script will create a vertical profile of elevation vs. a 3D variable from a profile file. Make the appropriate changes shown below to plot salinity at point 1 for HYD_001.

    002 sal profile script.PNG

    As shown above, the path to both the results directory and the name of the results file must be provided. Additionally, depending on which point you would like to plot a profile for, you will have to enter the coordinates as provided in the comment lines. Finally, depending on which variable you wish to plot, you may have to alter the var, x_limit, and x_label lines of code.
    An example of a profile plot produced in python is shown below:

    Python profile plot.png

    If you are currently completing Tutorial Module 5 you can return to the Basic 3D model (HYD_001).

    Sheet Plot

    Sheet plot with vectors

    As identified in the timeseries plots, oscillation in temperature is observed, presumably due to the tide. To further investigate how the temperature is affected by the tide and boundary conditions, a sheet plot of temperature with vectors can be produced. To produce a sheet plot with vectors using python, please navigate to the \tutorial\Basic folder and open the script '003_plot_sheet.py'. This script will visualise a given variable in plan view. Make the appropriate changes shown below to plot the temperature distribution for the HYD_000 model.

    003 plot sheet script.PNG

    As shown above, the path to the results file must be provided. Additionally, depending on which variable you wish to plot, you may have to alter the var, var_name, and var_lim lines of code.

    A sheet plot for temperature with vectors produced in Python is shown below:

    Sheet plot temperature grad vec python.gif

    If you are currently completing Tutorial Module 5 you can return to the Initial 2D model HYD_000.

    Impact Sheet plot

    An impact sheet plot will allow you to observe the changes to a variable in plan view. For example, during Tutorial Module 5, a waste water treatment plant (WWTP) is added to the water quality simulation. In order to observe the change to DO in the estuary, an impact sheet plot can be used. To produce an impact sheet plot, please navigate to \tutorial\Extended\3.sheets and open the script 'sh_006_impact_sheet_multiple_models.py'. The following steps provide a demonstration of how to configure the impact sheet plot for dissolved oxygen.

    • Verify that the script is pointed at the relevant TUFLOW FV results files (where WQ_000_WQ.nc is the base_res_name and WQ_001_WQ.nc is the dev_res_name),
    • Verify that the variables (sheet_variable) are set to 'WQ_OXY_OXY',
    • Verify that the colour scaling lines set up an appropriate Dissolved Oxygen (mg/L) scale.


    Before running the script, the User Input section should appear like the lines shown below:

    006 impact script.PNG

    After you run the script, you should see results as shown below:
    006 Impact plot.gif

    If you are currently completing Tutorial Module 5 you can return to the WWTP simulation results.

    Curtain Plot

    To view the results of the baroclinicity enabled simulation, HYD_002, we will produce a curtain plot. A curtain plot allows you to view a variable along a cross section as a function of chainage and depth (with time slider bar). Now that baroclinicity has been enabled, a curtain plot will allow us to see the formation of a salt wedge in the estuary.

    To produce a curtain plot, open the script ‘004_plot_curtain.py’. This script will create a cross sectional profile for a 3D variable using the model results file as input. The cross section will be plotted along the polyline as specified in the code (see below). Make the appropriate changes shown below to plot the salinity distribution for the HYD_002 model.

    004 curtain script.PNG


    As shown above, the path to the results file must be provided. Additionally, depending on which variable you wish to plot, you may have to alter the var, and var_lim lines of code.

    A curtain plot for salinity produced in Python is shown below:

    Python curtain animation.gif


    If you are currently completing Tutorial Module 5 you can return to the 3D model with baroclinicity HYD_002.

    Combined Plot

    In order to produce a combined plot, a profile file must first be written. To do this please refer to Writing a profile NetCDF file. Once this has been done, please navigate to the \tutorial\Extended\5.combined_plots folder and open the script ‘co_000_plot_multiple_ways'. This script will plot a profile, timeseries, sheet and curtain plot for 4 specified variables. In the User Input section of the code please ensure that the paths to both the results and profile files are provided. Then proceed to change the code accordingly for your chosen profile/timeseries as well as sheet and curtain variables. As an example, make the appropriate changes shown below to produce all 4 plots for velocity, including profile and timeseries plots at point 3, for the HYD_002 model.

    Combined script.PNG

    As shown above, depending on which point you would like to plot a profile for, you will have to enter the point name and coordinates as provided in the comment lines. Additionally, depending on which variables you wish to plot, you may have to alter the sheet_var, curt_var, prof_var, sheet_var_lim, curt_var_lim and prof_var_lim lines of code. Please note that the prof_var commands control the timeseries plot as well.

    A combined plot for velocity produced in Python is shown below:

    Python combined plotv2.gif

    If you are currently completing Tutorial Module 5 you can return to the water quality simulation results.