How to run a work package

This section provides guidance on how to interact with the Hosting Capacity Service by using our Python library. As an end user, you will programmatically interact with the service through the Energy Workbench Client Python Library which offers an interface to manage time series modelling jobs, known as work packages.

Work Packages

What is a Work Package?

A work package is a structured configuration that encapsulates all the information required to execute a specific time-series modelling run. It serves as a blueprint for defining the parameters and scope of the task. The extent of the network to be modelled for a given work package can vary across three dimensions: scenarios (different assumptions about load and generation forecasts), time period (years) and geographical area (ie feeders). Internally we call these SYF, for Scenarios, Years, and Feeders.

Configuration Elements

Configuration elements differ depending on the type of work package you want to run. At a high level, each work package is built from the following mutations:

Standard Work Package

Use a standard work package for forecast-based hosting capacity modelling across selected feeders, years, scenarios and time periods.

• Forecast Config: Defines the feeders, years, scenarios and time period for the forecast run, covering the study scope and historical load period.
• Generator Config: Controls OpenDSS model generation, covering model settings, solve settings and raw result outputs.
• Result Processor Config: Controls result processing, including performance metrics, writer settings and stored outputs.

Intrinsic Work Package

Use an intrinsic work package to assess capacity across LV customers by applying injections against configured network constraints.

• Allocation Config: Defines how capacity is allocated across included customers. Customers can apply the same kW increment to each included customer, or weight increments by existing import or export capacity. Uniform allocation is the simplest option; weighted allocation is useful when larger existing customers should receive proportionally larger increments.
• Constraints Config: Defines HV and LV thermal and voltage limits. Customers choose whether voltage limits, thermal limits or both should constrain the result, and can adjust voltage bounds, thermal rating basis and rating percentage to match their planning standard.
• Initial State Selector Config: Selects the initial state used to build the study. A classic intrinsic export study starts from a zero-load and zero-existing-DER baseline. A headroom-style study starts from an existing or forecast operating condition, usually selected from a reference scenario, reference year and fixed timestamp or peak-condition selector.
• Injection Resource Config: Defines the resource used for intrinsic capacity modelling, including whether the study is testing additional export generation, such as solar or battery export, or additional import load, such as electrification load. Customers can choose the supported resource representation, power factor and whether injection follows customer phases.
• Model Config: Sets model generation options, including voltage limits, load and generation ratios, regulator settings and other model translation settings.
• Results Writer Config: Defines where intrinsic results are written. Customers can write only the primary group-level results, or also write customer allocation details, violation details and debug snapshots. Violation details are useful when the customer needs to explain which asset or voltage limit constrained the result.
• Search Config: Controls how the intrinsic capacity search is performed, including the capacity step size per customer and the maximum number of search steps. Smaller steps give a more precise result but take longer to run.
• Solve Config: Defines solver settings for the snapshot model run, including iteration limits and convergence settings.
• SYF Config: Defines the feeders, scenarios and years to include. For intrinsic studies, this sets the study scope and can also support batching or reference selection where applicable.

High-Voltage Node Headroom Work Package

Use a high-voltage node headroom work package to assess available headroom at selected HV node locations.

• Constraints Config: Defines thermal and voltage constraints, including HV/LV thermal headroom limits and voltage bounds. Customers can use HV-only checks for a node-level planning view, or include LV checks when downstream LV effects should also limit the answer.
• Initial State Selector Config: Selects the initial state used to build the study. Customers choose the timestamp to use as the starting point for the run, and whether existing load and existing DER are included in that base condition. Including both gives a headroom result relative to the selected planning state.
• Injection Resource Config: Defines the resource used for headroom modelling, including whether the selected HV node is being tested for additional export headroom or additional import headroom. Export headroom tests how much generation can be added at the node; import headroom tests how much load can be added at the node.
• Model Config: Sets model generation options, including voltage limits, load and generation ratios, regulator settings and other model translation settings.
• Node Location Selector: Defines which HV node locations to assess, such as distribution transformer HV terminals, upstream switch terminals or line tee points. This work package is node-based, so the result is reported per selected location rather than per LV customer group.
• Search Config: Controls how the HV node headroom search is performed, including the capacity step size per node and the maximum number of search steps. The reported headroom is the last non-violating step before the first binding constraint, non-convergence event or configured search limit.
• Solve Config: Defines solver settings for the snapshot model run, including iteration limits and convergence settings.
• SYF Config: Defines the feeders, scenarios and years to include. For headroom studies, the selected scenario, year and operating timestamp define the base planning state used before additional import or export is applied.

For more comprehensive guidance on configuring and utilising work packages effectively, please refer to the Configuration documentation.

Prerequisites

Before you get started, ensure you have the following prerequisites in place:

1. Credentials: You need valid credentials to authenticate with the Energy Workbench server. All interactions with the Hosting Capacity Service occur through the Energy Workbench server. Contact Zepben to obtain your credentials.

