Work Package Configuration details
This page contains information on certain configuration elements that require more explanation or discussion than the regular Work Package Configuration Options page provides.
Span Level Ratings and Improved Network Collapsing
This feature is only available to certain customers. If you are interested in using this feature, please contact Zepben for more information.
The Span Level Ratings feature enables more granular control over network model construction by utilising individual span ratings rather than predefined line type categories. The Improved Network Collapsing allows for faster solve times by collapsing similar network sections based on their electrical characteristics, instead of just exact matches as previously. The ratingThreshold and simplifyPLSIThreshold can be used with or without Span Level Ratings. It was introduced to manage the additional complexity that span level ratings introduces in terms of node count, and thus reduce solve time back to more manageable levels, but will also benefit models that do not use span level ratings.
Load Modelling Mode
When OpenDSS solves a power flow, it needs to know how each load behaves when voltage rises or falls. Different types of electrical equipment respond differently. A resistive heater draws less power at lower voltage, while some industrial equipment maintains roughly constant power draw across a wide range. This setting lets you choose which behaviour best represents the loads in your network, and affects both the accuracy of results and how reliably the model converges on networks with voltage stress.
Voltage Windows: loadVMinPu, loadVMaxPu, genVMinPu, genVMaxPu
Before describing each mode, it is important to understand these four parameters, as they interact directly with the load modelling mode. They define the per-unit voltage range within which each model's intended behaviour applies. Outside that range, OpenDSS falls back to constant impedance behaviour to keep the solution stable. For example, with loadVMinPu=0.9, any load bus solving below 0.9 pu will be treated as constant impedance regardless of the mode selected, meaning it will draw less power than specified, without any warning. The generator equivalents (genVMinPu, genVMaxPu) apply the same logic to generation assets. Setting these windows wider allows the intended load model to apply across a broader range of network conditions; setting them narrower causes more loads to fall back to constant impedance on stressed networks.
Mode 1 - Constant Power (Default)
The load draws its specified kW and kVAr regardless of voltage, within the window defined by loadVMinPu and loadVMaxPu. This is generally speaking the standard choice when load data comes from measured consumption such as smart meter interval data, as it uses those values directly. When using this mode it is worth checking solved voltages across the network, any buses outside the voltage window will deliver less load than specified.
Mode 2 - Constant Impedance
Power scales with voltage squared — a 10% voltage drop produces roughly a 19% reduction in power draw. This accurately represents purely resistive loads such as electric water heaters and ovens, and is generally speaking the most numerically stable mode. It is a reliable fallback if Mode 1 is causing convergence difficulties, though it will underestimate consumption in voltage-stressed areas. Note that the loadVMinPu / loadVMaxPu window has no practical effect in this mode, since constant impedance is already the fallback behaviour.
Mode 3 - 6
These modes are intended for advanced use cases and should only be used in niche use-cases within the HCM. Consult OpenDSS documentation for further information.
Mode 7 - Constant Power, Fixed Impedance Reactive Power
Real power is constant and reactive power varies through a fixed impedance characteristic. This is the mode OpenDSS uses internally for generators.
Which mode should I use?
For most Hosting Capacity studies, Mode 1 is the appropriate choice, as it directly honours your input load data and is consistent with smart meter interval data. If you encounter convergence problems on heavily loaded or low-voltage feeders, Mode 2 is a reliable fallback, with the understanding that results will be slightly conservative in stressed areas. Widening loadVMinPu and loadVMaxPu is often a better first step than switching modes, as it extends the range over which Mode 1 behaves as intended before falling back to constant impedance. The remaining modes are for specialist studies and are unlikely to be needed for standard hosting capacity analysis.
Missing Load Data Handling
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| windowFillMissingLoad | bool | true | Flag to control gap filling. If True, an interval with no meter reading takes the most recent reading from the same time of day. If False, intervals with no reading are left at zero. |
Every customer in the model is given a load profile of a fixed length: one full year of intervals at the configured loadIntervalLengthHours (17,520 intervals for the default 30 minute setting). Real meter data can have gaps, so the model generator needs a rule for the intervals where no reading exists. This setting chooses that rule. It only affects work packages that read load over a time period, as fixed time work packages read a single timestamp and have nothing to fill.
What it does:
With windowFillMissingLoad = true (the default), the model generator keeps a rolling cache of the last reading seen for each time-of-day slot. An interval with no reading is filled from that cache, so a gap takes the most recent value recorded at that same clock time. A single missing half hour is filled from the previous day, a whole missing day reproduces the previous day's shape, and a longer outage repeats the last complete day until readings resume. Any period before a customer's first reading falls back to zero, since no reading has been cached yet for those slots. That fallback is a fixed zero and is not configurable.
With windowFillMissingLoad = false, only intervals with an exact matching reading in the timeseries database are populated. Every other interval stays at zero.
Either way, the four reading directions (real import, real export, reactive import, reactive export) are handled independently, so a reading that only populates some channels only updates those channels.
defaultLoadWatts and friendsThe defaultLoadWatts, defaultGenWatts, defaultLoadVar and defaultGenVar profiles are a separate mechanism and are not affected by this setting. They are substituted when a customer has no readings at all in the modelled window. windowFillMissingLoad applies to customers that do have readings, but with gaps in them.
Which setting should I use?
Leave this as true for most studies. Gap filling is deliberately simple and does not adjust for weekday versus weekend, temperature, or seasonal effects, but it keeps each customer's annual energy roughly consistent with what was actually measured, and it avoids the solver seeing artificial zero load periods.
Set it to false when a zero is the more honest answer than a synthesised value. Typical cases are datasets that are known to be complete (so any absent interval is a genuine zero rather than a data gap), meters that were installed or decommissioned partway through the window and should not have load projected across the period they were not in service, and externally generated synthetic profiles that already handle gaps upstream. Be aware that disabling it understates demand wherever data is genuinely missing, which will in turn overstate available hosting capacity for those customers.
See Missing Intervals and Gap Filling for the data ingestion perspective on this behaviour.
Network Fixers
Network fixers are a set of pre-processing steps that run before the network is solved.
Whilst this means that the model solved in the power flow model is not a 'true' reflection of the network 'as is' from the ingestors, these fixers are provided as a pragmatic concession to the observed fact that network models and load data are often imperfect, and that getting results for the network with some small tweaks made is better than having a model that doesn't solve at all. They correct common data quality issues in CIM network models that, if left unaddressed, would cause the power flow solver to produce inaccurate results or fail to converge. Each fixer is independently configurable and can be enabled or disabled via the work package configuration.
The fixers operate by reading the load data for each energy consumer across the modelled time period and identifying consumers whose peak load or generation violates a configured threshold.
They always run in the order listed below: single phase loads, then overloading consumers, then undersized service lines, then undersized LV lines. The order matters, as each fixer sees the network as left by the ones before it. A consumer relocated to the HV side of its transformer by the overloading consumer fixer is no longer an LV consumer by the time the conductor fixers run, so no LV conductors are upgraded on its behalf. Similarly, the single phase load fixer changes the phase count on the conductors it rephases, which changes the VA rating the conductor fixers calculate for them.
Single Phase Load Fixer
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| fixSinglePhaseLoads | bool | true | Flag to enable this feature. If True, then the model generator uses the maxSinglePhaseLoad threshold to upgrade single phase customers with high peak loads. If False, the maxSinglePhaseLoad parameter is ignored and this network fixer will not run. |
| maxSinglePhaseLoad | float | 30000.0 | The max peak load for a single phase customer, beyond which will trigger the single phase load fixing algorithm. |
This fixer corrects energy consumers that are recorded as single-phase in the CIM model but have a peak demand too large to be a realistic single-phase connection. The assumption is that a consumer drawing more than maxSinglePhaseLoad in watts (default 30,000 W) on a single phase is most likely a three-phase consumer with an incorrect phase assignment in the source data.
What it does:
A consumer is eligible for fixing if all of the following are true:
- It has a peak load across the modelled time period that exceeds
maxSinglePhaseLoad - It is single phase
- It is an LV consumer (base voltage at or below 1,000 V)
- It belongs to an LV feeder that is already three-phase at the feeder head (not a single phase transformer)
When a consumer meets these criteria, the fixer reassigns its terminals to three-phase (ABC or ABCN depending on whether a neutral is present). It then traces upstream through the network toward the distribution transformer, progressively spreading three-phase assignments to each conductor and switch it encounters along the way. The trace stops when it reaches a conductor that is already three-phase, or when it reaches the distribution transformer itself.
Overloading Consumer Fixer
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| fixOverloadingConsumers | bool | true | Flag to enable this feature. If True, the model generator uses the maxLoadTxRatio and maxGenTxRatio thresholds to identify and relocate consumers that are likely connected to the wrong side of a transformer. If False, this network fixer will not run. |
| maxLoadTxRatio | float | 3.0 | The maximum load-to-transformer rating ratio for a single consumer, beyond which the overloading consumer fixer will trigger. |
| maxGenTxRatio | float | 10.0 | The maximum generation-to-transformer rating ratio for a single consumer, beyond which the overloading consumer fixer will trigger. |
This fixer corrects energy consumers that have a peak demand or generation where they alone are exceeding the capacity of the distribution transformer they are connected to. Consumers in this situation are assumed to be HV industrial or commercial customers that have been incorrectly connected to the LV side of a transformer in the CIM data. The fixer relocates them to the HV terminal of the transformer.
What it does:
For each LV energy consumer, the fixer finds all distribution transformers that supply it (via its LV feeders) and sums their rated capacity (this is typically just one, but can be more than one in rare instances). If the consumer's peak load exceeds maxLoadTxRatio times the total transformer rating, or its peak generation exceeds maxGenTxRatio times the total transformer rating, the consumer is moved to the HV terminal of one of those transformers.
Relocation means all terminals of the consumer are disconnected from the LV bus and reconnected to the HV terminal. The consumer's base voltage is updated to match the HV side, and phase assignments are propagated accordingly.
Example: A consumer with a 50 kW peak load connected downstream of a 10 kVA transformer has a load-to-transformer ratio of 5:1. With maxLoadTxRatio = 3.0, this consumer would be detected and moved to the HV terminal of the transformer, treating it as an HV customer.
Undersized Service Line Fixer
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| fixUndersizedServiceLines | bool | true | Flag to enable this feature. If True, the model generator uses the maxLoadServiceLineRatio threshold to upgrade service line conductors with unrealistically low current ratings. If False, this network fixer will not run. |
| maxLoadServiceLineRatio | float | 1.5 | The maximum load-to-service-line rating ratio for a consumer, beyond which the undersized service line fixer will trigger. |
This fixer corrects service lines in the network that have current ratings too low for the load they serve, which would cause the solver to report persistent overloads or fail to converge. Unrealistically low ratings are a common data quality issue in CIM models, particularly for service line conductors. The fixer upgrades the affected conductors to a rating and impedance type from a pre-configured catalogue that can support the load, keeping the conductor's existing type (cable or overhead).
Starting from each energy consumer and tracing upstream, it upgrades any service line conductor whose rating multiplied by maxLoadServiceLineRatio is less than the consumer's peak load or generation. The trace stops as soon as it reaches a conductor that is sufficiently rated for the load, or when it hits a non service line.
What it does:
For each energy consumer, the fixer calculates its peak load or generation across the modelled time period and uses whichever is larger (largest absolute power value). It then traces upstream from the consumer. For each conductor encountered:
- If the conductor's VA rating multiplied by the
maxLoadServiceLineRatiois less than the consumer's peak, the conductor is upgraded. - The upgrade replaces the conductor's asset info (current rating and impedance values r, r0, x, x0) with the smallest entry in the conductor catalogue that can support the consumer's peak, keeping the conductor's existing type (an underground cable stays a cable, anything else becomes overhead wire). If the peak exceeds every catalogue entry, the largest entry is used.
Undersized LV Line Fixer
| Variable Name | Data Type | Default | Description |
|---|---|---|---|
| fixUndersizedLvLines | bool | true | Flag to enable this feature. If True, the model generator uses the maxLoadLvLineRatio threshold to upgrade LV backbone conductors with unrealistically low current ratings. If False, this network fixer will not run. |
| maxLoadLvLineRatio | float | 2.0 | The maximum load-to-LV-line rating ratio for a consumer, beyond which the undersized LV line fixer will trigger. |
This fixer corrects LV backbone conductors in the network that have current ratings too low for the load they serve. It traces all the way up to the distribution transformer, and uses maxLoadLvLineRatio as the threshold, which is typically set higher than the service line ratio to avoid upgrading backbone conductors that serve many consumers where a single high-demand consumer would otherwise trigger an upgrade.
What it does:
For each energy consumer, the fixer calculates its peak load or generation across the modelled time period and uses whichever is larger (largest absolute power value). It then traces upstream from the consumer. For each conductor encountered:
- If the conductor's VA rating multiplied by the
maxLoadLvLineRatiois less than the consumer's peak, the conductor is upgraded. - The upgrade replaces the conductor's asset info (current rating and impedance values r, r0, x, x0) with the smallest entry in the conductor catalogue that can support the consumer's peak, keeping the conductor's existing type (an underground cable stays a cable, anything else becomes overhead wire). If the peak exceeds every catalogue entry, the largest entry is used.
The trace stops as soon as it reaches a conductor that is adequately rated for the load, or when it reaches a transformer or any equipment at 1,000 V or above, whichever comes first. It starts at the consumer rather than at the end of the service line, so service line conductors are walked as well. In practice these have usually already been dealt with by the undersized service line fixer that ran immediately before, in which case the trace stops there. If fixUndersizedServiceLines is disabled and this fixer is left enabled, service lines will instead be sized against the looser maxLoadLvLineRatio threshold.