Public API Reference

PowerSystems Interface for Probabilistic Resource Adequacy Studies (PRAS)

Key Functions

• generate_pras_system: convert PSY to PRAS model
• assess: assess PRAS model

Key PRAS Types

• SystemModel: PRAS data structure
• SequentialMonteCarlo: method for PRAS analysis
• Shortfall: PRAS metric for missing generation
• LOLE: PRAS metric for loss of load expectation
• EUE: PRAS metric for energy unserved expectation

AreaInterchangeLimit <: InterfacePRAS

AreaInterchangeLimit produces interfaces from AreaInterchange objects

Each line must have a corresponding AreaInterchange. All AreaInterchange objects will be consolidated for each pair of directly connected regions.

DeviceRAModel{D <: PSY.Device, B <: AbstractRAFormulation}

Arguments

• D <: PSY.Device: Device type

  • formulation::SiennaPRASInterface.AbstractRAFormulation: Formulation containing configuration

A DeviceRAModel, like a DeviceModel in PowerSimulations, assigns a type of Component to a specific formulation. Unlike Sienna, we put configuration information in the formulation itself.

DeviceRAModel(
    ::Type{D<:PowerSystems.Device},
    ::Type{B<:SiennaPRASInterface.AbstractRAFormulation};
    time_series_names,
    kwargs...
) -> DeviceRAModel

Arguments

• ::Type{D}: Device type
• ::Type{B}: Formulation type
• time_series_names::Dict{Symbol, String}: Mapping of time series Symbol to names
• kwargs...: Additional arguments to pass to the formulation constructor

Keyword arguments in DeviceRAModel are passed to the formulation constructor.

You may also pass a time_series_names Dict to map time series Symbol to names.

Example

DeviceRAModel(
    PSY.Generator,
    GeneratorPRAS(max_active_power="max_active_power"),
)

DeviceRAModel(
    PSY.HydroEnergyReservoir,
    HydroEnergyReservoirPRAS;
    max_active_power="max_active_power",
    inflow="inflow",
    storage_capacity="storage_capacity",
)

DeviceRAModel(
    PSY.HybridSystem,
    HybridSystemPRAS;
    time_series_names=Dict(:max_active_power="max_active_power"),
)

EnergyReservoirSoC <: StoragePRAS

EnergyReservoirSoC is a storage formulation that keeps track oh state of charge.

GeneratorPRAS(; max_active_power, lump_renewable_generation, add_default_transition_probabilities, outage_probability, recovery_probability) <: AbstractRAFormulation

Arguments

• max_active_power::String: Name of time series to use for max active power

• lump_renewable_generation::Bool: Whether to lump renewable generation to regions

• add_default_transition_probabilities::Bool: Whether to add default outage data to generators

• outage_probability::String: Name of time series to use for outage_probability

• recovery_probability::String: Name of time series to use for recovery_probability

GeneratorPRAS produces generator entries in PRAS.

GeneratorStoragePRAS <: AbstractRAFormulation

Objects in Sienna that behave like generator and storage are mapped to generatorstorage in PRAS.

To add a generator storage formulation, you must also add a assign_to_gen_stor_matrices! function.

• HybridSystemPRAS
• HydroEnergyReservoirPRAS

HybridSystemPRAS(; max_active_power, add_default_transition_probabilities, outage_probability, recovery_probability) <: GeneratorStoragePRAS

Arguments

• max_active_power::String: Name of time series to use for max active power

• add_default_transition_probabilities::Bool: Whether to add default outage data

• outage_probability::String: Name of time series to use for outage_probability

• recovery_probability::String: Name of time series to use for recovery_probability

HybridSystemPRAS produces generatorstorage entries in PRAS.

HydroEnergyReservoirPRAS <: GeneratorStoragePRAS

Arguments

• max_active_power::String: Name of time series to use for max active power

• inflow::String: Name of time series to use for inflow

• storage_capacity::String: Name of time series to use for storage capacity

• add_default_transition_probabilities::Bool: Whether to add default outage data

• outage_probability::String: Name of time series to use for outage_probability

• recovery_probability::String: Name of time series to use for recovery_probability

LinePRAS <: AbstractRAFormulation

LinePRAS produces line entries in PRAS.

See assign_to_line_matrices! for the formulation handling. Any subtypes must implement this.

Arguments

• aggregation::Type{T} where T<:PowerSystems.AggregationTopology: Level of aggregation to use for PRAS regions

