FullNetworkSystems

Constructors for a Branch. The user has the option to define a Branch as a line e.g.

line1 = Branch("1", "A", "B", 10.0, 10.0, true, (100.0, 102.0), (5.0, 6.0), 1.0, 1.0)

where the final two values (resistance and reactance) can be left unspecified. Or the user can define a Branch` as a transformer:

trnasformer1 = Branch(
    "4", "A", "C", 10.0, 10.0, true, (100.0, 102.0), (5.0, 6.0), 1.0, 1.0, 0.5, 30.0
)

where two extra parameters are provided as the end representing tap and angle.

struct Branch

Type for static branch attributes. Branches may have between 0 and 2 break points which is why the break_points and penalties fields contain variable length Tuples.

Fields:

• name::String31

  Branch long name

• to_bus::String15

  Name of the bus the branch goes to

• from_bus::String15

  Name of the bus the branch goes from

• rate_a::Float64

  Power flow limit for the base case (pu)

• rate_b::Float64

  Power flow limit for contingency scenario (pu)

• is_monitored::Bool

  Boolean defining whether the branch is monitored

• break_points::Tuple{Float64, Float64}

  Break points of the branch. Branches can have 0, 1, or 2 break points. Zeros indicate no break point

• penalties::Tuple{Float64, Float64}

  Price penalties for each of the break points of the branch ($)

• resistance::Float64

  Resistance of the branch (pu)

• reactance::Float64

  Reactance of the branch (pu)

• is_transformer::Bool

  Boolean indicating whether the branch is a transformer

• tap::Union{Missing, Float64}

  Ratio between the nominal winding one and two voltages of the transformer

• angle::Union{Missing, Float64}

  Phase shift angle (radians)

struct Bus

Type for static bus attributes.

Fields:

• name::String15

  Bus name

• base_voltage::Float64

  Base voltage (kV)

struct Generator

Type for static generator attribute (i.e. things that describe a generator that are not time series data). Parameters given in pu assume a base power of 100MW.

Fields:

• unit_code::Int64

  Generator id/unit code

• zone::Int64

  Number of the zone the generator is located in

• startup_cost::Float64

  Cost of turning on the generator ($)

• shutdown_cost::Float64

  Cost of turning off the generator ($)

• no_load_cost::Float64

  Cost of the generator being on but not producing any MW ($ /hour)

• min_uptime::Float64

  Minimum time the generator has to be committed for (hours)

• min_downtime::Float64

  Minimum time the generator has to be off for (hours)

• ramp_up::Float64

  Rate at which the generator can increase generation (pu/minute)

• ramp_down::Float64

  Rate at which the generator can decrease generation (pu/minute)

• technology::Symbol

  Symbol describing the technology of the generator

abstract type GeneratorStatus

Abstract type for storing time series of generator status information.

struct GeneratorStatusDA <: GeneratorStatus

Generator status time series data needed for the day-ahead formulation.

Fields:

• hours_at_status::KeyedArray{Float64, 1}

  Hours each generator has been at its current commitment status at the start of the day

• availability::KeyedArray{Bool, 2}

  Flag indicating if the generator is available to be committed in each hour

• must_run::KeyedArray{Bool, 2}

  Flag indicating if the generator must be committed in each hour

struct GeneratorStatusRT <: GeneratorStatus

Generator status time series data needed for the real-time formulation.

Fields:

• commitment::KeyedArray{Bool, 2}

  Generator commitment status indicated by a Bool

• regulation_commitment::KeyedArray{Bool, 2}

  Generator regulation commitment status indicated by a Bool

struct GeneratorTimeSeries

Generator related time series data that is needed for both the day-ahead and real-time formulations. Values given in pu assume a base power of 100MW.

Fields:

• initial_generation::KeyedArray{Float64, 1}

  Generation of the generator at the start of the time period (pu)

• offer_curve::KeyedArray{Vector{Tuple{Float64, Float64}}, 2}

  Generator offer curves. KeyedArray where the axis keys are generator names x datetimes

• regulation_min::KeyedArray{Float64, 2}

  Generator minimum output in the ancillary services market (pu)

• regulation_max::KeyedArray{Float64, 2}

  Generator maximum output in the ancillary services market (pu)

• pmin::KeyedArray{Float64, 2}

  Generator minimum output (pu)

• pmax::KeyedArray{Float64, 2}

  Generator maximum output (pu)

• regulation_offers::KeyedArray{Union{Missing, Float64}, 2}

  Ancillary services regulation reserve offer prices ($ /pu). Generators not providing the service will have missing offer data.

• spinning_offers::KeyedArray{Union{Missing, Float64}, 2}

  Ancillary services spinning reserve offer prices ($ /pu). Generators not providing the service will have missing offer data.

• on_supplemental_offers::KeyedArray{Union{Missing, Float64}, 2}

  Ancillary services online supplemental reserve offer prices ($ /pu). Generators not providing the service will have missing offer data.

• off_supplemental_offers::KeyedArray{Union{Missing, Float64}, 2}

  Ancillary services offline supplemental reserve offer prices ($ /pu). Generators not providing the service will have missing offer data.

System

The abstract type for representing the whole power system including topology, static components and their attributes, and time series data.

Topology: Dictionaries linking generators, loads, and bids (if present) to buses. System wide static components and grid matrices: zones, buses, generators, branches, LODF and PTDF. Time series data: all the time series associated with generators, loads and bids. All stored as KeyedArrays of ids x datetimes.

mutable struct SystemDA <: System

Subtype of a System for modelling the day-ahead market.

Fields:

• gens_per_bus::Dictionaries.Dictionary{String15, Vector{Int64}}

  Dictionary where the keys are bus names and the values are generator ids at that bus

• incs_per_bus::Dictionaries.Dictionary{String15, Vector{String31}}

  Dictionary where the keys are bus names and the values are increment bid ids at that bus

• decs_per_bus::Dictionaries.Dictionary{String15, Vector{String31}}

  Dictionary where the keys are bus names and the values are decrement bid ids at that bus

• psls_per_bus::Dictionaries.Dictionary{String15, Vector{String31}}

  Dictionary where the keys are bus names and the values are price sensitive load bid ids at that bus

• loads_per_bus::Dictionaries.Dictionary{String15, Vector{String31}}

  Dictionary where the keys are bus names and the values are load ids at that bus

• zones::Dictionaries.Dictionary{Int64, Zone}

  Zones in the System, which will also include a Zone entry for the market wide zone

• buses::Dictionaries.Dictionary{String15, Bus}

  Buses in the System indexed by bus name

• generators::Dictionaries.Dictionary{Int64, Generator}

  Generators in the System indexed by unit code

• branches::Dictionaries.Dictionary{String31, Branch}

  Branches in the System indexed by branch name

• lodfs::Dictionaries.Dictionary{String, KeyedArray{Float64, 2}}

  The line outage distribution factor matrix of the system for a set of contingencies given by the keys of the Dictionary. Each entry is a KeyedArray with axis keys branch names x branch on outage

• ptdf::Union{Missing, KeyedArray{Float64, 2}}

  Power transfer distribution factor of the system. KeyedArray where the axis keys are branch names x bus names

• generator_time_series::GeneratorTimeSeries

  Generator related time series data

• generator_status::GeneratorStatusDA

  Generator status time series needed for the day-ahead formulation

• loads::KeyedArray{Float64, 2}

  Load time series data. KeyedArray where the axis keys are load ids x datetimes

• increments::KeyedArray{Vector{Tuple{Float64, Float64}}, 2}

  Increment bids time series data. KeyedArray where the axis keys are bid ids x datetimes

• decrements::KeyedArray{Vector{Tuple{Float64, Float64}}, 2}

  Decrement bids time series data. KeyedArray where the axis keys are bid ids x datetimes

• price_sensitive_loads::KeyedArray{Vector{Tuple{Float64, Float64}}, 2}

  Price sensitive load bids time series data. KeyedArray where the axis keys are bid ids x datetimes

mutable struct SystemRT <: System

Subtype of a System for modelling the real-time market.

Fields:

• gens_per_bus::Dictionaries.Dictionary{String15, Vector{Int64}}

  Dictionary where the keys are bus names and the values are generator ids at that bus

• loads_per_bus::Dictionaries.Dictionary{String15, Vector{String31}}

  Dictionary where the keys are bus names and the values are load ids at that bus

• zones::Dictionaries.Dictionary{Int64, Zone}

  Zones in the System, which will also include a Zone entry for the market wide zone

• buses::Dictionaries.Dictionary{String15, Bus}

  Buses in the System indexed by bus name

• generators::Dictionaries.Dictionary{Int64, Generator}

  Generators in the System indexed by unit code

• branches::Dictionaries.Dictionary{String31, Branch}

  Branches in the System indexed by branch name

• lodfs::Dictionaries.Dictionary{String, KeyedArray{Float64, 2}}

  The line outage distribution factor matrix of the system for a set of contingencies given by the keys of the Dictionary. Each entry is a KeyedArray with axis keys branch names x branch on outage

• ptdf::Union{Missing, KeyedArray{Float64, 2}}

  Power transfer distribution factor of the system. KeyedArray where the axis keys are branch names x bus names

• generator_time_series::GeneratorTimeSeries

  Generator related time series data

• generator_status::GeneratorStatusRT

  Generator status time series needed for the real-time formulation

• loads::KeyedArray{Float64, 2}

  Load time series data. KeyedArray where the axis keys are load ids x datetimes

struct Zone

Type defining a market zone. The Zone is identified by a number. The other fields contain the service requirements for the zone. Requirements are given in pu assuming a base power of 100MW.

Fields:

• number::Int64

  Zone number

• regulation::Float64

  Zonal regulation requirement (pu)

• operating_reserve::Float64

  Zonal operating reserve requirement (regulation + spinning + supplemental) (pu)

• good_utility::Float64

  Zonal good utility practice requirement (regulation + spinning) (pu)

_correct_lodf!(lodf_matrix::KeyedArray, br)

Sets the LODF row corresponding to branch br to zero, except for the element (br, br), which is set to -1. This is to ensure the post-contingency flow on a line that is going out and is also monitored is set to zero.

_incidence(buses, branches) -> SparseMatrix

Returns the sparse edge-node incidence matrix related to the buses and branches used as inputs. Matrix axes correspond to (keys(branches), keys(buses))

_series_susceptance(branches) -> Vector{Float64}

Calculates the susceptance of the elements in the branch Dictionary The calculation is different depending if the element is a line (no tap) or transformer (tap present).

big_mat_inv(mat::AbstractMatrix; block_size::Int=13_000) -> AbstractMatrix

Receives a matrix that is supposed to be inverted. If the size of the matrix is larger than the defined block_size, it first partitions the matrix into smaller blocks until the matrices that are supposed to be inverted have size less than block_size. The partitioned matrix would look like: mat = [A B; C D] where the size of A is guaranteed to be smaller than the block_size. If matrix D is larger than block_size, it gets partitioned D = [A1 B1;C1 D1] and this process continues until all Ais and Dis are smaller than block_size.

The default block_size is set to be 13_000 as we have empirically observed that, for matrices smaller than this size, the built-in inv can efficiently handle the inversion. This was set when doing the calculation of admittance matrix inverse in MISO and depending on the application, this number can be adjusted.

Staring from the right bottom corner of the partitioned matrix, we use block inversion matrix lemma (https://en.wikipedia.org/wiki/Block_matrix) iteratively until the full matrix inversion is computed.

branches_by_breakpoints(system::System) -> NTuple{3, Vector{String31}}

Returns three vectors containing of the names of branches which have 0, 1, and 2 breakpoints.

compute_lodf(system, branch_names_out) -> KeyedArray
compute_lodf(system::System, ptdf_matrix, branch_names_out) -> KeyedArray
compute_lodf(buses, branches, ptdf, branch_names_out) -> KeyedArray

Returns the M*O DC-Line Outage Distribution Factor (DC-LODF) matrix of the network.

Important Note: In the current implementation, we use lodf only if the contingency scenario does not have any line coming in service. We can also use this function if we want to ignore the lines coming in service.

Inputs

• buses::Buses
• branches::Branches
• ptdf_matrix: The pre-calculated PTDF matrix of the system
• branch_names_out: The names of the branches that are going out in the contingency scenario.

Output

• The LODF matrix as a KeyedArray. The axes are the branch names and branch_names_out.

compute_ptdf(system::System; block_size, reference_bus_index) -> KeyedArray
compute_ptdf(buses::Buses, branches::Branches; block_size, reference_bus_index) -> KeyedArray

Takes a system, or data for that system, representing a M branch, N bus grid and returns the M * N DC-Power Transfer Distribution Factor (DC-PTDF) matrix of the network.

For a ~15,000 bus system with aggregated borders, this is expected to take ~1 minute.

Keywords

• block_size=13_000: Block size to be used when partitioning a big matrix for inversion.
• reference_bus=first(keys(buses)): The name of the reference bus.

Output

• ::KeyedArray: The PTDF matrix; the axes contain the branch and bus names.

gens_per_zone(system::System)

Returns a Dict with keys of Zone numbers and values of generator names in that zone.

Returns time series data of flags indicating if the generator is available to be committed in each hour

Returns a Dictionary of Branch objects in the System indexed by branch name.

Returns a Dictionary of Bus objects in the System indexed by bus name.

Returns time series data of generator commitment status in each hour

get_datetimes(system)

Extract datetimes from a System.

Returns time series data of decrement bids.

Returns a Dictionary of decrement bids at each bus.

Returns a Dictionary of Generator objects in the System indexed by unit code.

Returns a Dictionary of unit codes at each bus.

Returns a Dictionary with zonal good utility practice requirements indexed by zone number.

Returns time series data of increment bids.

Returns a Dictionary of increment bids at each bus.

Returns a flag indicating whether each generator was on at the start of the day.

Returns the number of hours each generator was off at the start of the day.

Returns the generation of the generator at the start of the time period (pu)

Returns the number of hours each generator was on at the start of the day.

Returns a Dictionary of branches that are not transformers in the System indexed by name.

Returns time series data of the fixed loads in the system

Returns a Dictionary of load names at each bus.

Returns a Dictionary of the line outage distribution factor matrices for the System indexed by contingencies.

Returns time series data of flags indicating if the generator must be committed in each hour

Returns time series data of offer prices for ancillary servives offline supplemental reserves ($ /pu)

Returns time series data of the generator offer curves

Returns time series data of offer prices for ancillary servives online supplemental reserves ($ /pu)

Returns a Dictionary with zonal operating reserve requirements indexed by zone number.

Returns time series data of maximum generator output (pu)

Returns time series data of minimum generator output (pu)

Returns time series data of price sensitive load bids.

Returns a Dictionary of price sensitive load bids at each bus.

Returns the power transfer distribution factor of the system.

Returns time series data of generator regulation commitment status in each hour

Returns time series data of maximum generator output in the ancillary services market (pu)

Returns time series data of minimum generator output in the ancillary services market (pu)

Returns time series data of offer prices for ancillary servives regulation reserves ($ /pu)

Returns a Dictionary with zonal regulation requirements indexed by zone number.

Returns time series data of offer prices for ancillary servives spinning reserves ($ /pu)

Returns a Dictionary of transformers in the System indexed by name.

Returns time series data of both increment bids and decrement bids.

Returns the power transfer distribution factor of the system. Calculates it if missing from system