Skip To Content

Set Subnetwork Definition

Summary

Sets the properties for a subnetwork in a utility network.

The types of features that participate in a tier can be restricted by defining valid asset types from the device and line feature classes. Defining valid asset types helps enforce data correctness by limiting the types of features that can participate in a subnetwork for a specific tier.

Configuration parameters can be used to set properties when a trace is executed on the subnetwork.

Learn more about setting a subnetwork definition

Learn more about subnetwork management

Learn more about tracing utility networks

Usage

  • This tool also allows you to set and alter the subnetwork definition. To alter the values of the subnetwork definition, modify the parameter values and execute the tool again.

  • The network topology must be disabled.

  • The connected ArcGIS Enterprise portal account must be the portal utility network owner.

  • This tool should be executed when connected to the default version.

  • The input utility network must be from a database connection established as the database utility network owner.

Syntax

SetSubnetworkDefinition(in_utility_network, domain_network, tier_name, support_disjoint_subnetwork, valid_devices, valid_subnetwork_controller, valid_lines, aggregated_line, {diagram_template}, {summaries}, {condition_barriers}, {function_barriers}, {include_barriers}, {traversability_scope}, {propagators})
ParameterExplanationData Type
in_utility_network

The input utility network that contains the subnetwork.

Utility Network; Utility Network Layer
domain_network

The domain network that contains the subnetwork.

String
tier_name

The name of the tier that contains the subnetwork.

String
support_disjoint_subnetwork

Specifies whether the tier supports disjointed subnetworks. Disjointed subnetworks are two or more subnetworks that belong to the same tier and have the same subnetwork name but are not traversable. This option is only available for tiers within domain networks with a partitioned tier definition. Tiers in a domain network with a hierarchical tier definition always have this tier property set as true to support disjoint subnetworks.

  • SUPPORT_DISJOINT The input tier supports disjointed subnetworks.
  • NO_DISJOINTThe input tier does not support disjointed subnetworks. This is the default.
Boolean
valid_devices
[valid_devices,...]

The list of asset group/asset type pairs that will be considered as valid devices for the subnetwork.

String
valid_subnetwork_controller
[valid_subnetwork_controller,...]

The list of asset group/asset type pairs that can become subnetwork controllers in the subnetwork.

String
valid_lines
[valid_lines,...]

The list of asset group/asset type pairs that will be considered as valid lines for the subnetwork.

String
aggregated_line
[aggregated_line,...]

The valid lines whose geometry will be aggregated to generate the SubnetLine features. This list is a subset of the values specified in the valid_lines parameter.

String
diagram_template
[diagram_template,...]
(Optional)

The templates that will be used to generate subnetwork system diagrams for each subnetwork.

String
summaries
[[Function, Attribute, Filter Name, Filter Operator, Filter Type, Filter Value, Summary Attribute],...]
(Optional)

Sets the summary field to store function results when inserting or updating SubnetLine features.

Summaries components are as follows:

  • Function—Choose from a number of different calculation functions.
  • Attribute—Choose to filter by any network attribute defined in the system.
  • Filter Name—Choose to filter the function results by attribute name.
  • Filter Operator—Choose from a number of different operators.
  • Filter Type—Choose from a number of different filter types.
  • Filter Value—Set a specific value of the input filter attribute.
  • Summary Attribute—The field in the SubnetLine feature class that will persist the function result. Depending on the selected function and network attribute type, only the applicable type of user-added subnetwork attributes will be valid for this parameter. If a field to store the summary result does not exist in the SubnetLine feature class, the Add Field tool can be used to create one. A field can only support the result of one summary; therefore, each summary requires its own field in the SubnetLine feature class. See the following matrix of valid field types for the various functions: Matrix of valid field types for the summary attribute field, based on the function chosen

Possible values for the summaries Function options are as follows:

  • AVERAGEThe average of the input values.
  • COUNTThe number of features.
  • MAXThe maximum of the input values.
  • MINThe minimum of the input values.
  • ADDAdd the values.
  • SUBTRACTSubtract the values. Subnetwork controllers and loops trace types do not support the subtract function.

