CALCULATE DRAINDOWN

Summary

Calculate Draindown calculates drain volumes and maximum gravity drain rates for the release points you generated using the Create Release Points tool. In calculating drain volumes and gravity drain rates, the tool considers the elevation profile of the centerline route, pipeline shutdown time, product properties, and the placement of mainline block valves and check valves. For each release point, in addition to calculating drain volume and maximum gravity drain rate, the tool calculates the gravity drain rate for each local elevation maxima between the bounding highest upstream and downstream maximum elevation values (that define the extent of gravity drain), and also determines which portions of the line are drained, or remain filled, after gravity drain down is complete.

To learn more about the Liquids HCA Tool in general, please see Liquids HCA Tool Frequently Asked Questions.

To learn more about the structure of the Liquids HCA Tool project geodatabase, please see Liquids HCA Tool Data Dictionary.

Illustration

To learn more, please see How Calculate Draindown works.

Usage

Input Project Database – This is the project file geodatabase you created with the Initialize Database tool. The Liquids HCA Tool project geodatabase is intended to store all data inputs and outputs generated during the analysis process.
Input Release Point Features – Your input release point features are sourced from the project geodatabase and were created when you ran the Create Release Points tool. The tool looks for the OSPOINTM feature class in your specified project geodatabase and automatically sets this parameter to that value if the OSPOINTM feature class is present in your project geodatabase. If you specified a different name for your release point features when you ran Create Release Points, you’ll need to select that feature class here.

Calculate Draindown modifies your release points by populating the following data columns:

- DD_ELEV – The elevation of the release point, as calculated by Calculate Draindown. The tool uses a generalization algorithm to simplify the elevation profile. Accordingly, the elevation used by Calculation Draindown may vary slightly from the elevation extracted from the digital elevation layer used by Create Release Points.
- DRAIN_CALC – A flag field that indicates whether a release point is ‘significant’ in terms of the generalization algorithm. A value of ‘Yes’ indicates the release point is significant.
- DRAIN_VOL – This field stores the total drain volume for the release point, which consists of the pumping volume plus the gravity drain out volume.
- DRAIN_RATE – This field stores the maximum gravity drain rate experienced by the release point.
- H_LOOP_ID – If your centerline routes are networked (connected to each other via laterals, loops, etc.), it is quite possible that your release point is receiving product from other centerline route segments during the gravity drain down process. If this occurs, this field stores the edge ID of the network edge with the highest elevation location of any connected edge in the downstream (higher measure, typically) direction. (Edge information is stored in the EDGES table in the project geodatabase.) If the centerline route on which your release point is located is not connected to any other centerline routes, this field is assigned a value of ‘None.’
- DN_MAX_ELV – This field stores the highest elevation value on the downstream side of the release point (within the current valve section) on the underlying centerline route and thus delineates the location of the downstream boundary of the drain down extent for the release point on the underlying centerline route. Note that when the underlying centerline route is networked with other routes, the actual highest elevation point downstream of the release point may be on the network edge indicated by the value of H_LOOP_ID.
- DNMAXELV_M – This field stores the measure value of highest elevation value on the downstream side of release point (within the current valve section) on the underlying centerline route.
- DRN_VOL_DN – This field stores the gravity drain volume contributed to the release point from downstream side of the release point.
- N_DRNVOLDN – If the centerline route on which your release point falls is networked with other centerline routes, this field stores the network gravity drain down volume contribution from the downstream side of the release point. This value is zero if the centerline route on which your release point is located is not connected to any other centerline route.
- L_LOOP_ID – This field stores the edge ID of the network edge with the highest elevation location of any connected edge in the upstream (lower measure, typically) direction. If the centerline route on which your release point is located is not connected to any other centerline routes, this field is assigned a value of ‘None.’
- UP_MAX_ELV – This field stores the highest elevation value on the upstream side of the release point (within the current valve section) on the underlying centerline route and thus delineates the location of the upstream boundary of the drain down extent for the release point on the underlying centerline route. Note that when the underlying centerline route is networked with other routes, the actual highest elevation point upstream of the release point may be on the network edge indicated by the value of L_LOOP_ID.
- UPMAXELV_M – This field stores the measure value of the highest elevation value on the upstream side of the release point (within the current valve section) on the underlying centerline route.
- DRN_VOL_UP – This field stores the gravity drain volume contributed to the release point from upstream side of the release point.
- N_DRNVOLUP – If the centerline route on which your release point falls is networked with other centerline routes, this field stores the network gravity drain down volume contribution from the upstream side of the release point. This value is zero if the centerline route on which your release point is located is not connected to any other centerline route.