• device_models::Array{DeviceRAModel}: DeviceRAModels to translate components into PRAS

The RATemplate contains all configuration necessary for building a PRAS Simulation from a PowerSystems.jl System.

Since PRAS is an area-based model, we provide a level of aggregation to apply.

PRAS models are processed in reverse order, with later models taking precedence.

Example

template = RATemplate(
    PSY.Area,
    [
        DeviceRAModel(
            PSY.Generator,
            GeneratorPRAS(max_active_power="max_active_power"),
        ),
        DeviceRAModel(
            PSY.HydroEnergyReservoir,
            HydroEnergyReservoirPRAS(
                max_active_power="max_active_power",
                inflow="inflow",
                storage_capacity="storage_capacity",
            ),
        ),
    ],
)

StaticLoadPRAS <: LoadPRAS

Arguments

• max_active_power::String: Name of time series to use for max active power

StoragePRAS <: AbstractRAFormulation

Objects in Sienna that behave like storage are mapped to storage in PRAS.

Subtypes must provide assign_to_stor_matrices! function.

assess(
    sys::PowerSystems.System,
    template::RATemplate,
    method::SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...
) -> Any

Analyze resource adequacy using Monte Carlo simulation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• template::RATemplate: PRAS problem template
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

assess(
    sys::PowerSystems.System,
    method::SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...
) -> Any

Analyze resource adequacy using Monte Carlo simulation.

Uses default template with Area level aggregation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

assess(
    sys::PSY.System,
    aggregation::Type{AT},
    method::PRASCore.SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...,
) where {AT <: PSY.AggregationTopology}

Analyze resource adequacy using Monte Carlo simulation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• aggregation::Type{AT}: Aggregation topology to use in translating to PRAS
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

generate_outage_profile!(
    sys::PowerSystems.System,
    template::RATemplate,
    method::SequentialMonteCarlo
) -> PowerSystems.System

Analyze resource adequacy using Monte Carlo simulation and add the asset status from the worst sample to PSY.GeometricDistributionForcedOutage of the component.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• template::RATemplate: PRAS problem template
• method::PRASCore.SequentialMonteCarlo: Simulation method to use

Returns

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

generate_outage_profile!(
    sys::PowerSystems.System,
    method::SequentialMonteCarlo
) -> PowerSystems.System

Analyze resource adequacy using Monte Carlo simulation and add the asset status from the worst sample to PSY.GeometricDistributionForcedOutage of the component.

Uses default template with PSY.Area AggregationTopology.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• method::PRASCore.SequentialMonteCarlo: Simulation method to use

Returns

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

generate_outage_profile!(
    sys::PSY.System,
    aggregation::Type{AT},
    method::PRASCore.SequentialMonteCarlo,
) where {AT <: PSY.AggregationTopology, RM <: PRASCore.Results.ReliabilityMetric}

Analyze resource adequacy using Monte Carlo simulation and add the asset status from the worst sample to PSY.GeometricDistributionForcedOutage of the component.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• aggregation::Type{AT}: Aggregation topology to use in translating to PRAS
• method::PRASCore.SequentialMonteCarlo: Simulation method to use

Returns

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

generate_pras_system(
    sys::PowerSystems.System,
    template::RATemplate
) -> SystemModel{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}
generate_pras_system(
    sys::PowerSystems.System,
    template::RATemplate,
    export_location::Union{Nothing, String}
) -> SystemModel{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}

Use a RATemplate to create a PRAS system from a Sienna system.

Arguments

• sys::PSY.System: Sienna PowerSystems System
• template::RATemplate: RATemplate
• export_location::Union{Nothing, String}: Export location for PRAS SystemModel

Returns

• PRASCore.SystemModel: PRAS SystemModel

Examples

generate_pras_system(sys, template)

Note that the original system will only be set to NATURAL_UNITS.

generate_pras_system(
    sys::PowerSystems.System,
    aggregation::Type{AT<:PowerSystems.AggregationTopology}
) -> SystemModel{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}
generate_pras_system(
    sys::PowerSystems.System,
    aggregation::Type{AT<:PowerSystems.AggregationTopology},
    lump_region_renewable_gens::Bool
) -> SystemModel{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}
generate_pras_system(
    sys::PowerSystems.System,
    aggregation::Type{AT<:PowerSystems.AggregationTopology},
    lump_region_renewable_gens::Bool,
    export_location::Union{Nothing, String}
) -> SystemModel{_A, _B, T, MW, MWh} where {_A, _B, T<:Period}

