Skip to main content
Version: 0.5.0

How to Run a Model Calibration Work Package

This page provides a guide for network model calibration within the Hosting Capacity Module. It yields a table of tap settings for each off-load transformer, which can then be used in future work packages to run time-series modeling with the inferred tap positions. It also produces a set of raw results per energy consumer highlighting modelled (simulated) and measured (real) voltages, which can be used to for debugging and further analysis.

Prerequisites

See the How to Run a Work Package guide for prerequisites on basic Work Package setup, which are the same for running a Model Calibration Work Package.

See the Model Calibration Methodology page for a detailed overview of the calibration process, including data requirements.

How to run

Option 1: Using GraphQL​

Run a GraphQL query to start a Model Calibration Work Package.

mutation {runCalibration(calibrationName: "tap_settings_42", calibrationTimeLocal: "2025-01-15T00:00:00" , feeders: ["feeder1", "feeder2", "feeder3etc"])}

This will start a Model Calibration Work Package with the specified name and local time, for all feeders in the network model.

Parameters to change:

  • calibrationName is a unique identifier for the calibration
  • calibrationTimeLocal is the local time of the calibration in ISO 8601 format (it should not have a timezone offset, as the calibration time is assumed to be in the local timezone of the network model, which is set up in the underlying model)
  • feeders is an array of feeder identifiers to run the calibration on. If you want to run the calibration on all feeders in the network model, you can omit this parameter.

Option 2: Using the Python API​

In the eas-client-python client, run:

run_hosting_capacity_calibration(`calibration_name`, `local_calibration_time`,["`feeder1`", "`feeder2`", "`feeder3etc`"])

This will start a Model Calibration Work Package with the specified name and local time, for all feeders in the network model.

Parameters to change:

  • calibration_name is a unique identifier for the calibration
  • local_calibration_time is the local time of the calibration in ISO 8601 format (it should not have a timezone offset, as the calibration time is assumed to be in the local timezone of the network model, which is set up in the underlying model)
  • ["feeder1", "feeder2", "feeder3etc"] is an array of feeder identifiers to run the calibration on. If you want to run the calibration on all feeders in the network model, you can omit this parameter.
note

Make sure the time you specify has available PQV data in the database, otherwise the calibration will not run successfully. Not all times will have PQV data available, and will depend on the data you have ingested into the system. To see details of how the PQV data was used, see the logs for detailed information on an individual calibration run. Contact Zepben support if you need help with this.

caution

Only one set of calibration results can be used on a given Work Package. When running a Work Package, ensure you use calibration results that include all feeders present in the Work Package

Using the results​

Tap settings​

The tap settings from a calibration run are stored in the input database (input as they form part of the inputs to a regular work package), in a table called calibrated_taps. See the Calibrated Taps Table in the Input Tables section for a full breakdown. These can then be called by their unique name in a Work Package config for use in that Work Package.

Raw Results​

The raw results of the calibration run are stored in the calibration_meter_results table, which is stored in the results database. See the Calibration Meter results in the Results Tables section for a full breakdown.

For more info see the Model Calibration Methodology page, which provides a detailed overview of the calibration process, including data ingestion, model adjustments, load flow execution, and off-load tap position determination.

And the What is Network Model Calibration and why is it useful? page for an overview of the concepts behind network model calibration, its importance, and how it can be applied to improve the accuracy of power system models.