Input Route Features – Your input route features are sourced from the centerline route features you imported into the project geodatabase using the Initialize Database tool. The tool looks for the ROUTES feature class in your specified project geodatabase and automatically sets this parameter to that value if the ROUTES feature class is present in your project geodatabase. If you specified a different name for your copied centerline route features when you ran Initialize Database, you’ll need to select that feature class here. Note that the input route features must include populated ORIGINAL_ROUTE_ID, ROUTE_ID, FROM_MEAS, and TO_MEAS columns.
Input Global Inputs Table – The global inputs table that you populated using either the Enter Global Input Data tool or the Import Global Input Data tool is sourced from your specified project geodatabase. The tool looks for the GLOBAL_INPUTS table in your specified project geodatabase and automatically sets this parameter to that value if the GLOBAL_INPUTS table is present in your project geodatabase. If you specified a different name for your global inputs table when you ran Enter Global Input Data or Import Global Input Data, you’ll need to select that table here. The global inputs table provides attribution used by other tools in the Liquids HCA Analysis workflow. Calculate Draindown utilizes the following data columns from the global inputs table:
- ROUTE_ID – The field that uniquely identifies your centerline route features. ROUTE_ID values are copied to your output release point features and are used to look up the appropriate data record for the route in the global inputs table.
- XY_TOL – When the tool performs its calculations, it uses the release points to establish the shape of the centerline route in X and Y coordinates. Often, there are more points than needed to sufficiently define the shape of the centerline route in X and Y. The XY_TOL field value specifies the X/Y tolerance that is used to depopulate the X/Y profile (shape) of the route. X and Y values for release points that are significant in X and Y are used directly in the drain down calculation; X and Y values for non-significant points are interpolated.
- Z_TOL – When the tool performs its calculations, it uses the release points to establish the elevation profile for the centerline route. Often, there are more points than needed to establish a sufficiently accurate elevation profile. The Z_TOL field value specifies the elevation tolerance that is used to depopulate the elevation profile. Z values for release points that are significant in Z are used directly in the drain down calculation; Z values for non-significant points are interpolated.
- FLOWQSTN – This field stores product flow direction, which is used to delineate upstream vs. downstream flow in the pipeline in the drain down. If the product flow is in the same direction as increasing measure on the centerline route, the value is 1; otherwise, the value is 0.
- P_SD_TIME – This field stores the total time (in minutes) to shut down the pipeline, including pumps and remotely operated valves (ROVs). It is used in the drain down calculation to calculate the pumping volume for a release point.
- FLOW_RATE – This field stores the pumping flow rate (in bbl/hr) for the pipeline. It is used in the drain down calculation to calculate the pumping volume for a release point.
- PROD_DNSTY – This field stores the product density (in g/cc). It is used in the drain down calculation to calculate gravity drain rates for a release point.
- P_VAPOR – This field stores the pipeline product vapor pressure at the pipeline operating temperature (in psi). It is used to help determine which portions of the line are filled and unfilled after gravity drain down. When gravity drain down is complete, the evacuated portions of the line not open to air are subject to the product vapor pressure. For the first filled segment open to air, the product column elevation rises higher than the elevation of the release point due to atmospheric pressure acting on the product column in the pipe. This difference in elevation may be expressed mathematically as:

Δh = (atmospheric pressure – product vapor pressure) / (product density * g)

Where: Δh is the difference in elevation; and, g is the acceleration of gravity.

