Version: 0.5.1

Configuration

Model Processor Configuration

There are various elements that must be configures to sucessfully create a OpenDSS model from the input data, which are then used to run a Hosting Capacity Model work package.

Configs can be set up through config file or by hard coding in the variables

Here is a simple example that refers to external config files.

forecast_config = ForecastConfig(
    feeders=config["feeders"],
    years=config["forecast_years"],
    scenarios=config["scenarios"],
    load_time=TimePeriod(
        start_time=datetime.fromisoformat(config["load_time"]["start1"]),
        end_time=datetime.fromisoformat(config["load_time"]["end1"]),
    )
)

Configs

    feeder_configs = FeederConfigs(
      configs=[
        FeederConfig(
          feeder=config["feeders"][0],
          years=config["forecast_years"],
          scenarios=config["scenarios"],
          load_time=TimePeriod(
            start_time=datetime.fromisoformat(config["load_time"]["start2"]),
            end_time=datetime.fromisoformat(config["load_time"]["end2"]),
            load_overrides={
              "nmi1": TimePeriodLoadOverride(
                # Override profile needs to have entries covering a single day or a year.
                load_watts=[
                  1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0,
                  13.0, 14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0
                ],
                # Amount of entry between watts and var must match if both watts and vars exists.
                load_var=[
                  2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, 13.0,
                  14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0
                ],
                gen_var=None,
                gen_watts=None
              )
            }
          )
        ),
        # Fixed time example
        FeederConfig(
          feeder=config["feeders"][1],
          years=config["forecast_years"],
          scenarios=config["scenarios"],
          load_time=FixedTime(
            time=datetime.fromisoformat(config["load_time"]["start1"]),
            load_overrides={
              "nmi2": FixedTimeLoadOverride(
                # Fixed time load override supports any number of entries.
                load_watts=[1.0, 2.0, 3.0],
                # Same matching entry logic applies here when both watts and var exists.
                load_var=[2.0, 3.0, 4.0],
                gen_var=None,
                gen_watts=None
              )
            }
          )
        )
      ]
    )
    )

Common Config

Value	Type	Description and Defaults
timezone	TimeZone	the timezone the load data is is, for example, NEM time, eg "GMT+10"
startTime	Instant	The datetime where the data starts, such as "2022-04-01T00:00:00+10". The data is interval ending, such that 00:01:00 represents data from 12:30am to 1am. The timezone in the startTime and endTime value, represented by the '+X' at the end of the value, AND the timezone variable itself, must be present, and must match, to avoid model issues.
endTime	Instant	The datetime where the data ends, such as "2023-04-01T00:00:00+10". The data is interval ending, such that 00:01:00 represents data from 12:30am to 1am. The timezone in the startTime and endTime value, represented by the '+X' at the end of the value, AND the timezone variable itself, must be present, and must match, to avoid model issues.
fixedTime	Instant	Load time instant when generating a fixed time model. Cannot have both a fixed time and a start/end time, must be either a start/end time or a fixed time.
qualityAssuranceProcessing	boolean	This value can be true or false. If true, extra reporting is enabled in the openDSS model. More TODO

Generator Config

Including Model, Solve, and Raw Results

