Trace Geometric Network

Summary

Solves the specified network analysis problem based on the flags, barriers, and specified weight properties.

Usage

• This tool does not work with network datasets (the networks used by the ArcGIS Network Analyst extension).

• This tool performs a spatial search using the input flags and barriers to locate coincident features. This is used, in the case of flags, to determine which features the trace should originate from and, in the case of barriers, to determine which features should block the trace. Therefore, the input flags and barriers must be precisely located. In ModelBuilder, if you are uncertain whether the flags and barriers are located correctly, you can use the Snap tool in order to specify with which features the flags and barriers should be coincident.

• The output of this tool is a group layer containing one layer for each feature class contained within the input geometric network. Any features returned from the trace will be selected within their respective layer. When the input layers are present in the map, the output group layer may contain layers without a selection; these are empty layers from which no features were returned from the trace. In ModelBuilder, you can use the Select Data tool to extract specific layers from the group layer and the Make_Feature_Layer tool to create a feature layer from the output of the Select Data tool. Use the Get_Count tool to determine if any of the layers in the group layer are empty. This is especially useful when publishing your model to ArcGIS Server, since group layers are not supported as an output parameter type from a geoprocessing task. Because they aren't supported as direct output, you need to use the Select Data tool to create a single (nongroup) layer for output.

• This tool cannot be run while editing a geometric network in a personal geodatabase.

• Unlike other datasets, such as topology or network datasets, geometric networks do not have an associated layer; therefore, when using this tool in ArcMap, the geometric network must be selected from disk. There is no option to select the geometric network from a layer drop-down list as input.

Syntax

TraceGeometricNetwork_management (in_geometric_network, out_network_layer, in_flags, in_trace_task_type, {in_barriers}, {in_junction_weight}, {in_edge_along_digitized_weight}, {in_edge_against_digitized_weight}, {in_disable_from_trace}, {in_trace_ends}, {in_trace_indeterminate_flow}, {in_junction_weight_filter}, {in_junction_weight_range}, {in_junction_weight_range_not}, {in_edge_along_digitized_weight_filter}, {in_edge_against_digitized_weight_filter}, {in_edge_weight_range}, {in_edge_weight_range_not})