Sienna/Data PowerSystems.jl System is the input and an object of PRAS SystemModel is returned. ...

Arguments

• sys::PSY.System: Sienna/Data PowerSystems.jl System
• aggregation<:PSY.AggregationTopology: "PSY.Area" (or) "PSY.LoadZone" {Optional}
• lump_region_renewable_gens::Bool: Whether to lumps PV and Wind generators in a region because usually these generators don't have FOR data {Optional}
• export_location::String: Export location of the .pras file ...

Returns

- `PRASCore.SystemModel`: PRAS SystemModel object

Examples

julia> generate_pras_system(psy_sys, PSY.Area)
PRAS SystemModel

generate_pras_system(sys_location::String, aggregation; kwargs...)

Generate a PRAS SystemModel from a Sienna/Data PowerSystems System JSON file.

Arguments

• sys_location::String: Location of the Sienna/Data PowerSystems System JSON file
• aggregation::Type{AT}: Aggregation topology type
• lump_region_renewable_gens::Bool: Lumping of region renewable generators
• export_location::Union{Nothing, String}: Export location of the .pras file

Returns

• PRASCore.SystemModel: PRAS SystemModel

make_generator_outage_draws!(
    sys,
    initial_time::Dates.DateTime=nothing,
    resolution::TIMEPERIOD=nothing,
    steps::Int=nothing,
    horizon::Int=nothing,
) where {TIMEPERIOD <: Dates.TimePeriod}

Adds availability time series to the generators in the system.

Main function to make generator outage draws.

set_device_model!(
    template::RATemplate,
    _::Type{D<:PowerSystems.Device},
    _::Type{B<:SiennaPRASInterface.AbstractRAFormulation}
) -> Vector{DeviceRAModel}

Arguments

• template::RATemplate: Template to add device model to
• ::Type{D}: Device type
• ::Type{B}: Formulation type

Adds a device model to a RATemplate by passing the type to a constructor.

set_device_model!(
    template::RATemplate,
    device_model::DeviceRAModel{D}
) -> Vector{DeviceRAModel}

Arguments

• template::RATemplate: Template to add device model to
• device_model::DeviceRAModel{D}: Device model to add

Add a device model to a RATemplate. If an existing model already applies to the given device type, then a warning is issued. However, newer models will take precedence.

SystemModel{N, L, T<:Period, P<:PowerUnit, E<:EnergyUnit}

A SystemModel struct contains a representation of a power system to be studied with PRAS. See system specifications for more details on components of a system model.

Type Parameters

• N: Number of timesteps in the system model
• L: Length of each timestep in T units
• T: Time period type (e.g., Hour, Minute)
• P: Power unit type (e.g., MW, GW)
• E: Energy unit type (e.g., MWh, GWh)

Fields

• regions: Representation of system regions (Type - Regions)
• interfaces: Information about connections between regions (Type - Interfaces)
• generators: Collection of system generators (Type - Generators)
• region_gen_idxs: Mapping of generators to their respective regions
• storages: Collection of system storages (Type - Storages)
• region_stor_idxs: Mapping of storage resources to their respective regions
• generatorstorages: Collection of system generation-storages (Type - GeneratorStorages)
• region_genstor_idxs: Mapping of hybrid resources to their respective regions
• lines: Collection of transmission lines connecting regions (Type - Lines)
• interface_line_idxs: Mapping of transmission lines to interfaces
• timestamps: Time range for the simulation period
• attrs: Dictionary of system metadata and attributes

Constructors

SystemModel(regions, interfaces, generators, region_gen_idxs, storages, region_stor_idxs,
            generatorstorages, region_genstor_idxs, lines, interface_line_idxs,
            timestamps, [attrs])

Create a system model with all components specified.

SystemModel(generators, storages, generatorstorages, timestamps, load, [attrs])

Create a single-node system model with specified generators, storage, and load profile.

SystemModel(regions, interfaces, generators, region_gen_idxs, storages, region_stor_idxs,
            generatorstorages, region_genstor_idxs, lines, interface_line_idxs,
            timestamps::StepRange{DateTime}, [attrs])

Create a system model with DateTime timestamps (will be converted to UTC time zone).

