Internal API

DispatchProblem(sys::SystemModel)

Create a min-cost flow problem for the multi-region max power delivery problem with generation and storage discharging in decreasing order of priority, storage charging with excess capacity and demand response devices enabling load shed and shift functionality. Storage, GeneratorStorage, and Demand Response devices within a region are represented individually on the network.

This involves injections/withdrawals at one node (regional capacity surplus/shortfall) for each modelled region, as well as two/three nodes associated with each Storage/GeneratorStorage device, and a supplementary "slack" node in the network that can absorb undispatched power or pass unserved energy or unused charging capability through to satisfy power balance constraints. Demand Response devices are represented in a structurally similar manner as storage charging and discharging.

Flows from the generation nodes are free, while flows to charging and from discharging nodes are costed or rewarded according to the time-to-discharge of the storage device, ensuring efficient coordination across units, while enforcing that storage is only discharged once generation capacity is exhausted (implying an operational strategy that prioritizes resource adequacy over economic arbitrage). This is based on the storage dispatch strategy of Evans, Tindemans, and Angeli, as outlined in "Minimizing Unserved Energy Using Heterogenous Storage Units" (IEEE Transactions on Power Systems, 2019). Demand Response devices will borrow energy in devices with the longest payback window first, and vice versa for payback energy. Demand Response devices are utilized only after discharging all storage/genstor and paid back before storage/genstor charging.

Flows to the charging node have an attenuated negative cost (reward), incentivizing immediate storage charging if generation and transmission allows it, while avoiding charging by discharging other storage (since that would incur an overall positive cost).

Flows to the slack node (representing unused generation or storage discharge capacity) are free, but flows from the slack node to serve load incur the lost load penalty of 9999. Flows from the slack node in lieu of storage charging or discharging are free.

Flows on transmission interfaces assume a hurdle rate of 1 to keep unserved energy close to the source of the shortage and eliminate loop flows. This has the side-effect of disincentivising wheeling power across multiple regions for charging purposes, however.

Nodes in the problem are ordered as:

1. Regions generation surplus/shortfall (Regions order)
2. Storage discharge capacity (Storage order)
3. Storage charge capacity (Storage order)
4. GenerationStorage inflow capacity (GeneratorStorage order)
5. GenerationStorage discharge capacity (GeneratorStorage order)
6. GenerationStorage grid injection (GeneratorStorage order)
7. GenerationStorage charge capacity (GeneratorStorage order)
8. DemandResponse payback capacity (DemandResponse order)
9. DemandResponse borrowing capacity (DemandResponse order)
10. Slack node

Edges are ordered as:

1. Regions demand unserved (Regions order)
2. Regions generation unused (Regions order)
3. Interfaces forward flow (Interfaces order)
4. Interfaces reverse flow (Interfaces order)
5. Storage discharge to grid (Storage order)
6. Storage discharge unused (Storage order)
7. Storage charge from grid (Storage order)
8. Storage charge unused (Storage order)
9. GenerationStorage discharge to grid (GeneratorStorage order)
10. GenerationStorage discharge unused (GeneratorStorage order)
11. GenerationStorage inflow to grid (GenerationStorage order)
12. GenerationStorage total to grid (GeneratorStorage order)
13. GenerationStorage charge from grid (GeneratorStorage order)
14. GenerationStorage charge from inflow (GeneratorStorage order)
15. GenerationStorage charge unused (GeneratorStorage order)
16. GenerationStorage inflow unused (GeneratorStorage order)
17. DemandResponse payback to grid (DemandResponse order)
18. DemandResponse payback unused (DemandResponse order)
19. DemandResponse borrowing from grid (DemandResponse order)
20. DemandResponse borrowing unused (DemandResponse order)

StorageAvailability

The StorageAvailability result specification reports the sample-level discrete availability of Storages, producing a StorageAvailabilityResult.

A StorageAvailabilityResult can be indexed by storage device name and a timestamp to retrieve a vector of sample-level availability states for the unit in the given timestep. States are provided as a boolean with true indicating that the unit is available and false indicating that it's unavailable.

Example:

storavail, =
    assess(sys, SequentialMonteCarlo(samples=10), StorageAvailability())