Parameter	Explanation	Data Type
in_geometric_network	The geometric network on which the trace will be performed.	Geometric Network
out_network_layer	The name of the group layer that will store the results of the trace as a selected set.	Group Layer
in_flags	Point features representing a set of flags that serve as starting points for the tracing operation. For example, if you are performing an upstream trace, you use a flag to specify where the upstream trace will begin. Flags can be placed anywhere along edges or junctions, but junctions will be considered first when both a junction and edge are found at the location.	Feature Layer
in_trace_task_type	Trace task to be performed on the specified geometric network. FIND_COMMON_ANCESTORS — Find the common features that are upstream of a set of points in your network. Requires flow direction to be set on the geometric network. FIND_CONNECTED —Find the features that are connected to a given point through your network. FIND_LOOPS — Find loops within the network that are defined by determining for each connected feature, on which you placed a flag, the features that loop back on themselves (that is, can't be reached from more than one direction). FIND_DISCONNECTED — Find all of the features that are not connected to a given point through your network. FIND_PATH_UPSTREAM — Find an upstream path from a point in your network. The path found can be just one of a number of paths depending on whether or not your network contains loops. The flags you place on the network can be a mixture of edge flags and junction flags. Requires a weight to be defined for the trace and flow direction to be set on the geometric network. When a weight is not specified, the shortest path is determined by the least number of features between the two points. FIND_PATH — Find a path between two or more flags in the network. The path found can be just one of a number of paths between the flags depending on whether or not your network contains loops. The flags you place on the network must be either all edge flags or all junction flags. When a weight is not specified, the shortest path is determined by the least number of features between the two points. TRACE_DOWNSTREAM —Find all network features that lie downstream (with flow direction) of a given point in your network. Requires flow direction to be set on the geometric network. FIND_UPSTREAM_ACCUMULATION — Determine the total cost of all network features that lie upstream of a given point in your network. Requires a weight be defined for the trace and flow direction to be set on the geometric network. TRACE_UPSTREAM — Find all features that lie upstream (against flow direction) of a given point in your network. Requires flow direction to be set on the geometric network.	String
in_barriers (Optional)	Point features representing a set of barriers. Barriers define places in the network where traces cannot pass through. If you are only interested in tracing a particular part of your network, you can use barriers to isolate that part of the network. Barriers can be placed anywhere along edges or junctions, but junctions will be considered first when both a junction and edge are found at the location. The feature will be treated as disabled and will not be considered during the trace, unless you've set the in_trace_ends parameter to TRACE_ENDS to purposefully find features stopping the trace.	Feature Layer
in_junction_weight (Optional)	A junction weight that is used as a cost for traversing through any junction. The weight must already be defined for the given geometric network. This parameter is disabled or ignored when one of the following cost-independent trace task types is specified: FIND_COMMON_ANCESTORS FIND_CONNECTED FIND_LOOPS FIND_DISCONNECTED TRACE_DOWNSTREAM TRACE_UPSTREAM	String
in_edge_along_digitized_weight (Optional)	An edge weight that is used as a cost for traversing through an edge along the digitized direction of that edge. The weight must already be defined for the given geometric network. This parameter is disabled or ignored when one of the following cost-independent trace task types is specified: FIND_COMMON_ANCESTORS FIND_CONNECTED FIND_LOOPS FIND_DISCONNECTED TRACE_DOWNSTREAM TRACE_UPSTREAM	String
in_edge_against_digitized_weight (Optional)	An edge weight that is used as a cost for traversing through an edge against the digitized direction of that edge. The weight must already be defined for the given geometric network. This parameter is disabled or ignored when one of the following cost-independent trace task types is specified: FIND_COMMON_ANCESTORS FIND_CONNECTED FIND_LOOPS FIND_DISCONNECTED TRACE_DOWNSTREAM TRACE_UPSTREAM	String
in_disable_from_trace [in_disable_from_trace,...] (Optional)	List of feature classes that are disabled from participating in the trace. Specifying a feature class as disabled makes the trace operation treat all features in that feature class as either being disabled or as having a barrier placed on them. Use this option to exclude an entire feature class from consideration during a trace. For example, by disabling the switches layer in an electrical distribution network, setting the in_trace_ends parameter to TRACE_ENDS and tracing from a given point in the network, you can find the switches that need to be thrown to isolate this point from the network; these will be the features at which the trace operation is stopped.	String
in_trace_ends (Optional)	Indicates whether the trace should include all features or only those stopping the trace. Use this option when you need to determine which features are stopping a trace. In order to be returned from the trace operation with this option, features must fall into one of the following categories: The feature is connected to only one other geometric network feature (dead ends). The feature is disabled (including those in disabled feature classes). The feature has a barrier placed on it. TRACE_ENDS —Include those features stopping the trace. NO_TRACE_ENDS —Include all features. This is the default.	Boolean
in_trace_indeterminate_flow (Optional)	Indicates whether the trace should include all features or only those stopping the trace. TRACE_INDETERMINATE_FLOW —Trace features that have indeterminate or uninitialized flow direction. NO_TRACE_INDETERMINATE_FLOW —Do not trace features that have indeterminate or uninitialized flow direction. This is the default. Only honored when one flow-dependent trace task type is set: FIND_PATH_UPSTREAM TRACE_DOWNSTREAM FIND_UPSTREAM_ACCUMULATION TRACE_UPSTREAM	Boolean
in_junction_weight_filter (Optional)	The weight to use to create the junction weight filter, which is used to filter junction features during the trace.	String
in_junction_weight_range (Optional)	Specifies valid or invalid ranges of weight values for network features that can be traced. It is disabled when a cost-independent trace task type is set. In order to create a weight filter, you must specify valid weight ranges for the features. A weight filter can be composed of a number of ranges. When you specify multiple weight ranges, delimit the ranges with commas. Low and high values in a range are separated by a hyphen. Ranges consisting of a single value do not contain a hyphen and are delimited with commas, for example, 0-2,3,6,7-10.	String
in_junction_weight_range_not (Optional)	Applies the logical NOT operator to the specified junction weight ranges. By default, the junction weight ranges that you enter specify junction features that can be traced. By checking this option, you indicate that junction features with weights in the ranges you entered cannot be traced. AS_IS —Weight ranges specify features that can be traced. This is the default. NOT —Weight ranges specify features that cannot be traced.	Boolean
in_edge_along_digitized_weight_filter (Optional)	The weight to use to create the along-edge weight filter, which is used to filter edge features during the trace.	String
in_edge_against_digitized_weight_filter (Optional)	The weight to use to create the against-edge weight filter, which is used to filter edge features during the trace.	String
in_edge_weight_range (Optional)	Specifies valid or invalid ranges of weight values for network features that can be traced. It is disabled when a cost-independent trace task type is set. In order to create a weight filter, you must specify valid weight ranges for the features. A weight filter can be composed of a number of ranges. When you specify multiple weight ranges, you must delimit the ranges with commas. Low and high values in a range are separated by a hyphen. Ranges consisting of a single value do not contain a hyphen and are delimited with commas, for example, 0-2,3,6,7-10.	String
in_edge_weight_range_not (Optional)	Applies the logical NOT operator to the specified edge weight ranges. By default, the edge weight ranges that you enter specify edge features that can be traced. By checking this option, you indicate that edge features with weights in the ranges you entered cannot be traced. AS_IS —Weight ranges specify features that can be traced. This is the default. NOT —Weight ranges specify features that cannot be traced.	Boolean

Code sample

TraceGeometricNetwork example 1 (stand-alone script)

The following stand-alone Python script demonstrates how to use the TraceGeometricNetwork function in Python scripting to run a Find Connected Trace on a geometric network with Flags and no Barriers.

# Import arcpy module
import arcpy

# Local variables:
gnVersionFDS_Net = "C:/GeometricNetworks/GeometricNetwork.gdb/gnVersionFDS_with_GN/gnVersionFDS_1_Net"
Flags = "C:/GeometricNetworks/GeometricNetwork.gdb/gnVersionFDS_with_GN/Flags"
gnVersionFDS_1 = "gnVersionFDS_1_Net"

# Process: Trace Geometric Network
arcpy.TraceGeometricNetwork_management(gnVersionFDS_Net, gnVersionFDS_1, Flags, "FIND_CONNECTED", "", "", "", "", "", "NO_TRACE_ENDS", "", "", "", "AS_IS", "", "", "", "AS_IS")

TraceGeometricNetwork example 2 (stand-alone script)

The following stand-alone Python script demonstrates how to use the TraceGeometricNetwork function in Python scripting to run a Find Path Trace on a geometric network with Flags and no Barriers with a weight called Friction_Factor and a weight filter of 1 to 10.

# Import arcpy module
import arcpy

# Local variables:
Water_Net = "C:/GeometricNetworks/Montgomery.gdb/Water/Water_Net"
Flags = "C:/GeometricNetworks/Montgomery.gdb/Water/Flags"
Water_Net_2 = "Water_Net"

# Process: Trace Geometric Network
arcpy.TraceGeometricNetwork_management(Water_Net, Water_Net_2, Flags, "FIND_PATH", "", "", "Friction_Factor", "Friction_Factor", "", "NO_TRACE_ENDS", "", "", "", "AS_IS", "Friction_Factor", "Friction_Factor", "1-10", "AS_IS")

Environments

This tool does not use any geoprocessing environments.

Licensing information

• ArcGIS Desktop Basic: No
• ArcGIS Desktop Standard: Yes
• ArcGIS Desktop Advanced: Yes