- C5_VOL_PCT – This field stores the volume percentage of the product that consists of C₅₊ components (pentanes and higher). It is used in the drain down calculation to calculate gravity drain volume for a release point. The C₅₊fraction of the product is assumed to remain in a liquid state during gravity drain down. This is a conservative simplification of the actual physics of a pipeline rupture. Depending on conditions, a significant portion of the C₅₊fraction of the product can be entrained in the vapor phase (which is typically dominated by C₄ and lighter components).
- P_OP_TEMP – This field stores the pipeline operating temperature (in degrees C). It is used in the drain down calculation to calculate gravity drain rates for a release point.
- KIN_VISC – This field stores the kinematic viscosity of the product at a given reference temperature (in centistokes – cSt). It is used in the drain down calculation to calculate gravity drain rates for a release point.
- KVISC_TEMP – This field stores the reference temperature at which product kinematic viscosity was determined (in degrees C). It is used in the drain down calculation to calculate gravity drain rates for a release point.
- PIPE_ROUGH – This field stores pipe roughness (in m). It is used in the drain down calculation to calculate gravity drain rates for a release point.

Please see the Liquids HCA Tool Data Dictionary for a complete list of fields for the global inputs table.

Input Mainline Valve Features – You may optionally specify an input mainline valve feature layer, which is used in the drain down calculation to delineate drainage ranges on the pipeline centerline. The drainage range for a given release point is bounded by the nearest upstream and downstream mainline block valves, which are assumed to be closed at the beginning of gravity drain down. Your mainline valve features are copied into the project geodatabase.
Input Check Valve Features – You may optionally specify an input check valve feature layer, which is used in the drain down calculation to help delineate drainage ranges on the pipeline centerline. For a given release point, the nearest downstream check valve will define the boundary of the downstream leg of the drainage range for the release point. This is because check valves prevent backflow in the pipeline. For the same reason, check valves upstream of a given release point are ignored. Your mainline valve features are copied into the project geodatabase.
Valve Route Identifier Field – If you specify a mainline or check valve feature layer, you must also specify a field that identifies the underlying centerline route feature on which each valve feature occurs. Most pipeline data models store valves in a single layer; the tool expects that your input mainline valves and check valves share the same schema. The same route identifier field is used for both mainline and check valves.
Valve Measure Field – If you specify a mainline or check valve feature layer, you must also specify a field that stores the measure location on the underlying centerline route feature at which each valve feature occurs. The same measure field is used for both mainline and check valves.
Output Mainline Valve Features – This parameter defines the name of your copied mainline valves feature class in the project geodatabase. It appears if you specify an input mainline valve feature layer. The default value is ‘VALVES_MAINLINE.’
Output Check Valve Features – This parameter defines the name of your copied check valves feature class in the project geodatabase. It appears if you specify an input check valve feature layer. The default value is ‘VALVES_CHECK.’
Measure Units – When centerline route measure values are used to define pipe length (used to calculate pipe volume), you must specify the linear units of your centerline route measure values. The default value, ‘Feet,’ is typical for U.S. pipeline lines.
Elevation Units –The USGS 3DEP and Esri Terrain layers that are typically used to support overland flow simulation store elevation in meters, which is the default value for this parameter. If you are using your own source of elevation data, the units may differ, and you can specify them here.
Pipe Length Determination – This parameter determines how pipe length is determined for the drain down calculation. The default value is ‘Measure,’ which is defined by the measure values on the centerline route features underlying the release points. If you select ‘3D Geodesic Length,’ the tool calculates that value from release point X, Y, and Z location data.
Output Pipe Fill Status Table – This output table contains records defining the filled and unfilled portions of the line for each release point. By default, this output table is named ‘PIPE_FILL_STATUS.’ You can display the data in this table as a linear event layer using the Make Route Event Layer (Linear Referencing) tool to help visualize the results of gravity drain down for a given release point. (Note that you’ll want to apply a definition query on the linear event layer to restrict the records to a single release point.) For more information about the attribution of the pipe fill status table, see the Liquids HCA Tool Data Dictionary.
Output Drain Rate Status Table – This output table contains calculated gravity drain rate values for each local elevation maxima in the drainage range for each release point. By default, this output table is named ‘DRAIN_RATE_STATUS.’ Only the maximum calculated gravity drain rate for each release point is stored in the release point feature class, and the overland flow algorithm assumes a simple two-step hydrograph for each release point based on the pumping rate and the maximum gravity drain rate. (This conservative, simplifying assumption results in maximum overland transport of the plume.) The detailed gravity drain rate data in this table enables you to construct a detailed drain down hydrograph for any given release point, if desired. For more information about the attribution of the drain rate status table, see the Liquids HCA Tool Data Dictionary.
Output Edges Table – This output table stores the ‘edges’ in the centerline route drainage network. By default, this output table is named ‘EDGES.’ During the drain down calculation, the tool creates a simple edge-node network topology to help delineate drainage ranges for release points; edges are used to define the drainage ranges for individual release points. Edges are bound by centerline route end points, lateral connections (the lateral must physically touch the centerline route it connects to), and valves. For more information about the attribution of the edges table, see the Liquids HCA Tool Data Dictionary.
Output Junctions Table – This output table stores the ‘junctions’ in the centerline route drainage network. By default, this output table is named ‘JUNCTIONS.’ Junctions are defined by centerline route end points, lateral connection points (the lateral must physically touch the centerline route it connects to), and valves. For more information about the attribution of the junctions table, see the Liquids HCA Tool Data Dictionary.

