# FullNetworkSystems

Documentation for FullNetworkSystems.

`FullNetworkSystems.Branch`

`FullNetworkSystems.Branch`

`FullNetworkSystems.Bus`

`FullNetworkSystems.Generator`

`FullNetworkSystems.GeneratorStatus`

`FullNetworkSystems.GeneratorStatusDA`

`FullNetworkSystems.GeneratorStatusRT`

`FullNetworkSystems.GeneratorTimeSeries`

`FullNetworkSystems.System`

`FullNetworkSystems.SystemDA`

`FullNetworkSystems.SystemRT`

`FullNetworkSystems.Zone`

`FullNetworkSystems._correct_lodf!`

`FullNetworkSystems._incidence`

`FullNetworkSystems._series_susceptance`

`FullNetworkSystems.big_mat_inv`

`FullNetworkSystems.branches_by_breakpoints`

`FullNetworkSystems.compute_lodf`

`FullNetworkSystems.compute_ptdf`

`FullNetworkSystems.gens_per_zone`

`FullNetworkSystems.get_availability`

`FullNetworkSystems.get_branches`

`FullNetworkSystems.get_buses`

`FullNetworkSystems.get_commitment`

`FullNetworkSystems.get_datetimes`

`FullNetworkSystems.get_decrements`

`FullNetworkSystems.get_decs_per_bus`

`FullNetworkSystems.get_generators`

`FullNetworkSystems.get_gens_per_bus`

`FullNetworkSystems.get_good_utility_requirements`

`FullNetworkSystems.get_increments`

`FullNetworkSystems.get_incs_per_bus`

`FullNetworkSystems.get_initial_commitment`

`FullNetworkSystems.get_initial_downtime`

`FullNetworkSystems.get_initial_generation`

`FullNetworkSystems.get_initial_uptime`

`FullNetworkSystems.get_lines`

`FullNetworkSystems.get_loads`

`FullNetworkSystems.get_loads_per_bus`

`FullNetworkSystems.get_lodfs`

`FullNetworkSystems.get_must_run`

`FullNetworkSystems.get_off_supplemental_offers`

`FullNetworkSystems.get_offer_curve`

`FullNetworkSystems.get_on_supplemental_offers`

`FullNetworkSystems.get_operating_reserve_requirements`

`FullNetworkSystems.get_pmax`

`FullNetworkSystems.get_pmin`

`FullNetworkSystems.get_price_sensitive_loads`

`FullNetworkSystems.get_psls_per_bus`

`FullNetworkSystems.get_ptdf`

`FullNetworkSystems.get_regulation_commitment`

`FullNetworkSystems.get_regulation_max`

`FullNetworkSystems.get_regulation_min`

`FullNetworkSystems.get_regulation_offers`

`FullNetworkSystems.get_regulation_requirements`

`FullNetworkSystems.get_spinning_offers`

`FullNetworkSystems.get_transformers`

`FullNetworkSystems.get_virtuals`

`FullNetworkSystems.retrieve_ptdf`

`FullNetworkSystems.Branch`

— TypeConstructors 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`

.

`FullNetworkSystems.Branch`

— Type`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 `Tuple`

s.

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)

`FullNetworkSystems.Bus`

— Type`struct Bus`

Type for static bus attributes.

Fields:

`name::String15`

Bus name

`base_voltage::Float64`

Base voltage (kV)

`FullNetworkSystems.Generator`

— Type`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

`FullNetworkSystems.GeneratorStatus`

— Type`abstract type GeneratorStatus`

Abstract type for storing time series of generator status information.

`FullNetworkSystems.GeneratorStatusDA`

— Type`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

`FullNetworkSystems.GeneratorStatusRT`

— Type`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`

`FullNetworkSystems.GeneratorTimeSeries`

— Type`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.

`FullNetworkSystems.System`

— Type`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 `KeyedArray`

s of `ids x datetimes`

.

`FullNetworkSystems.SystemDA`

— Type`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`

`FullNetworkSystems.SystemRT`

— Type`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`

`FullNetworkSystems.Zone`

— Type`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)

`FullNetworkSystems._correct_lodf!`

— Method`_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.

`FullNetworkSystems._incidence`

— Method`_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))`

`FullNetworkSystems._series_susceptance`

— Method`_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).

`FullNetworkSystems.big_mat_inv`

— Method`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.

`FullNetworkSystems.branches_by_breakpoints`