assess(system::SystemModel, method::SequentialMonteCarlo, resultspecs::ResultSpec...)

Run a Sequential Monte Carlo simulation on a system using the method data and return resultspecs.

Arguments

• system::SystemModel: PRAS data structure
• method::SequentialMonteCarlo: method for PRAS analysis
• resultspecs::ResultSpec...: PRAS metric for metrics like Shortfall missing generation

Returns

• results::Tuple{Vararg{ResultAccumulator{SequentialMonteCarlo}}}: PRAS metric results

assess(
    sys::PSY.System,
    aggregation::Type{AT},
    method::PRASCore.SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...,
) where {AT <: PSY.AggregationTopology}

Analyze resource adequacy using Monte Carlo simulation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• aggregation::Type{AT}: Aggregation topology to use in translating to PRAS
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

assess(
    sys::PowerSystems.System,
    template::RATemplate,
    method::SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...
) -> Any

Analyze resource adequacy using Monte Carlo simulation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• template::RATemplate: PRAS problem template
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

assess(
    sys::PowerSystems.System,
    method::SequentialMonteCarlo,
    resultsspecs::PRASCore.Results.ResultSpec...
) -> Any

Analyze resource adequacy using Monte Carlo simulation.

Uses default template with Area level aggregation.

Arguments

• sys::PSY.System: PowerSystems.jl system model
• method::PRASCore.SequentialMonteCarlo: Simulation method to use
• resultsspec::PRASCore.Results.ResultSpec...: Results to compute

Returns

• Tuple of results from resultsspec: default is (ShortfallResult,)

SequentialMonteCarlo(;
    samples::Int=10_000,
    seed::Integer=rand(UInt64),
    verbose::Bool=false,
    threaded::Bool=true
)

Sequential Monte Carlo simulation parameters for PRAS analysis

It it recommended that you fix the random seed for reproducibility.

Arguments

• samples::Int=10_000: Number of samples
• seed::Integer=rand(UInt64): Random seed
• verbose::Bool=false: Print progress
• threaded::Bool=true: Use multi-threading

Returns

• SequentialMonteCarlo: PRAS simulation specification

Shortfall

The Shortfall result specification reports expectation-based resource adequacy risk metrics such as EUE and LOLE, producing a ShortfallResult.

A ShortfallResult can be directly indexed by a region name and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average unserved energy in that region and timestep. However, in most cases it's simpler to use EUE and LOLE constructors to directly retrieve standard risk metrics.

Example:

shortfall, =
    assess(sys, SequentialMonteCarlo(samples=1000), Shortfall())

period = ZonedDateTime(2020, 1, 1, 0, tz"UTC")

# Unserved energy mean and standard deviation
sf_mean, sf_std = shortfall["Region A", period]

# System-wide risk metrics
eue = EUE(shortfall)
lole = LOLE(shortfall)
neue = NEUE(shorfall)

# Regional risk metrics
regional_eue = EUE(shortfall, "Region A")
regional_lole = LOLE(shortfall, "Region A")
regional_neue = NEUE(shortfall, "Region A")

# Period-specific risk metrics
period_eue = EUE(shortfall, period)
period_lolp = LOLE(shortfall, period)

# Region- and period-specific risk metrics
period_eue = EUE(shortfall, "Region A", period)
period_lolp = LOLE(shortfall, "Region A", period)

See ShortfallSamples for recording sample-level shortfall results.

Surplus

The Surplus result specification reports unused generation and storage discharge capability of Regions, producing a SurplusResult.

A SurplusResult can be indexed by region name and timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average unused capacity in that region and timestep.

Example:

surplus, =
    assess(sys, SequentialMonteCarlo(samples=1000), Surplus())