In a typical Liquids HCA Tool analysis workflow, Calculate Draindown is executed following Create Release Points, and before Create GeoClaw Cases.

For visual reference on Liquids HCA Tool execution order, see Liquids HCA Tool Process Flow Diagrams.

Syntax

CalculateDraindown_ (in_workspace, in_ospointm_features, in_route_features, in_global_inputs_table, {in_mainline_valve_features}, {in_check_valve_features}, {in_valve_route_id_field}, {in_valve_measure_field}, {out_main_valve_features}, {out_check_valve_features}, {in_measure_units}, {in_elevation_units}, {in_pipedistance}, {in_from_measure}, {in_to_measure}, out_pipefill_status_table, out_drainrate_status_table, {out_edges_table}, {out_junctions_table})

Parameter

Explanation

Data Type

in_workspace

Dialog Reference

Specify your input project database.

There is no Python reference for this parameter.

Workspace

in_ospointm_features

Dialog Reference

Select your input release points features.

There is no Python reference for this parameter.

Feature Layer

in_route_features

Dialog Reference

Select your input centerline route features.

There is no Python reference for this parameter.

Feature Layer

in_global_inputs_table

Dialog Reference

Select the input global inputs table.

There is no Python reference for this parameter.

Table View

in_mainline_valve_features

(Optional)

Dialog Reference

Specify a mainline valve feature layer.

There is no Python reference for this parameter.

Feature Layer

in_check_valve_features

(Optional)

Dialog Reference

Specify a check valve feature layer.

There is no Python reference for this parameter.

Feature Layer

in_valve_route_id_field

(Optional)

Dialog Reference

Select the field containing the value that uniquely identifies the route feature underlying your valves.

There is no Python reference for this parameter.

Field

in_valve_measure_field

(Optional)

Dialog Reference

Select the field containing the measure value for your valve features.

There is no Python reference for this parameter.

Field

out_main_valve_features

(Optional)

Dialog Reference

Specify the output destination feature class for the copied input valve features.

There is no Python reference for this parameter.

Feature Layer

out_check_valve_features

(Optional)

Dialog Reference

Specify the output destination feature class for the copied input valve features.

There is no Python reference for this parameter.

Feature Layer

in_measure_units

(Optional)

Dialog Reference

Specify the linear units for the measure values of your release point features.

There is no Python reference for this parameter.

String

in_elevation_units

(Optional)

Dialog Reference

Specify the linear units of the elevation values for your release point features.

There is no Python reference for this parameter.

String

in_pipedistance

(Optional)

Dialog Reference

Select the method to use in calculating pipe length between release points.

There is no Python reference for this parameter.

String

in_from_measure

(Optional)

There is no dialog reference for this parameter.

Python Reference

If only one centerline route feature is present (or selected) in the input centerline route features, you may perform drain down calculations over only a portion of that centerline route feature, if desired. Enter the begin measure value for the calculation range using this parameter.

Double

in_to_measure

(Optional)

There is no dialog reference for this parameter.

Python Reference

If only one centerline route feature is present (or selected) in the input centerline route features, you may perform drain down calculations over only a portion of that centerline route feature, if desired. Enter the end measure value for the calculation range using this parameter.

Double

out_pipefill_status_table

Dialog Reference

Specify the destination table for the output pipe fill status table.

There is no Python reference for this parameter.

