A subnetwork trace configuration dictates which features and objects in a subnetwork are updated, exported, or traced. The subnetwork trace configuration is an optional component of the subnetwork definition.
A subnetwork trace configuration is set using the Set Subnetwork Definition tool. This tool defines the subnetwork trace configuration for all subnetworks in a tier. At this level, they represent the standard definition of subnetworks in a tier. An example in an electrical distribution network: although there is connectivity from the circuit breaker all the way to service points, you may want to terminate a trace for a single subnetwork at the switches that separate the circuits. The subnetwork trace configuration can incorporate these settings.
The Set Subnetwork Definition tool provides a set of configurable options that allow you to control which network features are included in the results based on their association role or barrier status. Associations can be used to include containers, content, and structures as well as check for the locatability of nonspatial objects. By default, Include Containers, Include Content, and Include Structures are enabled for the subnetwork definition and included when the subnetwork is updated, exported, or traced. Validate Locatability is disabled by default.
A combination of statements can be created in a single parameter using AND and OR Boolean operators. For example, you have three conditions and you want to find features that meet condition 1 and 2 or 1 and 3. You would create four conditions linked with ORs or ANDs, for example, stop tracing at active and open features, or stop tracing active, protective devices.
The subnetwork trace configuration set for the tier is used to provide information to the Update Subnetwork, Export Subnetwork, and Trace tools. Certain information stored in the standard definition can be overridden by adjusting parameters on the tool manually or programmatically. For example, you may want to see if a different combination of open valves would allow sufficient pressure to a residential area. When a trace configuration is modified for the execution of a tool, it does not modify the subnetwork definition of the tier you are tracing.
Note:
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.
The configuration options are as follows:
- Include Containers—Specifies whether containers will be included.
- Include Content—Specifies whether content of containers will be included.
- Include Structures—Specifies whether structures will be included.
- Include Barrier Features—Specifies whether barriers will be included.
- Validate Locatability—Specifies whether an error will be returned if unlocatable junction or edge objects are encountered.
- Summaries—Calculates and stores information about a subnetwork in the SubnetLine feature class.
- Condition Barriers—Defines a feature that will stop an operation based on network attributes and categories.
- Function Barriers—Defines a feature that will stop an operation based on a function.
- Apply Traversability To—Defines the traversability scope to enforce. Apply traversability to only junctions, only edges, or both junctions and edges.
- Propagators—Uses propagated network attributes to control what features are considered. A Substitution function is available. This parameter is only available via Python.
Summaries
Summaries are an optional component of the subnetwork trace configuration that allow you to gather additional information about a subnetwork and store it in an attribute of the SubnetLine feature class. For example, summaries can be used for subnetworks in a gas network to define the Maximum Allowable Operating Pressure (MAOP) for a pressure zone.
Summaries are configured using the Set Subnetwork Definition tool for all subnetworks in a tier. Configuration involves setting up a function, specifying a network attribute, and specifying an attribute from the SubnetLine feature class to store the result. A filter can optionally be specified to limit which features will be used in the summaries calculation.
If a field to store the summary result does not exist in the SubnetLine feature class, the Add Field tool can be used to add one. A field can only support the result of one summary; therefore, each summary requires its own field in the SubnetLine feature class.
The only tool that uses summaries is the Update Subnetwork tool. When updating a subnetwork, the tool writes the results of the summaries into the SubnetLine feature class for the summary attributes.
Summaries example with filter
The following is an example of the configuration parameters used to set up a summary attribute that will be populated when subnetworks are updated. This is handled under Summaries in the Subnetwork Trace Configuration section of the Set Subnetwork Definition tool:
For the medium-voltage tier in an electric network, a summary attribute of SUBNETWORKLENGTH is configured to include the total length of all medium voltage lines. The sum of the Shape length network attribute is calculated using the Add Function for only the medium-voltage lines in the network. In order to only apply the function for medium-voltage lines in the subnetwork, the Line Asset Group network attribute is used as the Filter Name with a Filter Type of SPECIFIC_VALUE and a Filter Value of 5 (the coded value for Medium Voltage).
| Parameter | Value |
|---|---|
Function | Add |
Attribute | Shape length |
Filter Name | Line Asset Group |
Filter Operator | IS_EQUAL_TO |
Filter Type | SPECIFIC_VALUE |
Filter Value | 5 |
Summary Attribute | SUBNETWORKLENGTH |
Barriers
Utility networks come with the ability to dynamically set barriers on features based on conditions and functions. Traversability barriers can be restricted to apply only to points, only to lines, or to both.
A condition barrier uses a network attribute, an operator and type, and an attribute value. For example, you could set a condition barrier that would continue to export features until the following condition is met: Device Status equal to Type 'Open', where Device Status is the network attribute, equal to is the operator, Type is the specific value, and Open is the attribute value.
Function barriers use a function, a network attribute, an operator, and a value. Function barriers can be used to do such things as restrict how far a trace travels from the starting point, or set a maximum pressure value to stop a trace at. The pressure or length of each line traveled is added to the total traveled so far. When the total length traveled reaches the value specified (for example, 5 + 10 + 20 + 5 + 10 = 50), the trace stops.
The Include Barrier Features option applies to all barrier types and can be configured as part of the subnetwork definition or manually set in the Trace tool.
Propagators and substitutions
Propagators calculate the value of network attributes for features downstream of controllers. In an electrical network, for example, if phase A is de-energized upstream, the propagator will calculate that the phase value of downstream features will have phase A deenergized, even though the network attribute of the features may indicate phase A.
Substitutions may be used during propagation; they map or convert each bit of a network attribute value to another bit. For example, if the substitution maps bit A to bit B, and a network attribute with a value of AC is discovered during propagation, the value AC is treated as BC since the substitution defined the mapping from A to B.
Both propagators and substitutions are defined during the subnetwork definition stage, and are used during trace operations, updating of subnetworks, or export of subnetworks.
To learn more, see Attribute propagation and Attribute substitution.
Tool application
The Update Subnetwork, Export Subnetwork, and Trace tools use all of the components mentioned above except for summaries. Only the Update Subnetwork tool uses summaries when executed.
To modify a subnetwork trace configuration when using the Update Subnetwork and Export Subnetwork tools, you must access the tools with Python or ArcGIS Pro SDK for .NET. The Trace tool allows you to modify any component, except propagators and substitutions, on the tool interface. To access propagators in the Trace tool, you must use Python, ModelBuilder, or the ArcGIS Pro SDK for .NET.
When executing a subnetwork-based trace using the Trace tool via Python, the Subnetwork Trace Configuration of the subnetwork definition is not used for the input Tier and must be manually specified.