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 Network Explorer Python SDK which offers an interface to manage time series modeling jobs, known as work packages.

note

EAS stands for the Evolve App Server, which is the Zepben backend service that powers the Network Explorer. You will see references to EAS throughout this documentation, which can be treated as synonymous with the Network Explorer.

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

Within a work package, various key elements can be specified to tailor your time series modeling:

• Selected Feeders: Choose which feeders to include in the modeling run, enabling you to focus on specific segments of your network.

• Scenarios: Define the scenarios to be used in the modeling, allowing you to simulate different conditions such as load forecasts, generation profiles, and other variables that may impact the network's performance.

• Timeframe Selection: Specify the years to be used for modeling, allowing you to target particular periods of interest to use as a base for forecasting.

• Results Handling: Configure how the results are managed, including options such as running quality assurance checks and selecting which parts of the results to store.

• Model Generation Details: Customize the modeling process by specifying options like whether to collapse SWER (Single Wire Earth Return) systems or defining the precise location of meters for result measurement.

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

Prerequisites

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

1. Credentials: You need valid credentials to authenticate with the EAS server. All interactions with the Hosting Capacity Service occur through the EAS server. Please talk to the Zepben team to obtain your credentials.

2. Python Installed: Your system should have Python version 3.7 or higher. 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. Python EAS 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, let's get started with the Hosting Capacity Service.

1. Import the EasClient Class

In your Python project, import the EasClient class by adding the following line at the top of your script:

from zepben.eas.client.eas_client import EasClient

2. Initialize the EasClient

Create an instance of the EasClient by providing your credentials:

client = EasClient(
    host=eas_server_host,
    port=eas_server_port,
    protocol=eas_server_protocol,
    client_id=eas_server_client_id,
    username=eas_server_username,
    password=eas_server_password,
    client_secret=eas_server_client_secret,
    verify_certificate=eas_server_verify_certificate,
    ca_filename=eas_server_ca_filename,
)

3. Interact with the Hosting Capacity Service

You're now ready to use the EasClient to interact with the Hosting Capacity Service and accomplish your tasks.

Run a Work Package

To start a time series modeling job (referred to as a work package), call the run_hosting_capacity_work_package method by passing a WorkPackageConfig instance with job details:

result = client.run_hosting_capacity_work_package(
    WorkPackageConfig(
        feeders,
        years,
        scenarios
    )
)

This method starts a modeling job and returns either a UUID as a reference for your work package or a list of errors if the job couldn't be started.

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, don't hesitate to reach out to our support team for assistance.