How to run an HV Node Headroom Work Package

Paid Feature - Only available for some customers

This feature is only available to certain customers. If you are interested in using this feature, please contact Zepben for more information.

This guide shows a basic Python example for starting an HV node headroom work package through the Energy Workbench Python client.

An HV node headroom work package estimates headroom at selected HV node locations. It uses the same feeder/year/scenario scope, initial load state, injection resource, constraints, model configuration, and solve configuration patterns as an LV Hosting Capacity work package. For a conceptual overview of how both modes work, see What is Intrinsic Hosting Capacity Mode?.

In this mode, HCM finds every HV node in the selected feeders that matches the configured nodeLocationSelector types. It tests those HV nodes one at a time by injecting additional load or generation at that point in the network until that node's headroom is found. That additional load or generation is then removed before the next HV node is tested.

Minimal Example

Create an EasClient, build an HvNodeHeadroomWorkPackageInput, then submit it using Mutation.run_hv_node_headroom_work_package.

from datetime import datetime

import asyncio
from zepben.eas.client.eas_client import EasClient
from zepben.eas import (
    Mutation,
    HvNodeHeadroomWorkPackageInput,
    IntrinsicInitialLoadStateConfigInput,
    IntrinsicInitialStateSelectorMode,
    IntrinsicSyfConfigInput,
)

client = EasClient(
    host=eas_server_host,
    port=eas_server_port,
    protocol=eas_server_protocol,
    access_token=eas_server_access_token,
    verify_certificate=eas_server_verify_certificate,
    ca_filename=eas_server_ca_filename,
)

work_package = HvNodeHeadroomWorkPackageInput(
    syf=IntrinsicSyfConfigInput(
        feeders=["feeder-mrid-1"],
        scenario="base",
        year=2030,
    ),
    initialStateSelector=IntrinsicInitialLoadStateConfigInput(
        selectorMode=IntrinsicInitialStateSelectorMode.FIXED_TIME,
        startTime=datetime.fromisoformat("2030-01-01T12:00:00"),
        includeLoads=True,
        includeExistingDer=True,
        loadScalingFactor=1.0,
        derScalingFactor=1.0,
    ),
)

async def main():
    result = await client.mutation(
        Mutation.run_hv_node_headroom_work_package(
            work_package,
            work_package_name="Example HV node headroom work package",
        )
    )
    print(result)

asyncio.run(main())

The mutation returns the new work package ID if the request is accepted.

Shared Configuration

HV node headroom work packages reuse these inputs from intrinsic work packages:

Field	Notes
syf	Same feeder, year, and scenario input as intrinsic work packages. See SYF Config.
initialStateSelector	Same initial load state selector as intrinsic work packages. See Initial State Selector Config.
injectionResource	Same injection resource input as intrinsic work packages. See Injection Resource Config.
constraints	Same voltage and thermal constraint input as intrinsic work packages. See Constraints Config.
model	Uses the same model configuration input as a normal hosting capacity work package.
solve	Uses the same solve configuration input as the intrinsic and normal hosting capacity work package inputs.

HV-Specific Configuration

Search Config

Use search to control the HV node headroom search.

work_package.search = HvNodeHeadroomSearchConfigInput(
    stepKwPerNode=5.0,
    maxStepsPerNode=1000,
)

Field	Default	Restriction
stepKwPerNode	1.0	Optional search increment in kW per node.
maxStepsPerNode	1000	Must be 1000 or less.

HV Node Location Selector Config

Use nodeLocationSelector to choose which HV node locations are included in the headroom calculation.

work_package.nodeLocationSelector = HvNodeLocationSelectorInput(
    locationKinds=[
        HvNodeLocationKind.DTX_HV_TERMINAL,
        HvNodeLocationKind.LINE_TEE,
    ],
)

Field	Default	Notes
locationKinds	[DTX_HV_TERMINAL]	Optional list of HV node location kinds to include.

Supported locationKinds values:

• DTX_HV_TERMINAL
• SWITCH_UPSTREAM_TERMINAL
• LINE_TEE

Monitoring The Run

After the mutation returns a work package ID, use the standard work package manager or progress APIs described in How to run a work package and How to manage work packages.

Understanding the Results

Once the work package completes, results are written to the Intrinsic Hosting Capacity output tables. HV node headroom runs produce the hv_node_headroom, binding_constraints, and constraint_violations tables. Note that lv_group_hosting_capacity and customer_allocations are not produced by HV node headroom runs.

For guidance on interpreting results — including headroom values, max-steps behaviour, and tracing binding constraints — see Understanding Intrinsic Results.