Possible values for the summaries Filter Type options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

The Filter Operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).
Value Table
condition_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Sets a traversability barrier condition on features based on a comparison to a network attribute or check for a category string. A condition barrier uses a network attribute, an operator and a type, and an attribute value. For example, stop a trace when a feature has the attribute Device Status equal to the specific value of Open. When a feature meets this condition, the trace stops. If you're using more than one attribute, you can use the Combine using parameter to define an And or an Or condition.

Condition barrier components are as follows:

  • Name—Choose to filter by any network attribute defined in the system.
  • Operator—Choose from a number of different operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • Value—Set a specific value of the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The condition barriers operator values are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES NOT INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INLCUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Possible values for the Type options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

The Combine Using values are as follows:

  • ANDCombine the condition barriers.
  • ORUse if either condition barrier is met.
Value Table
function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(Optional)

Sets a traversability barrier on features based on a function. Function barriers can be used to do such things as restrict how far the trace travels from the starting point, or set a maximum value to stop a trace. For example, the length of each line traveled is added to the total distance traveled so far. When the total length traveled reaches the value specified, the trace stops.

Function barrier components are as follows:

  • Function—Choose from a number of different calculation functions.
  • Attribute—Choose to filter by any network attribute defined in the system.
  • Operator—Choose from a number of different operators.
  • Value—Set a specific value of the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value, for example, for a function barrier that is calculating the sum of Shape length where the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you have already reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, so the trace goes farther.

Possible values for the function barrier function options are as follows:

  • AVERAGEThe average of the input values.
  • COUNTThe number of features.
  • MAXThe maximum of the input values.
  • MINThe minimum of the input values.
  • ADDAdd the values.
  • SUBTRACTSubtract the values.Subnetwork controllers and loops trace types do not support the subtract function.

The function barrier operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

The function barrier Use Local Values options are as follows:

  • TRUEUse local values.
  • FALSEUse global values. This is the default.
Value Table
include_barriers
(Optional)

Defines whether the traversability barrier features are included in the trace results. Traversability barriers are optional even if they have been preset in the subnetwork definition.

  • INCLUDE_BARRIERSTraversability barriers are included in the trace results. This is the default.
  • EXCLUDE_BARRIERSTraversability barriers are not included in the trace results.
Boolean
traversability_scope
(Optional)

The type of traversability to enforce. Traversability scope dictates whether traversability is enforced at junctions, edges, or both. For example, if a condition barrier is defined to stop the trace if Device Status is equal to Open and traversability scope is set to edges only, the trace would not stop even if the trace encounters an open device, because Device Status is only applicable for junctions. In other words, this parameter indicates to the trace whether or not to ignore junctions, edges, or both.

  • BOTH_JUNCTIONS_AND_EDGESApply traversability to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYApply traversability to only junctions.
  • EDGES_ONLYApply traversability to only edges.
String
propagators
[[Attribute, Substitution Attribute, Function, Operator, Value, Propagated Attribute],...]
(Optional)

Specifies the network attributes to propagate as well as how that propagation should occur during a trace. Propagated class attributes denote the key values on subnetwork controllers that are disseminated to the rest of the features in the subnetwork. For example, in an electric distribution model, you can propagate the phase value.

Propagators components are as follows:

  • Attribute—Choose to filter by any network attribute defined in the system.
  • Substitution Attribute—Use a substituted value instead of bitset network attribute values. Substitutions are encoded based on the number of bits in the network attribute being propagated. A substitution is a mapping of each bit in phase to another bit. For example, for Phase AC, one substitution could map bit A to B and bit C to null. In this example the substitution for 1010 (Phase AC) is 0000-0010-0000-0000 (512). The substitution captures the mapping so you know that Phase A was mapped to B and Phase C was mapped to null and not the other way around (that is, Phase A was not mapped to null and Phase C was not mapped to B).
  • Function—Choose from a number of different calculation functions.
  • Operator—Choose from a number of different operators.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.
  • Propagated Attribute—The name of the field in your network class that is used to store the calculated propagated values. The field type should be the same as the field type of the network attribute chosen for the Attribute value.