2. Python Installed: Your system should have Python version 3.10 or higher (3.12 recommended). If not, see How to install python. The rest of this guide assumes you have Python installed and configured correctly and that you have a basic understanding of how to use Python.

3. Energy Workbench Python Client Library Installed: Install the latest version of the zepben.eas Python library using pip:

pip install zepben.eas

For a basic Python script setup example to interact with the Hosting Capacity Service, visit our GitHub repository.

Getting Started

Now that you have everything set up, you are ready to use the Hosting Capacity Service.

1. Import the EasClient class by adding the following line at the top of your script:

from zepben.eas.client.eas_client import EasClient

2. Create an instance of the EasClient by providing your credentials. All parameters are keyword-only:

client = EasClient(
    host=eas_server_host,
    port=eas_server_port,
    protocol=eas_server_protocol,        # "https" by default
    access_token=eas_server_access_token,
    verify_certificate=eas_server_verify_certificate,
    ca_filename=eas_server_ca_filename,
)

The access_token is a personal access token (or machine token) generated in the Energy Workbench UI under your profile settings. The token role must be either SUPER_ADMIN or MODELLER.

note

Personal access tokens expire every 30 days, so you will need to update yours periodically.

3. You are now ready to use the EasClient to interact with the Hosting Capacity Service.

Run a Work Package

To start a hosting capacity modelling job (referred to as a work package), call the appropriate mutation method and pass the input object with job details.

There are three hosting capacity work package mutations:

• run_work_package: Runs a standard hosting capacity work package.
• run_intrinsic_work_package: Runs an intrinsic hosting capacity work package.
• run_hv_node_headroom_work_package: Runs a high-voltage node headroom work package.

The examples below show the top-level input objects used by each mutation. The nested configuration values are omitted here for conciseness.

Run a standard work package

Use run_work_package for a standard hosting capacity run:

result = client.mutation(Mutation.run_work_package(
    WorkPackageInput(
        forecastConfig=ForecastConfigInput(...),
        generatorConfig=HcGeneratorConfigInput(...),
        resultProcessorConfig=HcResultProcessorConfigInput(...)
    ),
    work_package_name="normal-wp"
))

Run an intrinsic work package

Use run_intrinsic_work_package for intrinsic hosting capacity analysis:

result = client.mutation(Mutation.run_intrinsic_work_package(
    IntrinsicWorkPackageInput(
        allocationConfig=IntrinsicAllocationConfigInput(...),
        constraintsConfig=IntrinsicConstraintsConfigInput(...),
        searchConfig=IntrinsicSearchConfigInput(...),
        injectionResourceConfig=IntrinsicInjectionResourceConfigInput(...),
        modelConfig=HcModelConfigInput(...),
        solveConfig=HcSolveConfigInput(...),
        syfConfig=IntrinsicSyfConfigInput(...),
        initialStateSelectorConfig=IntrinsicInitialLoadStateConfigInput(...),
        resultsWriterConfig=IntrinsicWriterConfigInput(...)
    ),
    work_package_name="intrinsic-wp"
))

Run a high-voltage node headroom work package

Use run_hv_node_headroom_work_package for HV node headroom analysis:

result = client.mutation(Mutation.run_hv_node_headroom_work_package(
    HvNodeHeadroomWorkPackageInput(
        constraintsConfig=IntrinsicConstraintsConfigInput(...),
        searchConfig=HvNodeHeadroomSearchConfigInput(...),
        injectionResourceConfig=IntrinsicInjectionResourceConfigInput(...),
        modelConfig=HcModelConfigInput(...),
        solveConfig=HcSolveConfigInput(...),
        nodeLocationSelector=HvNodeLocationSelectorInput(...),
        syfConfig=IntrinsicSyfConfigInput(...),
        initialStateSelectorConfig=IntrinsicInitialLoadStateConfigInput(...)
    ),
    work_package_name="hv-headroom-wp"
))

Each mutation starts a modelling job and returns either a UUID as a reference for your work package or a list of errors if the job could not be started. Note that the work_package_name is an arbitrary label for your run and can be any name that helps you identify it later.

Check Currently Running Jobs and Their Progress

To check the progress of currently running work packages, use the get_hosting_capacity_work_packages_progress method:

result = client.get_hosting_capacity_work_packages_progress()

This method returns an object displaying all work packages currently being processed by the Hosting Capacity Service.

Example:

{
    "pending": ["wp2", "wp3"],
    "inProgress": [
        {
            "id": "wp1",
            "progressPercent": 10,
            "pending": ["feeder10"],
            "generation": ["feeder8", "feeder9"],
            "execution": ["feeder7"],
            "resultProcessing": ["feeder5", "feeder6"],
            "failureProcessing": ["feeder2","feeder3","feeder4"],
            "complete": ["feeder1"]
        }
    ]
}

Cancel a Work Package

To cancel a work package currently being processed, call the cancel_hosting_capacity_work_package method and provide the work package UUID:

result = client.cancel_hosting_capacity_work_package(work_package_id)

If you encounter any issues or have questions, contact Zepben support.