PyTuflow: Difference between revisions

From Tuflow
Jump to navigation Jump to search
Browse history interactively
← Older edit
Content deleted Content added
VisualWikitext
No edit summary
 
(91 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=Introduction=
=Class: ResData=
PyTUFLOW is a library that acts as an API for your TUFLOW model. It allows easy interaction with the model results, contains a number of useful utilities for building TUFLOW models, and contains some useful parsers for files within the TUFLOW eco-system.


==Latest Documentation==
Class for TUFLOW time series results.
The PyTUFLOW documentation has moved to a new location: <u>[https://docs.tuflow.com/pytuflow/ PyTUFLOW Documentation]</u>.


The previous PyTUFLOW API has been deprecated and the wiki documentation has been archived. However, if needed, the archived documentation can still be accessed via the link in the section below.
Initialised as an empty object, or with results with a *.tpc in TUFLOW 2016 release and later or *.info in TUFLOW 2013 release.


==Archive Documentation==
<pre>
Guidance for earlier version of PyTuflow can be accessed via the following link: <u>[[PyTuflow_Archive| PyTuflow_Archive]]</u>.
import pytuflow as tu


<br>

{{Tips Navigation
res = tu.ResData() # initialising as an empty object
|uplink=[[Main_Page| Back to Wiki Main Page]]
# or
}}
res = tu.ResData('M01_5m_001.tpc') # initialising with results
</pre>

==Methods==
{|class="wikitable" style="text-align: left;"
|! style="background-color:#005581; font-weight:bold; color:white" width=30%| Method
|! style="background-color:#005581; font-weight:bold; color:white;" width=20%|Description
|! style="background-color:#005581; font-weight:bold; color:white;" width=25%|Returns
|-
|rowspan='1' style='text-align: left'|<b>[[#channelConnectionCount|channelConnectionCount]] (</b> ''str'' Node ID <b>)</b>
|rowspan='1'|Returns the number of channels connected to a given node
|''int'' Count
|-
|rowspan='1'|<b>[[#channelConnections|channelConnections]] (</b> ''str'' Node ID <b>)</b>
|rowspan='1'|Returns a list of the channels connected to a given node
|''list'' Channel IDs
|-
|rowspan='1'|<b>[[#channelCount|channelCount]] ()</b>
|rowspan='1'|Returns the total number of channels in results
|''int'' Count
|-
|rowspan='1'|<b>[[#channelResultTypes|channelResultTypes]] ()</b>
|rowspan='1'|Returns a list of all the available result types for channels
|list of Result Types
|-
|rowspan='1'|<b>[[#channels|channels]] ()</b>
|rowspan='1'|Returns a list of all the channels IDs in the results
|''list'' Channel IDs
|-
|rowspan='1'|<b>[[#channelsDownstream|channelsDownstream]] (</b> ''str'' Node ID <b>)</b>
|rowspan='1'|Returns a list of all the channels downstream of a given node
|''list'' Channel IDs
|-
|rowspan='1'|<b>[[#channelsUpstream|channelsUpstream]] (</b> ''str'' Node ID <b>)</b>
|rowspan='1'|Returns a list of all the channels upstream of a given node
|''list'' Channel IDs
|-
|rowspan='1'|<b>[[#format|format]] ()</b>
|rowspan='1'|Returns the result format i.e. '2013' or '2016'
|''str'' Format
|-
|rowspan='2'|<b>[[#getAdverseGradients|getAdverseGradients]] ()</b>
|rowspan='2'|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 )
|-
|rowspan='3'|<b>[[#getLongProfileData|getLongProfileData]] (</b> ''float'' Timestep, ''str'' Result Type, ''str'' Channel ID, [optional] ''str'' 2nd Channel ID <b>)</b>
|rowspan='3'|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 )
|-
|rowspan='2'|<b>[[#getLongProfileTimeOfMax|getLongProfileTimeOfMax]] ()</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
|-
|''list'' y values
|-
|rowspan='1'|<b>getPipes ()</b>
|rowspan='1'|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 ) ] ]
|-
|rowspan='3'|<b>getTimeSeriesData (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' domain <b>)</b>
|rowspan='3'|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 )
|-
|rowspan='2'|<b>load (</b> ''str'' filepath <b>)</b>
|rowspan='2'|Loads result file. File formats are *.tpc for TUFLOW release 2016 and later, or *.info for TUFLOW release 2013
|''bool'' Error
|-
|''str'' Message
|-
|rowspan='1'|<b>longProfileResultTypes ()</b>
|rowspan='1'|Returns list of available long profile result types
|''list'' Result Types
|-
|rowspan='3'|<b>maximum (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b>
|rowspan='3'|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
|-
|rowspan='3'|<b>maximumTimestepChange (</b> ''str'' Element, ''str'' Result Type, [optional] ''str'' Domain <b>)</b>
|rowspan='3'|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
|-
|rowspan='1'|<b>name ()</b>
|rowspan='1'|Returns the name of the result
|''str'' Name
|-
|rowspan='1'|<b>nodeCount ()</b>
|rowspan='1'|Returns the total number of nodes in the results
|''int'' Count
|-
|rowspan='1'|<b>nodeDownstream (</b> ''str'' Channel ID <b>)</b>
|rowspan='1'|Returns the name of the downstream node of a given channel
|''str'' Node ID
|-
|rowspan='1'|<b>nodeResultTypes (</b> ''str'' Channel ID <b>)</b>
|rowspan='1'|Returns a list of all the available result types for nodes
|''list'' Result Types
|-
|rowspan='1'|<b>nodes ()</b>
|rowspan='1'|Returns a list of all the node IDs in the results
|''list'' Node IDs
|-
|rowspan='1'|<b>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 ()</b>
|rowspan='1'|Returns a list of all the available Plot Output names
|''list'' PO ID
|-
|rowspan='1'|<b>poResultTypes ()</b>
|rowspan='1'|Returns a list of all the available Plot Output result types
|''list'' Result Types
|-
|rowspan='1'|<b>rlCount ()</b>
|rowspan='1'|Returns the total number of Reporting Locations (of all geometry type) in the results
|''int'' Count
|-
|rowspan='1'|<b>rlLineCount ()</b>
|rowspan='1'|Returns the total number of line Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>rlNames ()</b>
|rowspan='1'|Returns a list of all the Reporting Location names
|''list'' RL ID
|-
|rowspan='1'|<b>rlPointCount ()</b>
|rowspan='1'|Returns the total number of point Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>rlRegionCount ()</b>
|rowspan='1'|Returns the total number of region Reporting Locations in the results
|''int'' Count
|-
|rowspan='1'|<b>rlResultTypes ()</b>
|rowspan='1'|Returns a list of all the available Reporting Location result types
|''list'' Result Types
|-
|rowspan='1'|<b>source ()</b>
|rowspan='1'|Returns the full file path to the source result file (*.tpc or *.info)
|''str'' Path
|-
|rowspan='3'|<b>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
|-
|''str'' Message
|-
|''float'' Time (hrs)
|-
|rowspan='3'|<b>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
|-
|''str'' Message
|-
|''float'' Time (hrs)
|-
|}

==channelConnectionCount==

<b>channelConnectionCount (</b> Node ID <b>)</b><br>
Returns the number of channels connected to a given node<br>
;Parameters:
: '''Node ID:''' ''str''
:: Name or ID of node e.g. 'Chan_A.1'
;Returns:
: '''Count:''' ''int''
:: Number of connected channels
'''Example'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>
==channelConnections==

<b>channelConnections (</b> Node ID <b>)</b><br>
Returns a list of the channels connected to a given node<br>
;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'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==channelCount==

<b>channelCount ()</b><br>
Returns the total number of channels in results<br>
;Parameters:
: -
;Returns:
: '''Count:''' ''int''
:: Number of channels
'''Example'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==channelResultTypes==

<b>channelResultTypes ()</b><br>
Returns a list of all the available result types for channels<br>
;Parameters:
: -
;Returns:
: '''Out:''' ''list''
:: List of result types e.g. ['Q', 'V']
'''Example'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==channels==
<b>channels ()</b><br>
Returns a list of all the channels IDs in the results<br>
;Parameters:
: -
;Returns:
: '''Out:''' ''list''
:: List of channels e.g. ['Chan_A', 'Chan_B', 'Chan_C']
'''Example'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==channelsDownstream==
<b>channelsDownstream (</b> Node ID <b>)</b><br>
Returns a list of all the channels downstream of a given node<br>
;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'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==channelsUpstream==
<b>channelsUpstream (</b> Node ID <b>)</b><br>
Returns a list of all the channels upstream of a given node<br>
;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'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==format==
<b>format ()</b><br>
Returns the result format i.e. '2013' or '2016'<br>
;Parameters:
: -
;Returns:
: '''Format:''' ''str''
:: Format of results e.g. '2016'
'''Example'''
<pre>
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==getAdverseGradients==
<b>getAdverseGradients ()</b><br>
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<br>
;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'''
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==getLongProfileData==
<b>getLongProfileData (</b> Timestep, Result Type, Channel ID, [optional] 2nd Channel ID <b>)</b><br>
Returns long profile data from a given channel to another channel. If no second channel is specified will continue until no further channels downstream<br>
;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''
:: ''list'' x data points, ''list'' y data points e.g. ([0, 1, 2], [10, 20, 30])
'''Example'''
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow as tu

# Initialise result class
res = tu.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)
</pre>

==getLongProfileTimeOfMax==
<b>getLongProfileTimeOfMax ()</b><br>
Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method<b>
;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'''
<pre>
import matplotlib.pyplot as plt # plotting library
import pytuflow as tu

# Initialise result class
res = tu.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 to secondary axis
ax2.plot(x, 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)
</pre>

Latest revision as of 12:55, 19 December 2025

Introduction

PyTUFLOW is a library that acts as an API for your TUFLOW model. It allows easy interaction with the model results, contains a number of useful utilities for building TUFLOW models, and contains some useful parsers for files within the TUFLOW eco-system.

Latest Documentation

The PyTUFLOW documentation has moved to a new location: PyTUFLOW Documentation.

The previous PyTUFLOW API has been deprecated and the wiki documentation has been archived. However, if needed, the archived documentation can still be accessed via the link in the section below.

Archive Documentation

Guidance for earlier version of PyTuflow can be accessed via the following link: PyTuflow_Archive.


Up
Back to Wiki Main Page
Retrieved from "https://wiki.tuflow.com/w/index.php?title=PyTuflow&oldid=45265"