# nodal-to-zonal

**URL:** <https://forum.encoord.com/t/nodal-to-zonal/468>\
**Category:** Plugins\
**Tags:** latest-version\
**Created:** [January 7, 2026, 4:23am UTC](https://forum.encoord.com/t/nodal-to-zonal/468 "2026-01-07T04:23:27Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![jacob](https://forum.encoord.com/user_avatar/forum.encoord.com/jacob/32/11_2.png) [@jacob](https://forum.encoord.com/u/jacob)\
**Post date:** [January 7, 2026, 4:23am UTC](https://forum.encoord.com/t/nodal-to-zonal/468/1 "2026-01-07T04:23:27Z")

</div>

## Overview

The Nodal to Zonal Converter plugin converts a detailed nodal network model into a simplified zonal network model in SAInt. It aggregates multiple nodes within each zone into a single reference node and replaces inter-zone branches with zonal interties that represent transfer capacities as derived from shift factor calculations and equivalent impedances between zones.

## Versions Compatible with SAInt 3.8

- [v0.1.3](https://forum.encoord.com/uploads/short-url/AgGY6PZdLpdL6y2z4ZKmuNZPmfb.zip) (33.3 MB)

Screenshot:

 ![nodal_to_zonal](https://forum.encoord.com/uploads/default/original/1X/f1f87d7c4d6f6307a7e50987831bbcb799d1a6db.jpeg)

## Inputs

### Required Files

**SAInt Network File (.enet)**: The SAInt electric network file containing the nodal network topology. This file must include:

- Electric nodes (ENO) with zone assignments
- Electric branches (EBR) connecting nodes
- Zone objects (EZN) with reference node specifications
- External objects (EXT)

### Output Settings

**Output Directory** : The folder where the converted zonal network file will be saved. The original network file is first copied to this location, then the copy is modified in-place to create the zonal network. The original file is never modified.

**Custom Report Filename (Optional)**: Optional custom name for the generated HTML report file. If not specified, a default report filename will be used (output folder name + “.html”). If provided without extension, “.html” will be automatically appended.

**Custom Nodal Network Filename (Optional)**: Optional custom name for the output zonal network file. If not specified, the original filename will be used with a “\_ZONAL” suffix (e.g., “network.enet” → “network\_ZONAL.enet”). If provided without extension, “.enet” will be automatically appended. This file contains the converted zonal network.

**Update Records CSV Filename (Optional, API only)**: Optional custom name for the update records CSV file. If not specified, defaults to “update\_records.csv”. Note: This option is only available when using the API directly (e.g., `from_files()` function). The CLI and plugin UI interfaces use the default filename.

### System Settings

**SAInt API DLL Path** : Path to the SAInt API DLL file. Default: `C:\Program Files\encoord\SAInt-v3\SAInt-API.dll`

**Logging Level** : Controls the verbosity of logging output. Options: Debug, Info, Warning, Error, Critical

## Zone Configuration Requirements

**CRITICAL** : Each SAInt Zone object (EZN) must have the name of its reference node stored in the **ReferenceNodeName** property. The plugin reads this value to identify which node in each zone serves as the reference node for the zonal model.

- The reference node name must exactly match the name of an existing electric node (ENO) in the network
- The reference node must belong to the same zone as specified in the zone object
- If a zone’s ReferenceNodeName property does not contain a valid node name, the zone will be skipped with a warning

## Computation Logic

The conversion process follows these steps:

### 1. Generate SAInt Object Information

The plugin extracts all network objects from the SAInt network file:

- **Electric Nodes (ENO)**: Extracts node names and zone assignments
- **Electric Branches (EBR)**: Extracts branch names, object types (ObjType), endpoints, in-service status, PMAXDEF (maximum power transfer capacity), and XXDEF (impedance). Both PMAXDEF and XXDEF are parsed to handle infinity representations (e.g., “+Inf”, “INF”)
- **Zones (EZN)**: Extracts zone names and reference node names from the ReferenceNodeName property
- **Externals (EXT)**: Extracts external object names and their referenced nodes

Reference nodes are identified by matching zone ReferenceNodeName property values to node names, and these nodes are marked as reference nodes.

### 2. Create Zonal Interties

The plugin identifies branches that connect different zones and groups them into zonal interties:

1. **Branch Grouping** : All branches connecting two different zones are grouped by zone pair (from\_zone, to\_zone)
2. **Direction Determination** : For each zone pair, the plugin applies a majority rule:
  - If more branches flow from Zone A to Zone B than from Zone B to Zone A, the intertie direction is A → B
  - If the counts are equal, the original direction (A → B) is preserved

3. **Intertie Creation** : A zonal intertie object is created for each unique zone pair, containing all branches that connect those zones
4. **Naming** : Zonal interties are named using the pattern `ZONAL_INTERTIE_{from_zone}_{to_zone}`

Branches that connect nodes within the same zone are excluded from intertie creation.

### 3. Compute Zonal Intertie Capacity

For each zonal intertie, the plugin calculates the aggregate transfer capacity using power flow analysis:

1. **Injection Shift Factor (ISF) Calculation**: For each in-service branch in the intertie, the plugin computes the ISF using the SAInt API:

2. **Capacity Ratio Calculation** : For each in-service branch, the capacity ratio is computed as:

3. **Sum of Absolute ISF Values** : The sum of absolute ISF values across all in-service branches is computed:

4. **Zonal Intertie Capacity Calculation** : The zonal intertie capacity is computed as:

This approach ensures that the zonal intertie capacity accurately represents the aggregate transfer capability between zones while respecting individual branch constraints.

### 4. Compute Zonal Intertie Impedance

For each zonal intertie, the plugin calculates the proportionally equivalent impedance using the parallel impedance formula:

1. **Impedance Parsing** : The plugin extracts `XXDEF` values from branches, parsing them similarly to `PMAXDEF` to handle infinity representations (e.g., “+Inf”, “INF”)

2. **Parallel Impedance Calculation** : For each zonal intertie composed of multiple nodal branches, the equivalent impedance is computed as:

3. **Edge Case Handling** :

4. **Result** : The computed impedance value is stored in the `xxdef` attribute of each `ZonalIntertieInformation` object and will be applied to the zonal intertie line in the network.

This approach ensures that the zonal intertie impedance accurately represents the combined electrical behavior of the underlying parallel branches, maintaining the correct electrical characteristics in the simplified zonal model.

### 5. Update Network

The plugin performs the following network modifications to create the zonal model:

#### Create Zonal Intertie Lines

- Creates new branch objects (EBR) with object type “LI” connecting the reference nodes of each zone pair
- Each zonal intertie line connects `from_zone.reference_node` to `to_zone.reference_node`
- Lines are named using the zonal intertie name pattern (e.g., `LI.ZONAL_INTERTIE_{from_zone}_{to_zone}`)
- All network updates are performed within a batch update operation (beginEBatchUpdate/endEBatchUpdate) for efficiency

#### Update Node Visibility and Service Status

- Sets `Visible = False` for all non-reference nodes
- Sets `InService = False` for all non-reference nodes
- Reference nodes remain visible and in-service to represent their zones

#### Update Branch Visibility and Service Status

- Sets `Visible = False` for all original branches (non-zonal-intertie branches)
- Sets `InService = False` for all original branches
- This effectively removes the detailed nodal topology while preserving the zonal intertie lines

#### Set Zonal Intertie Capacity

- Updates the `PMAXDEF` property of each zonal intertie line with the computed capacity value
- Handles infinity values by converting them to “+Inf” string format for SAInt API compatibility
- If the zonal intertie pointer is not available (line creation failed) or capacity was not computed, the update is skipped with status SKIPPED

#### Set Zonal Intertie Impedance

- Updates the `XXDEF` property of each zonal intertie line with the computed impedance value
- The impedance value is converted to string format for SAInt API compatibility
- If the zonal intertie pointer is not available (line creation failed), the update is skipped with status SKIPPED

#### Update External Node References

- For each external object (EXT), updates its `NodeName` property to reference the zone’s reference node
- This ensures that external connections point to the appropriate reference node in the zonal model
- If an external’s zone is not found, the update is skipped with an error

## Network Updates Summary

The following table summarizes all network modifications performed:

| Object Type | Property | Update | Condition |
| --- | --- | --- | --- |
| **EBR** (Zonal Intertie Lines, type “LI”) | - | **CREATE** | New branch objects with type “LI” created for each zone pair |
| **EBR** (Zonal Intertie Lines, type “LI”) | PMAXDEF | **UPDATE** | Set to computed zonal intertie capacity (handles infinity as “+Inf”) |
| **EBR** (Zonal Intertie Lines, type “LI”) | XXDEF | **UPDATE** | Set to computed zonal intertie impedance |
| **ENO** (Electric Nodes) | Visible | **UPDATE** | Set to `False` for all non-reference nodes |
| **ENO** (Electric Nodes) | InService | **UPDATE** | Set to `False` for all non-reference nodes |
| **EBR** (Electric Branches) | Visible | **UPDATE** | Set to `False` for all original branches |
| **EBR** (Electric Branches) | InService | **UPDATE** | Set to `False` for all original branches |
| **EXT** (Externals) | NodeName | **UPDATE** | Set to zone’s reference node name |

## Output

The plugin generates:

1. **Zonal Network File** : The converted zonal network file saved to the output directory. By default, the filename is the original filename with “\_ZONAL” suffix (e.g., “network.enet” → “network\_ZONAL.enet”), or a custom filename if specified. This file contains the simplified zonal model with reference nodes and zonal interties.

2. **Update Records CSV File** : A CSV file containing all network update operations performed during the conversion. By default, the filename is “update\_records.csv”, or a custom filename if specified. The CSV includes:

3. **HTML Report** : A comprehensive HTML report containing:

The CSV and HTML report provide full traceability of the conversion process, allowing users to verify that all expected modifications were applied correctly.

## Changelog

### v0.1.3

#### Features

- **Initial Release (MVP)**: First release of the Nodal to Zonal Converter plugin with core conversion functionality
- **Proportionally Equivalent Impedances** : Implemented parallel impedance calculation for zonal interties using the formula `XXDEF_zonal = 1 / Σ(1/XXDEF_nodal_i)` to accurately represent combined electrical behavior of parallel branches
- **ISF Normalization in Capacity Calculation** : Updated PMAXDEF calculation to include Injection Shift Factor (ISF) normalization, ensuring accurate aggregate transfer capacity representation
- **Comprehensive Reporting** : Added HTML report and CSV update records with full traceability of all network modifications, including operation status, timestamps, and before/after values
- **Optimized Dependencies** : Updated reports to use smaller dependencies for improved performance

#### Improvements

- **Reference Node Property** : Changed zone reference node identification from “Info” property to “ReferenceNodeName” property for better compatibility with SAInt zone objects
- **Plugin Form Enhancements** : Improved plugin user interface form with better organization and usability
- **Default Output Naming** : Output zonal network files now use “\_ZONAL” suffix by default (e.g., “network.enet” → “network\_ZONAL.enet”)

#### Bug Fixes

- **Object Reference Bug** : Fixed object reference issues that could cause errors during network updates
- **Divide by Zero Handling** : Improved handling of divide-by-zero scenarios in capacity calculations, including proper handling when ISF = 0 (sets capacity ratio to infinity) and when minimum capacity ratio is infinity with zero ISF sum (sets capacity to 0.0)
- **Network Naming** : Fixed output network file naming to properly use zonal naming convention