Collections and instances

Time series and scenario sets

A PyPSA folder with several snapshots parses into a TimeSeries{BalancedNetwork}; a GridFM dataset parses into a ScenarioSet{BalancedNetwork}. Both hold typed values and follow Julia's collection conventions, a TimeSeries indexed by position and a ScenarioSet by string key.

series = parse("pypsa_folder/").value    # TimeSeries{BalancedNetwork}
length(series)
series[1]                                # BalancedNetwork, 1-based
for net in series
    sum(l.p_mw for l in net.loads)
end

scenarios = parse("gridfm_case14/").value  # ScenarioSet{BalancedNetwork}
keys(scenarios)                            # ["0", "1", ...]
scenarios["0"]                             # BalancedNetwork
haskey(scenarios, "7")
for (id, net) in scenarios
    println(id, ": ", length(net.buses), " buses")
end

Reading an entry does not copy the network. An OperatingPoint has a network property.

Calculation instances and solutions

A calculation instance pairs a network with the specification of one calculation, and instance.network gives you that network back. You construct one from a network module:

case = parse("case9.m")
opf = to_dc_opf_instance(case)           # PioModule{DcOpfInstance}
opf.value.network                        # the BalancedNetwork
opf.history[1].name                      # "to_dc_opf_instance"
emit(opf, "matpower")                    # writes the network; diagnoses the rest
serialize(opf, "case9_dcopf.pio.json")

Constructor	Result
`to_dc_pf_instance`, `to_ac_pf_instance`	`DcPfInstance`, `AcPfInstance`
`to_dc_opf_instance`, `to_ac_opf_instance`	`DcOpfInstance`, `AcOpfInstance`
`to_mc_ac_pf_instance`, `to_mc_ac_opf_instance`	`McAcPfInstance`, `McAcOpfInstance` over a `MulticonductorNetwork`
`to_lindist3flow_opf_instance`	`LinDist3FlowOpfInstance` over a radial `MulticonductorNetwork`

McAcPfInstance.source_boundaries is a lazy vector of VoltageSource records. Each row supplies the source bus, phase terminals, phasors and optional reference_terminal; a named reference is the other voltage endpoint on that bus and does not imply grounding. The vector retains its instance owner.

A LinDist3FlowOpfInstance uses fixed reference phasors and lossless, linearized voltage drops. Its metadata property returns owned node and conductor identities, root nodes, and reference voltages in volts and radians. Conductor records identify parent and child terminals, reversal relative to the source line, and source line rows and conductor positions using Julia's 1-based indexing. Positive line power flows from parent to child.

LinDist3FlowOpfSolution quantities include terminal_voltage_squared in squared volts, and line_active_power, line_reactive_power, source_active_power, source_reactive_power, generator_active_power, and generator_reactive_power in watts and vars. Each vector follows its instance axes. These types use PowerIO IR generation 2 with distinct structural type names. Readers without LinDist3Flow support reject those types; existing types retain their representation.

A solution answers an instance. solution.instance is that instance, solution.network is the network the solution is defined over, solution.termination is the solver status ("converged", "iteration_limit", "infeasible", "unbounded", "failed", "not_reported"), and solution.objective is the reported objective or nothing. You read a named quantity by indexing with its name and get one Vector{Float64} in table order:

solution = parse("example_0.json").value  # AcOpfSolution from OPFData
solution.instance.network
solution["bus_voltage_magnitude"]
solution["bus_voltage_angle"]
solution["generator_active_power"]
solution["branch_from_active_flow"]

scuc = parse("scenario_002/").value       # AcScucSolution from a GO Challenge 3 pair
time_count(scuc)
scuc["bus_voltage_magnitude", 1]          # time position 1

An unknown quantity name throws PowerIOError with code REQUEST.CAPI.QUANTITY_UNKNOWN. A SocwrOpfSolution comes from a second order cone relaxation of an AC OPF instance, so it reports an objective_lower_bound and is not an AC feasible point.

AC SCUC inputs

An AcScucInstance also carries the scheduling data of the unit commitment problem. instance.inputs reads it into a ScucInputs record: the collection sizes, the interval durations in hours, the input tables, and the instance wide violation costs. Times are hours, powers and energies per unit, and phase shifts radians.

instance = parse("goc3_small.json").value   # AcScucInstance
inputs = instance.inputs
inputs.dimensions.period_count              # 2
inputs.interval_durations                   # [1.0, 1.0] hours

device = inputs.devices[1]                  # ScucDevice
device.id                                   # ComponentId("generator", "sd_00")
device.kind                                 # "producer"
device.minimum_up_time_hours
device.periods[1].active_power_max_pu       # bounds in interval 1
device.periods[1].energy_cost_blocks        # the piecewise energy price

inputs.active_reserve_zones[1].buses        # Vector{ComponentId}
inputs.contingencies[1].components          # what the contingency takes out
inputs.violation_costs.active_power_balance

Every table is a plain Vector, so filter, map, and indexing all work, and a lookup by source identity is a Dict over the table:

by_uid = Dict(d.id.local_id => d for d in inputs.devices)
by_uid["sd_00"].startup_cost

A device's ScucReactiveCapability states how its reactive range depends on its active power. kind selects which fields the input sets: "none" leaves all of them nothing, "linear" sets the intercept and slope, and "bounded" sets the two intercept bounds and the two slope bounds. The same reading is available through the instance a solution answers, as solution.instance.inputs.

PowerIO.ScucInputs — Type

ScucInputs

The scheduling inputs of one AcScucInstance, read through instance.inputs.

dimensions: a NamedTuple of collection sizes, such as dimensions.period_count and dimensions.device_count.
interval_durations: the length of each interval in hours, in chronological order.
devices, shunts, branch_switching_costs, transformer_controls, active_reserve_zones, reactive_reserve_zones, contingencies: the input tables in source order.
violation_costs: the instance wide penalty prices.

The tables are plain vectors, so filter, Dict, and indexing all work. A lookup by source identity is a Dict over the table, as in Dict(d.id.local_id => d for d in inputs.devices).