From df298241cc2aba40c92f5ce1113c6e2ec0eba3fa Mon Sep 17 00:00:00 2001 From: Joseph McKinsey Date: Thu, 16 Jan 2025 12:38:29 -0700 Subject: [PATCH 1/4] Add documentation on adding outage data to a system --- .../src/tutorials/how_do_i_add_outage_data.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/src/tutorials/how_do_i_add_outage_data.md diff --git a/docs/src/tutorials/how_do_i_add_outage_data.md b/docs/src/tutorials/how_do_i_add_outage_data.md new file mode 100644 index 0000000..de43f2d --- /dev/null +++ b/docs/src/tutorials/how_do_i_add_outage_data.md @@ -0,0 +1,82 @@ +# How do I add outage data to Sienna? + +You can attach outage data to `PowerSystems` `Components` by using the +supplemental attribute [`GeometricDistributionForcedOutage`](https://nrel-sienna.github.io/PowerSystems.jl/stable/api/public/#PowerSystems.GeometricDistributionForcedOutage). + +## Step 1 : Parse your outage data into Sienna + +`SiennaPRASInterface.jl` uses outage information in the form of independent `mean_time_to_recovery` +in units of hours and `outage_transition_probability` in probability of outage per hour. +A simple Markov model models the transitions between out and active using these parameters. + +We support data either being fixed and specified in the `GeometricDistributionForcedOutage` object +or attached as time-series to the `GeometricDistributionForcedOutage` struct. + +### Creating a `GeometricDistributionForcedOutage` from fixed data + +```julia +using PowerSystems +transition_data = GeometricDistributionForcedOutage(; + mean_time_to_recovery=10, # Units of hours + outage_transition_probability=0.005, # Probability for outage per hour +) +``` + +### Creating a `GeometricDistributionForcedOutage` from time series data + +Time series should be attached to a `GeometricDistributionForcedOutage` object +under the keys `recovery_probability` (1/`mean_time_to_recovery`) and `outage_probability`. + +See the [Sienna time-series documentation on working with time-series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/). + +```julia +using PowerSystems +using Dates +using TimeSeries + +transition_data = GeometricDistributionForcedOutage(; + mean_time_to_recovery=10, # Units of hours + outage_transition_probability=0.005, # Probability for outage per hour +) + +outage_probability = [0.1, 0.1, 0.2, 0.3, 0.2, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.4] +recovery_probability = [0.1, 0.1, 0.2, 0.3, 0.2, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.4] + +# Your resolution and length must match the other SingleTimeSeries in your System. +resolution = Dates.Minute(5) +timestamps = range(DateTime("2020-01-01T08:00:00"); step = resolution, length = 24) +outage_timearray = TimeArray(timestamps, outage_probability) +outage_time_series = SingleTimeSeries(; + name = "outage_probability", + data = outage_timearray, +) + +recovery_timearray = TimeArray(timestamps, recovery_probability) +recovery_time_series = SingleTimeSeries(; + name = "recovery_probability", + data = recovery_timearray, +) + +# Here we assume you have a system named sys +PSY.add_time_series!(sys, transition_data, outage_time_series) +PSY.add_time_series!(sys, transition_data, recovery_time_series) +``` + +## Step 2 : Attaching Data to Components + +Once you have a `GeometricDistributionForcedOutage` object, then you can add it to +any components with that data: + +```julia +component = get_component(Generator, sys, "test_generator") +add_supplemental_attribute!(sys, component, transition_data) +``` + +## Step 3 : Run simulations and verify result + +```julia +using SiennaPRASInterface +method = SequentialMonteCarlo(samples=10_000, seed=1) +shortfalls, = assess(sys, PowerSystems.Area, sequential_monte_carlo, Shortfall()) +eue = EUE(shortfalls) +``` \ No newline at end of file From 6544aeb6564d8a2e39da3368b8ffbb078090c314 Mon Sep 17 00:00:00 2001 From: Joseph McKinsey <31461013+josephmckinsey@users.noreply.github.com> Date: Thu, 16 Jan 2025 12:45:29 -0700 Subject: [PATCH 2/4] Apply suggestions from juliaformatter Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/tutorials/how_do_i_add_outage_data.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/src/tutorials/how_do_i_add_outage_data.md b/docs/src/tutorials/how_do_i_add_outage_data.md index de43f2d..9f3ae4a 100644 --- a/docs/src/tutorials/how_do_i_add_outage_data.md +++ b/docs/src/tutorials/how_do_i_add_outage_data.md @@ -44,18 +44,13 @@ recovery_probability = [0.1, 0.1, 0.2, 0.3, 0.2, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0 # Your resolution and length must match the other SingleTimeSeries in your System. resolution = Dates.Minute(5) -timestamps = range(DateTime("2020-01-01T08:00:00"); step = resolution, length = 24) +timestamps = range(DateTime("2020-01-01T08:00:00"); step=resolution, length=24) outage_timearray = TimeArray(timestamps, outage_probability) -outage_time_series = SingleTimeSeries(; - name = "outage_probability", - data = outage_timearray, -) +outage_time_series = SingleTimeSeries(; name="outage_probability", data=outage_timearray) recovery_timearray = TimeArray(timestamps, recovery_probability) -recovery_time_series = SingleTimeSeries(; - name = "recovery_probability", - data = recovery_timearray, -) +recovery_time_series = + SingleTimeSeries(; name="recovery_probability", data=recovery_timearray) # Here we assume you have a system named sys PSY.add_time_series!(sys, transition_data, outage_time_series) From 52244eca99fac8bcab7dc561464aa85db2bbc6f4 Mon Sep 17 00:00:00 2001 From: Joseph McKinsey Date: Thu, 16 Jan 2025 13:03:24 -0700 Subject: [PATCH 3/4] Fix make.jl to point to tutorial --- docs/make.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 87abf9b..90dbb31 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -4,7 +4,7 @@ import OrderedCollections: OrderedDict pages = OrderedDict( "Welcome Page" => "index.md", - "Tutorials" => "tutorials/intro_page.md", + "Tutorials" => Any["How do I add outage data?" => "tutorials/how_do_i_add_outage_data.md"], "Public API Reference" => "api/public.md", "Internal API Reference" => "api/internal.md", ) From 575bd4ca438f0a6db1bb82170e9a09b9e1f53c1c Mon Sep 17 00:00:00 2001 From: Joseph McKinsey Date: Thu, 16 Jan 2025 13:08:11 -0700 Subject: [PATCH 4/4] Run formatter --- docs/make.jl | 3 ++- docs/src/tutorials/how_do_i_add_outage_data.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 90dbb31..ffa2866 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -4,7 +4,8 @@ import OrderedCollections: OrderedDict pages = OrderedDict( "Welcome Page" => "index.md", - "Tutorials" => Any["How do I add outage data?" => "tutorials/how_do_i_add_outage_data.md"], + "Tutorials" => + Any["How do I add outage data?" => "tutorials/how_do_i_add_outage_data.md"], "Public API Reference" => "api/public.md", "Internal API Reference" => "api/internal.md", ) diff --git a/docs/src/tutorials/how_do_i_add_outage_data.md b/docs/src/tutorials/how_do_i_add_outage_data.md index 9f3ae4a..c8dba39 100644 --- a/docs/src/tutorials/how_do_i_add_outage_data.md +++ b/docs/src/tutorials/how_do_i_add_outage_data.md @@ -74,4 +74,4 @@ using SiennaPRASInterface method = SequentialMonteCarlo(samples=10_000, seed=1) shortfalls, = assess(sys, PowerSystems.Area, sequential_monte_carlo, Shortfall()) eue = EUE(shortfalls) -``` \ No newline at end of file +```