Table

out_drainrate_status_table

Dialog Reference

Specify the destination table for the output drain rate status table.

There is no Python reference for this parameter.

Table

out_edges_table

(Optional)

Dialog Reference

Specify the destination table for the output drainage network edges table.

There is no Python reference for this parameter.

Table

out_junctions_table

(Optional)

Dialog Reference

Specify the destination table for the output drainage network junctions table.

There is no Python reference for this parameter.

Table

Code sample

The following script demonstrates how to use the Calculate Draindown tool with file geodatabase data:

import arcpy

arcpy.ImportToolbox(r”C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\Lib\site-packages\liquidshca\esri\toolboxes\LiquidsHCA.pyt”)

arcpy.env.workspace = r “C:\data\test.gdb”

in_workspace = r “C:\data\test.gdb”

release_points = r “C:\data\test.gdb\OSPPOINTM”

route_features = r “C:\data\test.gdb\ROUTES”

global_inputs = r “C:\data\test.gdb\GLOBAL_INPUTS”

main_valves = “Mainline_Valves”

check_valves = “Check_Valves”

valve_route_id = “ROUTE_ID”

valve_measure = “FROM_MEAS”

out_main_valves = r “C:\data\test.gdb\VALVES_MAINLINE”

out_check_valves = r “C:\data\test.gdb\VALVES_CHECK”

measure_units = “Feet”

elev_units = “Meters”

pipe_dist = “Measure”

begin_meas = None

end_meas = None

out_pipe_fill_status = r “C:\data\test.gdb\PIPE_FILL_STATUS”

out_drain_rate_status = r “C:\data\test.gdb\DRAIN_RATE_STATUS”

out_edges = r “C:\data\test.gdb\EDGES”

out_junctions = r “C:\data\test.gdb\JUNCTIONS”

arcpy.liquidshca.CalculateDraindown(in_workspace, release_points, route_features, global_inputs, main_valves, check_valves, valve_route_id, valve_measure, out_main_valves, out_check_valves, measure_units, elev_units, pipe_dist, begin_meas, end_meas, out_pipe_fill_status, out_drain_rate_status, out_edges, out_junctions)

Environments

Current Workspace, Extent, Output Coordinate System, Geographic Transformations, Output has M values, M Resolution, M Tolerance, Output XY Domain, XY Resolution, XY Tolerance, Default Output Z Value, Output has Z values, Z Tolerance, Z Resolution, Output CONFIG Keyword, Scratch Workspace, Qualified Field Names, Auto Commit, Output M Domain, Output Z Domain

Licensing information

This tool requires a valid Liquids HCA Tool user license or subscription. Please see the Request License and Register Licensetool help topics for details on obtaining and registering a Liquids HCA Tool software license.

Credits

Use limitations

There are no access and use limitations for this item.

Summary

Illustration

Usage

Syntax

Code sample

import arcpy

arcpy.ImportToolbox(r”C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\Lib\site-packages\liquidshca\esri\toolboxes\LiquidsHCA.pyt”)

arcpy.env.workspace = r “C:\data\test.gdb”

in_workspace = r “C:\data\test.gdb”

release_points = r “C:\data\test.gdb\OSPPOINTM”

route_features = r “C:\data\test.gdb\ROUTES”

global_inputs = r “C:\data\test.gdb\GLOBAL_INPUTS”

main_valves = “Mainline_Valves”

check_valves = “Check_Valves”

valve_route_id = “ROUTE_ID”

valve_measure = “FROM_MEAS”

out_main_valves = r “C:\data\test.gdb\VALVES_MAINLINE”

out_check_valves = r “C:\data\test.gdb\VALVES_CHECK”

measure_units = “Feet”

elev_units = “Meters”

pipe_dist = “Measure”

begin_meas = None

end_meas = None

out_pipe_fill_status = r “C:\data\test.gdb\PIPE_FILL_STATUS”

out_drain_rate_status = r “C:\data\test.gdb\DRAIN_RATE_STATUS”

out_edges = r “C:\data\test.gdb\EDGES”

out_junctions = r “C:\data\test.gdb\JUNCTIONS”

Environments

Licensing information

Related topics

Tags

Credits

Use limitations

CALCULATE DRAINDOWN