Tracing a utility network is done to discover answers and solve problems with regard to the state of your network at any moment. To trace a utility network, use the Trace tool.
Along with these trace types, the Trace tool also includes a comprehensive set of advanced configurations used to refine each provided trace type. These configurations allow you to establish traversability, distinguish what features should be returned, and set up calculations to be performed. ModelBuilder can be used to save complex configurations and also allows you to reduce the number of parameters presented on the model tool interface. This helps you and others rerun advanced traces with just one click.
For example, you have been tasked to draw up a report on the number of customers fed by each transformer with a voltage over 60 for a specific feeder. In the report, you must include the total load for those transformers and mark which ones are on wooden poles over 25 years old, with the last inspection being over 5 years ago to indicate a pole inspection is required. You run a single preconfigured trace that returns all of this information to you.
Setting subnetwork trace configurations in the subnetwork definition allows the Trace tool to be autopopulated when executing a trace against a specific tier. This applies for subnetwork-based traces. For example, you always want your subnetwork traces to stop at protective devices, effectively indicating the end of the feeder. You also always want to calculate the total load for each feeder. You probably do not want to set these parameters every time you run a subnetwork-based trace, which is why a standard subnetwork definition can be defined for all subnetworks in a tier. A subnetwork definition is set by the administrator when a tier is created (before subnetworks are added to it). When the tier is specified in the Trace tool, the advanced parameters are autopopulated with the subnetwork trace definition set for the input tier. Any trace configuration parameters that are populated can be overwritten manually in the tool before executing the trace.
During the setup of a trace, you can modify or add onto the subnetwork trace definition. You can do such things as control the types of features traced (pipe diameter greater than 6 inches), choose what types of features you want returned (all open valves), and perform calculations using network attributes (total the length of the AB-phase lines).
Each configuration component is examined in the following sections. See the Trace tool for parameter options and usage information.
Define the trace region
In the Trace tool, you must specify where the trace is allowed to travel within your network. Defining a traceable area helps to ensure the intended part of the network is traced. It is also used to restrict traversal to other tiers for certain trace types. Three pieces of information are used to denote the extent of a traceable area: domain network, tier, and subnetwork. The type of trace determines the required pieces of information; therefore, not all traces will have these parameters.
Specifying a domain network restricts a trace to only that domain network. All traces require a domain network to be set. Some traces require a tier and optionally a subnetwork to be specified. Other types of traces require a tier and a target tier to be set (upstream and downstream). A target tier allows you to trace across multiple tiers within a domain network.
The Tier parameter is used to restrict tracing to a particular tier when specified in the Trace tool. It is also used to automatically populate trace configuration parameters with values set for the subnetwork definition. When starting points are used in conjunction with the Tier parameter, the starting points must reside within the specified tier. The Target Tier parameter is used for Upstream and Downstream traces and indicates the boundary of the traceable network; a trace can traverse within, but not beyond, the target tier.
When tracing across multiple tiers, trace configuration settings are loaded for the initial tier. The following trace configuration settings are loaded for each new tier the trace encounters:
- Traversability scope
- Condition barriers
- Function barriers
For Subnetwork traces, selecting a Subnetwork Name value allows you to specify what subnetwork to trace instead of using starting points. This uses the subnetwork controller or controllers for the specified subnetwork as the starting point for the trace.
Include containers, content, structures, and barriers in results
This set of configurable options in the Trace tool allows you to configure the features that are included in the results based on their association role or barrier status. Association features can include containers, content, and structures. By default, everything but containers, their content, and structures is returned in the results of a trace.
Include containers in the results of a trace. Any container features for the content features that are traced will also be included in the trace results. This configuration can also be used to trace a structure network, for example, returning connected underground ducts.
Include up to First Spatial Container
Specifies whether to limit the containers returned to include only those encountered up to, and including, the first spatial container for each network element in the trace results. If no spatial containers are encountered but nonspatial containers are present for a given network element, all nonspatial containers will be included in results. This parameter is only available when Include Containers is enabled.
Include up to First Spatial Container
Include content features in the results of a trace. This encompasses content from containers that are included in the trace results. To disambiguate between the different types of containers, use an Output filter to filter your results.
Include structures in the results of a trace. This is helpful for such tasks as reporting structural assets.
Include Barrier Features
Include barriers in the results of a trace. This encompasses feature barriers set in the Trace Locations pane as well as dynamically configured barriers: condition barriers, function barriers, filter barriers, and filter function barriers. The subnetwork definition can be used to configure whether barriers are included in trace results as part of the subnetwork trace configuration.
The selection set returned by a trace may display unexpected results when barriers are placed on edge features with midspan connectivity and the Include Barrier Features option is disabled. If any part of the feature is returned by the trace, the entire feature is selected and displayed in the trace result.
Include Barrier Features
The Include Barrier Features configuration option does not apply to features with terminals.
Ignore Barriers At Starting Points
Ignore barriers in the trace configuration if they are starting points. This may be useful when performing an upstream protective device trace and using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.
Ignore Barriers At Starting Points
Ensure network consistency
A consistent area of a network is one that does not have any dirty areas; the network topology has been validated. This is the only way to guarantee a trace is reading the latest information about your network from the network topology. Some trace types require the subnetworks you trace to be clean as well. To learn more, see Dirty subnetworks.
The Validate Consistency configuration option in the Trace tool allows you to ensure the trace results are consistent with the network topology. When Validate Consistency is set to true, the trace operation fails if any dirty areas intersect the trace path. When this occurs, the tool returns an error that includes the class name and global id of features or objects in the trace path that are found to be dirty, as shown in the example below:
ERROR 002041: One or more dirty areas were discovered.
Failed to execute (Trace).
The following scenarios will not cause an error to be raised about inconsistencies in the trace results:
- Dirty areas from newly created features.
- Dirty areas from associated containers or structures when the Include Containers or Include Structures options are disabled.
To clean and remove dirty areas, validate the network topology.
Not having the Validate Consistency check box checked can lead to unexpected trace results; for example, a feature is deleted from a network that breaks the only path between location A and location B. A dirty area is created for the deleted feature. Before the network topology is validated, a trace is executed to find connected features starting at location A, with the Validate Consistency option unchecked. The trace reaches location B and the tool completes with no warnings. Location B was reached because the deletion of the feature connecting A to B has not been reflected in the network topology by executing a validate operation.
If the Validate Consistency option is checked in the example above, when the trace reaches the dirty area marking the deleted feature, the trace fails and an error is returned to let you know a dirty area was encountered. After the topology is validated for the area being traced, the trace cannot reach location B, as the deleted feature is now reflected in the network topology. If the network topology is not validated for the entire extent of the area that will be traced, other dirty areas could be encountered.
Even though information in the network topology is up to date for the traceable area, the subnetworks may be dirty. Ensure the traceable subnetworks are updated as well. To learn more, see Update subnetworks.
When this option is checked, the trace fails, and tool returns an error if any dirty areas intersect the trace path. If this option is not checked, dirty areas are ignored. This option is checked by default.
Control what is traced
Barriers are used during a trace to denote a stopping location; features beyond that location are not traced. The results of a trace will not include features past a barrier, but can optionally include the barrier itself. The Result Types parameter provides an Aggregated Geometry option that enables partial features to be returned as geometry in trace results.
The Traversability section of the Trace tool includes condition barriers and function barriers to control the traversability of a trace. Condition barriers are expressions based on network attributes or network categories to define where a trace should stop. Function barriers define when a trace should stop when a condition is satisfied.
Traversability scope is further controlled by the traversability_scope parameter that is labeled Apply Traversability To in the Trace tool. This parameter determines whether traversability is applied to both junctions and edges, junctions only, or edges only. For example, if traversability is applied to junctions only and an edge satisfies the condition specified in a condition barrier, the trace will not stop at the edge due to the traversability scope.
To learn more, see Barriers.
Set up functions
A function is a trace configuration that allows you to run calculations on network attributes associated with traced features, for example, the sum of the length of all the wire traced. More than one function can be specified for a trace.
In addition, an optional network attribute filter can be added to each function; when specified, the function will only be applied to features that satisfy the network attribute filter.
An optional network attribute filter can be added to each function. When specified, the function will only be applied to features that satisfy the network attribute filter. Filters in functions are used to introduce a conditional requirement. For example, add up the length of all the lines where the Phases Current attribute includes the values A, B, and C.
Trace configurations that use apportioned network attributes with functions (Add, Average, Count, Max, Min, and Subtract) return apportionable results based on edge elements. For example, using a function within a connected trace to count the shape length attribute returns a count based on the individual edge features and not the entire line. See Apportionable network attributes for more details.
Control what is returned
To control what is returned in the results of a trace, output filters and result types are used.
An output filter screens every feature encountered during a trace to check if it meets the criteria specified in the filter. For example, a trace returns all upstream protective devices from a starting point in an electrical network.
There are two types of Output filters available in the Trace tool: Output Asset Types and Output Conditions.
An Output Asset Types filter is used to include only the asset types specified in the trace results. For example, a pole report for an electric network would include an output asset type filter and only include poles in the results.
The Output Conditions filter supports network categories and network attributes. For example, an output condition uses a specific network category name to return all isolating devices in a gas network. This operation returns all features with the Isolating network category assigned. A trace on a gas network could return emergency valves, bypass valves, system valves, or short stops. Features without this network category are still traced, but they are not included in the results.
Network attributes are stored in the network topology and are associated with a field in one or more feature classes. In an output condition, the name of the network attribute, an operator, and a value that is valid for the network attribute are specified. In the case of a leak in a water network, a network attribute is input to return pinchable pipes. In this case, the Line class has a field named Pinchable. This field is associated with a network attribute named Pinchable. The Output Conditions parameter is configured to look for feature classes with the Pinchable network attribute where the value is equal to True. The results of the trace include features from a feature class with this field and the value True, as well as features from classes without the Pinchable field.
Given the behavior of network attributes in output conditions, to return pinchable pipes, it is necessary to use an Output Asset Type filter. For example, in the Esri-provided Gas utility network, from the PipelineLine class, in the Distribution Pipe asset group, the Plastic PE asset type would be specified. With the two filters, IsPinchable = True AND AssetType = Plastic PE, the trace results will only include pinchable plastic PE pipes.
Multiple Output Conditions values can be implemented using the Combine Using parameter. Both types of outputs can be used and more than one output type can be set up. Combining output types allows you to do such things as return all 12-inch pinchable Plastic PE pipes that exceed 80 PSI.
The optional Result Types parameter provides the ability to control the type of results returned by the trace. The Aggregated Geometry and Selection result types can be specified independently or concurrently to generate output geometries and a selection set for a trace operation.
The Aggregated Geometry option enables trace results to be returned as multipart geometry in a feature class. This honors the location of starting points and barriers placed midspan on edge features to return partial feature results.
Review the images below to compare the differences between the selection and aggregated geometry result type options in a downstream trace. The network below contains five line features (represented as f1, f2, f3, f4, and f5) that are composed of nine edge elements (represented as e1, e2, e3, and so on).
In this example, which includes barrier features, the selection result returns seven point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, and f5::e1,e2). The aggregated geometry result returns the same features but excludes edge elements f1::e1,e2 and f5::e2.
When a barrier is placed along an edge with the Include Barrier Features configuration option checked, the trace will stop at the barrier feature and return partial feature geometry for the edge in the trace results. If the Include Barrier Features option is unchecked, the trace will stop at the prior line end or junction encountered with midspan connectivity.
The examples below show the difference in trace results when using the Include Barrier Features option to include or exclude barrier features in the trace results. In this example, both the starting point and barrier are placed along an edge. With this option enabled, the selection result returns six point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, f3::e1, f4::e1, and f5::e1,e2). The aggregated geometry result will return the same five line features but excludes edge elements f1::e1 and f5::e2. Partial geometry is returned for the edge element f1::e2. The selection result would not change if we were to exclude barrier features with Include Barrier Features unchecked; however, the aggregated geometry results would additionally exclude f1::e2.
When the Aggregated Geometry option is selected for the result type, five additional parameters are provided to define the trace output behavior:
- Clear All Previous Trace Results
- Trace Name
- Aggregated Points
- Aggregated Lines
- Aggregated Polygons
The Clear All Previous Trace Results check box provides an option to truncate or append to the contents of the feature classes chosen to store aggregated geometry.
Clear All Previous Trace Results
The optional Trace Name parameter enables the creation of a string identifier for the trace operation to assist with identification of trace results.
The Aggregated Points, Aggregated Lines, and Aggregated Polygons parameters enable you to specify feature classes for storage of the aggregated result geometry. By default, each parameter is populated with a system-generated feature class stored in the project's default geodatabase:
- Trace_Results_Aggregated_Lines—A line feature class
- Trace_Results_Aggregated_Points—A multipoint feature class
- Trace_Results_Aggregated_Polygons—A polygon feature class
These feature classes are created automatically if they do not exist. Existing feature classes can also be used to store aggregated geometry. If a feature class other than the default is used, it must contain a String field named TRACENAME and match the geometry type of the output.
The generation of output geometry with partial feature results provides a more accurate representation of the trace and enables comparison and reuse of trace results for other tasks.
When the Selection option is selected for the result type, an additional Selection Type parameter is provided to define how the selection will be applied and what action to perform if a selection already exists.
Work with bitwise operators
The trace configuration uses a common set of operators that are used to define barriers, filters, functions, and outputs for the trace results. Standard operators are used to evaluate feature attributes to check if they are equal, less than, or greater than a value.
Standard operators used in the trace configuration are Is equal to, Does not equal, Is greater than, Is greater than or equal to, Is less than, and Is less than or equal to.
Bitwise operators incorporate the use of bits in their logic by analyzing a value's bitset. These operators provide power and flexibility and are more commonly used in advanced applications of tracing. The tracing framework can work with these bits independent of the meaning that the user defines.
Bitwise operators used in the trace configuration include the following:
- Includes the values—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
- Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
- Includes any—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
- Does not include any—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).
When modeling phase in an electric utility network, the dataset can be configured to use bitsets. A set of values is configured for each permissible phase combination and the bit representation (each bit has a meaning). A coded value domain is configured with the acceptable phase values and assigned to attributes that use phase. For use in the trace configuration, a network attribute is configured in the phase field.
The table below outlines how phase can be modeled using bitsets. The bit value is stored as the code, and the phase value is used for the description in the coded value domain. The binary column in the table shows the binary representation of each bitset. Bitwise operators deconstruct an attribute to assess each piece to check if it satisfies the operational logic. If a network attribute is AC (101) and the value being compared is BC (011); the Includes the values operator would not evaluate to true because the middle bit (B) is not in AC, whereas using the Includes any operator would evaluate to true, since bit C is in both AC and BC.
|Binary||Bit value||Phase value|
For example, to find all features in the subnetwork with a Phases Current value that includes A, a subnetwork trace on an electric distribution domain network is performed. The starting point is set on a service point with a Phases Current value of A and the following trace configuration is specified as a filter barrier. The filter barrier is configured to exclude features that do not include phase A from the trace result. To ensure that the barrier features are not included in the trace results, the trace configuration option Include Barrier Features is set to false. The trace results include subnetwork features that have a Phases Current value of A or a Phases Current value that includes A.
Name: Phases Current
Operator: Does not include any (Bitwise AND equals False)
Type: Specific value
Value: 4 (code for A)
Perform calculations on traced network features
A substitution is a type of network attribute. It is a value used to calculate the propagated value for features with the attribute substitution category assigned to its asset type. The resulting substitution value is then used to calculate the value for next connected feature. To use attribute substitution, propagation must be configured.