Internal API
Modules = [SiennaPRASInterface, PRAS]
+Public = falseModules = [SiennaPRASInterface, PRAS]
+Public = falseSettings
This document was generated with Documenter.jl version 0.27.25 on Thursday 19 December 2024. Using Julia version 1.11.2.
SiennaPRASInterface — ModulePowerSystems Interface for Probabilistic Resource Adequacy Studies (PRAS)
Key Functions
generate_pras_system: convert PSY to PRAS modelassess: assess PRAS modelKey PRAS Types
SystemModel: PRAS data structureSequentialMonteCarlo: method for PRAS analysisShortfall: PRAS metric for missing generationLOLE: PRAS metric for loss of load expectationEUE: PRAS metric for energy unserved expectationSiennaPRASInterface.generate_pras_system — Functiongenerate_pras_system(sys::PSY.System, aggregation; kwargs...)Sienna/Data PowerSystems.jl System is the input and an object of PRAS SystemModel is returned. ...
Arguments
sys::PSY.System: Sienna/Data PowerSystems.jl Systemaggregation<:PSY.AggregationTopology: "PSY.Area" (or) "PSY.LoadZone" {Optional}availability::Bool: Takes into account avaialability of StaticInjection components when building the PRAS System {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 objectExamples
julia> generate_pras_system(psy_sys)
+PRAS SystemModelgenerate_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 fileaggregation::Type{AT}: Aggregation topology typeavailability::Bool: Availability of components in the Systemlump_region_renewable_gens::Bool: Lumping of region renewable generatorsexport_location::Union{Nothing, String}: Export location of the .pras fileReturns
PRASCore.SystemModel: PRAS SystemModelPRASCore.Systems.SystemModel — TypeSystemModelA SystemModel contains a representation of a power system to be studied with PRAS.
PRASCore.Simulations.assess — Functionassess(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 structuremethod::SequentialMonteCarlo: method for PRAS analysisresultspecs::ResultSpec...: PRAS metric for metrics like Shortfall missing generationReturns
results::Tuple{Vararg{ResultAccumulator{SequentialMonteCarlo}}}: PRAS metric resultsassess(
+ sys::PSY.System,
+ aggregation::Type{AT},
+ method::PRASCore.SequentialMonteCarlo,
+ resultsspecs::PRASCore.Results.ResultSpec...,
+) where {AT <: PSY.AggregationTopology}Estimate resource adequacy using Monte Carlo simulation.
Arguments
sys::PSY.System: PowerSystems.jl system modelaggregation::Type{AT}: Aggregation topology to use in translating to PRASmethod::PRASCore.SequentialMonteCarlo: Simulation method to useresultsspec::PRASCore.Results.ResultSpec...: Results to computeReturns
resultsspec: default is (ShortfallResult,)PRASCore.Simulations.SequentialMonteCarlo — TypeSequentialMonteCarlo(;
+ 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 samplesseed::Integer=rand(UInt64): Random seedverbose::Bool=false: Print progressthreaded::Bool=true: Use multi-threadingReturns
SequentialMonteCarlo: PRAS simulation specificationPRASCore.Results.Shortfall — TypeShortfallThe 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)
+
+# Regional risk metrics
+regional_eue = EUE(shortfall, "Region A")
+regional_lole = LOLE(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.
PRASCore.Results.Surplus — TypeSurplusThe 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.
PRASCore.Results.Flow — TypeFlowThe 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_meanSee FlowSamples for sample-level flow results.
PRASCore.Results.Utilization — TypeUtilizationThe 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_meanSee UtilizationSamples for sample-level utilization results.
PRASCore.Results.StorageEnergy — TypeStorageEnergyThe 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.
PRASCore.Results.GeneratorStorageEnergy — TypeGeneratorStorageEnergyThe 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.
PRASCore.Results.LOLE — TypeLOLELOLE 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.
PRASCore.Results.EUE — TypeEUEEUE 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.
Missing docstring for val. Check Documenter's build log for details.
Missing docstring for stderror. Check Documenter's build log for details.
SiennaPRASInterface.generate_outage_profile — Functiongenerate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)Process the assess results to get timeseries of generator status and include this timeseries data to the corresponding component in PSY System and exported using to_json method (serializing the PSY System).
...
Arguments
pras_system::PRASCore.SystemModel: PRAS Systemnum_runs::Int64: Number of PRAS runspsy_sys::PSY.System: PSY Systemnum_scenarios::Int64: Number of scenarios of user interest.location::String: Location to store outage profile. ...Examples
julia> generate_outage_profile(results, pras_sys, psy_sys, 1)
+PSY System exported using to_json method in InfrastructureSystemsSiennaPRASInterface.generate_csv_outage_profile — Functiongenerate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)Process the assess results to get timeseries of generator status and include this timeseries data to the corresponding component in PSY System and exported using to_json method (serializing the PSY System).
...
Arguments
pras_system::PRASCore.SystemModel: PRAS Systemnum_runs::Int64: Number of PRAS runspsy_sys::PSY.System: PSY Systemnum_scenarios::Int64: Number of scenarios of user interest.location::String: Location to store outage profile. ...Examples
julia> generate_outage_profile(results, pras_sys, psy_sys, 1)
+PSY System exported using to_json method in InfrastructureSystemsSiennaPRASInterface.add_csv_time_series! — Functionadd_csv_time_series!(
+ sys_DA,
+ sys_RT,
+ outage_csv_location::String;
+ days_of_interest::Union{Nothing, UnitRange}=nothing,
+ add_scenario::Union{Nothing, Int}=nothing,
+)Generates outage profile for two stage PowerSimulation and adds availability time series data to Generators in PSY System from CSV files.
SiennaPRASInterface.add_csv_time_series_single_stage! — Functionadd_csv_time_series_single_stage!(
+ sys_DA,
+ outage_csv_location::String;
+ days_of_interest::Union{Nothing, UnitRange}=nothing,
+ add_scenario::Union{Nothing, Int}=nothing,
+)Generates outage profile for single stage PowerSimulation and adds availability time series.
SiennaPRASInterface.make_generator_outage_draws! — Functionmake_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.
PRASCore.Results.ShortfallSamples — TypeShortfallSamplesThe 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)
+
+# Regional risk metrics
+regional_eue = EUE(shortfall, "Region A")
+regional_lole = LOLE(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.
PRASCore.Results.SurplusSamples — TypeSurplusSamplesThe 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) == 10Note 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.
PRASCore.Results.FlowSamples — TypeFlowSamplesThe 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 == -samples2Note 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.
PRASCore.Results.UtilizationSamples — TypeUtilizationSamplesThe 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 == samples2Note 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.
PRASCore.Results.StorageEnergySamples — TypeStorageEnergySamplesThe 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) == 10Note 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.
PRASCore.Results.GeneratorStorageEnergySamples — TypeGeneratorStorageEnergySamplesThe 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) == 10Note 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.
PRASCore.Results.GeneratorAvailability — TypeGeneratorAvailabilityThe 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) == 10PRASCore.Results.GeneratorStorageAvailability — TypeGeneratorStorageAvailabilityThe 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) == 10PRASCore.Results.LineAvailability — TypeLineAvailabilityThe 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) == 10Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 19 December 2024. Using Julia version 1.11.2.
SiennaPRASInterface.jl is a Julia package that provides an interface to PRAS.jl from Sienna's PowerSystem.jl's System data model.
The Probabilistic Resource Adequacy Suite (PRAS) analyzes the resource adequacy of a bulk power system using Monte Carlo methods.
To use SiennaPRASInterface.jl, you first need a System from PowerSystems.jl
] add SiennaPRASInterfaceAdd outage information to generators using the supplemental attribute GeometricDistributionForcedOutage.
using PowerSystems
+transition_data = GeometricDistributionForcedOutage(;
+ mean_time_to_recovery=10, # Units of hours
+ outage_transition_probability=0.005, # Probability for outage per hour
+)
+component = get_component(Generator, sys, "test_generator")
+add_supplemental_attribute!(sys, component, transition_data)using SiennaPRASInterface
+method = SequentialMonteCarlo(samples=10_000, seed=1)
+shortfalls, = assess(sys, PowerSystems.Area, sequential_monte_carlo, Shortfall())
+eue = EUE(shortfalls)SiennaPRASInterface has been developed as part of the Transmission Planning Tools Maintenance project at the U.S. Department of Energy's National Renewable Energy Laboratory (NREL) funded by DOE Grid Deployment Office (GDO).
Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 19 December 2024. Using Julia version 1.11.2.
Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 19 December 2024. Using Julia version 1.11.2.
Tutorials to be created soon.
Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 19 December 2024. Using Julia version 1.11.2.