Difference between revisions of "Python Library TUFLOW Results"

From Tuflow
Jump to navigation Jump to search
(Created page with "=Introduction= For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions: * Combines the 1D...")
 
Line 1: Line 1:
 +
<font size=250%; color="red">Currently Under Construction</font>
 +
<br><br>
 
=Introduction=
 
=Introduction=
 
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
 
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
Line 29: Line 31:
 
* error (logical) set to True if an error has been encountered.
 
* error (logical) set to True if an error has been encountered.
 
* message (string), if an error has occurred the message string will be populated with an error message.
 
* message (string), if an error has occurred the message string will be populated with an error message.
−
==Get Timeseries==
+
==Get Time-series==
−
Timeseries at a 1D, 2D or reporting location can be returned using the following syntax:
+
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
 
<pre>
 
<pre>
 
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
 
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
Line 40: Line 42:
 
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point.  If unsure or unknown this can be set to a dummy string such as 'dummy'.</li>
 
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point.  If unsure or unknown this can be set to a dummy string such as 'dummy'.</li>
 
The return arguments are:
 
The return arguments are:
−
<li>found (logical) ????
+
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
 +
<li>results (numpy array) - The return array for the requested data.</li>
 +
<li>message (string) - If the data is not found, this message string contains information.</li>
 +
For example:
 +
<pre>
 +
found, results, message = res.getTS('ds3','1D','Q','L')
 +
</pre>
 +
Will return flow (Q) data for the 1D channel with ID ds3.  The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
 +
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>.  See the examples below.
 +
==Long Profile Functions==
 +
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned.  If two channels are specified, long profile data will only be returned for the channels between the specified channels.
  
 +
===Get Long Profile Connectivity (LP_getConnectivity)===
 +
This determines and stores the connectivity of the specified channels.  This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
 +
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
 +
The inputs to this are:
 +
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
 +
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
 +
The return arguments are:
 +
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
 +
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
 +
<pre>
 +
error, message = res.LP_getConnectivity('FC01.40',None)
 +
</pre>
 +
Determines all the channels downstream of '''FC01.40'''.
 +
<pre>
 +
error, message = res.LP_getConnectivity('FC01.40','ds3')
 +
</pre>
 +
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
 +
===Get Long Profile Static Data (LP_getStaticData)===
 +
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps.  This includes:
 +
* distance information
 +
* maximum data
 +
* bed levels
 +
The syntax is:
 +
<pre>error, message = res.LP_getStaticData()</pre>
 +
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
 +
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
 +
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
 +
===Get Long Profile Data (LP_getData)===
 +
This function gets data at a specific time.  If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated.  The syntax is:
 +
<pre>
 +
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
 +
</pre>
 +
The inputs to this are:
 +
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
 +
<li>Time - The time in hours to get the data for.</li>
 +
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
 +
The return arguments are:
 +
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
 +
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
 +
<pre>
 +
error, message = res.LP_getData('Head',1,0.01)
 +
</pre>
 +
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
 +
=Examples=
 +
<pre>
 +
import os #operating system functions
 +
import sys #system functions
 +
import matplotlib.pyplot as plt
 +
import TUFLOW_results2016
  
−
=Examples=
+
res = TUFLOW_results2015.ResData()
 +
error, message = res.Load(input_res)
 +
if error:
 +
    print(message)
 +
    sys.exit()
 +
print('loaded')
 +
</pre>
  
 
=Other Versions=
 
=Other Versions=
 
An older version that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results for this version).  This is currently undocumented, however, if you would like this please contact support@tuflow.com.
 
An older version that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results for this version).  This is currently undocumented, however, if you would like this please contact support@tuflow.com.

Revision as of 20:44, 14 March 2016

Currently Under Construction

Introduction

For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:

  • Combines the 1D results, 2D plot outputs and new reporting location data
  • The outputs are stored in a separate Plot folder in the TUFLOW results directory
  • .tpc (TUFLOW Plot Control file links to data in csv and gis folders
  • Has additional Node and Channel information files contain connectivity information

This is the default approach for the 2016 version but can be modified with the TUFLOW command "Output Approach == Pre 2016" (refer to the manual for more information on this command.
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib.

Dependencies

The TUFLOW results library calls a number of python libraries, these are:

  • csv
  • numpy
  • os
  • sys

Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation http://www.numpy.org/.

Compatible Python Versions

The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.

Functionality

Import

This library is imported with the typical python syntax.

import TUFLOW_results2016

Initialise Results (ResData)

An instance of the results can be initialised with the following syntax: 

res = TUFLOW_results2016.ResData()

Load Results

Results are loaded in with the syntax below. 

error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')

The two return arguments are:

  • error (logical) set to True if an error has been encountered.
  • message (string), if an error has occurred the message string will be populated with an error message.

Get Time-series

Time-series at a 1D, 2D or reporting location can be returned using the following syntax: 

found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)

The inputs to this are:

  • ID - The ID of the 1D, 2D or reporting location feature.
  • Domain - The domain to return the results for, this will be one of 1D, 2D or RL (for reporting location data)
  • Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!
  • Geometry - The GIS geometry of the object, L for line, or P for point. If unsure or unknown this can be set to a dummy string such as 'dummy'.

    • The return arguments are:

  • found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.
  • results (numpy array) - The return array for the requested data.
  • message (string) - If the data is not found, this message string contains information.

    • For example: 

    found, results, message = res.getTS('ds3','1D','Q','L')

    Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects. Note As the time data typically does not change (this is not a return argument) but can be accessed by the res.times. See the examples below.

    Long Profile Functions

    When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

    Get Long Profile Connectivity (LP_getConnectivity)

    This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is: 

    error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)

    The inputs to this are:

  • Upstream Channel ID - The ID of the Upstream 1D channel.
  • Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to None.

    • The return arguments are:

  • error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).
  • message (string) - If an error is returned this message string contains information on the issue.
    • error, message = res.LP_getConnectivity('FC01.40',None)

    Determines all the channels downstream of FC01.40. 

    error, message = res.LP_getConnectivity('FC01.40','ds3')

    Determines the channels between FC01.40 and ds3, an error will be returned if these channels are not connected.

    Get Long Profile Static Data (LP_getStaticData)

    Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:

    • distance information
    • maximum data
    • bed levels

    The syntax is: 

    error, message = res.LP_getStaticData()

    There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:

  • error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).
  • message (string) - If an error is returned this message string contains information on the issue.

    • Get Long Profile Data (LP_getData)

    This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the LP_getData will need to be repeated. The syntax is: 

    error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)

    The inputs to this are:

  • Data type - The results data to return, this is one of 'Head' or 'Energy'
  • Time - The time in hours to get the data for.
  • Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.

    • The return arguments are:

  • error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).
  • message (string) - If an error is returned this message string contains information on the issue.
    • error, message = res.LP_getData('Head',1,0.01)

    Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.

    Examples

    import os						#operating system functions
import sys						#system functions
import matplotlib.pyplot as plt
import TUFLOW_results2016

res = TUFLOW_results2015.ResData()
error, message = res.Load(input_res)
if error:
    print(message)
    sys.exit()
print('loaded')

    Other Versions

    An older version that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results for this version). This is currently undocumented, however, if you would like this please contact support@tuflow.com.

    Retrieved from "https://wiki.tuflow.com/w/index.php?title=Python_Library_TUFLOW_Results&oldid=9795"