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 to represent the standard definition of subnetworks in a tier. An example in an electrical distribution network: although there is connectivity from the circuit breaker 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 options 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 whether a different combination of open valves would allow sufficient pressure to a residential area. When a trace configuration is modified for the running 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 function information about a subnetwork in the SubnetLine feature class.
- Condition Barriers—Defines a feature or object that will stop an operation based on network attributes and categories.
- Function Barriers—Defines a feature or object 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 network features are considered. A Substitution function is available. This parameter is only available 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, you can use summaries in a gas network to communicate the Maximum Allowable Operating Pressure (MAOP) and output the total number of customer services for a pressure zone.
You can configure summaries as part of the subnetwork trace configuration for all valid features and nonspatial objects defined for the tier's subnetwork definition using the Set Subnetwork Definition tool. Configuration involves setting up a function, specifying a network attribute, and specifying an attribute from the SubnetLine feature class to store the result. Optionally, you can set a filter to limit which features will be used in the summaries calculation.
The following matrix of valid field types can be used to define the Summary Attribute field based on the specified function and network attribute field type. For example, to create a summary to report the average from a network attribute type of long, you can create a field of type double on the SubnetLine feature class and specify it as the Summary Attribute field.
You can use the Add Field tool to add a field to store the summary result if one does not exist. 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 operation writes the results of the summaries into the SubnetLine feature class for the summary attributes.
When summaries are present, a record is created in the class to display subnetwork and summary information even when the Aggregated Lines for SubnetLine feature class parameter is not specified as part of the subnetwork definition for the tier. This creates a record with empty geometry and may be useful when you want to summarize subnetwork information when working with nonspatial network features or situations in which multiple SubnetLine features overlap, reducing the utility of the geometry while still enabling access to summary information.
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.
The table below displays the parameters to create Summaries in the Subnetwork Trace Configuration section of the tool. Refer to the Summaries parameter of the Set Subnetwork Definition tool for more details on the arguments required for this trace configuration component.
In this example, 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. To only apply the function for medium-voltage lines in the subnetwork, the system-provided network attribute Asset group is used as the Filter Name text, with Filter Type set to SPECIFIC_VALUE and Filter Value set to 5 (the coded value for Medium Voltage).
| Parameter | Value |
|---|---|
Function | Add |
Attribute | Shape length |
Filter Name | Asset group |
Filter Operator | IS_EQUAL_TO |
Filter Type | SPECIFIC_VALUE |
Filter Value | 5 |
Summary Attribute | SUBNETWORKLENGTH |
Barriers
Utility networks can 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 can 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 restrict how far a trace travels from the starting point or set a maximum pressure value at which to stop a trace. 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 de-energized, 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, subnetworks updates, or subnetworks exports.
To learn more, see Use attribute propagation and Use attribute substitution.
Tool application
The Update Subnetwork, Export Subnetwork, and Trace tools use all of the components mentioned above with the exception of summaries. Only the Update Subnetwork tool uses summaries when run.
Modifications can be made to the subnetwork trace configuration when the Update Subnetwork and Export Subnetwork tools are run using Python or ArcGIS Pro SDK. 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 ArcGIS Pro SDK.
When a subnetwork-based trace is run using the Trace tool through Python, the subnetwork trace configuration for the input tier is not applied automatically and must be manually specified.