Difference between revisions of "PyTuflow"
Ellis Symons (talk | contribs) |
Chris Huxley (talk | contribs) |
||
(44 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
+ | =Introduction= | ||
+ | PyTUFLOW is a package of Python tools for extracting TUFLOW Classic and HPC time series results. It can be used to automate output tasks such as checking model health, goodness-of-fit for model calibration, viewing on-the-fly model output (used in conjunction with <tt><font color="blue">Write PO Online</font> <font color="red">==</font> ON</tt>), and high-volume output plotting from production runs.<br><Br> | ||
+ | For worked examples demonstrating the use of PyTUFLOW, please register for the free <u>[https://www.tuflow.com/training/training-catalogue/tt004e-introduction-to-python-for-tuflow-elearning/ Introduction to Python for TUFLOW]</u> eLearning Course. | ||
+ | |||
+ | =Installation= | ||
+ | The PyTuflow library can be installed via Python's packaging manager (pip).<br> | ||
+ | Open up the command prompt and enter the following:<br> | ||
+ | <pre> | ||
+ | python -m pip install pytuflow | ||
+ | </pre> | ||
+ | |||
+ | If python is not on your system path, you can navigate to the folder containing the <tt>python.exe</tt> before trying to install PyTuflow<br> | ||
+ | e.g.<br> | ||
+ | <pre> | ||
+ | cd c:\Python39 | ||
+ | python -m pip install pytuflow | ||
+ | </pre> | ||
+ | |||
=Class: ResData= | =Class: ResData= | ||
Line 6: | Line 24: | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
− | res = | + | res = pytuflow.ResData() # initialising as an empty object |
# or | # or | ||
− | res = | + | res = pytuflow.ResData('M01_5m_001.tpc') # initialising with results |
</pre> | </pre> | ||
Line 66: | Line 84: | ||
|''tuple'' Profile Data ( ''list'' x values, ''list'' y values ) | |''tuple'' Profile Data ( ''list'' x values, ''list'' y values ) | ||
|- | |- | ||
− | |rowspan='2'|<b>[[# | + | |rowspan='2'|<b>[[#getLongProfileTimeOfMaximum|getLongProfileTimeOfMaximum]] ()</b> |
|rowspan='2'|Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method | |rowspan='2'|Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method | ||
|''list'' x values | |''list'' x values | ||
Line 138: | Line 156: | ||
|''list'' PO ID | |''list'' PO ID | ||
|- | |- | ||
− | |rowspan='1'|<b>poResultTypes ()</b> | + | |rowspan='1'|<b>[[#poResultTypes|poResultTypes]] ()</b> |
|rowspan='1'|Returns a list of all the available Plot Output result types | |rowspan='1'|Returns a list of all the available Plot Output result types | ||
|''list'' Result Types | |''list'' Result Types | ||
|- | |- | ||
− | |rowspan='1'|<b>rlCount ()</b> | + | |rowspan='1'|<b>[[#rlCount|rlCount]] ()</b> |
|rowspan='1'|Returns the total number of Reporting Locations (of all geometry type) in the results | |rowspan='1'|Returns the total number of Reporting Locations (of all geometry type) in the results | ||
|''int'' Count | |''int'' Count | ||
|- | |- | ||
− | |rowspan='1'|<b>rlLineCount ()</b> | + | |rowspan='1'|<b>[[#rlLineCount|rlLineCount]] ()</b> |
|rowspan='1'|Returns the total number of line Reporting Locations in the results | |rowspan='1'|Returns the total number of line Reporting Locations in the results | ||
|''int'' Count | |''int'' Count | ||
|- | |- | ||
− | |rowspan='1'|<b>rlNames ()</b> | + | |rowspan='1'|<b>[[#rlNames|rlNames]] ()</b> |
|rowspan='1'|Returns a list of all the Reporting Location names | |rowspan='1'|Returns a list of all the Reporting Location names | ||
|''list'' RL ID | |''list'' RL ID | ||
|- | |- | ||
− | |rowspan='1'|<b>rlPointCount ()</b> | + | |rowspan='1'|<b>[[#rlPointCount|rlPointCount]] ()</b> |
|rowspan='1'|Returns the total number of point Reporting Locations in the results | |rowspan='1'|Returns the total number of point Reporting Locations in the results | ||
|''int'' Count | |''int'' Count | ||
|- | |- | ||
− | |rowspan='1'|<b>rlRegionCount ()</b> | + | |rowspan='1'|<b>[[#rlRegionCount|rlRegionCount]] ()</b> |
|rowspan='1'|Returns the total number of region Reporting Locations in the results | |rowspan='1'|Returns the total number of region Reporting Locations in the results | ||
|''int'' Count | |''int'' Count | ||
|- | |- | ||
− | |rowspan='1'|<b>rlResultTypes ()</b> | + | |rowspan='1'|<b>[[#rlResultTypes|rlResultTypes]] ()</b> |
|rowspan='1'|Returns a list of all the available Reporting Location result types | |rowspan='1'|Returns a list of all the available Reporting Location result types | ||
|''list'' Result Types | |''list'' Result Types | ||
|- | |- | ||
− | |rowspan='1'|<b>source ()</b> | + | |rowspan='1'|<b>[[#source|source]] ()</b> |
|rowspan='1'|Returns the full file path to the source result file (*.tpc or *.info) | |rowspan='1'|Returns the full file path to the source result file (*.tpc or *.info) | ||
|''str'' Path | |''str'' Path | ||
|- | |- | ||
− | |rowspan='3'|<b>timeOfMaximum (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b> | + | |rowspan='3'|<b>[[#timeOfMaximum|timeOfMaximum]] (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b> |
|rowspan='3'|Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | |rowspan='3'|Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | ||
|''bool'' Error | |''bool'' Error | ||
Line 178: | Line 196: | ||
|''float'' Time (hrs) | |''float'' Time (hrs) | ||
|- | |- | ||
− | |rowspan='3'|<b>timeOfMaximumTimestepChange (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b> | + | |rowspan='3'|<b>[[#timeOfMaximumTimestepChange|timeOfMaximumTimestepChange]] (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b> |
|rowspan='3'|Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | |rowspan='3'|Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | ||
|''bool'' Error | |''bool'' Error | ||
Line 200: | Line 218: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 219: | Line 237: | ||
print(message) | print(message) | ||
</pre> | </pre> | ||
+ | |||
==channelConnections== | ==channelConnections== | ||
Line 231: | Line 250: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 264: | Line 283: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 294: | Line 313: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 325: | Line 344: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 357: | Line 376: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 390: | Line 409: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 422: | Line 441: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 454: | Line 473: | ||
<pre> | <pre> | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 537: | Line 556: | ||
<pre> | <pre> | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 577: | Line 596: | ||
</pre> | </pre> | ||
− | == | + | ==getLongProfileTimeOfMaximum== |
− | <b> | + | <b>getLongProfileTimeOfMaximum ()</b><br> |
Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method<br> | Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method<br> | ||
;Parameters: | ;Parameters: | ||
Line 590: | Line 609: | ||
<pre> | <pre> | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 654: | Line 673: | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
from matplotlib.patches import Polygon # will add pipes and culverts as polygon | from matplotlib.patches import Polygon # will add pipes and culverts as polygon | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 732: | Line 751: | ||
<pre> | <pre> | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 773: | Line 792: | ||
<pre> | <pre> | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 829: | Line 848: | ||
import os # library for operating system file and directory manipulation | import os # library for operating system file and directory manipulation | ||
import matplotlib.pyplot as plt # plotting library | import matplotlib.pyplot as plt # plotting library | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 890: | Line 909: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 915: | Line 934: | ||
'''Example''' | '''Example''' | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 956: | Line 975: | ||
Maximum flow in a channel | Maximum flow in a channel | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 977: | Line 996: | ||
Maximum water level at a node | Maximum water level at a node | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,016: | Line 1,035: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,046: | Line 1,065: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,075: | Line 1,094: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,105: | Line 1,124: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,135: | Line 1,154: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,166: | Line 1,185: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,198: | Line 1,217: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,228: | Line 1,247: | ||
'''Example'''<br> | '''Example'''<br> | ||
<pre> | <pre> | ||
− | import pytuflow | + | import pytuflow |
# Initialise result class | # Initialise result class | ||
− | res = | + | res = pytuflow.ResData() |
# load .tpc result file | # load .tpc result file | ||
Line 1,239: | Line 1,258: | ||
# check results were loaded successfully before calling function | # check results were loaded successfully before calling function | ||
if not err: | if not err: | ||
− | po_names = res. | + | po_names = res.poNames() |
# print to console | # print to console | ||
print('PO Names:) | print('PO Names:) | ||
for po_name in po_names: | for po_name in po_names: | ||
print(po_name) | print(po_name) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==poResultTypes== | ||
+ | <b>poResultTypes ()</b><br> | ||
+ | Returns a list of all the available Plot Output result types<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Out:''' ''list'' | ||
+ | :: List of available result types for Plot Outputs e.g. ['Q', 'H', 'V'] | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | result_types = res.poResultTypes() | ||
+ | # print to console | ||
+ | print('Available result types for Plot Outputs are:) | ||
+ | for result_type in result_types: | ||
+ | print(result_type) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlCount== | ||
+ | <b>rlCount ()</b><br> | ||
+ | Returns the total number of Reporting Locations (of all geometry type) in the results<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Count:''' ''int'' | ||
+ | :: Number of RL objects | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | rl_count = res.rlCount() | ||
+ | # print to console | ||
+ | print('{0} RL objects in results.format(node_count)) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlLineCount== | ||
+ | <b>rlLineCount ()</b><br> | ||
+ | Returns the total number of line Reporting Locations in the results<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Count:''' ''int'' | ||
+ | :: Number of RL Line objects | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | rl_line_count = res.rlLineCount() | ||
+ | # print to console | ||
+ | print('{0} RL Line objects in results.format(node_line_count)) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlNames== | ||
+ | <b>rlNames ()</b><br> | ||
+ | Returns a list of all the Reporting Location names<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Out:''' ''list'' | ||
+ | :: List of all RL names in results e.g. ['Reporting_Loc_1', 'Reporting_Loc_2', 'Reporting_Loc_3'] | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | rl_names = res.rlNames() | ||
+ | # print to console | ||
+ | print('RL Names:) | ||
+ | for rl_name in rl_names: | ||
+ | print(rl_name) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlPointCount== | ||
+ | <b>rlPointCount ()</b><br> | ||
+ | Returns the total number of point Reporting Locations in the results<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Count:''' ''int'' | ||
+ | :: Number of RL Point objects | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | rl_point_count = res.rlPointCount() | ||
+ | # print to console | ||
+ | print('{0} RL Point objects in results.format(node_point_count)) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlRegionCount== | ||
+ | <b>rlRegionCount ()</b><br> | ||
+ | Returns the total number of region Reporting Locations in the results<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Count:''' ''int'' | ||
+ | :: Number of RL Region objects | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | rl_region_count = res.rlRegionCount() | ||
+ | # print to console | ||
+ | print('{0} RL Region objects in results.format(node_region_count)) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==rlResultTypes== | ||
+ | <b>rlResultTypes ()</b><br> | ||
+ | Returns a list of all the available Reporting Location result types<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Out:''' ''list'' | ||
+ | :: List of available result types for Reporting Locations e.g. ['Q', 'H', 'Vol'] | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | result_types = res.rlResultTypes() | ||
+ | # print to console | ||
+ | print('Available result types for Reporting Locations are:) | ||
+ | for result_type in result_types: | ||
+ | print(result_type) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==source== | ||
+ | <b>source ()</b><br> | ||
+ | Returns the full file path to the source result file (*.tpc or *.info)<br> | ||
+ | ;Parameters: | ||
+ | : - | ||
+ | ;Returns: | ||
+ | : '''Source:''' ''str'' | ||
+ | :: Full path to result file | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | source = res.source() | ||
+ | # print to console | ||
+ | print('Successfully loaded result from {0}.format(source)) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==timeOfMaximum== | ||
+ | <b>timeOfMaximum (</b> Element, Result Type, [optional] Domain <b>)</b><br> | ||
+ | Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')<br> | ||
+ | ;Parameters: | ||
+ | : '''Element:''' ''str'' | ||
+ | :: Channel, Node, or RL element to get maximum result for. PO results do not currently support getting time of maximum. | ||
+ | : '''Result Type:''' ''str'' | ||
+ | :: Result type e.g. 'H' | ||
+ | : '''Domain:''' ''str'' | ||
+ | :: Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements. | ||
+ | ;Returns: | ||
+ | : '''Error:''' ''bool'' | ||
+ | :: Returns False on success, True when an error occurred | ||
+ | : '''Message:''' ''str'' | ||
+ | :: Accompanying error message if an error occurred | ||
+ | : '''Time of Maximum:''' ''float'' | ||
+ | :: Time of maximum | ||
+ | '''Example''' | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | node = 'Chan_A.1' | ||
+ | tom = res.timeOfMaximum(channel, 'H') | ||
+ | # print to console | ||
+ | print('Time of max water level at {0} is {1} hrs'.format(channel, tom) | ||
+ | else: | ||
+ | # did not load correctly, print error message to console | ||
+ | print(message) | ||
+ | </pre> | ||
+ | |||
+ | ==timeOfMaximumTimestepChange== | ||
+ | <b>timeOfMaximumTimestepChange (</b> Element, Result Type, [optional] Domain <b>)</b><br> | ||
+ | Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')<br> | ||
+ | ;Parameters: | ||
+ | : '''Element:''' ''str'' | ||
+ | :: RL element to get time of maximum change in a single timestep for. Currently RL elements are the only supported type. | ||
+ | : '''Result Type:''' ''str'' | ||
+ | :: Result type e.g. 'H' | ||
+ | : '''Domain:''' ''str'' | ||
+ | :: Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements. | ||
+ | ;Returns: | ||
+ | : '''Error:''' ''bool'' | ||
+ | :: Returns False on success, True when an error occurred | ||
+ | : '''Message:''' ''str'' | ||
+ | :: Accompanying error message if an error occurred | ||
+ | : '''Maximum''' ''float'' | ||
+ | :: Time of maximum value change | ||
+ | '''Example'''<br> | ||
+ | <pre> | ||
+ | import pytuflow | ||
+ | |||
+ | # Initialise result class | ||
+ | res = pytuflow.ResData() | ||
+ | |||
+ | # load .tpc result file | ||
+ | path = r'C:\TUFLOW\results\M04_5m_001.tpc' | ||
+ | err, message = res.load(path) | ||
+ | |||
+ | # check results were loaded successfully before calling function | ||
+ | if not err: | ||
+ | loc = 'Reporting Location 1' | ||
+ | tom_ts = res.timeOfMaximumTimestepChange(channel, 'Q') | ||
+ | # print to console | ||
+ | print('Time of max flow change in any given timestep at {0} is {1} hrs'.format(loc, tom_ts) | ||
else: | else: | ||
# did not load correctly, print error message to console | # did not load correctly, print error message to console | ||
print(message) | print(message) | ||
</pre> | </pre> |
Latest revision as of 19:29, 7 March 2022
Introduction
PyTUFLOW is a package of Python tools for extracting TUFLOW Classic and HPC time series results. It can be used to automate output tasks such as checking model health, goodness-of-fit for model calibration, viewing on-the-fly model output (used in conjunction with Write PO Online == ON), and high-volume output plotting from production runs.
For worked examples demonstrating the use of PyTUFLOW, please register for the free Introduction to Python for TUFLOW eLearning Course.
Installation
The PyTuflow library can be installed via Python's packaging manager (pip).
Open up the command prompt and enter the following:
python -m pip install pytuflow
If python is not on your system path, you can navigate to the folder containing the python.exe before trying to install PyTuflow
e.g.
cd c:\Python39 python -m pip install pytuflow
Class: ResData
Class for TUFLOW time series results.
Initialised as an empty object, or with results with a *.tpc in TUFLOW 2016 release and later or *.info in TUFLOW 2013 release.
import pytuflow res = pytuflow.ResData() # initialising as an empty object # or res = pytuflow.ResData('M01_5m_001.tpc') # initialising with results
Methods
Method | Description | Returns |
channelConnectionCount ( str Node ID ) | Returns the number of channels connected to a given node | int Count |
channelConnections ( str Node ID ) | Returns a list of the channels connected to a given node | list Channel IDs |
channelCount () | Returns the total number of channels in results | int Count |
channelResultTypes () | Returns a list of all the available result types for channels | list of Result Types |
channels () | Returns a list of all the channels IDs in the results | list Channel IDs |
channelsDownstream ( str Node ID ) | Returns a list of all the channels downstream of a given node | list Channel IDs |
channelsUpstream ( str Node ID ) | Returns a list of all the channels upstream of a given node | list Channel IDs |
format () | Returns the result format i.e. '2013' or '2016' | str Format |
getAdverseGradients () | Returns locations of any adverse water level or energy level (if result type available) gradients in long profile. Note getLongProfileData method must be called prior to calling this method | tuple Adverse Water Level Gradient Locations ( list x data, list y data ) |
tuple Adverse Energy Level Gradient Locations ( list x data, list y data ) | ||
getLongProfileData ( float Timestep, str Result Type, str Channel ID, [optional] str 2nd Channel ID ) | Returns long profile data from a given channel to another channel. If no second channel is specified will continue until no further channels downstream | bool Error |
str Message | ||
tuple Profile Data ( list x values, list y values ) | ||
getLongProfileTimeOfMaximum () | Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method | list x values |
list y values | ||
getPipes () | Returns any pipe or culvert data in the current profile. Note getLongProfileData method must be called prior to calling this method | list pipes [ list pipe vertexes [ tuple vertex ( x point, y point ) ] ] |
getTimeSeriesData ( str Element, str Result Type, [optional] str domain ) | Returns time series data for the given element (1D node, 1D channel, 2D PO, RL) for a the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | bool Error |
str Message | ||
tuple time series data ( list x data, list y data ) | ||
load ( str Filepath ) | Loads result file. File formats are *.tpc for TUFLOW release 2016 and later, or *.info for TUFLOW release 2013 | bool Error |
str Message | ||
longProfileResultTypes () | list Result Types | |
maximum ( str Element, str Result Type, [optional] str Domain ) | Returns the maximum result value for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | bool Error |
str Message | ||
float Maximum Value | ||
maximumTimestepChange ( str Element, str Result Type, [optional] str Domain ) | Returns the maximum change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | bool Error |
str Message | ||
float Maximum Value | ||
name () | Returns the name of the result | str Name |
nodeCount () | Returns the total number of nodes in the results | int Count |
nodeDownstream ( str Channel ID ) | Returns the name of the downstream node of a given channel | str Node ID |
nodeResultTypes () | Returns a list of all the available result types for nodes | list Result Types |
nodes () | Returns a list of all the node IDs in the results | list Node IDs |
nodeUpstream ( str Channel ID ) | Returns the name of the upstream node of a given channel | str Node ID |
poNames () | Returns a list of all the available Plot Output names | list PO ID |
poResultTypes () | Returns a list of all the available Plot Output result types | list Result Types |
rlCount () | Returns the total number of Reporting Locations (of all geometry type) in the results | int Count |
rlLineCount () | Returns the total number of line Reporting Locations in the results | int Count |
rlNames () | Returns a list of all the Reporting Location names | list RL ID |
rlPointCount () | Returns the total number of point Reporting Locations in the results | int Count |
rlRegionCount () | Returns the total number of region Reporting Locations in the results | int Count |
rlResultTypes () | Returns a list of all the available Reporting Location result types | list Result Types |
source () | Returns the full file path to the source result file (*.tpc or *.info) | str Path |
timeOfMaximum ( str Element, str Result Type, [optional] str Domain ) | Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | bool Error |
str Message | ||
float Time (hrs) | ||
timeOfMaximumTimestepChange ( str Element, str Result Type, [optional] str Domain ) | Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL') | bool Error |
str Message | ||
float Time (hrs) |
channelConnectionCount
channelConnectionCount ( Node ID )
Returns the number of channels connected to a given node
- Parameters
- Node ID: str
- Name or ID of node e.g. 'Chan_A.1'
- Returns
- Count: int
- Number of connected channels
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' conn_count = res.channelConnectionCount(node) # print to console print('{0} channels connected to {1}'.format(conn_count, node)) else: # did not load correctly, print error message to console print(message)
channelConnections
channelConnections ( Node ID )
Returns a list of the channels connected to a given node
- Parameters
- Node ID: str
- Name or ID of node e.g. 'Chan_A.1'
- Returns
- Out: list
- List of connected channels e.g. ['Chan_A', 'Chan_B']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' conn_chans = res.channelConnections(node) # print to console print('Channels connected to {0}:'.format(node)) for chan in conn_chans: print(chan) else: # did not load correctly, print error message to console print(message)
channelCount
channelCount ()
Returns the total number of channels in results
- Parameters
- -
- Returns
- Count: int
- Number of channels
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: chan_count = res.channelCount() # print to console print('{0} channels in results'.format(chan_count)) else: # did not load correctly, print error message to console print(message)
channelResultTypes
channelResultTypes ()
Returns a list of all the available result types for channels
- Parameters
- -
- Returns
- Out: list
- List of result types e.g. ['Q', 'V']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: chan_rt = res.channelResultTypes() # print to console print('Available channel result types:') for rt in chan_rt: print(rt) else: # did not load correctly, print error message to console print(message)
channels
channels ()
Returns a list of all the channels IDs in the results
- Parameters
- -
- Returns
- Out: list
- List of channels e.g. ['Chan_A', 'Chan_B', 'Chan_C']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: chans = res.channels() # print to console print('Channels:') for chan in chans: print(chan) else: # did not load correctly, print error message to console print(message)
channelsDownstream
channelsDownstream ( Node ID )
Returns a list of all the channels downstream of a given node
- Parameters
- Node ID: str
- Name or ID of node e.g. 'Chan_A.1'
- Returns
- Out: list
- List of channels e.g. ['Chan_B']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' dns_chans = res.channelsDownstream(node) # print to console print('Channels downstream of {0}:'.format(node)) for chan in dns_chans: print(chan) else: # did not load correctly, print error message to console print(message)
channelsUpstream
channelsUpstream ( Node ID )
Returns a list of all the channels upstream of a given node
- Parameters
- Node ID: str
- Name or ID of node e.g. 'Chan_A.1'
- Returns
- Out: list
- List of channels e.g. ['Chan_A']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' ups_chans = res.channelsUpstream(node) # print to console print('Channels upstream of {0}:'.format(node)) for chan in ups_chans: print(chan) else: # did not load correctly, print error message to console print(message)
format
format ()
Returns the result format i.e. '2013' or '2016'
- Parameters
- -
- Returns
- Format: str
- Format of results e.g. '2016'
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: format = res.format() # print to console print('Results format: {0}'.format(format) else: # did not load correctly, print error message to console print(message)
getAdverseGradients
getAdverseGradients ()
Returns locations of any adverse water level or energy level (if result type available) gradients in long profile. Note getLongProfileData method must be called prior to calling this method
- Parameters
- -
- Returns
- Adverse water level gradients: tuple
- ( list x data, list y data ) e.g. ([0, 5], [10, 12])
- Adverse energy level gradients: tuple
- ( list x data, list y data ) e.g. ([0, 5], [11, 14])
Example
import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # get long profiles and add to plot chan = 'Chan_A' timestep = 1.0 result_types = ['Bed Level', 'H'] # get both water level and bed level for rt in result_types: err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan) # check for error before plotting if not err_lp: x, y = data ax.plot(x, y, label=rt) else: # error occurred getting long profile data, print error message to console print(mess_lp) # check for adverse gradients adv = res.getAdverseGradients() for i, data in enumerate(adv): x, y = data # get appropriate label # getAdverseGradients() returns 2 datasets: # first dataset adverse water level # second dataset adverse energy level if i == 0: # first dataset label = 'Adverse Water Levels' else: # second dataset label = 'Adverse Energy Levels' # add to plot as points ax.plot(x, y, label=label, marker='o', linestyle='None') # add legend to plot lines, labs = ax.get_legend_handles_labels() ax.legend(lines, labs) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
getLongProfileData
getLongProfileData ( Timestep, Result Type, Channel ID, [optional] 2nd Channel ID )
Returns long profile data from a given channel to another channel. If no second channel is specified will continue until no further channels downstream
- Parameters
- Timestep: float or str
- Output timestep to plot. Can be a value e.g. 1.5 or string e.g. 'max'
- Result Type: str
- Result type e.g. 'H'
- Channel ID: str
- Starting channel for long profile e.g. 'Chan_A'
- 2nd Channel ID: str
- Optional downstream channel ID to stop the long profile at e.g. 'Chan_D'
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Data: tuple
- x data points: list
- data point: float
- y data points: list
- data point: float
- e.g. ([0, 1, 2, 3, 4, 5], [10, 20, 30, 20, 10, 0]
- data point: float
- x data points: list
Example
import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # get long profiles and add to plot chan = 'Chan_A' timestep = 1.0 result_types = ['Bed Level', 'H'] # get both water level and bed level for rt in result_types: err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan) # check for error before plotting if not err_lp: x, y = data ax.plot(x, y, label=rt) else: # error occurred getting long profile data, print error message to console print(mess_lp) # add legend to plot lines, labs = ax.get_legend_handles_labels() ax.legend(lines, labs) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
getLongProfileTimeOfMaximum
getLongProfileTimeOfMaximum ()
Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method
- Parameters
- -
- Returns
- x data: list
- x points for plotting time of max along long profile e.g. [0, 1, 2, 3, 4, 5]
- y data: list
- y points for plotting time of max along long profile e.g. [10, 11, 12, 13, 14, 15]
Example
import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # get long profiles and add to plot chan = 'Chan_A' timestep = 'max' # maximum result along profile result_types = ['Bed Level', 'H'] # get both water level and bed level for rt in result_types: err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan) # check for error before plotting if not err_lp: x, y = data ax.plot(x, y, label=rt) else: # error occurred getting long profile data, print error message to console print(mess_lp) # also plot time of max water level on secondary axis tom_x, tom_y = res.getLongProfileTimeOfMaximum() ax2 = ax.twinx() # initialise secondary axis # add to plot on secondary axis ax2.plot(tom_x, tom_y, label='Time of Maximum', linestyle='--') # combine axis legends and add to plot lines, labs = ax.get_legend_handles_labels() lines2, labs2 = ax2.get_legend_handles_labels() comb_lines = lines + lines2 comb_labs = labs + labs2 ax.legend(comb_lines, comb_labs) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
getPipes
getPipes ()
Returns any pipe or culvert data in the current profile. Note getLongProfileData method must be called prior to calling this method
- Parameters
- -
- Returns
- Pipe list: list
- Vertex list: list
- Vertex coords: tuple
- e.g. [[(0, 0), (0, 1), (1, 1), (1, 0)], [(1, 1), (1, 2), (2, 2), (2, 1)]]
- Vertex coords: tuple
- Vertex list: list
Example
import matplotlib.pyplot as plt # plotting library from matplotlib.patches import Polygon # will add pipes and culverts as polygon import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # get long profiles and add to plot chan = 'Chan_A' timestep = 1.0 result_types = ['Bed Level', 'H'] # get both water level and bed level for rt in result_types: err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan) # check for error before plotting if not err_lp: x, y = data ax.plot(x, y, label=rt) else: # error occurred getting long profile data, print error message to console print(mess_lp) # get pipes and culverts and add to plot pipes = res.getPipes() for pipe in pipes: # loop through all pipes polygon = Polygon(pipe, facecolor='0.9', edgecolor='0.5', label='Culverts and Pipes') ax.add_patch(polygon) # add legend to plot lines, labs = ax.get_legend_handles_labels() # filter duplicate legend items # for example if there is more than one pipe or culvert we only want that to appear once in the legend unique_lines = [] unique_labels = [] for i, label in enumerate(labs): if label not in unique_labels: unique_labels.append(label) unique_lines.append(lines[i]) ax.legend(unique_lines, unique_labels) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
getTimeSeriesData
getTimeSeriesData ( Element, Result Type, [optional] domain )
Returns time series data for the given element (1D node, 1D channel, 2D PO, RL) for a the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')
- Parameters
- Element: str
- Channel, Node, PO, or RL element to get time series data for
- Result Type: str
- Result type e.g. 'H'
- Domain: str
- Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements.
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Data: tuple
- x data points: list
- y data points: list
- e.g. ([0, 1, 2, 3, 4, 5], [10, 20, 30, 20, 10, 0]
Examples
Plotting results for multiple elements on the same graph
import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # get time series data and add to plot elements = ['Chan_A', 'Chan_B', 'Chan_C'] result_type = 'Q' for element in elements: err_ts, mess_ts, data = res.getTimeSeriesData(element, result_type) # check for error before plotting if not err_ts: x, y = data ax.plot(x, y, label=element) else: # error occurred getting time series data, print error message to console print(mess_ts) # add legend to plot lines, labs = ax.get_legend_handles_labels() ax.legend(lines, labs) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
Plotting water level and velocity on the same plot using a secondary axis
import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before continuing if not err: # initialise plot fig, ax = plt.subplots() # initialise secondary axis ax2 = ax.twinx() # get time series data and add to plot elements = ['Chan_A', 'Chan_B', 'Chan_C'] result_types = ['Q', 'V'] for element in elements: for result_type in result_types: err_ts, mess_ts, data = res.getTimeSeriesData(element, result_type) # check for error before plotting if not err_ts: x, y = data label = '{0}: {1}'.format(result_type, element) # plot Q on first axis, V on secondary axis if result_type == 'Q': # first axis ax.plot(x, y, label=label) else: # must be 'V' # secondary axis ax2.plot(x, y, label=label, linestyle='--') else: # error occurred getting time series data, print error message to console print(mess_ts) # combine primary and secondary axis items and add to legend lines, labs = ax.get_legend_handles_labels() lines2, labs2 = ax2.get_legend_handles_labels() lines_comb = lines + lines2 labs_comb = labs + labs2 ax.legend(lines_comb, labs_comb) # show plot fig.show() else: # did not load correctly, print error message to console print(message)
Saving a separate plot for each element as a *.png
import os # library for operating system file and directory manipulation import matplotlib.pyplot as plt # plotting library import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # save directory for figures save_dir = r'C:TUFLOW\results\figures' # check results were loaded successfully before continuing if not err: # get time series data and add to plot elements = ['Chan_A', 'Chan_B', 'Chan_C'] result_type = 'Q' for element in elements: err_ts, mess_ts, data = res.getTimeSeriesData(element, result_type) # check for error before plotting if not err_ts: # initialise plot fig, ax = plt.subplots() x, y = data ax.plot(x, y, label=element) # add legend to plot lines, labs = ax.get_legend_handles_labels() ax.legend(lines, labs) # add axis labels ax.set_xlabel('Time (hrs)') ax.set_ylabel('Flow (m3/s)') # save fig save_name = 'Figure_{0}_{1}.png'.format(element, result_type) save_path = os.path.join(save_dir, save_name) fig.savefig(save_path) else: # error occurred getting time series data, print error message to console print(mess_ts) else: # did not load correctly, print error message to console print(message)
load
load ( Filepath )
Loads result file. File formats are *.tpc for TUFLOW release 2016 and later, or *.info for TUFLOW release 2013
- Parameters
- Filepath: str
- Full path to *.tpc or *.info
- Returns
- Error: bool
- Returns False on success, returns True if an error occurred
- Message: str
- Accompanying error message if an error occurs
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check if an error occurred if err: # print message print(message)
longProfileResultTypes
longProfileResultTypes ()
Returns list of available long profile result types
- Parameters
- -
- Returns
- out: list
- List of available result types for long profile plotting
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: lp_rt = res.longProfileResultTypes() # print to console print('Available long profile result types:') for rt in lp_rt: print(rt) else: # did not load correctly, print error message to console print(message)
maximum
maximum ( Element, Result Type, [optional] Domain )
Returns the maximum result value for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')
- Parameters
- Element: str
- Channel, Node, or RL element to get maximum result for. PO results do not currently support getting maximum value.
- Result Type: str
- Result type e.g. 'H'
- Domain: str
- Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements.
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Maximum float
- Maximum result
Examples
Maximum flow in a channel
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: channel = 'Chan_A' maximum = res.maximum(channel, 'Q') # print to console print('Max flow at {0} is {1} m3/s'.format(channel, maximum) else: # did not load correctly, print error message to console print(message)
Maximum water level at a node
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' maximum = res.maximum(channel, 'H') # print to console print('Max water level at {0} is {1} mRL'.format(node, maximum) else: # did not load correctly, print error message to console print(message)
maximumTimestepChange
maximumTimestepChange ( Element, Result Type, [optional] Domain )
Returns the maximum change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')
- Parameters
- Element: str
- RL element to get maximum change in a single timestep for. Currently RL elements are the only supported type.
- Result Type: str
- Result type e.g. 'H'
- Domain: str
- Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements.
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Maximum float
- Maximum value change in any given timestep
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: loc = 'Reporting Location 1' tsMaximum = res.maximumTimestepChange(channel, 'Q') # print to console print('Max flow change in any given timestep at {0} is {1} m3/s'.format(loc, tsMaximum) else: # did not load correctly, print error message to console print(message)
name
name ()
Returns the name of the result
- Parameters
- -
- Returns
- Name: str
- Name of results
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: name = res.name() # print to console print('Results from {0} loaded successfully.format(name)) else: # did not load correctly, print error message to console print(message)
nodeCount
nodeCount ()
Returns the total number of nodes in the results
- Parameters
- -
- Returns
- Count: int
- Number of nodes
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node_count = res.nodeCount() # print to console print('{0} nodes in results.format(node_count)) else: # did not load correctly, print error message to console print(message)
nodeDownstream
nodeDownstream ( Channel ID )
Returns the name of the downstream node of a given channel
- Parameters
- Channel ID: str
- Name or ID of channel
- Returns
- Node ID: str
- Name or ID of downstream node
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: channel = 'Chan_A' dns_node = res.nodeDownstream(channel) # print to console print('Downstream node of channel {0} is {1}'.format(channel, dns_node)) else: # did not load correctly, print error message to console print(message)
nodeResultTypes
nodeResultTypes ()
Returns a list of all the available result types for nodes
- Parameters
- -
- Returns
- Out: list
- List of available result types for nodes e.g. ['H', 'E']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: result_types = res.nodeResultTypes() # print to console print('Available result types for nodes are:) for result_type in result_types: print(result_type) else: # did not load correctly, print error message to console print(message)
nodes
nodes ()
Returns a list of all the node IDs in the results
- Parameters
- -
- Returns
- Out: list
- List of all nodes names in results e.g. ['Chan_A.1', 'Chan_A.2', 'Chan_B.2', 'Chan_C.2'...]
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: nodes = res.nodes() # print to console print('Nodes:) for node in nodes: print(node) else: # did not load correctly, print error message to console print(message)
nodeUpstream
nodeUpstream ( Channel ID )
Returns the name of the upstream node of a given channel
- Parameters
- Channel ID: str
- Name or ID of channel
- Returns
- Node ID: str
- Name or ID of upstream node
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: channel = 'Chan_A' ups_node = res.nodeUpstream(channel) # print to console print('Upstream node of channel {0} is {1}'.format(channel, ups_node)) else: # did not load correctly, print error message to console print(message)
poNames
poNames ()
Returns a list of all the available Plot Output names
- Parameters
- -
- Returns
- Out: list
- List of all PO names in results e.g. ['Loc_1', 'Loc_2', 'Loc_3']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: po_names = res.poNames() # print to console print('PO Names:) for po_name in po_names: print(po_name) else: # did not load correctly, print error message to console print(message)
poResultTypes
poResultTypes ()
Returns a list of all the available Plot Output result types
- Parameters
- -
- Returns
- Out: list
- List of available result types for Plot Outputs e.g. ['Q', 'H', 'V']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: result_types = res.poResultTypes() # print to console print('Available result types for Plot Outputs are:) for result_type in result_types: print(result_type) else: # did not load correctly, print error message to console print(message)
rlCount
rlCount ()
Returns the total number of Reporting Locations (of all geometry type) in the results
- Parameters
- -
- Returns
- Count: int
- Number of RL objects
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: rl_count = res.rlCount() # print to console print('{0} RL objects in results.format(node_count)) else: # did not load correctly, print error message to console print(message)
rlLineCount
rlLineCount ()
Returns the total number of line Reporting Locations in the results
- Parameters
- -
- Returns
- Count: int
- Number of RL Line objects
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: rl_line_count = res.rlLineCount() # print to console print('{0} RL Line objects in results.format(node_line_count)) else: # did not load correctly, print error message to console print(message)
rlNames
rlNames ()
Returns a list of all the Reporting Location names
- Parameters
- -
- Returns
- Out: list
- List of all RL names in results e.g. ['Reporting_Loc_1', 'Reporting_Loc_2', 'Reporting_Loc_3']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: rl_names = res.rlNames() # print to console print('RL Names:) for rl_name in rl_names: print(rl_name) else: # did not load correctly, print error message to console print(message)
rlPointCount
rlPointCount ()
Returns the total number of point Reporting Locations in the results
- Parameters
- -
- Returns
- Count: int
- Number of RL Point objects
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: rl_point_count = res.rlPointCount() # print to console print('{0} RL Point objects in results.format(node_point_count)) else: # did not load correctly, print error message to console print(message)
rlRegionCount
rlRegionCount ()
Returns the total number of region Reporting Locations in the results
- Parameters
- -
- Returns
- Count: int
- Number of RL Region objects
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: rl_region_count = res.rlRegionCount() # print to console print('{0} RL Region objects in results.format(node_region_count)) else: # did not load correctly, print error message to console print(message)
rlResultTypes
rlResultTypes ()
Returns a list of all the available Reporting Location result types
- Parameters
- -
- Returns
- Out: list
- List of available result types for Reporting Locations e.g. ['Q', 'H', 'Vol']
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: result_types = res.rlResultTypes() # print to console print('Available result types for Reporting Locations are:) for result_type in result_types: print(result_type) else: # did not load correctly, print error message to console print(message)
source
source ()
Returns the full file path to the source result file (*.tpc or *.info)
- Parameters
- -
- Returns
- Source: str
- Full path to result file
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: source = res.source() # print to console print('Successfully loaded result from {0}.format(source)) else: # did not load correctly, print error message to console print(message)
timeOfMaximum
timeOfMaximum ( Element, Result Type, [optional] Domain )
Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')
- Parameters
- Element: str
- Channel, Node, or RL element to get maximum result for. PO results do not currently support getting time of maximum.
- Result Type: str
- Result type e.g. 'H'
- Domain: str
- Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements.
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Time of Maximum: float
- Time of maximum
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: node = 'Chan_A.1' tom = res.timeOfMaximum(channel, 'H') # print to console print('Time of max water level at {0} is {1} hrs'.format(channel, tom) else: # did not load correctly, print error message to console print(message)
timeOfMaximumTimestepChange
timeOfMaximumTimestepChange ( Element, Result Type, [optional] Domain )
Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')
- Parameters
- Element: str
- RL element to get time of maximum change in a single timestep for. Currently RL elements are the only supported type.
- Result Type: str
- Result type e.g. 'H'
- Domain: str
- Optional input to specify which domain the Element belongs in. If left as default (None) and there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements.
- Returns
- Error: bool
- Returns False on success, True when an error occurred
- Message: str
- Accompanying error message if an error occurred
- Maximum float
- Time of maximum value change
Example
import pytuflow # Initialise result class res = pytuflow.ResData() # load .tpc result file path = r'C:\TUFLOW\results\M04_5m_001.tpc' err, message = res.load(path) # check results were loaded successfully before calling function if not err: loc = 'Reporting Location 1' tom_ts = res.timeOfMaximumTimestepChange(channel, 'Q') # print to console print('Time of max flow change in any given timestep at {0} is {1} hrs'.format(loc, tom_ts) else: # did not load correctly, print error message to console print(message)