Work Package Configuration Options
There are various elements that must be configured to successfully create a OpenDSS model from the input data, which are then used to run a Hosting Capacity Model work package. This page describes the configuration options available in running a Work Package via the Python API.
This section outlines how the Hosting Capacity Module work packages are configured. These work packages represent a 'job' within the Hosting Capacity Module, and have a defined sets of scope and configuration:
The scope of the modelling to be undertaken is defined as the overall WorkPackageConfig object, which includes:
- A name for the work package
- A syf_config object, which defines the scope of the work package in terms of:
- Scenarios (in terms of the set(s) of uptake forecasts to be used)
- Years (in terms of the calendar years to model or forecast)
- Feeders (In terms of a list of feeders to model)
- A time period that defines a set of AMI load data, which is to be used as the basis for the work package and adjusted by the selected forecasts.
- A generator_config object, which defines how the underlying power flow model are to be generated and solved, including:
- Model configuration (in terms of how the power flow model is to be built, including what 'fixes' are to be applied to the model to help give better results from incomplete or inaccurate data)
- Solve configuration (in terms of how the power flow model is to be solved)
- Raw results configuration (in terms of what raw results are to be written out to storage)
- Node Level Results Config (in terms of what node level results are to be included during the power flow solve)
- A result_processor_config object, which defines how the results of the work package are to be processed and written out, including:
- Writer configuration, which controls what metrics are included, and how they are to be stored (although generally your administrator will have only deployed one output/storage option as part of deployment)
- Stored results configuration (in terms of what stored results are to be written out)
- Metrics configuration (in terms of what metrics are to be calculated and written out)
- A parameter called
quality_assurance_processingthat is part of the umbrella WorkPackage Config object, which is used to enable extra reporting in the raw OpenDSS file, and is only relevant in the context of the OpenDSS Exporting.
Examples
Detailed Option Descriptions and Defaults
The default values listed below are the base HCM defaults, and may be overridden based on your deployment. Please check with Zepben for any questions
Work Package Config
The Work Package Config is the main configuration object that contains all the necessary configurations for running a Hosting Capacity Model work package. It includes the forecast configuration, generator configuration, result processor configuration, and quality assurance processing flag (quality_assurance_processing).
SYFConfig Parameters
The SYFConfig object is used to define the SYF (scenario, year, feeder) and time parameters for the work package.
It can be one of two types — a ForecastConfig or a FeederConfig. These have very similar structures and parameters. The ForecastConfig is used to define the SYF that applies to all feeders in a given work package, while the FeederConfigs allows for individual SYF and time parameters for each feeder in the work package.
Note that base scenario is a hardcoded scenario that is always included in addition to any scenarios you provide in the configuration. The base scenario represents the current state of the network without any additional DER uptake, and is used as a reference point for comparing the impact of other scenarios. Naming a scenario base will cause issues and is not recommended.
GeneratorConfig Parameters
The GeneratorConfig object is used to define the configuration for generating the power flow models. It includes the model configuration, solve configuration, and raw results configuration.
Model Config Parameters
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| vm_pu | float | 1.0 | The per unit voltage of the energy source defined at the head of the feeder within each feeder model. Depreciated in favour of the 4 more specific values below |
| load_vmin_pu | float | 0.80 | Minimum per unit voltage for which the load model selected is assumed to apply. Below this value, the load model reverts to a constant impedance model. |
| load_vmax_pu | float | 1.15 | Maximum per unit voltage for which the load model selected is assumed to apply. Above this value, the load model reverts to a constant impedance model. |
| gen_vmin_pu | float | 0.70 | Minimum per unit voltage for which the generator model selected is assumed to apply. Below this value, the generator model reverts to a constant impedance model. |
| gen_vmax_pu | float | 2.00 | Maximum per unit voltage for which the generator model selected is assumed to apply. Above this value, the generator model reverts to a constant impedance model. |
| load_model | int | 1 | Load/generator modeling mode (1 to 7): Specifies how loads and generators in OpenDSS should be modelled. Options: 1: Standard constant P+jQ load. (Default) 2: Constant impedance load. 3: Const P, Quadratic Q (like a motor). 4: Nominal Linear P, Quadratic Q (feeder mix). Use this with CVRfactor. 5: Constant Current Magnitude 6: Const P, Fixed Q 7: Const P, Fixed Impedance Q. |
| collapse_swer | bool | false | Flag to control the collapse of SWER networks back to their Isolation Transformers, to simplify models. |
| calibration | bool | false | Apply calibration using PQV data. |
| use_span_level_threshold | bool | false | Controls whether the system uses span level ratings (designedrating from CIM) or only normal current rating (ratedcurrent from CIM) values during the Rating Normalising step. Warning: When enabling this feature (setting to true), ensure you also set an appropriate rating_threshold value between 0 and 100 (e.g., 5 for 5%). |
| rating_threshold | float | 0.0 | Percentage threshold used for current rating comparisons in the network normaliser. Value should be between 0 and 100, where 5 = 5%, 12.5 = 12.5%, etc. A value of 0 (0%) finds exact matches only, while higher values allow for more network simplification and thus faster solve times. Valid range: 0.0 to 100.0 (values higher than ~10 could lead to model oversimplification). See detailed section below for more information. |
| simplify_plsi_threshold | float | 0.0 | Percentage threshold used for PerLengthSequenceImpedance (PLSI) comparisons in the network normaliser. Value should be between 0 and 100, where 5 = 5%, 12.5 = 12.5%, etc. A value of 0 (0%) finds exact matches only, while higher values allow for more network simplification and thus faster solve times. Valid range: 0.0 to 100.0 (values higher than ~10 could lead to model oversimplification). See detailed section below for more information. |
| p_factor_forecast_pv | float | 1.0 | Power factor to set for scenario (forecast) model Generators during model translation. |
| p_factor_base_imports | float | null | Power factor to set for base model Loads during model translation. If null the model will use the reactive power specified in the load profiles. |
| fix_single_phase_loads | bool | true | Finds consumers with a peak load (within the modelled time period) greater than the configured max_single_phase_load value. Upgrades these consumers to three-phase loads to correct data inaccuracies in reported phase numbers. Traces upstream to the distribution transformer and spreads 3 phases (ABCN) back to the transformer where possible. |
| max_single_phase_load | float | 30000.0 | The max peak load for a single phase customer, beyond which will trigger the single phase load fixing algorithm mentioned above. |
| fix_overloading_consumers | bool | true | Finds consumers that have peak load or generation (within the modelled time period) greater than the capacity of the transformer they are attached to by a configurable factor, and then reconfigures them to be HV consumers (attached above the transformer). The aim is to identify HV consumers that have been incorrectly connected as LV consumers, and resolve this connectivity. |
| max_load_tx_ratio | float | 3.0 | The maximum load to transformer rating ratio for a single consumer to trigger the overloading consumer fixer. For a ratio of 2, if a customer with a peak 30kW load was downstream of a 10kVA transformer, this would be a ratio of 3:1 and thus trigger the overloading consumers fixer. |
| max_gen_tx_ratio | float | 10.0 | The maximum generation to transformer rating ratio for a single consumer to trigger the overloading consumer fixer. For a ratio of 2, if a customer with peak generation of 30kW was downstream of a 10kVA transformer, this would be a ratio of 3:1 and thus trigger the overloading consumers fixer. |
| fix_undersized_service_lines | bool | true | Finds consumers that have a peak load (within the modelled time period) greater than the capacity of the service line of the consumer by a configured factor. The intent is to find service lines that have unrealistically low current ratings which would stop convergence, and upgrade them to sensible ratings. When a conductors rating is upgraded, the impedance is also upgraded to match, utilising a pre-configured catalogue of rating and impedance data, and matching the phase configuration of the consumer. |
| max_load_service_line_ratio | float | 1.5 | The maximum load to service line rating ratio to trigger the undersized service lines fixer. For example given a ratio of 2, if a customer with peak load of 10kW had a service line supporting only 5kVA, this would be a ratio of 2:1 and thus trigger the undersized service line fixer. Note: service lines are generally considered to be the conductors immediately connecting to a consumer. |
| max_load_lv_line_ratio | float | 2.0 | The maximum load to LV line rating ratio to trigger the undersized service lines fixer for LV conductors. For example given a ratio of 5, if a customer with peak load of 50kW was connected to LV backbone conductors supporting only 10kVA, this would be a ratio of 5:1 and thus trigger the undersized service line fixer for the LV conductors. Note the LV line fixer will fix all conductors upstream of the consumer up to the distribution transformer they are connected to. |
| collapse_lv_networks | bool | false | Flag to control whether to collapse lv network in the model. |
| feeder_scenario_allocation_strategy | str | ADDITIVE | Strategy for scenario ev, pv and bess allocation. ADDITIVE will be each year is built upon the last years allocation, while RANDOM will be a different allocation every year |
| closed_loop_v_reg_enabled | bool | true | Create models with a Closed Loop Voltage Regulator at the Zone sub. If false, existing voltage regulator's in the zone sub will be used. |
| closed_loop_v_reg_replace_all | bool | true | Replace all existing Voltage Regulators with Closed Loop Voltage Regulator. If false existing zone sub regulators will be modelled as-is which may be in non-closed loop configuration. |
| closed_loop_v_reg_set_point | float | 0.985 | Scaling factor for the base voltage to form the set point (0.0-2.0). |
| closed_loop_v_band | float | 2.0 | VBand value in percentage. |
| closed_loop_time_delay | int | 100 | Time delay (seconds) for closed loop control |
| closed_loop_v_limit | float | 1.1 | Maximum voltage at regulating transformer's secondary bus. |
| default_tap_changer_time_delay | int | 100 | Tap changer time delay (seconds). |
| default_tap_changer_set_point_pu | float | 1.0 | Tap changer set point. |
| default_tap_changer_band | float | 2.0 | Tap changer band value. |
| split_phase_default_load_loss_percentage | float | 0.4 | Load loss % for split-phase transformers. |
| split_phase_lv_kv | float | 0.25 | Split phase LV voltage. |
| swer_voltage_to_line_voltage | List[List[int]] | [230,400] [240,415] [250,433] [6350,11000] [6400,11000] [12700,22000] [19100,33000] | Mapping SWER voltages to line-to-line. |
| load_placement | LoadPlacement | PER_USAGE_POINT | Create loads per UsagePoint (PER_ENERGY_CONSUMER) or EnergyConsumer (PER_ENERGY_CONSUMER) |
| load_interval_length_hours | float | 0.5 | Load interval in fractions of an hour, 1.0 = 60 minute intervals, 0.5 = 30 minute intervals |
| meter_placement_config | MeterPlacementConfig | MeterPlacementConfig() | Configuration to determine where to place EnergyMeters for collecting results, see below for details. |
| seed | int | null | A seed to use when generating the model. Re-using the same seed will result in the same model being generated.This mainly controls the random scattering of DER devices such as solar and batteries within a feeder, matching the forecasts provided. |
| transformer_tap_settings | str | null | The name of the set of distribution transformer tap settings to be applied to the model from the Calibration results. If null, tap settings from the network model will be applied. |
| ctPrimScalingFactor | float | null | The scaling factor to apply to the primary current of CTs in the model. This is used to adjust the primary current readings to match the expected primary current of the transformer. |
| simplify_network | bool | true | Flag to control whether to the network model simplifcation steps will run, as configured in other parameters. If this is False, then other values will be overridden and no network collapsing, simplifiying or normalising will occur. |
| collapse_negligible_impedances | bool | true | Flag to control whether to collapse conductors with negligible impedance during network simplification. Negligible means either Line Resistance is less than 0.001 Ohms OR Line Reactance is less than 0.001 Ohms. This is useful for removing very short sections of line that are not significant to the model. 0.001 Ohms is the default, and can be changed on a per environment level, contact Zepben. This was previously an implicit step of model building and always true, now configurable. Leaving it to true is recommended. |
| combine_common_impedances | bool | true | Flag to control whether to combine conductors with common impedance during network simplification. This was previously an implicit step of model building and always true, now configurable. Leaving it to true is recommended. If this is false, other parameters that control common impedance collapsing will not run. |
| emergAmpScaling | float | 1.5 | Scaling factor for emergency current rating in lineCodes (Defaults to 1.5, which means the emergency threshold is 150% of normal current threshold). |
Meter Placement Config
The Meter Placement Config is used to determine where to place EnergyMeters for collecting results (where the measurement zones are). It includes the type of placement and the configuration for the placement.
::: If a downstream trace encounters an LV circuit loop (where tracing returns to the original fuse), the system detects this condition and creates the measurement_zone at the transformer only, excluding downstream fuses. This ensures consistent, reproducible measurement_zones across multiple runs. :::
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| feeder_head | bool | true | Whether to place a meter at the voltage source at the feeder head. |
| dist_transformers | bool | true | Whether to place a meter at the secondary winding of each distribution transformer. |
| switch_meter_placement_configs | List[SwitchMeterPlacementConfig] | null | Specifies which switch classes to place meters at, and the regex pattern to match for in the switch names. See below for details. |
| energy_consumer_meter_group | str | null | The ID of the meter group to use for populating EnergyMeters at EnergyConsumers, as per the meter_group_id of the energy_consumer_meters input table. For more information, see the Energy Consumer Meters section of the Input Tables documentation. |
SwitchMeterPlacementConfig
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| meter_switch_class | SwitchClass | null | The CIM class of Switch to create meters at. Options are BREAKER, DISCONNECTOR, FUSE, JUMPER, LOAD_BREAK_SWITCH or RECLOSER |
| name_pattern | str | null | A Regex pattern to match on for Switch names. Eg, ".Circuit Head Switch." and DISCONNECTOR set for meter_switch_class places energy meters (and thus measurement zones) on all switches of class 'DISCONNECTOR' with a name that includes the string 'Circuit Head Switch' in it. See https://regexr.com/ for more information on regular expressions and to test that your pattern matches your needs. |
Solve Config
The Solve config related to options used in the OpenDSS model.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| norm_vmin_pu | float | 0.9 | Normal minimum per unit voltage. |
| norm_vmax_pu | float | 1.054 | Normal maximum per unit voltage. |
| emerg_vmin_pu | float | 0.8 | Emergency minimum per unit voltage. |
| emerg_vmax_pu | float | 1.1 | Emergency maximum per unit voltage. |
| base_frequency | int | 50 | Base frequency for the simulation, in Hz |
| voltage_bases | List[float] | (0.4, 0.433, 6.6, 11.0, 22.0, 33.0, 66.0, 132.0) | List of voltage base values, in kV |
| max_iter | int | 25 | Max solve iterations to run in the underlying OpenDSS simulation before failing. |
| max_control_iter | int | 20 | Max control iterations to run in the underlying OpenDSS before failing. |
| mode | str | YEARLY | Run OpenDSS in YEARLY or DAILY mode. |
| step_size_minutes | float | 60 | The step size for the solver in minutes. |
Raw Results Config
Whether to produce raw results generated from OpenDSS. You will likely always want defaults for this, as setting any of these to False will limit the results you get and should only be used as a potential performance optimisation if they are unnecessary.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| energy_meter_voltages_raw | bool | True | Produce energy meter voltages results. |
| energy_meters_raw | bool | True | Produce energy meter results. |
| results_per_meter | bool | True | Produce results per EnergyMeter. |
| overloads_raw | bool | True | Produce overloads. |
| voltage_exceptions_raw | bool | True | Produce voltage exceptions. |
NodeLevelResultsConfig Parameters
This sections controls how the node_level_results table is populated. If any of the last 5 values are not null/false, the table will be populated, otherwise it will not. It is used to collect results at specific nodes in the network, such as switches, transformers, conductors and energy consumers. This table is independant from all other output tables, they can be turned on or off and it will have no impact on the Node Level Results table, and vice versa.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| collect_voltage | bool | true | Include voltage values in node level results. |
| collect_current | bool | true | Include current values in node level results. |
| collect_power | bool | true | Include power values in node level results. |
| mrids_to_collect | List[str] | null | A list of MRIDs to collect node level results at. Note: Depending on network simplification and translation, these MRIDs may not exist in the final OpenDSS and no results will be collected in that case. Note that if running work package across multiple feeders, this will generate a lot of logs as the MRIDs won't be found on feeders they are not in, but the core functionality will still work. |
| collect_all_switches | bool | false | Collect node level results at all switches in the feeders that are part of this work package. |
| collect_all_transformers | bool | false | Collect node level results at all transformers in the feeders that are part of this work package. |
| collect_all_conductors | bool | false | Collect node level results at all conductors in the feeders that are part of this work package. |
| collect_all_energy_consumers | bool | false | Collect node level results at all energy consumers in the feeders that are part of this work package. |
Note: depending on the settings used for collapsing and simplifying switches, transformers and conductors, the results collected may not match 1:1 with the objects in the CIM model, as some may have been collapsed or simplified away (particularly conductors). If you want to ensure results are collected at every single location, you should set simplify_network to false in the GeneratorConfig.
ResultProcessorConfig
The Result Processor Config is used to configure how the results of the work package are processed and stored. Includes sub-configs; WriterConfig (containing the WriterOutputConfig, which itself contains the EnhancedMetricsConfig), the StoredResultsConfig and MetricsResultsConfig.
WriterConfig
The Writer Config is used to configure how the results of the work package are written. It includes the type of writer (Postgres or Parquet) and the configuration for the output writer.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| writer_type | WriterType | POSTGRES or PARQUET | Whether to write output to Parquet files or a Postgres database. Check with your administrator which result types are supported. |
| output_writer_config | WriterOutputConfig | The configuration for the output writer and which details to store. |
WriterOutputConfig contains only the EnhancedMetricsConfig, as below.
EnhancedMetricsConfig
The Enhanced Metrics Config is used to configure the Network Performance Metrics Enhanced table and what values will be stored in it.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| populate_enhanced_metrics | bool | True | Whether to populate enhanced metrics. |
| populate_enhanced_metrics_profile | bool | False | Whether to populate enhanced metrics profiles. |
| populate_duration_curves | bool | True | Whether to populate duration curves. |
| populate_constraints | bool | True | Whether to populate constraints. |
| populate_weekly_reports | bool | True | Whether to populate weekly reports. |
| calculate_normal_for_load_thermal | bool | True | Whether to calculate normal values for load thermal. |
| calculate_emerg_for_load_thermal | bool | True | Whether to calculate emergency values for load thermal. |
| calculate_normal_for_gen_thermal | bool | True | Whether to calculate normal values for generator thermal. |
| calculate_emerg_for_gen_thermal | bool | True | Whether to calculate emergency values for generator thermal. |
| calculate_co2 | bool | True | Whether to calculate CO₂ cost values. |
StoredResultsConfig
The Stored Results Config controls the raw results that will be stored.
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| energy_meter_voltages_raw | bool | False | Store the Output Table Energy Meter Voltages Raw](../reference/output-tables#energy-meter-voltages-raw). |
| energy_meters_raw | bool | False | Store the table Energy Meters Raw. |
| overloads_raw | bool | True | Store the table Overloads Raw. |
| voltage_exceptions_raw | bool | False | Store the table Voltage Exceptions Raw. |
Storing raw results will utilise a lot of storage space and should be done only very carefully, and likely avoided for large Work Packages.
MetricsResultsConfig
The Metrics Results Config controls the basic (and semi-depreciated) Network Performance Metrics table. It contains a single boolean value to determine whether to populate the table.