Value	Type	Description and Defaults
pFactorBaseExports	Double	Power factor to set for base model Generators during model translation. If null the model will use the reactive power specified in the load profiles. NOTE: If set, it will override all reactive power in the input data with this value.
pFactorBaseImports	Double	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. NOTE: If set, it will override all reactive power in the input data with this value.
pFactorForecastPv	Double	Power factor to set for scenario (forecast) model Generators during model translation.
fixSinglePhaseLoads	boolean	if true, enables the maxSinglePhaseLoad value and thus changes to the model as described. If false, no changes are made to the model
maxSinglePhaseLoad	Double	Value in Watt. The single phase load fixer finds consumers that have a peak load (within the modelled time period) greater than a configured value (default 30000W), and upgrades them to three-phase loads. The intent is to correct data inaccuracies where the number of phases reported for a consumer appears to be incorrect. By default, we expect a 30kW load would not appear on a single phase consumer, so we upgrade them to three-phase. This consists of tracing upstream to the distribution transformer and spreading 3 phases (ABCN) back to the transformer where possible.
maxLoadLvLineRatio	Double	This value is the ratio that a line in the LV network can be over its nominal capacity before it is automatically upgraded. The intent is to find LV lines that have unrealistically low current ratings which would stop convergence, and upgrade them to sensible ratings. When a conductors rating is upgraded, we also then upgrade the impedances to a type in line with the new rating, utilising a pre-configured catalogue of rating and impedance data, and matching the phase configuration of the consumer.
maxLoadServiceLineRatio	Double	This value is the ratio that a service line in can be over its nominal capacity before it is automatically upgraded. 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, we also then upgrade the impedances to a type in line with the new rating, utilising a pre-configured catalogue of rating and impedance data, and matching the phase configuration of the consumer.
maxLoadTxRatio	Double	The overloading consumer fixer finds consumers that have peak load (within the modelled time period) greater than the capacity of the transformer they are attached to by a configurable ratio, 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.
maxGenTxRatio	Double	The overloading consumer fixer finds consumers that have peak generation (within the modelled time period) greater than the capacity of the transformer they are attached to by a configurable ratio, 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.
fixOverloadingConsumers	boolean	this enables the 'maxLoadTxRatio' and 'maxGenTxRatio' fixes.
fixUndersizedServiceLines	boolean	this enables the 'maxLoadLvLineRatio' and 'maxLoadServiceLineRatio' fixes.
feederScenarioAllocationStrategy	ADDITIVE or RANDOM	Strategy for scenario ev, pv and bess allocation. ADDITIVE will be each year is built upon the last year's allocation, while RANDOM will be a different allocation every year.
closedLoopVRegEnabled	boolean	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.
feederHead	boolean	controls whether to place a meter at the voltage source at the feeder head.
distTransformers	boolean	controls hether to place a meter at the secondary winding of each distribution transformer.
energyConsumerMeterGroup	String	The ID of the meter group to use for populating EnergyMeters at EnergyConsumers. Can be null
meterSwitchClass	SwitchClass	Specifies which switch classes to place meters at, and the regex pattern to match for in the switch names. Option are BREAKER, DISCONNECTOR, FUSE, JUMPER, LOAD_BREAK_SWITCH, RECLOSER)
namePattern	String	Defaults to ".*"
normVMinPu	Double	the normal (ie non-emergency) minimum voltage per unit before it is considered to be undervoltage. Defaults to 0.9
normVMaxPu	Double	the normal (ie non-emergency) maximum voltage per unit before it is considered to be overvoltage. Defaults to 1.054
emergVMinPu	Double	the emergency minimum voltage, per unit. Defaults to 0.8
emergVMaxPu	Double	the emergency maximum voltage, per unit. Defaults to 1.1
baseFrequency	Int	the baseline frequency. Defaults to 50
closedLoopVRegEnabled:	Boolean	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. Default is true
closedLoopVRegReplaceAll:	Boolean	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. Default is true
closedLoopVRegSetPoint:	Double	Scaling factor for the base voltage to form the set point (0.0-2.0). Default is 0.985
closedLoopVBand:	Double	Band value in percentage. Default is 2.
closedLoopTimeDelay:	Int	Time delay in seconds. Default is 100
closedLoopVLimit:	Double	Maximum voltage at regulating transformer's secondary bus.
defaultLoadWatts	List of Doubles	A list of readings to be used as default load watts when no load data is found. Default is null
defaultGenWatts	List of Doubles	A list of readings to be used as default generation watts when no generation data is found. Default is null
defaultLoadVar	List of Doubles	A list of readings to be used as default load car when no load data is found. Default is null
defaultGenVar	List of Doubles	A list of readings to be used as default gen var when no load data is found. Default is null
splitPhaseDefaultLoadLossPercentage	Double	Default is 0.4
defaultTapChangerTimeDelay:	Int	Default is 100
defaultTapChangerSetPointPu:	Double	Default is 1
defaultTapChangerBand:	Double	Default is 2
splitPhaseLVKV:	Double	Default is 0.25
voltageBases	List of Doubles	A list of voltages used for for modelling, in Kv. Defaults to (0.4, 0.433, 6.6, 11.0, 22.0, 33.0, 66.0, 132.0)
maxIter	Int	the maximum number of iterations used in the OpenDSS model. Defaults to 25
maxControlIter	Int	the maximum number of control loops in OpenDSS. Defaults to 20
mode	YEARLY or DAILY	the OpenDSS solve mode. Defaults to YEARLY
stepSizeMinutes	Int	the step size time interval, in minutes, used in the OpenDSS model. Defaults to 60

ResultProcessor Config

Value	Type	Description and Defaults
energyMeterVoltagesRaw	Boolean	Defaults to true.
energyMetersRaw	Boolean	Defaults to true.
resultsPerMeter	Boolean	Defaults to true.
overloadsRaw	Boolean	Defaults to true.
voltageExceptionsRaw	Boolean	Defaults to true.
calculatePerformanceMetrics	Boolean	Determines if Performance Metrics will be calculated. Defaults to false.
populateEnhancedMetrics	Boolean	Determines if Performance Metrics Enhanced will be calculated. Defaults to false.
populateEnhancedMetricsProfile	Boolean	Defaults to false.
populateDurationCurves	Boolean	Determines if duration_curve output table will be calculated. Defaults to false.
populateConstraints	Boolean	Determines if constraints output table will be calculated. Defaults to false.
populateWeeklyReports	Boolean	Determines if weekly_reports output table will be calculated. Defaults to false.
calculateNormalForLoadThermal	Boolean	Determines if NormalForLoadThermal outputs will be calculated. Defaults to true.
calculateEmergForLoadThermal	Boolean	Determines if EmergForLoadThermal outputs will be calculated. Defaults to true.
calculateNormalForGenThermal	Boolean	Determines if NormalForGenThermal outputs will be calculated. Defaults to true.
calculateEmergForGenThermal	Boolean	Determines if EmergForGenThermal outputs will be calculated. Defaults to true.
calculateCO2	Boolean	Determines if CO2 outputs will be calculated. Defaults to true.
vmPu	Double	Voltage per-unit of voltage source. Defaults to 1
vMinPu	Double	Minimum per unit voltage for which the load model selected and generator model is assumed to apply. Below this value, the load/gen model reverts to a constant impedance model. For generator model used, this is used to determine the upper current limit. For example, if Vminpu is 0.90 then the current limit is (1/0.90) = 111%.
vMaxPu	Double	Maximum per unit voltage for which the load model selected and generator model is assumed to apply. Above this value, the load/gen model reverts to a constant impedance model.
loadModel	Int	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
collapseSWER	Boolean	Whether to collapse SWER network. Defaults to False
calibration	Boolean	Whether to apply calibration modifications to model. Defaults to False

Model Processor Configuration​

Common Config​

Generator Config​

ResultProcessor Config​

Model Processor Configuration

Common Config

Generator Config

ResultProcessor Config