PyTuflow: Difference between revisions
Content deleted Content added
Ellis Symons (talk | contribs) No edit summary |
|||
| (51 intermediate revisions by 2 users not shown) | |||
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=
Line 6 ⟶ 24:
<pre>
import pytuflow
res =
# or
res =
</pre>
Line 66 ⟶ 84:
|''tuple'' Profile Data ( ''list'' x values, ''list'' y values )
|-
|rowspan='2'|<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
|''list'' x values
Line 122 ⟶ 140:
|''str'' Node ID
|-
|rowspan='1'|<b>[[#nodeResultTypes|nodeResultTypes]] (
|rowspan='1'|Returns a list of all the available result types for nodes
|''list'' Result Types
|-
|rowspan='1'|<b>[[#nodes|nodes]] ()</b>
|rowspan='1'|Returns a list of all the node IDs in the results
|''list'' Node IDs
|-
|rowspan='1'|<b>[[#nodeUpstream|nodeUpstream]] (</b> ''str'' Channel ID <b>)</b>
|rowspan='1'|Returns the name of the upstream node of a given channel
|''str'' Node ID
|-
|rowspan='1'|<b>[[#poNames|poNames]] ()</b>
|rowspan='1'|Returns a list of all the available Plot Output names
|''list'' PO ID
|-
|rowspan='1'|<b>[[#poResultTypes|poResultTypes]] ()</b>
|rowspan='1'|Returns a list of all the available Plot Output result types
|''list'' Result Types
|-
|rowspan='1'|<b>[[#rlCount|rlCount]] ()</b>
|rowspan='1'|Returns the total number of Reporting Locations (of all geometry type) in the results
|''int'' Count
|-
|rowspan='1'|<b>[[#rlLineCount|rlLineCount]] ()</b>
|rowspan='1'|Returns the total number of line Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>[[#rlNames|rlNames]] ()</b>
|rowspan='1'|Returns a list of all the Reporting Location names
|''list'' RL ID
|-
|rowspan='1'|<b>[[#rlPointCount|rlPointCount]] ()</b>
|rowspan='1'|Returns the total number of point Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>[[#rlRegionCount|rlRegionCount]] ()</b>
|rowspan='1'|Returns the total number of region Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>[[#rlResultTypes|rlResultTypes]] ()</b>
|rowspan='1'|Returns a list of all the available Reporting Location result types
|''list'' Result Types
|-
|rowspan='1'|<b>[[#source|source]] ()</b>
|rowspan='1'|Returns the full file path to the source result file (*.tpc or *.info)
|''str'' Path
|-
|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')
|''bool'' Error
Line 178 ⟶ 196:
|''float'' Time (hrs)
|-
|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')
|''bool'' Error
Line 200 ⟶ 218:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 219 ⟶ 237:
print(message)
</pre>
==channelConnections==
Line 231 ⟶ 250:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 264 ⟶ 283:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 294 ⟶ 313:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 325 ⟶ 344:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 357 ⟶ 376:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 390 ⟶ 409:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 422 ⟶ 441:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 454 ⟶ 473:
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 537 ⟶ 556:
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 577 ⟶ 596:
</pre>
==getLongProfileTimeOfMaximum==
<b>
Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method<br>
;Parameters:
Line 590 ⟶ 609:
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 654 ⟶ 673:
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 =
# load .tpc result file
Line 732 ⟶ 751:
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 765 ⟶ 784:
# show plot
else:
# did not load correctly, print error message to console
Line 773 ⟶ 792:
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 829 ⟶ 848:
import os # library for operating system file and directory manipulation
import matplotlib.pyplot as plt # plotting library
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 890 ⟶ 909:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 915 ⟶ 934:
'''Example'''
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 956 ⟶ 975:
Maximum flow in a channel
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 977 ⟶ 996:
Maximum water level at a node
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,016 ⟶ 1,035:
'''Example'''<br>
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,046 ⟶ 1,065:
'''Example'''<br>
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,075 ⟶ 1,094:
'''Example'''<br>
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,105 ⟶ 1,124:
'''Example'''<br>
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,126 ⟶ 1,145:
==nodeResultTypes==
<b>nodeResultTypes (
Returns a list of all the available result types for nodes<br>
;Parameters:
Line 1,135 ⟶ 1,154:
'''Example'''<br>
<pre>
import pytuflow
# Initialise result class
res =
# load .tpc result file
Line 1,151 ⟶ 1,170:
for result_type in result_types:
print(result_type)
else:
# did not load correctly, print error message to console
print(message)
</pre>
==nodes==
<b>nodes ()</b><br>
Returns a list of all the node IDs in the results<br>
;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'''<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:
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)
</pre>
==nodeUpstream==
<b>nodeUpstream (</b> Channel ID <b>)</b><br>
Returns the name of the upstream node of a given channel<br>
;Parameters:
: '''Channel ID:''' ''str''
:: Name or ID of channel
;Returns:
: '''Node ID:''' ''str''
:: Name or ID of upstream node
'''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:
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)
</pre>
==poNames==
<b>poNames ()</b><br>
Returns a list of all the available Plot Output names <br>
;Parameters:
: -
;Returns:
: '''Out:''' ''list''
:: List of all PO names in results e.g. ['Loc_1', 'Loc_2', '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:
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)
</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:
# did not load correctly, print error message to console
| |||