samples = storavail["MyStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

@assert samples isa Vector{Bool}
@assert length(samples) == 10

DEFAULT outage data which is used when outage_flag is set to FALSE

Based on ERCOT historical data

Filtered Transformer Types

These transformers are not modeled as lines in PRAS.

Default GeometricDistributionForcedOutage SupplementalAttributes

This will be added to the component for which no outage data is provided.

AbstractRAFormulation

Abstract type for translating a Sienna object in PRAS. Multiple objects can use the same formulation.

Formulations are also intended to contain information about their configuration such as time series names.

PRAS formulation subtypes for specific PRAS types

• GeneratorPRAS
• StoragePRAS (abstract type)
• GeneratorStoragePRAS (abstract type)

InterfacePRAS <: AbstractRAFormulation

InterfacePRAS produces interface entries in PRAS.

If not supplied, then interfaces will be generated by Lines

Subtypes must provide add_to_interface! function.

LoadPRAS <: AbstractRAFormulation

See add_to_load_matrix for how the formulation is used to add load to regions.

S2P_metadata

Struct to store metadata for the Sienna to PRAS conversion

SPIOutageResult(; shortfall_samples, gen_availability, stor_availability, gen_stor_availability)

Arguments

• shortfall_samples::PRASCore.Results.ShortfallSamplesResult: Shortfall Sample Result

• gen_availability::PRASCore.Results.GeneratorAvailabilityResult: Generator Availability Result

• stor_availability::PRASCore.Results.StorageAvailabilityResult: Storage Availability Result

• gen_stor_availability::PRASCore.Results.GeneratorStorageAvailabilityResult: GeneratorStorage Availability Result

SPIOutageResult is used to parse Tuple{Vararg{PRAS.PRASCore.Results.Result}} and add structure to it.

outage_data

Struct to store the outage information for a component.

add_asset_status!(
    sys::PowerSystems.System,
    results::SiennaPRASInterface.SPIOutageResult,
    template::RATemplate
)

Add the asset status from the worst sample to GeometricDistributionForcedOutage of the component.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• results::T: SPIOutageResult
• template::RATemplate: PRAS problem template

Returns

- PSY System with asset availability times series added to PSY.GeometricDistributionForcedOutage for all components for which asset status is available

Add default data to a system from OUTAGE_INFO_FILE (ERCOT data).

add_to_interface!(
    _::AreaInterchangeLimit,
    interface,
    s2p_meta,
    forward_row,
    backward_row
) -> Any

Add flow limits of an Sienna interface to an existing PRAS interface

Check whether a DeviceRAModel applies to a given type

assign_to_gen_stor_matrices!(
    formulation::HybridSystemPRAS,
    g_s::PowerSystems.Device,
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    turbine_to_reservoir_mapping::Dict{PowerSystems.HydroUnit, PowerSystems.HydroReservoir},
    charge_cap_array,
    discharge_cap_array,
    inflow_array,
    energy_cap_array,
    gridinj_cap_array,
    gridwdr_cap_array
) -> Any

Apply HybridSystem Formulation to fill in a row of a PRAS Matrix. Views should be passed in for all arrays.

assign_to_line_matrices!(
    _::LinePRAS,
    line::PowerSystems.Branch,
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    forward_cap,
    backward_cap
) -> Any

Apply LinePRAS to create PRAS matrices for lines. Views should be passed in.

build_component_to_formulation(_, sys, device_models)

Constructs a dictionary from Sienna Devices to formulation objects

build_interfaces_from_lines(
    line_forward_cap::Matrix{Int64},
    line_backward_cap::Matrix{Int64},
    interface_reg_idxs::Vector{Tuple{Int64, Int64}},
    interface_line_idxs::Vector{UnitRange{Int64}},
    s2p_meta::SiennaPRASInterface.S2P_metadata
) -> Interfaces{_A, MW} where _A

Create PRAS interfaces from PRAS Lines

check_file(loc::String)

Check if the file exists and is openable.

filter_component_to_formulation(gens_to_formula)

Filter the dictionary from Sienna Devices to GeneratorPRAS formulation objects for Lumped vs. NonLumped

Get whether default forced outages needed to be added to generators

Get whether default forced outages needed to be added to generatorstorages

Get whether default forced outages needed to be added to generatorstorages

get_aggregation_function(::PSY.Area)

Get getter function based on PSY.AggregationTopology

Uses a PRAS device model to find all components matching it in a system.

get_available_components_in_aggregation_topology(
    type::Type{<:PSY.StaticInjection},
    sys::PSY.System,
    region::PSY.AggregationTopology,
)

Get available components in the AggregationTopology region of the given type.

Get DeviceRAModel for PRAS AbstractAvailabilityResult

Get DeviceRAModel for PRAS AbstractAvailabilityResult

Get DeviceRAModel for PRAS AbstractAvailabilityResult

Get formulation from a DeviceRAModel

get_gen_storage_region_indices(
    sys::PowerSystems.System,
    regions,
    component_to_formulation::Dict{PowerSystems.Device, GeneratorStoragePRAS}
) -> Tuple{Any, Any}

Extract components with a generator storage formulation.

get_generator_category(gen::StaticInjection)

Get the category of the generator.

Arguments

• gen::StaticInjection: Generator

Returns

• String: Category of the generator

get_generator_region_indices(
    sys::PowerSystems.System,
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    regions,
    component_to_formulation::Dict{PowerSystems.Device, GeneratorPRAS}
) -> Tuple{Any, Any, Dict{String, Vector{PowerSystems.Device}}}

Extraction of generators using formulation dictionary to create a list of generators and appropriate indices for PRAS. Note that objects with 0 max active power are excluded.

Get inflow time series name

Get whether renewable generation is lumped to regions

Get max active power time series name

Get max active power time series name

Get outage_probability time series name

Get outage_probability time series name

Get outage_probability time series name

Turn a time series into an Array of floored ints

Get recovery_probability time series name

Get recovery_probability time series name

Get recovery_probability time series name

get_region_loads(
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    regions,
    loads_to_formulations::Dict{PowerSystems.Device, SiennaPRASInterface.LoadPRAS}
) -> Matrix{Int64}

Extract region load as a matrix of Int64 values.

get_sorted_lines(lines::Vector{PSY.Branch}, region_names::Vector{String})

Get sorted lines, interface region indices, and interface line indices.

Arguments

• lines::Vector{PSY.Branch}: Lines
• region_names::Vector{String}: Region names

Returns

• sorted_lines::Vector{PSY.Branch}: Sorted lines
• interface_reg_idxs::Vector{Tuple{Int, Int}}: Interface region indices
• interface_line_idxs::Vector{UnitRange{Int}}: Interface line indices

get_sorted_region_tuples(lines::Vector{PSY.Branch}, region_names::Vector{String})

Get sorted (regfrom, regto) tuples of inter-regional lines.

Get storage capacity time series name

get_storage_region_indices(
    sys::PowerSystems.System,
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    regions,
    component_to_formulation::Dict{PowerSystems.Device, StoragePRAS}
) -> Tuple{Any, Any}

Extraction of storage devices using formulation dictionary to create a list of storage devices and appropriate indices for PRAS.

get_timestamps(initial_time, resolution, steps, horizon)

Return a vector of timestamps starting from initial_time with resolution and steps for horizon steps

initializeavailability!(rng, availability, nexttransition, devices, tlast)

Arguments

• rng::Random.AbstractRNG: Random number generator
• availability::Vector{Bool}: Vector of availability status
• nexttransition::Vector{Int}: Vector of next transition time
• devices::Vector{PSY.Generator}: Vector of devices with outage SupplementalAttributes
• t_last::Int: Last time step

Returns

Modifies input arguments and rereturns

• availability::Vector{Bool}: Vector of availability status
• nexttransition::Vector{Int}: Vector of next transition time

line_rating(line::Branch)

Get the line rating.

Arguments

• line::Branch: Line

Returns

• Tuple{forward_capacity::Float64, backward_capacity::Float64}: Line rating

line_type(line::Branch)

Get the line type.

Arguments

• line::Branch: Line

Returns

• String: Line type

process_generators(
    gen::Array{PowerSystems.Device},
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    component_to_formulation::Dict{PowerSystems.Device, GeneratorPRAS},
    lumped_mapping::Dict{String, Vector{PowerSystems.Device}}
) -> Generators{_A, _B, T, MW} where {_A, _B, T<:Period}

Apply GeneratorPRAS to process all generators objects into rows in PRAS matrices:

• Capacity, λ, μ

Negative max active power will translate into zeros for time series data.

process_genstorage(
    gen_stor::Array{PowerSystems.Device},
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    component_to_formulation::Dict{PowerSystems.Device, GeneratorStoragePRAS};
    turbine_to_reservoir_mapping
)

Apply GeneratorStoragePRAS to create PRAS matrices for generator storage

process_interfaces(
    interface_reg_idxs::Vector{Tuple{Int64, Int64}},
    regions,
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    interfaces_to_formulation::Dict{PowerSystems.Device, SiennaPRASInterface.InterfacePRAS}
) -> Interfaces{_A, MW} where _A

Process interfaces using a formulation dictionary to create PRAS matrices.

process_lines(
    sorted_lines::Vector{PowerSystems.Branch},
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    lines_to_formulation::Dict{PowerSystems.Device, LinePRAS}
) -> Lines{_A, _B, T, MW} where {_A, _B, T<:Period}

Create PRAS from sorted lines and formulations.

process_storage(
    stor::Array{PowerSystems.Device},
    s2p_meta::SiennaPRASInterface.S2P_metadata,
    component_to_formulation::Dict{PowerSystems.Device, StoragePRAS}
) -> Storages{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}

Apply StoragePRAS to process all storage objects

rate_to_probability(for_gen::Float64, mttr::Int64)

Converts the forced outage rate and mean time to repair to the λ and μ parameters

Arguments

• for_gen::Float64: Forced outage rate [1/T]
• mttr::Int64: Mean time to repair [T]

Returns

• λ::Float64: Transition probability from online to offline [1/T]
• μ::Float64: Transition rate from offline to online [1/T]

Reference

https://core.ac.uk/download/pdf/13643059.pdf

runchecks(sys_location::String)

Check if the System JSON file is serialized as well as other files required.

update_availability!(rng, availability, nexttransition, devices, t_now, t_last)

Return availability and next transition with new randomness