surplus_mean, surplus_std =
    surplus["Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

See SurplusSamples for sample-level surplus results.

Flow

The Flow result specification reports the estimated average flow across transmission Interfaces, producing a FlowResult.

A FlowResult can be indexed by a directional Pair of region names and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average net flow magnitude and direction relative to the given directed interface in that timestep. For a query of "Region A" => "Region B", if estimated average flow was from A to B, the reported value would be positive, while if average flow was in the reverse direction, from B to A, the value would be negative.

Example:

flows, =
    assess(sys, SequentialMonteCarlo(samples=1000), Flow())

flow_mean, flow_std =
    flows["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
flow2_mean, flow2_std =
    flows["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
@assert flow_mean == -flow2_mean

See FlowSamples for sample-level flow results.

Utilization

The Utilization result specification reports the estimated average absolute utilization of Interfaces, producing a UtilizationResult.

Whereas Flow reports the average directional power transfer across an interface, Utilization reports the absolute value of flow relative to the interface's transfer capability (counting the effects of line outages). For example, a symmetrically-constrained interface which is fully congested with max power flowing in one direction in half of the samples, and the other direction in the remaining samples, would have an average flow of 0 MW, but an average utilization of 100%.

A UtilizationResult can be indexed by a Pair of region names and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average utilization of the interface. Given the absolute value nature of the outcome, results are independent of direction. Querying "Region A" => "Region B" will yield the same result as "Region B" => "Region A".

Example:

utils, =
    assess(sys, SequentialMonteCarlo(samples=1000), Utilization())

util_mean, util_std =
    utils["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

util2_mean, util2_std =
    utils["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

@assert util_mean == util2_mean

See UtilizationSamples for sample-level utilization results.

StorageEnergy

The StorageEnergy result specification reports the average state of charge of Storages, producing a StorageEnergyResult.

A StorageEnergyResult can be indexed by storage device name and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average energy level for the given storage device in that timestep.

Example:

storenergy, =
    assess(sys, SequentialMonteCarlo(samples=1000), StorageEnergy())

soc_mean, soc_std =
    storenergy["MyStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

See StorageEnergySamples for sample-level storage states of charge.

See GeneratorStorageEnergy for average generator-storage states of charge.

GeneratorStorageEnergy

The GeneratorStorageEnergy result specification reports the average state of charge of GeneratorStorages, producing a GeneratorStorageEnergyResult.

A GeneratorStorageEnergyResult can be indexed by generator-storage device name and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating the average energy level for the given generator-storage device in that timestep.

Example:

genstorenergy, =
    assess(sys, SequentialMonteCarlo(samples=1000), GeneratorStorageEnergy())

soc_mean, soc_std =
    genstorenergy["MyGeneratorStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

See GeneratorStorageEnergySamples for sample-level generator-storage states of charge.

See StorageEnergy for average storage states of charge.

LOLE

LOLE reports loss of load expectation over a particular time period and regional extent. When the reporting period is a single simulation timestep, the metric is equivalent to loss of load probability (LOLP).

Contains both the estimated value itself as well as the standard error of that estimate, which can be extracted with val and stderror, respectively.

EUE

EUE reports expected unserved energy over a particular time period and regional extent.

Contains both the estimated value itself as well as the standard error of that estimate, which can be extracted with val and stderror, respectively.

ShortfallSamples

The ShortfallSamples result specification reports sample-level unserved energy outcomes, producing a ShortfallSamplesResult.

A ShortfallSamplesResult can be directly indexed by a region name and a timestamp to retrieve a vector of sample-level unserved energy results in that region and timestep. EUE and LOLE constructors can also be used to retrieve standard risk metrics.

Example:

shortfall, =
    assess(sys, SequentialMonteCarlo(samples=10), ShortfallSamples())

period = ZonedDateTime(2020, 1, 1, 0, tz"UTC")

samples = shortfall["Region A", period]

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

# System-wide risk metrics
eue = EUE(shortfall)
lole = LOLE(shortfall)
neue = NEUE(shortfall)

# Regional risk metrics
regional_eue = EUE(shortfall, "Region A")
regional_lole = LOLE(shortfall, "Region A")
regional_neue = NEUE(shortfall, "Region A")

# Period-specific risk metrics
period_eue = EUE(shortfall, period)
period_lolp = LOLE(shortfall, period)

# Region- and period-specific risk metrics
period_eue = EUE(shortfall, "Region A", period)
period_lolp = LOLE(shortfall, "Region A", period)

Note that this result specification requires large amounts of memory for larger sample sizes. See Shortfall for average shortfall outcomes when sample-level granularity isn't required.

SurplusSamples

The SurplusSamples result specification reports sample-level unused generation and storage discharge capability of Regions, producing a SurplusSamplesResult.

A SurplusSamplesResult can be indexed by region name and timestamp to retrieve a vector of sample-level surplus values in that region and timestep.

Example:

surplus, =
    assess(sys, SequentialMonteCarlo(samples=10), SurplusSamples())

samples = surplus["Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

Note that this result specification requires large amounts of memory for larger sample sizes. See Surplus for estimated average surplus values when sample-level granularity isn't required.

FlowSamples

The FlowSamples result specification reports the sample-level magnitude and direction of power flows across Interfaces, producing a FlowSamplesResult.

A FlowSamplesResult can be indexed by a directional Pair of region names and a timestamp to retrieve a vector of sample-level net flow magnitudes and directions relative to the given directed interface in that timestep. For a query of "Region A" => "Region B", if flow in one sample was from A to B, the reported value would be positive, while if flow was in the reverse direction, from B to A, the value would be negative.

Example:

flows, =
    assess(sys, SequentialMonteCarlo(samples=10), FlowSamples())

samples = flows["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

samples2 = flows["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

@assert samples == -samples2

Note that this result specification requires large amounts of memory for larger sample sizes. See Flow for estimated average flow results when sample-level granularity isn't required.

UtilizationSamples

The UtilizationSamples result specification reports the sample-level absolute utilization of Interfaces, producing a UtilizationSamplesResult.

Whereas FlowSamples reports the directional power transfer across an interface, UtilizationSamples reports the absolute value of flow relative to the interface's transfer capability (counting the effects of line outages). For example, a 100 MW symmetrically-constrained interface which is fully congested may have a flow of +100 or -100 MW, but in both cases the utilization will be 100%. If a 50 MW line in the interface went on outage, flow may drop to +50 or -50 MW, but utilization would remain at 100%.

A UtilizationSamplesResult can be indexed by a Pair of region names and a timestamp to retrieve a vector of sample-level utilizations of the interface in that timestep. Given the absolute value nature of the outcome, results are independent of direction. Querying "Region A" => "Region B" will yield the same result as "Region B" => "Region A".

Example:

utils, =
    assess(sys, SequentialMonteCarlo(samples=10), UtilizationSamples())

samples =
    utils["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

samples2 =
    utils["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

@assert samples == samples2

Note that this result specification requires large amounts of memory for larger sample sizes. See Utilization for sample-averaged utilization results when sample-level granularity isn't required.

StorageEnergySamples

The StorageEnergySamples result specification reports the sample-level state of charge of Storages, producing a StorageEnergySamplesResult.

A StorageEnergySamplesResult can be indexed by storage device name and a timestamp to retrieve a vector of sample-level charge states for the device in the given timestep.

Example:

storenergy, =
    assess(sys, SequentialMonteCarlo(samples=10), StorageEnergySamples())

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

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

Note that this result specification requires large amounts of memory for larger sample sizes. See StorageEnergy for estimated average storage state of charge when sample-level granularity isn't required.

GeneratorStorageEnergySamples

The GeneratorStorageEnergySamples result specification reports the sample-level state of charge of GeneratorStorages, producing a GeneratorStorageEnergySamplesResult.

A GeneratorStorageEnergySamplesResult can be indexed by generator-storage device name and a timestamp to retrieve a vector of sample-level charge states for the device in the given timestep.

Example:

genstorenergy, =
    assess(sys, SequentialMonteCarlo(samples=10), GeneratorStorageEnergySamples())

samples = genstorenergy["MyGeneratorStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

Note that this result specification requires large amounts of memory for larger sample sizes. See GeneratorStorageEnergy for estimated average generator-storage state of charge when sample-level granularity isn't required.

GeneratorAvailability

The GeneratorAvailability result specification reports the sample-level discrete availability of Generators, producing a GeneratorAvailabilityResult.

A GeneratorAvailabilityResult can be indexed by generator name and 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:

genavail, =
    assess(sys, SequentialMonteCarlo(samples=10), GeneratorAvailability())

samples = genavail["MyGenerator123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

GeneratorStorageAvailability

The GeneratorStorageAvailability result specification reports the sample-level discrete availability of GeneratorStorages, producing a GeneratorStorageAvailabilityResult.

A GeneratorStorageAvailabilityResult can be indexed by generator-storage name and 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:

genstoravail, =
    assess(sys, SequentialMonteCarlo(samples=10), GeneratorStorageAvailability())

samples = genstoravail["MyGenerator123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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

LineAvailability

The LineAvailability result specification reports the sample-level discrete availability of Lines, producing a LineAvailabilityResult.

A LineAvailabilityResult can be indexed by line name and 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:

lineavail, =
    assess(sys, SequentialMonteCarlo(samples=10), LineAvailability())

samples = lineavail["MyLine123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]

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