Possible values for the propagators function are as follows:

  • PROPAGATED_BITWISE_ANDCompare the values from one feature to the next.
  • PROPAGATED_MINGet the minimum value.
  • PROPAGATED_MAXGet the maximum value.

The propagator operator values are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).
Note:

This parameter is only available via Python.

Value Table

Derived Output

NameExplanationData Type
out_utility_network

The updated input utility network.

Utility Network

Code sample

SetSubnetworkDefinition example (stand-alone script)

This example sets the subnetwork definition in a domain named ElectricDistribution.

'''****************************************************************************
Name:        SetSubnetworkDefinition.py
Description: This script sets the subnetwork definition for a tier in a Utility Network
Created by:  Esri
****************************************************************************'''

# Import required modules        
import arcpy

# Set local variables
in_utility_network = "ElectricDistribution"
domain_network = "ElecDist"
tier_name = "Medium Voltage"
support_disjoint_subnetwork = "SUPPORT_DISJOINT"
valid_devices = "'CircuitBreaker/Unknown';'CircuitBreaker/Air powered';'NetworkProtector/Unknown';'NetworkProtector/NetworkProtector';'Transformer/Unknown';'Transformer/Buck boost';'Transformer/Single-phase overhead';'Transformer/Single-phase padmounted';'Transformer/Three-phase padmounted';'Transformer/Power';'Transformer/Step';'Transformer/Vault'"
valid_subnetwork_controller = "'CircuitBreaker/Unknown';'CircuitBreaker/Air powered'"
valid_lines = "'Busbar/Unknown';'Busbar/Busbar';'Connector/Unknown';'Connector/Connector';'LowVoltage/Unknown';'LowVoltage/Overhead';'LowVoltage/Underground';'MediumVoltage/Unknown';'MediumVoltage/Single-phase overhead';'MediumVoltage/Two-phase overhead';'MediumVoltage/Three-phase overhead';'MediumVoltage/Single-phase underground';'MediumVoltage/Two-phase underground';'MediumVoltage/Three-phase underground';'IsolatedNeutral/Unknown';'IsolatedNeutral/Concentric neutral';'IsolatedNeutral/Neutral';'SubTransmission/Unknown';'SubTransmission/Overhead';'SubTransmission/Underground'"
aggregated_line = "'Busbar/Unknown';'Busbar/Busbar';'MediumVoltage/Unknown';'MediumVoltage/Single-phase overhead';'MediumVoltage/Two-phase overhead';'MediumVoltage/Three-phase overhead';'MediumVoltage/Single-phase underground';'MediumVoltage/Two-phase underground';'MediumVoltage/Three-phase underground'"
diagram_template = "Basic"
summaries = ""
condition_barriers = "'Device Status' IS_EQUAL_TO SPECIFIC_VALUE 'Opened' #"
function_barriers = ""
include_barriers = "INCLUDE_BARRIERS"
traversability_scope = "BOTH_JUNCTIONS_AND_EDGES"
propagators = ""

# Run the SetSubnetworkDefinition tool
arcpy.SetSubnetworkDefinition_un(in_utility_network, 
                                 domain_network, 
                                 tier_name, 
                                 support_disjoint_subnetwork, 
                                 valid_devices, 
                                 valid_subnetwork_controller, 
                                 valid_lines, 
                                 aggregated_line, 
                                 diagram_template, 
                                 summaries, 
                                 condition_barriers, 
                                 function_barriers, 
                                 include_barriers, 
                                 traversability_scope, 
                                 propagators)

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: No
  • Standard: Yes
  • Advanced: Yes

Related topics