— Method`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.

`FullNetworkSystems.compute_lodf`

— Method```
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`

.

The resulting LODF matrix is sensitive to the input PTDF matrix. Using a thresholded PTDF as input might lead to imprecisions in constrast to using the full PTDF.

`FullNetworkSystems.compute_ptdf`

— Method```
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.

The input data must have no isolated components or islands.

`FullNetworkSystems.gens_per_zone`

— Method`gens_per_zone(system::System)`

Returns a `Dict`

with keys of `Zone`

numbers and values of generator names in that zone.

`FullNetworkSystems.get_availability`

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

`FullNetworkSystems.get_branches`

— MethodReturns a `Dictionary`

of `Branch`

objects in the `System`

indexed by branch name.

`FullNetworkSystems.get_buses`

— MethodReturns a `Dictionary`

of `Bus`

objects in the `System`

indexed by bus name.

`FullNetworkSystems.get_commitment`

— MethodReturns time series data of generator commitment status in each hour

`FullNetworkSystems.get_datetimes`

— Method`get_datetimes(system)`

Extract datetimes from a `System`

.

`FullNetworkSystems.get_decrements`

— MethodReturns time series data of decrement bids.

`FullNetworkSystems.get_decs_per_bus`

— MethodReturns a `Dictionary`

of decrement bids at each bus.

`FullNetworkSystems.get_generators`

— MethodReturns a `Dictionary`

of `Generator`

objects in the `System`

indexed by unit code.

`FullNetworkSystems.get_gens_per_bus`

— MethodReturns a `Dictionary`

of unit codes at each bus.

`FullNetworkSystems.get_good_utility_requirements`

— MethodReturns a `Dictionary`

with zonal good utility practice requirements indexed by zone number.

`FullNetworkSystems.get_increments`

— MethodReturns time series data of increment bids.

`FullNetworkSystems.get_incs_per_bus`

— MethodReturns a `Dictionary`

of increment bids at each bus.

`FullNetworkSystems.get_initial_commitment`

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

`FullNetworkSystems.get_initial_downtime`

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

`FullNetworkSystems.get_initial_generation`

— MethodReturns the generation of the generator at the start of the time period (pu)

`FullNetworkSystems.get_initial_uptime`

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

`FullNetworkSystems.get_lines`

— MethodReturns a `Dictionary`

of branches that are not transformers in the `System`

indexed by name.

`FullNetworkSystems.get_loads`

— MethodReturns time series data of the fixed loads in the system

`FullNetworkSystems.get_loads_per_bus`

— MethodReturns a `Dictionary`

of load names at each bus.

`FullNetworkSystems.get_lodfs`

— MethodReturns a `Dictionary`

of the line outage distribution factor matrices for the `System`

indexed by contingencies.

`FullNetworkSystems.get_must_run`

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

`FullNetworkSystems.get_off_supplemental_offers`

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

`FullNetworkSystems.get_offer_curve`

— MethodReturns time series data of the generator offer curves

`FullNetworkSystems.get_on_supplemental_offers`

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

`FullNetworkSystems.get_operating_reserve_requirements`

— MethodReturns a `Dictionary`

with zonal operating reserve requirements indexed by zone number.

`FullNetworkSystems.get_pmax`

— MethodReturns time series data of maximum generator output (pu)

`FullNetworkSystems.get_pmin`

— MethodReturns time series data of minimum generator output (pu)

`FullNetworkSystems.get_price_sensitive_loads`

— MethodReturns time series data of price sensitive load bids.

`FullNetworkSystems.get_psls_per_bus`

— MethodReturns a `Dictionary`

of price sensitive load bids at each bus.

`FullNetworkSystems.get_ptdf`

— MethodReturns the power transfer distribution factor of the system.

`FullNetworkSystems.get_regulation_commitment`

— MethodReturns time series data of generator regulation commitment status in each hour

`FullNetworkSystems.get_regulation_max`

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

`FullNetworkSystems.get_regulation_min`

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

`FullNetworkSystems.get_regulation_offers`

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

`FullNetworkSystems.get_regulation_requirements`

— MethodReturns a `Dictionary`

with zonal regulation requirements indexed by zone number.

`FullNetworkSystems.get_spinning_offers`

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

`FullNetworkSystems.get_transformers`

— MethodReturns a `Dictionary`

of transformers in the `System`

indexed by name.

`FullNetworkSystems.get_virtuals`

— MethodReturns time series data of both increment bids and decrement bids.

`FullNetworkSystems.retrieve_ptdf`

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