From 84a65547c6a1f5f29b83f0aac932a83ae6b3b995 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 9 Jan 2025 14:36:13 -0700 Subject: [PATCH 01/25] Begin documentation build with documenter.jl --- .gitignore | 3 +++ docs/Project.toml | 7 +++++++ docs/make.jl | 35 +++++++++++++++++++++++++++++++ docs/serve.jl | 15 +++++++++++++ docs/src/PRASCore/index.md | 4 ++++ docs/{ => src}/getting-started.md | 0 docs/{ => src}/index.md | 4 +++- 7 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/serve.jl create mode 100644 docs/src/PRASCore/index.md rename docs/{ => src}/getting-started.md (100%) rename docs/{ => src}/index.md (92%) diff --git a/.gitignore b/.gitignore index 1fe04f98..baa3d467 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ Manifest.toml *.DS_Store *.pras *.json + +docs/build/ +docs/site/ \ No newline at end of file diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..6da7032f --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,7 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" +PRASCore = "c5c32b99-e7c3-4530-a685-6f76e19f7fe2" + +[compat] +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..83e85da7 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,35 @@ +using Documenter +using PRASCore +#using Package2 +#using Package3 + +# Generate the unified documentation +makedocs( + sitename = "PRAS", + format = Documenter.HTML( + prettyurls = get(ENV, "CI", nothing) == "true", + canonical = "https://nrel.github.io/PRAS/stable" + ), + modules = [PRASCore.Results,PRASCore.Systems], + pages = [ + "Home" => "index.md", + "PRASCore" => [ + "Overview" => "PRASCore/index.md", + #"API Reference" => "PRASCore/api.md" + ], + # "Package2" => [ + # "Overview" => "package2/index.md", + # "API Reference" => "package2/api.md" + # ], + # "Package3" => [ + # "Overview" => "package3/index.md", + # "API Reference" => "package3/api.md" + # ] + ] +) + +deploydocs( + repo = "github.com/NREL/PRAS", + devbranch = "main", + push_preview = true +) \ No newline at end of file diff --git a/docs/serve.jl b/docs/serve.jl new file mode 100644 index 00000000..bf4ab0e4 --- /dev/null +++ b/docs/serve.jl @@ -0,0 +1,15 @@ +using LiveServer +using Pkg + +# Develop all packages +for pkg in readdir("../packages") + pkg_path = joinpath("..", "packages", pkg) + isdir(pkg_path) || continue + Pkg.develop(PackageSpec(path=pkg_path)) +end + +# Build docs +include("make.jl") + +# Serve documentation +serve(dir="build") \ No newline at end of file diff --git a/docs/src/PRASCore/index.md b/docs/src/PRASCore/index.md new file mode 100644 index 00000000..3dc43661 --- /dev/null +++ b/docs/src/PRASCore/index.md @@ -0,0 +1,4 @@ +```@autodocs +Modules = [PRASCore.Results,PRASCore.Systems] +Order = [:function,:type] +``` diff --git a/docs/getting-started.md b/docs/src/getting-started.md similarity index 100% rename from docs/getting-started.md rename to docs/src/getting-started.md diff --git a/docs/index.md b/docs/src/index.md similarity index 92% rename from docs/index.md rename to docs/src/index.md index d320b2c1..3e96dfde 100644 --- a/docs/index.md +++ b/docs/src/index.md @@ -8,4 +8,6 @@ assessment, including simulation of energy-limited resources such as storage. PRAS is developed and maintained at the US [National Renewable Energy Laboratory](https://www.nrel.gov/) (NREL). -For help installing PRAS, see the [instructions in the PRAS GitHub page](https://github.com/NREL/PRAS). To get started using PRAS, see the [Getting Started](./getting-started) page. +For help installing PRAS, see the [instructions in the PRAS GitHub page](https://github.com/NREL/PRAS). To get started using PRAS, see the [Getting Started](./getting-started.md) page. + + From a892cdb68a441277326ffe9954becee126b4e439 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 6 Aug 2025 16:36:02 -0600 Subject: [PATCH 02/25] Docs updates --- PRASCore.jl/src/Simulations/Simulations.jl | 2 +- docs/Project.toml | 2 ++ docs/make.jl | 30 +++++++++++-------- docs/src/PRASCapacityCredits/api.md | 4 +++ docs/src/PRASCapacityCredits/index.md | 10 +++++++ docs/src/PRASCore/api.md | 19 ++++++++++++ docs/src/PRASCore/index.md | 5 +--- docs/src/PRASFiles/api.md | 4 +++ docs/src/PRASFiles/index.md | 10 +++++++ .../src/SystemModel_HDF5_spec.md | 0 docs/src/getting-started.md | 4 +-- docs/src/index.md | 2 +- docs/src/installation.md | 20 +++++++++++++ 13 files changed, 90 insertions(+), 22 deletions(-) create mode 100644 docs/src/PRASCapacityCredits/api.md create mode 100644 docs/src/PRASCapacityCredits/index.md create mode 100644 docs/src/PRASCore/api.md create mode 100644 docs/src/PRASFiles/api.md create mode 100644 docs/src/PRASFiles/index.md rename SystemModel_HDF5_spec.md => docs/src/SystemModel_HDF5_spec.md (100%) create mode 100644 docs/src/installation.md diff --git a/PRASCore.jl/src/Simulations/Simulations.jl b/PRASCore.jl/src/Simulations/Simulations.jl index 0178c75e..b9f220b6 100644 --- a/PRASCore.jl/src/Simulations/Simulations.jl +++ b/PRASCore.jl/src/Simulations/Simulations.jl @@ -75,7 +75,7 @@ and return `resultspecs`. - `system::SystemModel`: PRAS data structure - `method::SequentialMonteCarlo`: method for PRAS analysis - - `resultspecs::ResultSpec...`: PRAS metric for metrics like [`Shortfall`](@ref) missing generation + - `resultspecs::ResultSpec...`: PRAS metric for metrics like [`Shortfall`](@ref PRASCore.Results.Shortfall) missing generation # Returns diff --git a/docs/Project.toml b/docs/Project.toml index 6da7032f..165edb32 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,7 +1,9 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" +PRASCapacityCredits = "2e1a2ed5-e89d-4cd3-bc86-c0e88a73d3a3" PRASCore = "c5c32b99-e7c3-4530-a685-6f76e19f7fe2" +PRASFiles = "a2806276-6d43-4ef5-91c0-491704cd7cf1" [compat] Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl index 83e85da7..a30312f4 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,7 +1,7 @@ using Documenter using PRASCore -#using Package2 -#using Package3 +using PRASFiles +using PRASCapacityCredits # Generate the unified documentation makedocs( @@ -10,22 +10,26 @@ makedocs( prettyurls = get(ENV, "CI", nothing) == "true", canonical = "https://nrel.github.io/PRAS/stable" ), - modules = [PRASCore.Results,PRASCore.Systems], + modules = [PRASCore, PRASFiles, PRASCapacityCredits], pages = [ "Home" => "index.md", + "Installation" => "installation.md", + "Getting Started" => "getting-started.md", "PRASCore" => [ "Overview" => "PRASCore/index.md", - #"API Reference" => "PRASCore/api.md" + "API Reference" => "PRASCore/api.md" ], - # "Package2" => [ - # "Overview" => "package2/index.md", - # "API Reference" => "package2/api.md" - # ], - # "Package3" => [ - # "Overview" => "package3/index.md", - # "API Reference" => "package3/api.md" - # ] - ] + "PRASFiles" => [ + "Overview" => "PRASFiles/index.md", + "API Reference" => "PRASFiles/api.md" + ], + "PRASCapacityCredits" => [ + "Overview" => "PRASCapacityCredits/index.md", + "API Reference" => "PRASCapacityCredits/api.md" + ] + ], + checkdocs = :exports, + warnonly = true, ) deploydocs( diff --git a/docs/src/PRASCapacityCredits/api.md b/docs/src/PRASCapacityCredits/api.md new file mode 100644 index 00000000..3e0cb82f --- /dev/null +++ b/docs/src/PRASCapacityCredits/api.md @@ -0,0 +1,4 @@ +```@autodocs +Modules = [PRASCapacityCredits] +Order = [:function,:type] +``` diff --git a/docs/src/PRASCapacityCredits/index.md b/docs/src/PRASCapacityCredits/index.md new file mode 100644 index 00000000..16da55fe --- /dev/null +++ b/docs/src/PRASCapacityCredits/index.md @@ -0,0 +1,10 @@ +# PRAS Capacity Credits + +PRASCapacityCredits.jl provides functionality for calculating capacity credits of different resource types within a power system. This package integrates with PRASCore for resource adequacy analysis and capacity credit calculations. + +This package includes: +- Methods for calculating capacity credits using various methodologies +- Integration with PRASCore system models and results +- Analysis tools for understanding resource contributions to reliability + +For detailed information on available methods and types, see the [API Reference](./api.md). diff --git a/docs/src/PRASCore/api.md b/docs/src/PRASCore/api.md new file mode 100644 index 00000000..5f3840af --- /dev/null +++ b/docs/src/PRASCore/api.md @@ -0,0 +1,19 @@ +# PRASCore API reference + +## Systems +```@autodocs +Modules = [PRASCore.Systems] +Order = [:function] +``` + +## Simulations +```@autodocs +Modules = [PRASCore.Simulations] +Order = [:function] +``` + +## Results +```@autodocs +Modules = [PRASCore.Results] +Order = [:function] +``` diff --git a/docs/src/PRASCore/index.md b/docs/src/PRASCore/index.md index 3dc43661..a27694a0 100644 --- a/docs/src/PRASCore/index.md +++ b/docs/src/PRASCore/index.md @@ -1,4 +1 @@ -```@autodocs -Modules = [PRASCore.Results,PRASCore.Systems] -Order = [:function,:type] -``` +# PRAS Core \ No newline at end of file diff --git a/docs/src/PRASFiles/api.md b/docs/src/PRASFiles/api.md new file mode 100644 index 00000000..7a3faf0e --- /dev/null +++ b/docs/src/PRASFiles/api.md @@ -0,0 +1,4 @@ +```@autodocs +Modules = [PRASFiles] +Order = [:function,:type] +``` diff --git a/docs/src/PRASFiles/index.md b/docs/src/PRASFiles/index.md new file mode 100644 index 00000000..9ed9f195 --- /dev/null +++ b/docs/src/PRASFiles/index.md @@ -0,0 +1,10 @@ +# PRAS Files + +PRASFiles.jl provides functionality for reading and writing PRAS-specific file formats, allowing you to save and load resource adequacy data structures. + +This package enables: +- Loading and saving PRAS system models +- Importing data from various formats +- Exporting results and system information to standard formats + +For detailed information on available methods and types, see the [API Reference](./api.md). diff --git a/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md similarity index 100% rename from SystemModel_HDF5_spec.md rename to docs/src/SystemModel_HDF5_spec.md diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index c0dd2673..f8ec2714 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -1,8 +1,6 @@ # Getting Started with PRAS -For a complete overview of PRAS, see the -[v0.6 documentation report](https://www.nrel.gov/docs/fy21osti/79698.pdf). -This page provides a briefer overview to help you start running PRAS quickly. +Once you have PRAS [installed](./installation.md), this page provides a brief overview to help you start running PRAS quickly. ## Parallel Processing diff --git a/docs/src/index.md b/docs/src/index.md index 3e96dfde..8e352859 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -8,6 +8,6 @@ assessment, including simulation of energy-limited resources such as storage. PRAS is developed and maintained at the US [National Renewable Energy Laboratory](https://www.nrel.gov/) (NREL). -For help installing PRAS, see the [instructions in the PRAS GitHub page](https://github.com/NREL/PRAS). To get started using PRAS, see the [Getting Started](./getting-started.md) page. +To get started on using PRAS, see the [installation](./installation.md) and [getting Started](./getting-started.md) pages. diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 00000000..aa460bcd --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1,20 @@ +# Installation + +PRAS is written in the [Julia](https://julialang.org/) numerical programming +language. If you haven't already, your first step should be to install Julia. +Instructions are available at +[julialang.org/downloads](https://julialang.org/downloads/). + +Once you have Julia installed, PRAS can be installed from the Julia [General registry](https://pkgdocs.julialang.org/v1/registries/) which is installed by default if you have no other registries installed. + +From the main Julia prompt, type `]` to enter the package management REPL. +The prompt should change from `julia>` to something like `(v1.10) pkg>` +(your version number may be slightly different). +Type (or paste) the following (minus the `pkg>` prompt) +``` +pkg> add PRAS +``` + +This will automatically install the PRAS Julia module and all of its +related dependencies. At this point you can hit Backspace to switch back to the +main `julia>` prompt. \ No newline at end of file From 42c3c3b45756f1e68edd35f83168e1f398039ca1 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 7 Aug 2025 14:45:07 -0600 Subject: [PATCH 03/25] Add more docs --- docs/Project.toml | 4 - docs/make.jl | 29 ++- docs/serve.jl | 4 +- docs/src/PRAS/acknowledgements.md | 8 + docs/src/PRAS/capacity-credit.md | 221 +++++++++++++++++ docs/src/PRAS/extending.md | 271 ++++++++++++++++++++ docs/src/PRAS/inputs.md | 204 +++++++++++++++ docs/src/PRAS/introduction.md | 22 ++ docs/src/PRAS/results.md | 327 +++++++++++++++++++++++++ docs/src/PRAS/simulations.md | 61 +++++ docs/src/getting-started.md | 142 +++-------- docs/src/images/genstorexamples.pdf | Bin 0 -> 41131 bytes docs/src/images/inputoutput.pdf | Bin 0 -> 54087 bytes docs/src/images/networkflow.pdf | Bin 0 -> 50804 bytes docs/src/images/resourceparameters.pdf | Bin 0 -> 62566 bytes docs/src/index.md | 8 +- docs/src/resource-adequacy.md | 54 ++++ 17 files changed, 1218 insertions(+), 137 deletions(-) create mode 100644 docs/src/PRAS/acknowledgements.md create mode 100644 docs/src/PRAS/capacity-credit.md create mode 100644 docs/src/PRAS/extending.md create mode 100644 docs/src/PRAS/inputs.md create mode 100644 docs/src/PRAS/introduction.md create mode 100644 docs/src/PRAS/results.md create mode 100644 docs/src/PRAS/simulations.md create mode 100644 docs/src/images/genstorexamples.pdf create mode 100644 docs/src/images/inputoutput.pdf create mode 100644 docs/src/images/networkflow.pdf create mode 100644 docs/src/images/resourceparameters.pdf create mode 100644 docs/src/resource-adequacy.md diff --git a/docs/Project.toml b/docs/Project.toml index 165edb32..1814eb33 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,9 +1,5 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" -LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" -PRASCapacityCredits = "2e1a2ed5-e89d-4cd3-bc86-c0e88a73d3a3" -PRASCore = "c5c32b99-e7c3-4530-a685-6f76e19f7fe2" -PRASFiles = "a2806276-6d43-4ef5-91c0-491704cd7cf1" [compat] Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl index a30312f4..3b7a78e8 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -13,19 +13,22 @@ makedocs( modules = [PRASCore, PRASFiles, PRASCapacityCredits], pages = [ "Home" => "index.md", - "Installation" => "installation.md", - "Getting Started" => "getting-started.md", - "PRASCore" => [ - "Overview" => "PRASCore/index.md", - "API Reference" => "PRASCore/api.md" + "Installation instructions" => "installation.md", + "Resource adequacy" => "resource-adequacy.md", + "Quick start" => "getting-started.md", + "System model specification" => "SystemModel_HDF5_spec.md", + "PRAS" => [ + "Introduction" => "PRAS/introduction.md", + "Input System Specification" => "PRAS/inputs.md", + "Simulation Specifications" => "PRAS/simulations.md", + "Result Specifications" => "PRAS/results.md", + "Capacity Credit Calculation" => "PRAS/capacity-credit.md", + "Extending PRAS" => "PRAS/extending.md", ], - "PRASFiles" => [ - "Overview" => "PRASFiles/index.md", - "API Reference" => "PRASFiles/api.md" - ], - "PRASCapacityCredits" => [ - "Overview" => "PRASCapacityCredits/index.md", - "API Reference" => "PRASCapacityCredits/api.md" + "API Reference" => [ + "PRASCore" => "PRASCore/api.md", + "PRASFiles" => "PRASFiles/api.md", + "PRASCapacityCredits" => "PRASCapacityCredits/api.md" ] ], checkdocs = :exports, @@ -33,7 +36,7 @@ makedocs( ) deploydocs( - repo = "github.com/NREL/PRAS", + repo = "github.com/NREL/PRAS.git", devbranch = "main", push_preview = true ) \ No newline at end of file diff --git a/docs/serve.jl b/docs/serve.jl index bf4ab0e4..ff4cc908 100644 --- a/docs/serve.jl +++ b/docs/serve.jl @@ -2,8 +2,8 @@ using LiveServer using Pkg # Develop all packages -for pkg in readdir("../packages") - pkg_path = joinpath("..", "packages", pkg) +for pkg in ["PRASCore.jl", "PRASFiles.jl", "PRASCapacityCredits.jl"] + pkg_path = joinpath("..", pkg) isdir(pkg_path) || continue Pkg.develop(PackageSpec(path=pkg_path)) end diff --git a/docs/src/PRAS/acknowledgements.md b/docs/src/PRAS/acknowledgements.md new file mode 100644 index 00000000..684e25f8 --- /dev/null +++ b/docs/src/PRAS/acknowledgements.md @@ -0,0 +1,8 @@ +# Acknowledgments + +Special thanks to NREL's Trieu Mai, Paul Denholm, and Greg Brinkman for their +support and feedback in preparing this work, and to Sarah Awara and Sinnott +Murphy (NREL), as well as Armando Figueroa Acevedo (Black & Veatch), for +reviewing drafts of this report. Additional thanks go +to Jaquelin Cochran, Bethany Frew, Wesley Cole, and Aaron Bloom for +their broad historical support in the development of the PRAS model. diff --git a/docs/src/PRAS/capacity-credit.md b/docs/src/PRAS/capacity-credit.md new file mode 100644 index 00000000..5e4a6b74 --- /dev/null +++ b/docs/src/PRAS/capacity-credit.md @@ -0,0 +1,221 @@ +# Capacity Credit Calculation + +Resource adequacy paradigms premised on adding resource capacities together to +meet a planning reserve margin require the quantification of a "capacity credit" (sometimes called "capacity value") +for individual resources. While the process of assigning capacity credits is +relatively straightforward for thermal generating units with consistent +potential contributions to system adequacy throughout the day and year +(assuming no fuel constraints), the contributions of variable and +energy-limited resources can be much more difficult to represent as a +single capacity rating. + +In these cases, an accurate characterization depends on +the broader system context in which the resource operates. +Probabilistically derived capacity credit calculations +provide a technology-agnostic means of expressing the contributions of +different resources (with diverse and potentially complicated operating +characteristics and constraints) in terms of a common, simple measure of +capacity. + +PRAS provides two different methods for mapping incremental resource adequacy +contributions to generic capacity: Equivalent Firm Capacity (**EFC**) +and Effective Load Carrying Capability (**ELCC**). In each case, the user +must provide PRAS with two system representations: one that contains the study +resource (the augmented system), and one that does not (the base system). The +difference between the two systems is then quantified in terms of a capacity +credit. + +By choosing what is included in the base case relative to the augmented case, +the user can study either the average, portfolio-level capacity credit of a +resource class (by excluding all resources of that class from the base case, +and including them all in the augmented case) or the marginal capacity credit +(by including almost all of the resource type in the base case, and adding a +single incremental unit in the augmented case). + +Note that probabilistically derived capacity credit calculations always involve +some kind of measurement of the reduction in system risk associated with moving +from the base system to the augmented system. If the base system's risk cannot +be reduced (perhaps because the base system's shortfall risk is too small to +obtain a non-zero estimate, or because shortfall only occurs in load pockets +elsewhere in the system), adequacy-based capacity credit metrics may not be +meaningful. In these cases, the starting system may need to be modified, or a +different capacity credit calculation method may be required. + +The remainder of this chapter provides details on the theoretical and practical +aspects of using EFC and ELCC for capacity credit analysis in PRAS. Further +mathematical details regarding capacity credit are available in +[Zachary and Dent (2011)](#references). + +## Equivalent Firm Capacity (EFC) + +### Theory + +EFC calculates the amount of idealized "firm" capacity (uniformly available +across all periods, without ever going on outage) that is required to +reproduce the observed resource adequacy benefit (reduction of a specific risk +metric) associated with some study resource of interest. It requires both a base case system (without the study +resource added) and an augmented system (with the study resource added). The +analysis then proceeds as follows: + +1. Assess the shortfall risk of the base system according to the + chosen metric (EUE or LOLE). +2. Assess the (lower) shortfall risk of the augmented system according + to the chosen metric. +3. Reassess the shortfall risk of the base system after adding some + amount of "firm" capacity. If the risk matches that of the augmented + system, stop. The amount of firm capacity added is the + Equivalent Firm Capacity of the study resource. +4. If the base+firm and augmented system risks do not match, change the + amount of firm capacity added to the base system, repeating until + the chosen shortfall risk metrics for each system match. + +Typically, the counterfactual firm capacity is added +to the system as a direct replacement for the study resource, and so is located +in the same region (or distributed across multiple regions in corresponding +proportions) as the study resource. PRAS uses a bisection method to +find the appropriate total firm capacity to add to the base system. + +### Usage + +Performing an EFC assessment in PRAS requires specifying two different +`SystemModel`s: one representing the base system, and a second +representing the augmented system. It also requires specifying the probabilistic risk metric to +use when comparing system risks, an upper bound on the EFC (usually, +the nameplate capacity of the study resource) and to which region(s) the +counterfactual firm capacity should be added. Finally, the simulation +specification should be provided (any simulation method can be used). + +For example, to calculate EFC based on EUE for a resource in region A, with an +upper EFC bound of 1000 MW (assuming the `SystemModel`s are represented +in MW), using the sequential Monte Carlo simulation specification: + +```julia +assess(base_system, augmented_system, + EFC{EUE}(1000, "A"), SequentialMonteCarlo()) +``` + +If the study resources are spread over multiple regions (for example, 600 MW +of wind in region A and 400 MW of wind in region B), the fraction of total firm +capacity added to each region can be specified as: + +```julia +assess(base_system, augmented_system, + EFC{EUE}(1000, ["A"=>0.6, "B"=>0.4]), SequentialMonteCarlo()) +``` + +The `EFC()` specification accepts multiple optional keyword +arguments, which can be provided in any order: + +**p_value**: A floating point value giving the maximum allowable p-value +from a one-sided hypothesis test. The test considers whether the lower risk +metric used during bisection is in fact less than the upper risk metric. If the p-value exceeds this level, the +assessment will terminate early due to a lack of statistical power. Note that this only matters for simulation +specifications returning estimates with non-zero standard errors, i.e. +Monte Carlo-based methods. Defaults to `0.05`. + +**capacity_gap**: An integer giving the maximum desired difference between +reported upper and lower bounds on capacity credit. Once the gap between upper +and lower bounds is less than or equal to this value, the assessment will +terminate. Defaults to `1`. + +**verbose**: A boolean value defaulting to `false`. If `true`, +PRAS will output informative text describing the progress of the assessment. + +## Effective Load Carrying Capability (ELCC) + +### Theory + +ELCC quantifies the capacity credit of a study resource according to the +amount of additional constant load the system can serve while +maintaining the same shortfall risk. Like EFC, it requires both a base case +system (without the study resource added) and an augmented system (with the +study resource added). The analysis then proceeds as follows: + +1. Assess the shortfall risk of the base system according to the + chosen metric (EUE or LOLE). +2. Assess the (lower) shortfall risk of the augmented system according + to the chosen metric. +3. Reassess the shortfall risk of the augmented system after adding some + amount of constant load. If the risk matches that of the base + system, stop. The amount of constant load added is the + Effective Load Carrying Capability of the study resource. +4. If the base and augmented+load system risks do not match, change the + amount of load added to the augmented system, repeating until + the chosen shortfall risk metrics for each system match. + +ELCC calculations in a multi-region system require choosing where load should +be increased. There are many possible options, including uniformly distributing +new load across each region, distributing load proportional to +total energy demand in each region, and adding load only in the region with +the study resource. The "correct" choice will depend on the goals of the +specific analysis. Once the regional load distribution is specified, PRAS uses +a bisection method to find the appropriate amount of total load to add to the +system. + +### Usage +Performing an ELCC assessment in PRAS requires specifying two different +`SystemModel`s: one representing the base system, and a second +representing the augmented system. It also requires specifying the probabilistic risk metric to +use when comparing system risks, an upper bound on the ELCC (usually, +the nameplate capacity of the study resource) and to which region(s) the +additional load should be added. Finally, the simulation +specification should be provided. + +For example, to calculate ELCC based on EUE for a resource intending to serve +load in region A, with an upper ELCC bound of 1000 MW (assuming the `SystemModel`s are represented +in MW): + +```julia +assess(base_system, augmented_system, + ELCC{EUE}(1000, "A"), SequentialMonteCarlo()) +``` + +If the load serving assessment is to be spread over multiple regions +(for example, 50% of load in region A and 50% in region B), the fraction of additional load added +to each region can be specified as: + +```julia +assess(base_system, augmented_system, + ELCC{EUE}(1000, ["A"=>0.5, "B"=>0.5]), SequentialMonteCarlo()) +``` + +The `ELCC()` specification accepts multiple optional keyword +arguments, which can be provided in any order: + +**p_value**: A floating point value giving the maximum allowable p-value +from a one-sided hypothesis test. The test considers whether the lower risk +metric used during bisection is in fact less than the upper risk metric. If the p-value exceeds this level, the +assessment will terminate early due to a lack of statistical power. Note that this only matters for simulation +specifications returning estimates with non-zero standard errors, i.e. +Monte Carlo-based methods. Defaults to `0.05`. + +**capacity_gap**: An integer giving the maximum desired difference between +reported upper and lower bounds on capacity credit. Once the gap between upper +and lower bounds is less than or equal to this value, the assessment will +terminate. Defaults to `1`. + +**verbose**: A boolean value defaulting to `false`. If `true`, +PRAS will output informative text describing the progress of the assessment. + +## Capacity Credit Results + +Both EFC and ELCC assessments return `CapacityCreditResult` objects. +These objects contain information on estimated lower and upper bounds of the +capacity credit, as well as additional details about the process through +which the capacity credit was calculated. Results can be retrieved as follows: + +```julia +cc_result = assess(base_system, augmented_system, EFC{EUE}(1000, "A"), + SequentialMonteCarlo()) + +# Get lower and upper bounds on CC estimate +cc_lower = minimum(cc_result) +cc_upper = maximum(cc_result) + +# Get both bounds at once +cc_lower, cc_upper = extrema(cc_result) +``` + +## References + +Zachary, S., & Dent, C. J. (2011). Probability theory of capacity value of additional generation. Proc. IMechE Part O: J. Risk and Reliability, 226, 33-43. diff --git a/docs/src/PRAS/extending.md b/docs/src/PRAS/extending.md new file mode 100644 index 00000000..2a01b0f2 --- /dev/null +++ b/docs/src/PRAS/extending.md @@ -0,0 +1,271 @@ +# Extending PRAS + +PRAS provides opportunties for users to non-invasively build on its general +simulation framework by redefining how simulations are executed, augmenting +how results are reported, or both. This allows for customized analyses +without requiring the user to modify code in the main PRAS package or +implement their own model from scratch. + +To implement custom functionality, a user needs to define specific Julia data +structures as well as implement function methods that operate on those +structures. Julia's multiple dispatch functionality can then identify and use +these newly defined capabilities when the `assess` function is invoked +appropriately. + +## Custom Simulation Specifications + +Custom simulation specifications allow for redefining how PRAS models system +operations. In addition to the data structures and methods listed here, +defining a new simulation specification also requires defining the appropriate +simulation-result interactions (see [Simulation-Result Interfaces](#simulation-result-interfaces)). + +### New Data Structure Requirements + +The following new data structure (struct / type) should be defined in Julia: + +#### Simulation Specification + +The main type representing the new simulation specification. It should be a +subtype of the `SimulationSpec` abstract type and can contain +fields that store simulation parameters (such as the number of Monte Carlo +samples to run or the random number generation seed to use). For example: + +```julia +struct MyCustomSimSpec <: SimulationSpec + nsamples::UInt64 + seed::UInt64 +end +``` + +### New Method Requirements + +The following new function method should be defined in Julia: + +#### assess + +The method to be invoked when the `assess` function is called with the +previously defined simulation specification. By convention, the method should +take a `SystemModel` as the first argument, followed by a specific subtype of +`SimulationSpec`, followed by one or more unspecified subtypes of +`ResultSpec`. For example (using the `MyCustomSimSpec` type +defined above): + +```julia +function PRAS.assess( + sys::SystemModel, simspec::MyCustomSimSpec, resultspecs::ResultSpec...) + + # Implement the simulation logic for MyCustomSimSpec here + + # This will include simulation-result interaction calls to result + # recording methods, which will need to be implemented by any result + # specification wanting to be compatible with MyCustomSimSpec + +end +``` + +## Custom Result Specifications + +Custom result specifications allow for saving out additional information that +may be generated during simulations of system operations. In addition to the +data structures and methods listed here, defining a new result specification +also requires defining the appropriate simulation-result interactions (see +[Simulation-Result Interfaces](#simulation-result-interfaces)). + +### New Data Structure Requirements +The following new data structures (structs / types) should be defined in Julia: + +#### Result Specification + +The main type representing the result specification. It should be a subtype of +the `ResultSpec` abstract type and can contain fields that store result +parameters (although this is usually not necessary). For example: + +```julia +struct MyCustomResultSpec <: ResultSpec +end +``` + +#### Result + +The type of the data that is returned at the end of an assessment and stores +any information to be reported to the end-user. It should be a subtype of the +`Result` abstract type and should contain fields that store the desired +results. For example: + +```julia +struct MyCustomResult <: Result + myoutput1::Float64 + myoutput2::Vector{Bool} +end +``` + +### New Method Requirements + +#### Indexing + +Result data should support index lookups to report overall results or values +for specific time periods, regions, interfaces, units, etc. +The specifics of how the result data is indexed will depend on the nature of +the result type, but will likely involve implementing one of more of the +following methods (here we assume the new result type is +`MyCustomResult`): + +```julia +Base.getindex(result::MyCustomResult) +Base.getindex(result::MyCustomResult, region_or_unit::String) +Base.getindex(result::MyCustomResult, interface::Pair{String,String}) +Base.getindex(result::MyCustomResult, period::ZonedDateTime) +Base.getindex(result::MyCustomResult, + region_or_unit::String, period::ZonedDateTime) +Base.getindex(result::MyCustomResult, + interface::Pair{String,String}, period::ZonedDateTime) +``` + +#### Risk Metrics + +If the result includes information that can be used to calculate resource +adequacy metrics, some or all of following new function methods should be +defined (here we assume the new result type is `MyCustomResult`): + +```julia +PRAS.LOLE(result::MyCustomResult) +PRAS.LOLE(result::MyCustomResult, region::String) +PRAS.LOLE(result::MyCustomResult, period::ZonedDateTime) +PRAS.LOLE(result::MyCustomResult, region::String, period::ZonedDateTime) + +PRAS.EUE(result::MyCustomResult) +PRAS.EUE(result::MyCustomResult, region::String) +PRAS.EUE(result::MyCustomResult, period::ZonedDateTime) +PRAS.EUE(result::MyCustomResult, region::String, period::ZonedDateTime) +``` + +If desired, new result specifications may define additional result-specific +accessor methods as well. + +## Simulation-Result Interfaces + +Result specifications need a way to map information produced by a simulation +to outcomes of interest. The specifics of how this is implemented will vary +between simulation specifications, but in general, a specific `assess` +method will invoke another method that records abstract results. This +recording method will then be implemented by all of the concrete result +specifications wishing to support that simulation specification. A very +simplified example of this pattern is: + +```julia +function assess( + sys::SystemModel, simspec::MyCustomSimSpec, resultspecs::ResultSpec...) + + # Implement the simulation logic for MyCustomSimSpec here, + # and collect full results + simulationdata = ... + + # Store requested results + results = () + for resultspec in resultspecs + results = (results..., record(simspec, resultspec, simulationdata)) + end + + return results + +end + +function record( + simspec::MyCustomSimSpec, resultspec::Shortfall, simulationdata) + # Map simulationdata to shortfall results here + return ShortfallResult(...) +end + +function record( + simspec::MyCustomSimSpec, resultspec::Surplus, simulationdata) + # Map simulationdata to surplus results here + return SurplusResult(...) +end + +function record( + simspec::MyCustomSimSpec, resultspec::MyCustomResultSpec, simulationdata) + # Map simulationdata to my custom results here + return MyCustomResult(...) +end +``` + +By implementing the types and methods described here, a new result +specification can be made compatible with these existing simulation types. In +each case, we assume the `MyResultSpec <: ResultSpec` and +`MyResult <: Result` types have been previously defined. + +### Result Accumulator + +A sequential Monte Carlo result accumulator incrementally collects relevant +intermediate outcomes as chronological simulations under different random +samples are performed. + +```julia +# Define the accumulator structure +struct SMCMyResultAccumulator <: ResultAccumulator{SequentialMonteCarlo,MyResultSpec} + # fields for holding intermediate data go here +end + +# Help PRAS know which accumulator type to expect before one's created +PRAS.ResourceAdequacy.accumulatortype(::SequentialMonteCarlo, ::MyResultSpec) = + SMCMyResultAccumulator + +# Initialize a new accumulator +function PRAS.ResourceAdequacy.accumulator( + sys::SystemModel, simspec::SequentialMonteCarlo, resultspec::MyResultSpec) + return SMCMyResultAccumulator(...) +end +``` + +#### record! + +Once system operations in a given time period `t` have been simulated +within a given chronological sample sequence `s`, the `record!` +method extracts outcomes of interest from one or both of the system's +current `state` and the solution to the period's dispatch problem +`prob`. These results are used to update the accumulator `acc` +in-place. + +```julia +PRAS.ResourceAdequacy.record!( + acc::SMCMyResultAccumulator, sys::SystemModel, state::SystemState, + prob::DispatchProblem, s::Int, t::Int) +``` + +#### reset! + +At the end of each chronological sequence of time periods `s`, the +`reset!` method updates the accumulator `acc` in-place to +finalize recording of any results requiring information from multiple periods, +and prepare the accumulator to start receiving values from a new chronological +simulation sequence. + +```julia +PRAS.ResourceAdequacy.reset!(acc::SMCMyResultAccumulator, s::Int) + +# Often no action is required here, +# so a simple one-line implementation is possible +PRAS.ResourceAdequacy.reset!(acc::SMCMyResultAccumulator, s::Int) = nothing +``` + +#### merge! + +For multithreaded assessments PRAS creates one accumulator per worker thread (parallel task) and merges each thread's accumulator information togther once work is completed. `merge!` defines how an accumulator `a` should be updated in-place to incorporate the results obtained by another accumulator `b`. + +```julia +PRAS.ResourceAdequacy.merge!( + a::SMCMyResultAccumulator, b::SMCMyResultAccumulator) +``` + +#### finalize! + +Once all of the thread accumulators have been merged down to a single accumulator reflecting results from all of the threads, this final accumulator `acc` is mapped to the final result output through a `finalize` method. + +```julia +function PRAS.ResourceAdequacy.finalize( + acc::SMCMyResultAccumulator, sys::SystemModel) + + return MyResult(...) + +end +``` diff --git a/docs/src/PRAS/inputs.md b/docs/src/PRAS/inputs.md new file mode 100644 index 00000000..2570e01b --- /dev/null +++ b/docs/src/PRAS/inputs.md @@ -0,0 +1,204 @@ +# Input System Specification + +Assessing the resource adequacy of a power system requires a description +of the various resources available to that system, as well as its requirements +for serving load. In PRAS, this involves representing the +system's supply, storage, transmission, and demand characteristics in a specific +data format. This information is stored in memory as a `SystemModel` +Julia data structure, and on disk as an HDF5-formatted file with a +`.pras` file extension. Loading the system data from disk to memory is +accomplished via the following Julia code: + +```julia +using PRAS +sys = SystemModel("filepath/to/mysystem.pras") +``` + +A full technical specification of the `.pras` storage format is +available in the PRAS source code repository. +Storing system data in this format ensures that it will remain +readable in the future, even if PRAS' in-memory data representation changes. +Newer versions of the PRAS package are always able to read +`.pras` files created for older versions. + +An in-memory `SystemModel` data structure can also be written back to +disk: + +```julia +savemodel(sys, "filepath/to/mynewsystem.pras") +``` + +PRAS simulates simplified power system operations over one or +more consecutive time periods. The number of time periods to model and the +temporal duration of a single time period are specified on a per-system basis, +and must be consistent with provided starting and ending timestamps (defined +with respect to a specific time zone). + +When working with multiple years of +weather data, a user may wish to create separate system models and perform runs +for each year independently, or create a single system model containing the +full multi-year dataset. The first approach can be useful for studying +inter-annual variability of annual risk metrics using only the built-in +methods -- while this is also possible with a single multi-year run, it +requires some additional post-processing work. + +PRAS represents a power system as one or more **regions**, each containing +zero or more **generators**, **storages**, and +**generator-storages**. **Interfaces** contain **lines** and +allow power transfer between two regions. The table below summarizes +the characteristics of the different resource types (generators, storages, +generator-storages, and lines), and the +remainder of this section provides more details about each resource type +and their associated resource collections (regions or interfaces). + +| Parameter | Generator | Storage | Generator-Storage | Line | +|-----------|-----------|---------|-------------------|------| +| *Associated with a(n)...* | *Region* | *Region* | *Region* | *Interface* | +| *Name* | • | • | • | • | +| *Category* | • | • | • | • | +| Generation Capacity | • | | | | +| Inflow Capacity | | | • | | +| Charge Capacity | | • | • | | +| Discharge Capacity | | • | • | | +| Energy Capacity | | • | • | | +| Charge Efficiency | | • | • | | +| Discharge Efficiency | | • | • | | +| Carryover Efficiency | | • | • | | +| Grid Injection Capacity | | | • | | +| Grid Withdrawal Capacity | | | • | | +| Forward Transfer Capacity | | | | • | +| Backward Transfer Capacity | | | | • | +| Available→Unavailable Transition Probability | • | • | • | • | +| Unavailable→Available Transition Probability | • | • | • | • | + +*Table: PRAS resource parameters. Parameters in italic are fixed values; all others are provided as a time series.* + +## Regions +PRAS does not represent the power system's individual electrical buses. Intead, +PRAS **regions** are used to represent a collection of electrical buses +that are grouped together for resource adequacy assessment purposes. Power +transfer between buses within a single PRAS region is assumed to take place on +a "copper sheet" with no intraregional transfer limits or line reliability +limitations considered. + +In a PRAS system representation, each region is associated with a descriptive +name and an aggregate load time series, representing the total real power +demand across all buses in the region, for every simulation period defined +by the model. + +## Generators + +Electrical supply resources with no modeled energy constraints (e.g., a thermal +generator that can never exhaust its fuel supply) are represented in PRAS as +**generators**. Generators are the simplest supply resource modeled in +PRAS. In addition to a descriptive name and category, each generator unit is +associated with a time series of maximum generating capacity. This +time series can be a simple constant value (e.g., for a thermal plant) or can +change in any arbitrary manner (e.g., for a solar PV array). Each generator is +associated with a single PRAS region. + +For each period of an operations simulation, each generator takes on one of +two possible availability states. If the unit is available, it is capable of +injecting power up to its maximum generation capacity (for that time period) in +its associated region. If the unit is unavailable (representing some kind of +unplanned or forced outage), it is incapable of injecting any power into the +system. Between time periods, the unit may randomly transition to the +opposite state according to unit-specific state transition probabilities. Like +maximum available capacity, these transition probabilities are represented as +time series, and so may be different during different time periods. + +![Relations between power and energy parameters for generator, storage, and generator-storage resources.](../images/resourceparameters.pdf) + +## Storages + +Resources that can shift electrical power availability forward in time but do +not provide an overall net addition of energy into the system (e.g., a battery) +are referred to as **storages** in PRAS. Like generators, storages are +associated with descriptive name and category metadata. +Each storage unit has both a charge and discharge capacity time series, representing the +device's maximum ability to withdraw power from or inject power into the grid +at a given point in time (as with generator capacity, these values may remain +constant over the simulation or may vary to reflect external constraints). + +Storage units also have a maximum energy capacity time series, reflecting the +maximum amount of dischargeable energy the device can hold at a given point in +time (increasing or decreasing this value will change the duration of time for +which the device could charge or discharge at maximum power). The storage's +state of charge increases with charging and decreases with +discharging, and must always remain between zero and the maximum energy +capacity in that time period. The energy flow relationships between +these capacities are depicted visually in the figure above. + +If a storage device is charged and the maximum +energy capacity decreases such that the state of charge exceeds the energy +limit, the additional energy is automatically "spilled" (the surplus energy +is not injected into the grid, but simply vanishes from the system). + +Storage units may incur losses when moving energy into or out of the device +(charge and discharge efficiency), or forward in time (carryover efficiency). +When charging the unit, the effective increase to the state +of charge is determined by multiplying the charging power by the charge +efficiency. Similarly, when discharging the unit, the effective decrease to the +state of charge is calculated by dividing the discharge power by the discharge +efficiency. The available state of charge in the next time +period is determined by multiplying the state of charge in the current time +period by the carryover efficiency. + +Just as with generators, storages may be in available or unavailable states, and +move between these states randomly over time, according to provided state +transition probabilities. Unavailable storages cannot inject power into or +withdraw power from the grid, but they do maintain their energy state of charge +during an outage (minus any carryover losses occuring over time). + +## Generator-Storages + +Resources that add net new energy into the system but can also move that +energy forward in time instead of injecting it immediately (see figure below for examples) are referred to as +**generator-storages** in PRAS. As the name suggests, they combine the +characteristics of both generator and storage devices into a single unit. + +As with generator and storage units, generator-storages have associated +name and category metadata, and two availability states with random +transition probabilities. They have a potentially time-varying maximum inflow +capacity (representing potential new energy being added to the system and +analogous to the generator's maximum generating capacity) as well as +all the power and energy capacity and efficiency parameters associated with +storages. They also have separate maximum grid injection and withdrawal capacity time series, +reflecting the fact that (for example) they may not be able to discharge their +internal storage at full capacity while simultaneously injecting their full +exogenous energy inflow to the grid. The energy flow relationships between +these capacities are depicted visually in the figure above. + +A generator-storage in the unavailable state can neither charge nor discharge +its storage, nor send energy inflow to the grid. Like storage, it does retain +its state of charge during outages (subject to carryover losses). + +![Example applications of the generator-storage resource type](../images/genstorexamples.pdf) + +## Interfaces + +**Interfaces** define a potential capability to directly exchange power +between two regions. Any set of two regions can have at most one interface +connecting them. Each interface has both a "forward" and "backward" +time-varying maximum transfer capability: the maximum "forward" transfer +capability refers to the largest amount of total net power that can be moved +from the first region to the second at a given point of time. Similarly, the +maximum "backward" transfer capability refers to the largest amount of total +net power that can be moved from the second region to the first. + +## Lines + +Individual **lines** are assigned to a single specific interface and +enable moving power between the two regions defined by that interface. Like +other resources, a line is associated with name and category metadata, and +transitions randomly between two availability states according to potentially +time-varying transition probabilities. Like interfaces, lines have a +potentially time-varying "forward" and "backward" transfer capability, where the forward and backward directions +match those associated with the line's interface. + +The total interregional transfer +capability of an interface in a given direction is the lower of either the +sum of transfer limits of available lines in that interface, or the +interface-level transfer limit. A line in the unavailable state cannot move +power between regions, and so does not contribute to the corresponding +interface's sum of line-level transfer limits. diff --git a/docs/src/PRAS/introduction.md b/docs/src/PRAS/introduction.md new file mode 100644 index 00000000..07fc1266 --- /dev/null +++ b/docs/src/PRAS/introduction.md @@ -0,0 +1,22 @@ +# Basic PRAS Structure and Usage + +As illustrated in Figure 1, PRAS maps a provided representation of a power system to a probabilistic description of operational outcomes of interest, using a particular choice of operations simulation. The input system representation is called a "system model", the choice of operational representation is referred to as a "simulation specification", and different types of operating outcomes of interest are described by "result specifications". + +![PRAS model structure and corresponding assessment function arguments](../images/inputoutput.pdf) + +*Figure 1: PRAS model structure and corresponding assessment function arguments* + +PRAS is written in the Julia programming language, and is controlled through the use of Julia scripts. The three components of a PRAS resource adequacy assessment (a system model, a simulation specification, and result specifications) map directly to the Julia function arguments required to launch a PRAS run. A typical resource adequacy assessment with PRAS involves creating or loading a system model, then invoking PRAS' `assess` function to perform the analysis: + +```julia +using PRAS + +sys = SystemModel("filepath/to/mysystem.pras") + +shortfallresult, flowresult = + assess(sys, SequentialMonteCarlo(), Shortfall(), Flow()) + +eue, lole = EUE(shortfallresult), LOLE(shortfallresult) +``` + +More details on running PRAS via Julia code will be provided throughout the remainder of this report. In particular, the [Inputs](inputs.md) section will detail the information contained in a system model input, the [Simulations](simulations.md) section will explain the built-in simulation specification options in PRAS and the various modelling assumptions associated with each, and the [Results](results.md) section will outline PRAS' available result specifications. The [Capacity Credit](capacity-credit.md) section will cover how PRAS can calculate the capacity credit of specific resources based on the results of resource adequacy assessments, and the [Extending](extending.md) section will provide information on extending PRAS beyond its built-in capabilities. \ No newline at end of file diff --git a/docs/src/PRAS/results.md b/docs/src/PRAS/results.md new file mode 100644 index 00000000..8debfb6f --- /dev/null +++ b/docs/src/PRAS/results.md @@ -0,0 +1,327 @@ +# Result Specifications + +Different analyses require different kinds of results, and different levels of +detail within those results. PRAS considers many operational decisions and +system states internally, not all of which are relevant outputs for every analysis. When a user invokes +PRAS' `assess` function, one or more "result specifications" must be provided in order to indicate +the simulation outcomes that are of interest, and the desired level of +sample aggregation or unit type (if applicable) for which those +results should be reported. In general, sample-level disaggregation +should be used with care, as this can require large amounts of memory if +simulating with many samples. + +The current version of PRAS includes six built-in result specification +families, with additional user-defined specifications possible (see +[Custom Result Specifications](extending.md#custom-result-specifications)). These families can be classified into regional +results (**Shortfall** and **Surplus**), interface results +(**Flow** and **Utilization**), and unit results +(**Availability** and **Energy**). + +When invoking `assess` in Julia, result specifications are provided as +the final arguments to the function call, and a tuple of results are returned +in that same order. (Note that a tuple is *always* returned, even if a +single result specification is requested.) An example of requesting three +result specifications is: + +```julia +surplus, flow, genavail = assess( + sys, SequentialMonteCarlo(), Surplus(), Flow(), GeneratorAvailability()) +``` + +Depending on the result specification, a result object may support indexing +into it to obtain results for a specific time period, region, interface, or +unit. For example, using the results returned above: + +```julia +timestamp = ZonedDateTime(2020, 1, 1, 13, tz"UTC") +genname = "Generator 1" +regionname = "Region A" +interface = "Region A" => "Region B" + +# get the sample mean and standard deviation of observed total system +# surplus capacity at 1pm UTC on January 1, 2020: +m, sd = surplus[timestamp] + +# get the sample mean and standard deviation of observed surplus capacity +# in Region A at 1pm UTC on January 1, 2020: +m, sd = surplus[regionname, timestamp] + +# get the sample mean and standard deviation of average interface flow +# between Region A and Region B: +m, sd = flow[interface] + +# get the sample mean and standard deviation of interface flow +# between Region A and Region B at 1pm UTC on January 1, 2020: +m, sd = flow[interface, timestamp] + +# get the vector of random generator availability states in every sample +# for Generator 1, at 1pm UTC on January 1, 2020: +states = genavail[genname, timestamp] +``` + +Results can be reported in different ways depending on the result +specification being used, and not all types of indexing are appropriate for +every result specification. For example, it would not make sense to aggregate +interface flows across all interfaces in the system, or surplus power +(potentially from energy-limited devices) across all time periods. + +The remainder of this chapter provides additional +details about the six built-in result specification families in PRAS. + +## Regional Results + +The Shortfall and Surplus result families are defined over regions, and their +result objects can all be indexed into by region name. The table below outlines the simulation specifications that members of +these families are compatible with, as well as the levels of disaggregation +they support. + +| Result Specification | Units | SMC | Sample | Region | Timestep | Region + Timestep | +|----------------------|-------|-----|--------|--------|---------|------------------| +| `Shortfall` | Energy | • | | • | • | • | +| `ShortfallSamples` | Energy | • | • | • | • | • | +| `Surplus` | Power | • | | | • | • | +| `SurplusSamples` | Power | • | • | | • | • | + +*Table: Regional result specification characteristics.* + +### Shortfall +The Shortfall family of result specifications (`Shortfall` and +`ShortfallSamples`) reports on unserved energy +occuring during simulations. As quantifying unserved energy is the core aspect +of resource adequacy analysis, in practice almost every assessment requests a +Shortfall-related result. The basic `Shortfall` specification is most +commonly used and reports average shortfall results, while +`ShortfallSamples` provides more detailed results at the level of +individual simulations (samples). + +Shortfall result objects can be indexed into by region, timestep, both region +and timestep, or neither. Indexing on neither (via `result[]`) reports +the total shortfall across all regions and time periods. + +Shortfall results are unique among the built-in result types in that the raw +results can also be converted to specific probabilistic risk metrics +(**EUE** and **LOLE**). For sampling-based methods, both metric +estimates and the standard error of those estimates are provided. For example, +after assessing the system, metrics across all regions and the full simulation +horizon can be extracted as: + +```julia +shortfall, = assess(sys, SequentialMonteCarlo(), Shortfall()) +eue_overall = EUE(shortfall) +lole_overall = LOLE(shortfall) +``` + +More specific metrics can be obtained as well: + +```julia +region = "Region A" +period = ZonedDateTime(2020, 1, 1, 0, tz"America/Denver") + +eue_period = EUE(shortfall, period) +lole_region = LOLE(shortfall, region) +eue_region_period = EUE(shortfall, region, period) +``` + +### Surplus +The Surplus family of result specifications (`Surplus` and +`SurplusSamples`) reports on excess grid injection capacity (via +generation or discharging) in the system. This can be used to study +"near misses" where shortfall came close to occuring but did not actually +happen. The `Surplus` specification reports average surplus across +samples, while `SurplusSamples` reports simulation-level observations. + +Surplus capacity is reported in terms of power, and so results are always +disaggregated by timestep (indexed either by timestep or both region and +timestep). + +## Interface Results + +The Flow and Utilization families of result specifications are defined over +interfaces, and their result objects can all be indexed into by a pair of +region names (indicating the source and destination regions for power +transfer). The table below outlines the simulation specifications +that members of these families are compatible with, as well as the levels of +disaggregation they support. + +| Result Specification | Units | SMC | Sample | Interface | Timestep | Interface + Timestep | +|----------------------|-------|-----|--------|-----------|---------|---------------------| +| `Flow` | Power | • | | • | | • | +| `FlowSamples` | Power | • | • | • | | • | +| `Utilization` | -- | • | | • | | • | +| `UtilizationSamples` | -- | • | • | • | | • | + +*Table: Interface result specification characteristics.* + +### Flow + +The Flow family of result specifications (`Flow` and +`FlowSamples`) reports the direction and magnitude of power transfer +on an interface. This can be used to study which regions are importers vs +exporters of energy, either on average or at specific periods in time. The +`Flow` specification reports average flow across all samples, while +`FlowSamples` reports simulation-level observations. Flow results are +directional, so the order in which the regions are provided when looking up +a result will determine the result's sign. For example: + +```julia +m1, sd1 = flow["Region A" => "Region B"] +m2, sd2 = flow["Region B" => "Region A"] + +m1 == -m2 # true +sd1 == sd2 # true +``` + +Flow values are reported in terms of power, and results are always +disaggregated by interface. Results that aggregate over time report the average +flow over the time span. + +### Utilization + +The Utilization family of result specifications (`Utilization` and +`UtilizationSamples`) is similar to the Flow +family, but reports the fraction of an interface's +available transfer capacity that is used in the direction of flow, instead of +the flow power itself. Results can therefore range between 0 and 1. +This metric can be useful for studying the impact of line outages and +transmission congestion on unserved energy. +The `Utilization` specification reports average flow across all samples, +while `UtilizationSamples` reports simulation-level observations. Unlike +Flow, Utilization results are not directional and so will report the same +utilization regardless of the flow direction implied by the order of the +provided regions: + +```julia +util, = assess(sys, SequentialMonteCarlo(), Utilization()) +util["Region A" => "Region B"] == util["Region B" => "Region A"] +``` + +Utilization values are unitless, and results are always +disaggregated by interface. Results that aggregate over time report the average +utilization over the time span. + +## Unit Results + +The Availability and Energy families of result specifications are defined over +individual units, and their result objects can all be indexed into by a unit +name and timestep. The table below outlines the simulation +specifications that members of these families are compatible with, as well as +the levels of disaggregation they support. + +| Result Specification | Units | SMC | Sample | Unit | Timestep | Unit + Timestep | +|----------------------|-------|-----|--------|------|---------|----------------| +| `GeneratorAvailability` | -- | • | • | | | • | +| `StorageAvailability` | -- | • | • | | | • | +| `GeneratorStorageAvailability` | -- | • | • | | | • | +| `LineAvailability` | -- | • | • | | | • | +| `StorageEnergy` | Energy | • | | | • | • | +| `StorageEnergySamples` | Energy | • | • | | • | • | +| `GeneratorStorageEnergy` | Energy | • | | | • | • | +| `GeneratorStorageEnergySamples` | Energy | • | • | | • | • | + +*Table: Unit result specification characteristics.* + +### Availability + +The Availability family of result specifications +(`GeneratorAvailability`, `StorageAvailability`, +`GeneratorStorageAvailability`, and `LineAvailability`) reports the availability state +(available, or unavailable due to an unplanned outage) of individual units in +the simulation. The four result specification variants correspond to the four +categories of resources: generators, storages, generator-storages, and +lines. Availability is reported as a boolean value (with `true` +indicating the unit is available, and `false` indicating it isn't), and +is always disaggregated by unit, timestep, and sample. + +### Energy + +The Energy family of result specifications (`StorageEnergy`, +`StorageEnergySamples`, `GeneratorStorageEnergy`, and +`GeneratorStorageEnergySamples`) reports the energy state-of-charge +associated with individual energy-limited resources. Result specification +variants are available for selecting the category of energy-limited resource +(storage or generator-storage) to report, as well as for requesting +sample-level disaggregation. Energy is always disaggregated by timestep and +may also be disaggregated by unit (get the state of charge of a single +unit) or aggregated across the system (get the sum of states of charge +of all storage devices in the system). + +## Additional Examples + +This section provides a more complete example of running a PRAS assessment, +with a hypothetical analysis process making use of multiple different +results. + +```julia +using PRAS + +# Load in a system model from a .pras file. +# This hypothetical system has an hourly time resolution with an +# extent / simulation horizon of one year. +sys = SystemModel("mysystem.pras") + +# This system has multiple regions and relies on battery storage, so +# run a sequential Monte Carlo analysis: +shortfall, utilization, storage = assess( + sys, SequentialMonteCarlo(samples=10000, seed=1), + Shortfall(), Utilization(), StorageEnergy()) + +# Start by checking the overall system adequacy: +lole = LOLE(shortfall) # event-hours per year +eue = EUE(shortfall) # unserved energy per year +``` + +Suppose LOLE is below the target threshold but EUE seems high, suggesting large +amounts of unserved energy are concentrated in a small number of hours. What +do the hourly results show? + +```julia +# Note 1: LOLE.(shortfall, many_hours) is Julia shorthand for calling LOLE +# on every timestep in the collection many_hours +# Note 2: Here results are in terms of event-hours per hour, which is +# equivalent to the loss-of-load probability (LOLP) for each hour +lolps = LOLE.(shortfall, sys.timestamps) +``` + +One might see that a particular hour has an LOLP near 1.0, indicating that +load is consistently getting dropped in that period. Is this a local issue or +system-wide? One can check the unserved energy by region in that hour: + +```julia +shortfall_period = ZonedDateTime(2020, 8, 21, 17, tz"America/Denver") +unserved_by_region = EUE.(shortfall, sys.regions.names, shortfall_period) +``` + +Perhaps only one region (D) has non-zero EUE in that hour, indicating that this +must be a load pocket issue. We can also look at the utilization of interfaces +into that region in that period: + +```julia +utilization["Region A" => "Region D", shortfall_period] +utilization["Region B" => "Region D", shortfall_period] +utilization["Region C" => "Region D", shortfall_period] +``` + +These sample-averaged utilizations should all be very close to 1.0, indicating +that power transfers are consistently maxed out; neighbouring regions have +power available but can't send it to Region D. + +Transmission expansion is clearly one solution to this adequacy issue. Is local +storage another alternative? One can check on the average state-of-charge of +the existing battery in that region, both in the hour before and during the +problematic period: + +```julia +storage["Battery D1", shortfall_period-Hour(1)] +storage["Battery D1", shortfall_period] +``` + +It may be that the battery is on average fully charged going in to the event, +and perhaps retains some energy during the event, even as load is being +dropped. The device's ability to mitigate the shortfall must then be limited +only by its discharge capacity, so given that the event doesn't last long, +adding additional short-duration storage in this region would help. + +Note that if the event was less consistent, this analysis could also have been +performed on the subset of samples in which the event was observed, using the +`ShortfallSamples`, `UtilizationSamples`, and +`StorageEnergySamples` result specifications instead. diff --git a/docs/src/PRAS/simulations.md b/docs/src/PRAS/simulations.md new file mode 100644 index 00000000..463e5d18 --- /dev/null +++ b/docs/src/PRAS/simulations.md @@ -0,0 +1,61 @@ +# Simulation Specifications + +There are many different simplifying assumptions that can be made when +simulating power system operations for the purpose of studying resource +adequacy. The level of simplification a modeller is willing to accept +will depend on the goals of the study and the computational resources +available to carry out the modelling exercise. + +PRAS is referred to as a "suite" because of its inclusion of multiple power +system operations models of varying fidelity and computational complexity. +Each PRAS analysis (a single invocation of PRAS' `assess` function) is associated with exactly one of these +operational models, or "simulation specifications". A simulation specification +encodes a particular set of assumptions and simplifications that will be used +when simulating operations in order to assess the resource adequacy of the +study system. + +The current version of PRAS defines the **Sequential Monte Carlo** specification, +with additional user-defined specifications possible (see [Custom Simulation Specifications](extending.md#custom-simulation-specifications)). The remainder of this +section describes the methods and underlying assumptions of each of these +built-in simulation specifications. + +## Sequential Monte Carlo + +The Sequential Monte Carlo method simulates the chronological evolution of the system, tracking individual unit-level outage states and the state of charge of energy-limited resources. While it is the most computationally intensive simulation method provided in PRAS, it remains much simpler (and therefore runs much faster) than a production cost model. + +### Theory and Assumptions + +The Sequential Monte Carlo method simulates unit-level outages using a two-state Markov model. In each time period, the availability state of each generator, storage, generator-storage, and line either changes or remains the same, at random, based on the unit's provided state transition probabilities. The capacities from each available generator (or line) in a given time period are then added together to determine the total available generating (transfer) capacity for a region (interface). Storage and generator-storage units are similarly enabled or disabled based on their availability states. + +Like with the Non-Sequential Monte Carlo simulation specification, pipe-and-bubble power transfers between regions are possible, subject to interface and line transfer limits, and there is a small penalty applied to transfers in order to prevent loop flows. + +The Sequential Monte Carlo method is unique in its ability to represent energy-limited resources (storages and generator-storages). These resources are dispatched conservatively so as to approximately minimize unserved energy over the full simulation horizon, charging from the grid whenever surplus generating capacity is available, and discharging only when needed to avoid or mitigate unserved energy. Charging and discharging is coordinated between resources using the time-to-go priority described in [Evans et al. (2019)](#references): resources that would be able to discharge the longest at their maximum rate are discharged first, and resources that would take the longest time to charge at their maximum charge rate are charged first. Cross-charging (discharging one resource in order to charge another) is not permitted. + +In Sequential Monte Carlo simulations, one "sample" involves chronological simulation of the system over the full operating horizon. Unserved energy results for each hour and the overall horizon are recorded before restarting the simulation and repeating the process with new random outage draws. Once all samples have been completed, hourly and overall system risk metrics can be calculated. + +### Usage + +A sequential Monte Carlo resource adequacy assessment is invoked by calling PRAS' `assess` method in Julia, with `SequentialMonteCarlo()` as the simulation specification argument: + +```julia +assess(sys, SequentialMonteCarlo(), Shortfall()) +``` + +The `SequentialMonteCarlo()` specification accepts several optional keyword arguments, which can be provided in any order: + +**samples**: A positive integer value defaulting to `10000`. It defines the number of samples (replications) to be used in the Monte Carlo simulation process. + +**seed**: An integer defaulting to a random value. It defines the seed to beused for random number generation when sampling generator and line outage state transitions. + +**threaded**: A boolean value defaulting to `true`. If `true`, PRAS will parallelize simulations across the number of threads available to Julia. Setting this to `false` can help with debugging if an assessment is hanging. + +**verbose**: A boolean value defaulting to `false`. If `true`, +PRAS will output informative text describing the progress of the assessment. + +## References + +Billinton, R. (1970). Power System Reliability Evaluation. Gordon and Breach. + +Evans, M. P., Tindemans, S. H., & Angeli, D. (2019). Minimizing Unserved Energy Using Heterogeneous Storage Units. IEEE Transactions on Power Systems, 34(5), 3647-3656. + +Haringa, G. E., Jordan, G. A., & Garver, L. L. (1991). Application of Monte Carlo simulation to multi-area reliability evaluations. IEEE Computer Applications in Power, 4(1), 21-25. diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index f8ec2714..9734e44f 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -4,10 +4,7 @@ Once you have PRAS [installed](./installation.md), this page provides a brief ov ## Parallel Processing -PRAS uses multi-threading, so be sure to set the environment variable -controlling the number of threads available to Julia (36 in this Bash example, -which is a good choice for NREL Eagle nodes - on a laptop you would probably -only want 4 or so) before running scripts or launching the REPL: +PRAS uses multi-threading, so be sure to set the environment variable controlling the number of threads available to Julia (36 in this Bash example, which is a good choice for NREL Eagle nodes - on a laptop you would probably only want 4 or so) before running scripts or launching the REPL: ```sh export JULIA_NUM_THREADS=36 @@ -15,10 +12,7 @@ export JULIA_NUM_THREADS=36 ## Power System Data -The recommended way to store and retreive PRAS system data is in an HDF5 file -that conforms to the -[PRAS system data format](https://github.com/NREL/PRAS/blob/master/SystemModel_HDF5_spec.md). -Once your system is represented in that format you can load it into PRAS with: +The recommended way to store and retreive PRAS system data is in an HDF5 file that conforms to the [PRAS system data format](./SystemModel_HDF5_spec.md). Once your system is represented in that format you can load it into PRAS with: ```julia using PRAS @@ -27,44 +21,19 @@ sys = SystemModel("filepath/to/systemdata.pras") ## Resource Adequacy Assessment -PRAS functionality is distributed across groups of -modular specifications that can be mixed, extended, or replaced to support the -needs of a particular analysis. When assessing reliability or capacity value, -one can define the specs to be used while passing along any associated -parameters or options. +PRAS functionality is distributed across groups of modular specifications that can be mixed, extended, or replaced to support the needs of a particular analysis. When assessing reliability or capacity value, one can define the specs to be used while passing along any associated parameters or options. The categories of specifications are: -**Simulation Specifications**: How should power system operations be simulated? -Options are `Convolution` and `SequentialMonteCarlo`. +**Simulation Specifications**: How should power system operations be simulated? You can use the `SequentialMonteCarlo` specification. -**Result Specifications**: What kind and level of detail of results should be -saved out during simulations? -Options include `Shortfall`, `Surplus`, interface `Flow`, `StorageEnergy`, -and `GeneratorStorageEnergy`. Not all simulation specifications support all -result specifications. -(See the [PRAS documentation](https://www.nrel.gov/docs/fy21osti/79698.pdf) -for more details.) +**Result Specifications**: What kind and level of detail of results should be saved out during simulations? Options include `Shortfall`, `Surplus`, interface `Flow`, `StorageEnergy`, and `GeneratorStorageEnergy`. See [Result specification](./PRAS/results.md) for more details. -**Capacity Credit Specifications**: If performing a capacity credit -calculation, which method should be used? -Options are `EFC` and `ELCC`. +**Capacity Credit Specifications**: If performing a capacity credit calculation, which method should be used? Options are `EFC` and `ELCC`. ### Running an analysis -Analysis centers around the `assess` method with different arguments passed -depending on the desired analysis to run. -For example, to run a copper-plate convolution-based reliability assessment -(`Convolution`) with LOLE and EUE reporting (`Shortfall`), -one would run: - -```julia -assess(mysystemmodel, Convolution(), Shortfall()) -``` - -If you instead want to run a simulation that considers energy-limited resources -and transmission constraints, using 100,000 Monte Carlo samples, -the method call becomes: +Analysis centers around the `assess` method with different arguments passed depending on the desired analysis to run. For example, if you instead want to run a simulation that considers energy-limited resources and transmission constraints, using 100,000 Monte Carlo samples, the method call becomes: ```julia assess(mysystemmodel, SequentialMonteCarlo(samples=100_000), Shortfall()) @@ -78,8 +47,7 @@ assess(mysystemmodel, SequentialMonteCarlo(samples=100_000), Shortfall(), Flow() ### Querying Results -Each result type requested returns a seperate result object. These objects can -then be queried using indexing syntax to extract values of interest. +Each result type requested returns a seperate result object. These objects can then be queried using indexing syntax to extract values of interest. ```julia shortfalls, flows = @@ -88,30 +56,23 @@ shortfalls, flows = flows["Region A" => "Region B"] ``` -The full PRAS documentation provides more details on how different result -object types can be indexed. +The full PRAS documentation provides more details on how different result object types can be indexed. -Because the main results of interest from resource adequacy assessments are -probabilistic risk metrics (i.e. EUE and LOLE), `Shortfall` result objects -define some additional methods: a particular risk metric can be -obtained by calling that metric's constructor with the `Shortfall` -result object. For example, to obtain the system-wide LOLE and EUE over the -simulation period: +Because the main results of interest from resource adequacy assessments are probabilistic risk metrics (i.e. EUE and LOLE), `Shortfall` result objects +define some additional methods: a particular risk metric can be obtained by calling that metric's constructor with the `Shortfall` result object. For example, to obtain the system-wide LOLE and EUE over the simulation period: ```julia lole = LOLE(shortfalls) eue = EUE(shortfalls) ``` -Single-period metrics can also be extracted. For example, to get system-wide -EUE for April 27th, 2024 at 1pm EST: +Single-period metrics can also be extracted. For example, to get system-wide EUE for April 27th, 2024 at 1pm EST: ```julia period_eue = EUE(shortfalls, ZonedDateTime(2024, 4, 27, 13, tz"EST")) ``` -Region-specific metrics can also be extracted. For example, to obtain the LOLE -of Region A across the entire simulation period: +Region-specific metrics can also be extracted. For example, to obtain the LOLE of Region A across the entire simulation period: ```julia eue_a = LOLE(shortfalls, "Region A") @@ -125,17 +86,12 @@ period_eue_a = EUE(shortfalls, "Region A", ZonedDateTime(2024, 4, 27, 13, tz"EST ## Capacity Credit Calculations -Capacity credit calcuations build on probabilistic resource adequacy assessment -to provided capacity-based quantifications of the marginal benefit to -system resource adequacy associated with a specific resource or collection of -resources. Two capacity credit metrics (EFC and ELCC) are currently supported. +Capacity credit calcuations build on probabilistic resource adequacy assessment to provided capacity-based quantifications of the marginal benefit to system resource adequacy associated with a specific resource or collection of resources. Two capacity credit metrics (EFC and ELCC) are currently supported. ### Equivalent Firm Capacity (EFC) -`EFC` estimates the amount of idealized, 100%-available capacity that, when -added to a baseline system, reproduces the level of system adequacy associated -with the baseline system plus the study resource. The following parameters must -be specified: +`EFC` estimates the amount of idealized, 100%-available capacity that, when added to a baseline system, reproduces the level of system adequacy associated +with the baseline system plus the study resource. The following parameters must be specified: - The risk metric to be used for comparison (i.e. EUE or LOLE) - A known upper bound on the EFC value (usually the resource's nameplate @@ -144,8 +100,7 @@ be specified: typically chosen to match the regional distribution of the study resource's nameplate capacity. -For example, to assess the EUE-based EFC of a new resource with 1000 MW -nameplate capacity, added to the system in a single region named "A": +For example, to assess the EUE-based EFC of a new resource with 1000 MW nameplate capacity, added to the system in a single region named "A": ```julia # The base system, with power units in MW @@ -161,8 +116,7 @@ efc = assess( min_efc, max_efc = extrema(efc) ``` -If the study resource were instead split between regions "A" (600MW) and "B" -(400 MW), one could specify the firm capacity distribution as: +If the study resource were instead split between regions "A" (600MW) and "B" (400 MW), one could specify the firm capacity distribution as: ```julia efc = assess( @@ -172,10 +126,7 @@ efc = assess( ### Equivalent Load Carrying Capability (ELCC) -`ELCC` estimates the amount of additional load that can be added to the system -(in every time period) in the presence of a new study resource, while -maintaining the baseline system's original adequacy level. The following -parameters must be specified: +`ELCC` estimates the amount of additional load that can be added to the system (in every time period) in the presence of a new study resource, while maintaining the baseline system's original adequacy level. The following parameters must be specified: - The risk metric to be used for comparison (i.e. EUE or LOLE) - A known upper bound on the ELCC value (usually the resource's nameplate @@ -184,8 +135,7 @@ parameters must be specified: somewhat ambiguous in multi-region systems, so assumptions should be clearly specified when reporting analysis results. -For example, to assess the EUE-based ELCC of a new resource with 1000 MW -nameplate capacity, serving new load in region "A": +For example, to assess the EUE-based ELCC of a new resource with 1000 MW nameplate capacity, serving new load in region "A": ```julia # The base system, with power units in MW @@ -201,8 +151,7 @@ elcc = assess( min_elcc, max_elcc = extrema(elcc) ``` -If instead the goal was to study the ability of the new resource to provide -load evenly to regions "A" and "B", one could use: +If instead the goal was to study the ability of the new resource to provide load evenly to regions "A" and "B", one could use: ```julia elcc = assess( @@ -212,43 +161,12 @@ elcc = assess( ### Capacity credit calculations in the presence of sampling error -For non-deterministic assessment methods (i.e. Monte Carlo simulations), -running a resource adequacy assessment with different random number generation -seeds will result in different risk metric estimates for the same underlying -system. Capacity credit assessments can be sensitive to this uncertainty, -particularly when attempting to study the impact of a small resource on a -large system with a limited number of simulation samples. - -PRAS takes steps to a) limit this uncertainty and b) warn against -potential deficiencies in statistical power resulting from this uncertainty. - -First, the same random seed is used across all simulations in the capacity -credit assessment process. If the number of resources and their reliability -parameters (MTTF and MTTR) remain constant across the baseline and augmented -test systems, seed re-use ensures that unit-level outage profiles remain -identical across RA assessments, providing a fixed background against which to -measure changes in RA resulting from the addition of the study resource. Note -that satisfying this condition requires that the study resource be present in -the baseline case, but with its contributions eliminated (e.g. by setting its -capacity to zero). When implementing an assessment method that modifies the -user-provided system to add new resources (such as EFC), the programmer should -assume this invariance exists in the provided data, and not violate it in any -automated modifications. - -Second, capacity credit assessments have two different stopping criteria. The -ideal case is that the upper and lower bounds on the capacity -credit metric converge to be sufficiently tight relative to a desired level -of precision. This target precision is 1 system power unit (e.g. MW) by -default, but can be relaxed to loosen the convergence bounds if desired via -the `capacity_gap` keyword argument. Once the lower and upper bounds are -tighter than this gap, their values are returned. - -Additionally, at each bisection step, a hypothesis test is performed to ensure -that the theoretically-larger bounding risk metric is in fact larger than the -smaller-valued risk metric with a specified level of statistical significance. -By default, this criteria is a maximum p-value of 0.05, although this value -can be changed as desired via the `p_value` keyword argument. If at some point -the null hypothesis (the higher risk is not in fact larger than the lower -risk) cannot be rejected at the desired significance level, the assessment -will provide a warning indicating the size of the remaining capacity gap and -return the lower and upper bounds on the capacity credit estimate. +For non-deterministic assessment methods (i.e. Monte Carlo simulations), running a resource adequacy assessment with different random number generation seeds will result in different risk metric estimates for the same underlying system. Capacity credit assessments can be sensitive to this uncertainty, particularly when attempting to study the impact of a small resource on a large system with a limited number of simulation samples. + +PRAS takes steps to a) limit this uncertainty and b) warn against potential deficiencies in statistical power resulting from this uncertainty. + +First, the same random seed is used across all simulations in the capacity credit assessment process. If the number of resources and their reliability parameters (MTTF and MTTR) remain constant across the baseline and augmented test systems, seed re-use ensures that unit-level outage profiles remain identical across RA assessments, providing a fixed background against which to measure changes in RA resulting from the addition of the study resource. Note that satisfying this condition requires that the study resource be present in the baseline case, but with its contributions eliminated (e.g. by setting its capacity to zero). When implementing an assessment method that modifies the user-provided system to add new resources (such as EFC), the programmer should assume this invariance exists in the provided data, and not violate it in any automated modifications. + +Second, capacity credit assessments have two different stopping criteria. The ideal case is that the upper and lower bounds on the capacity credit metric converge to be sufficiently tight relative to a desired level of precision. This target precision is 1 system power unit (e.g. MW) by default, but can be relaxed to loosen the convergence bounds if desired via the `capacity_gap` keyword argument. Once the lower and upper bounds are tighter than this gap, their values are returned. + +Additionally, at each bisection step, a hypothesis test is performed to ensure that the theoretically-larger bounding risk metric is in fact larger than the smaller-valued risk metric with a specified level of statistical significance. By default, this criteria is a maximum p-value of 0.05, although this value can be changed as desired via the `p_value` keyword argument. If at some point the null hypothesis (the higher risk is not in fact larger than the lower risk) cannot be rejected at the desired significance level, the assessment will provide a warning indicating the size of the remaining capacity gap and return the lower and upper bounds on the capacity credit estimate. diff --git a/docs/src/images/genstorexamples.pdf b/docs/src/images/genstorexamples.pdf new file mode 100644 index 0000000000000000000000000000000000000000..40e5ae03b0a5465a32e531aec66c6b3556fa3816 GIT binary patch literal 41131 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 z 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 Xc6UNNAi#w{1PO3iSQIoA32^@()w`QJ literal 0 HcmV?d00001 diff --git a/docs/src/index.md b/docs/src/index.md index 8e352859..a11514ce 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,9 +1,5 @@ -The Probabilistic Resource Adequacy Suite (PRAS) provides an open-source, -research-oriented collection of tools for analysing the resource adequacy of a -bulk power system. The simulation methods offered support everything from -classical convolution-based analytical techniques through to high-performance -sequential Monte Carlo methods supporting multi-region composite reliability -assessment, including simulation of energy-limited resources such as storage. +The Probabilistic Resource Adequacy Suite (PRAS) provides an open-source, research-oriented collection of tools for analysing the resource adequacy of a +bulk power system. It allows the user to simulate power system operations under a wide range of operating conditions in order to study the risk of failing to meet demand (due to a lack of supply or deliverability), and identify the time periods and regions in which that risk occurs. It offers high-performance sequential Monte Carlo methods supporting multi-region composite reliability assessment, including simulation of energy-limited resources such as storage. PRAS is developed and maintained at the US [National Renewable Energy Laboratory](https://www.nrel.gov/) (NREL). diff --git a/docs/src/resource-adequacy.md b/docs/src/resource-adequacy.md new file mode 100644 index 00000000..8d20e63c --- /dev/null +++ b/docs/src/resource-adequacy.md @@ -0,0 +1,54 @@ +# Resource Adequacy Background + +An electrical power system is considered resource adequate if it has procured +sufficient resources (including supply, transmission, and responsive demand) +such that it runs a sufficiently low risk of invoking emergency measures (such +as involuntary load shedding) due to resource unavailablity or deliverability +constraints. Resource adequacy +is a necessary (but not sufficient) condition for overall power system +reliability, which considers a broader set of system constraints including +operational flexibility and the stability of system voltages and frequency. + +Probabilistic resource adequacy assessment is the process by which resource +shortfall risk is quantified. It involves mapping quantified uncertainties in +system operating conditions (primarily forced outages of generators and lines) into +probability distributions for operating outcomes of interest by simulating +system operations under different probabilistically weighted +scenarios. The nature of those simulations varies between models, and can range +from simple snapshot comparisons of peak demand versus available supply, +through to chronological simulations of system dispatch and power flow over +the full operating horizon. + +The resulting outcomes can then be used to calculate industry-standard +probabilistic risk metrics [NERC Probabilistic Assessment Working Group, 2018](#references): + +**Expected Unserved Energy (EUE)** is the expected (average) total energy +shortfall over the study period. It may be expressed in energy units +(e.g. GWh per year) or normalized against the system's total energy demand and +expressed as a fraction (normalized EUE, or NEUE, expressed as a percentage or +in parts-per-million, ppm). + +**Loss-of-Load Expectation (LOLE)** is the expected (average) count of +periods experiencing shortfall over the study period. It is expressed in terms +of event-periods (e.g. event-hours per year, event-days per year). When +reported in terms of event-hours, LOLE is sometimes referred to as LOLH +(loss-of-load hours). + +While a system's shortfall risk can never be eliminated entirely, if these +risk metrics are assessed to be lower than some predetermined threshold, the +system is considered resource adequate. + +It can sometimes also be useful to express the average and/or incremental +contribution of a particular resource to overall system adequacy in terms of +capacity. This quantity (either in units of power, or as a fraction of the +unit's nameplate capacity) is known as the capacity credit (sometimes called +capacity value) of the resource. While many different methods are used to +estimate the capacity credit of a resource, the most rigorous approaches +generally involve assessing the change in probabilistic system adequacy +associated with adding or removing the resource from the system. As a result, +capacity credit calculation is often closely associated with probabilistic +resource adequacy assessment. + +## References + +NERC Probabilistic Assessment Working Group. (2018). Probabilistic Adequacy and Measures. North American Electric Reliability Corporation. \ No newline at end of file From b20a60d502bf3dbfbe6deeece7b435b29443bb53 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Fri, 8 Aug 2025 11:00:43 -0600 Subject: [PATCH 04/25] Try using devcontainer --- .devcontainer/devcontainer.json | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..e4b4fda9 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,32 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/JuliaLang/devcontainer-templates/tree/main/src/julia +{ + "name": "Julia", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + + // Features to add to the dev container. More info: https://containers.dev/features. + "features": { + // A Feature to install Julia via juliaup. More info: https://github.com/JuliaLang/devcontainer-features/tree/main/src/julia. + "ghcr.io/julialang/devcontainer-features/julia:1": { + + }, + "ghcr.io/devcontainers/features/git:1": { + "ppa": true, + "version": "latest" + }, + "ghcr.io/devcontainers/features/git-lfs:1": { + "autoPull": true, + "version": "latest" + } + } + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Configure tool-specific properties. + // "customizations": {}, + + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} From 5486351fd67975204f8f3670b31b652a812ae110 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Tue, 12 Aug 2025 08:53:36 -0600 Subject: [PATCH 05/25] Add Docker image to allow installing NREL certs --- .devcontainer/Dockerfile | 7 +++++++ .devcontainer/devcontainer.json | 8 ++++---- .gitignore | 2 +- 3 files changed, 12 insertions(+), 5 deletions(-) create mode 100644 .devcontainer/Dockerfile diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 00000000..0eedf2d7 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,7 @@ +FROM mcr.microsoft.com/devcontainers/base:ubuntu + +# Install NREL root certs. +# Uncomment the following lines if you're using devcontainers on a NREL machine +# RUN curl -fsSLk -o /usr/local/share/ca-certificates/nrel_root.crt https://raw.github.nrel.gov/TADA/nrel-certs/v20180329/certs/nrel_root.pem && \ +# curl -fsSLk -o /usr/local/share/ca-certificates/nrel_xca1.crt https://raw.github.nrel.gov/TADA/nrel-certs/v20180329/certs/nrel_xca1.pem && \ +# update-ca-certificates \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index e4b4fda9..cd0f193c 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,9 +1,7 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the // README at: https://github.com/JuliaLang/devcontainer-templates/tree/main/src/julia { - "name": "Julia", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "build": { "dockerfile": "Dockerfile" }, // Features to add to the dev container. More info: https://containers.dev/features. "features": { @@ -19,7 +17,9 @@ "autoPull": true, "version": "latest" } - } + }, + + "postCreateCommand": "julia --project=PRAS.jl -e 'import Pkg; Pkg.develop([(path=\"PRASCore.jl\",),(path=\"PRASFiles.jl\",),(path=\"PRASCapacityCredits.jl\",)])'", // Use 'forwardPorts' to make a list of ports inside the container available locally. // "forwardPorts": [], diff --git a/.gitignore b/.gitignore index baa3d467..542f2276 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ Manifest.toml *.DS_Store *.pras -*.json +PRASFiles.jl/test/PRAS_Results_Export/ docs/build/ docs/site/ \ No newline at end of file From 7d616c08ae90e495a27e4819623c5b73efe14417 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:05:30 -0600 Subject: [PATCH 06/25] Add CI to generate docs --- .devcontainer/Dockerfile | 2 +- .github/workflows/docs.yml | 36 ++++++++++++++++++++++++++++++++++++ docs/make.jl | 3 ++- 3 files changed, 39 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 0eedf2d7..a2cfc98c 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,7 +1,7 @@ FROM mcr.microsoft.com/devcontainers/base:ubuntu # Install NREL root certs. -# Uncomment the following lines if you're using devcontainers on a NREL machine +# Uncomment the following lines (5-7) if you're using devcontainers on a NREL machine # RUN curl -fsSLk -o /usr/local/share/ca-certificates/nrel_root.crt https://raw.github.nrel.gov/TADA/nrel-certs/v20180329/certs/nrel_root.pem && \ # curl -fsSLk -o /usr/local/share/ca-certificates/nrel_xca1.crt https://raw.github.nrel.gov/TADA/nrel-certs/v20180329/certs/nrel_xca1.pem && \ # update-ca-certificates \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..b86d063c --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +name: Documentation + +on: + push: + branches: + - adddocs + - main + tags: '*' + pull_request: + +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v3 + - uses: julia-actions/setup-julia@latest + with: + version: '1.10' + - name: Configure doc environment + run: | + julia --project=docs/ -e ' + using Pkg + # Develop all packages in workspace + for pkg in ["PRAS", "PRASCore", "PRASCapacityCredits", "PRASFiles"] + if isdir("$pkg.jl") + Pkg.develop(path="$pkg.jl") + end + end + Pkg.instantiate()' + - name: Build and deploy docs + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: julia --project=docs/ docs/make.jl deploy=true diff --git a/docs/make.jl b/docs/make.jl index 3b7a78e8..a48a48cf 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -38,5 +38,6 @@ makedocs( deploydocs( repo = "github.com/NREL/PRAS.git", devbranch = "main", - push_preview = true + push_preview = true, + versions = nothing ) \ No newline at end of file From acdd3595d7f671c0ec87e3c8dfa23c390424722e Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:10:49 -0600 Subject: [PATCH 07/25] Change branches from which Documentation action is run --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b86d063c..d6adad31 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,7 +3,7 @@ name: Documentation on: push: branches: - - adddocs + - ssh/docgen - main tags: '*' pull_request: From 796018720b9da38a6ff8238558efeeec65ef6a57 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:22:18 -0600 Subject: [PATCH 08/25] Change package dev command in docs action --- .github/workflows/docs.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d6adad31..c33c7ebb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -18,17 +18,19 @@ jobs: - uses: actions/checkout@v3 - uses: julia-actions/setup-julia@latest with: - version: '1.10' + version: 'latest' - name: Configure doc environment run: | julia --project=docs/ -e ' + println(pwd()); using Pkg # Develop all packages in workspace - for pkg in ["PRAS", "PRASCore", "PRASCapacityCredits", "PRASFiles"] - if isdir("$pkg.jl") - Pkg.develop(path="$pkg.jl") - end - end + Pkg.develop([ + (path="PRASCore.jl",), + (path="PRASFiles.jl",), + (path="PRASCapacityCredits.jl",) + (path="PRAS.jl",) + ]) Pkg.instantiate()' - name: Build and deploy docs env: From bb315b2c7e0400c0d5f70b939e1138b15bfccf2f Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:24:17 -0600 Subject: [PATCH 09/25] Change Julia version in docs action --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c33c7ebb..be5154d8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/checkout@v3 - uses: julia-actions/setup-julia@latest with: - version: 'latest' + version: '1' - name: Configure doc environment run: | julia --project=docs/ -e ' From 46e0a8dee0abb3e61fc34c752af559c8dfaa16d5 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:25:37 -0600 Subject: [PATCH 10/25] Change pkg dev command in docs action --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index be5154d8..8d354733 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -26,10 +26,10 @@ jobs: using Pkg # Develop all packages in workspace Pkg.develop([ - (path="PRASCore.jl",), - (path="PRASFiles.jl",), - (path="PRASCapacityCredits.jl",) - (path="PRAS.jl",) + (path="PRASCore.jl",), + (path="PRASFiles.jl",), + (path="PRASCapacityCredits.jl",), + (path="PRAS.jl",) ]) Pkg.instantiate()' - name: Build and deploy docs From 0dde4318f84a8ec1a293489dc11204d8266b8373 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 13 Aug 2025 14:36:59 -0600 Subject: [PATCH 11/25] Change the devbranch --- docs/make.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index a48a48cf..645c2a95 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -37,7 +37,7 @@ makedocs( deploydocs( repo = "github.com/NREL/PRAS.git", - devbranch = "main", + devbranch = "ssh/docgen", push_preview = true, versions = nothing ) \ No newline at end of file From c2662cd3dd059d15a39b8e7fe5b2fc9b35ba1669 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 14 Aug 2025 16:39:21 -0600 Subject: [PATCH 12/25] Add dosctrings for PRAS Core structs --- PRASCore.jl/src/Systems/SystemModel.jl | 47 +++++++++++- PRASCore.jl/src/Systems/assets.jl | 101 +++++++++++++++++++++++++ PRASCore.jl/src/Systems/collections.jl | 31 ++++++++ 3 files changed, 175 insertions(+), 4 deletions(-) diff --git a/PRASCore.jl/src/Systems/SystemModel.jl b/PRASCore.jl/src/Systems/SystemModel.jl index eb74c9b0..e5a0b1bd 100644 --- a/PRASCore.jl/src/Systems/SystemModel.jl +++ b/PRASCore.jl/src/Systems/SystemModel.jl @@ -1,8 +1,47 @@ """ - SystemModel - -A `SystemModel` contains a representation of a power system to be studied -with PRAS. + 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](@ref system_specification) 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](@ref)) +- `interfaces`: Information about connections between regions (Type - [Interfaces](@ref)) +- `generators`: Collection of system generators (Type - [Generators](@ref)) +- `region_gen_idxs`: Mapping of generators to their respective regions +- `storages`: Collection of system storages (Type - [Storages](@ref)) +- `region_stor_idxs`: Mapping of storage resources to their respective regions +- `generatorstorages`: Collection of system generation-storages (Type - [GeneratorStorages](@ref)) +- `region_genstor_idxs`: Mapping of hybrid resources to their respective regions +- `lines`: Collection of transmission lines connecting regions (Type - [Lines](@ref)) +- `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). """ struct SystemModel{N, L, T <: Period, P <: PowerUnit, E <: EnergyUnit} regions::Regions{N, P} diff --git a/PRASCore.jl/src/Systems/assets.jl b/PRASCore.jl/src/Systems/assets.jl index 0269521d..c3aea7cb 100644 --- a/PRASCore.jl/src/Systems/assets.jl +++ b/PRASCore.jl/src/Systems/assets.jl @@ -114,6 +114,41 @@ function Base.vcat(gs::Generators{N,L,T,P}...) where {N, L, T, P} end +""" + Storages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} + +A struct representing storage-only devices within a power system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `L`: Length of each timestep in T units +- `T`: The time period type used for temporal representation, subtype of `Period` +- `P`: The power unit used for capacity measurements, subtype of `PowerUnit` +- `E`: The energy unit used for energy storage, subtype of `EnergyUnit` + +# Fields + - `names`: Name of storage device + - `categories`: Category of storage device + - `charge_capacity`: Maximum available charging capacity for each storage unit in each + timeperiod, expressed in units given by the `power_units` (`P`) type parameter + - `discharge_capacity`: Maximum available discharging capacity for each storage unit in + each timeperiod, expressed in units given by the `power_units` (`P`) type parameter + - `energy_capacity`: Maximum available energy storage capacity for each storage unit in + each timeperiod, expressed in units given by the `energy_units` (`E`) type parameter + - `charge_efficiency`: Ratio of power injected into the storage device's reservoir to + power withdrawn from the grid, for each storage unit in each timeperiod. Unitless. + - `discharge_efficiency`: Ratio of power injected into the grid to power withdrawn from + the storage device's reservoir, for each storage unit in each timeperiod. Unitless. + - `carryover_efficiency`: Ratio of energy available in the storage device's reservoir at + the beginning of one period to energy retained at the end of the previous period, for + each storage unit in each timeperiod. Unitless. + - `λ` (failure probability): Probability the unit transitions from operational to forced + outage during a given simulation timestep, for each storage unit in each timeperiod. + Unitless. + - `μ` (repair probability): Probability the unit transitions from forced outage to + operational during a given simulation timestep, for each storage unit in each + timeperiod. Unitless. +""" struct Storages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} <: AbstractAssets{N,L,T,P} names::Vector{String} @@ -236,6 +271,47 @@ function Base.vcat(stors::Storages{N,L,T,P,E}...) where {N, L, T, P, E} end +""" + GeneratorStorages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} + +A struct representing generator-storage combination resources within a power system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `L`: Length of each timestep in T units +- `T`: The time period type used for temporal representation, subtype of `Period` +- `P`: The power unit used for capacity measurements, subtype of `PowerUnit` +- `E`: The energy unit used for energy storage, subtype of `EnergyUnit` + +# Fields + - `names`: Name of generator-storage unit + - `categories`: Category of generator-storage unit + - `charge_capacity`: Maximum available charging capacity for each generator-storage + unit in each timeperiod, in `power_units` (`P`) + - `discharge_capacity`: Maximum available discharging capacity for each generator-storage + unit in each timeperiod, in `power_units` (`P`) + - `energy_capacity`: Maximum available energy storage capacity for each generator-storage + unit in each timeperiod, in `energy_units` (`E`) + - `charge_efficiency`: Ratio of power injected into the device's reservoir to power + withdrawn from the grid, for each generator-storage unit in each timeperiod. Unitless. + - `discharge_efficiency`: Ratio of power injected into the grid to power withdrawn from + the device's reservoir, for each generator-storage unit in each timeperiod. Unitless. + - `carryover_efficiency`: Ratio of energy available in the device's reservoir at the + beginning of one period to energy retained at the end of the previous period, for each + generator-storage unit in each timeperiod. Unitless. + - `inflow`: Exogenous power inflow available to each generator-storage unit in each + timeperiod, in `power_units` (`P`) + - `gridwithdrawal_capacity`: Maximum available capacity to withdraw power from the grid + for each generator-storage unit in each timeperiod, in `power_units` (`P`) + - `gridinjection_capacity`: Maximum available capacity to inject power to the grid for + each generator-storage unit in each timeperiod, in `power_units` (`P`) + - `λ` (failure probability): Probability the unit transitions from operational to forced + outage during a given simulation timestep, for each generator-storage unit in each + timeperiod. Unitless. + - `μ` (repair probability): Probability the unit transitions from forced outage to + operational during a given simulation timestep, for each generator-storage unit in each + timeperiod. Unitless. +""" struct GeneratorStorages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} <: AbstractAssets{N,L,T,P} names::Vector{String} @@ -390,6 +466,31 @@ function Base.vcat(gen_stors::GeneratorStorages{N,L,T,P,E}...) where {N, L, T, P end +""" + Lines{N,L,T<:Period,P<:PowerUnit} + +A struct representing individual transmission lines between regions in a power +system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `L`: Length of each timestep in T units +- `T`: The time period type used for temporal representation, subtype of `Period` +- `P`: The power unit used for capacity measurements, subtype of `PowerUnit` + +# Fields + - `names`: Name of line + - `categories`: Category of line + - `forward_capacity`: Maximum available power transfer capacity from `region_from` to + `region_to` along the line, for each line in each timeperiod, in `power_units` (`P`) + - `backward_capacity`: Maximum available power transfer capacity from `region_to` to + `region_from` along the line, for each line in each timeperiod, in `power_units` (`P`) + - `λ` (failure probability): Probability the line transitions from operational to forced + outage during a given simulation timestep, for each line in each timeperiod. Unitless. + - `μ` (repair probability): Probability the line transitions from forced outage to + operational during a given simulation timestep, for each line in each timeperiod. + Unitless. +""" struct Lines{N,L,T<:Period,P<:PowerUnit} <: AbstractAssets{N,L,T,P} names::Vector{String} diff --git a/PRASCore.jl/src/Systems/collections.jl b/PRASCore.jl/src/Systems/collections.jl index 1d144e9e..a265ae94 100644 --- a/PRASCore.jl/src/Systems/collections.jl +++ b/PRASCore.jl/src/Systems/collections.jl @@ -1,3 +1,17 @@ +""" + Regions{N,P<:PowerUnit} + +A struct representing regions within a power system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `P`: The power unit used for demand measurements, subtype of `PowerUnit` + +# Fields + - `names`: Name of region (unique) + - `load`: Aggregated electricity demand in each region for each timeperiod, in + `power_units` (`P`) +""" struct Regions{N,P<:PowerUnit} names::Vector{String} @@ -24,6 +38,23 @@ Base.:(==)(x::T, y::T) where {T <: Regions} = Base.length(r::Regions) = length(r.names) +""" + Interfaces{N,P<:PowerUnit} + +A struct representing transmission interfaces between regions in a power system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `P`: The power unit used for interface limits, subtype of `PowerUnit` + +# Fields + - `regions_from`: Index of the first region connected by the interface + - `regions_to`: Index of the second region connected by the interface + - `limit_forward`: Maximum possible total power transfer from `regions_from` to + `regions_to`, for each interface in each timeperiod, in `power_units` (`P`) + - `limit_backward`: Maximum possible total power transfer from `regions_to` to + `regions_from`, for each interface in each timeperiod, in `power_units` (`P`) +""" struct Interfaces{N,P<:PowerUnit} regions_from::Vector{Int} From 924b1e16c26e01d47fc62fbef32e9d0746592155 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 14 Aug 2025 16:40:51 -0600 Subject: [PATCH 13/25] Update documentation website structure, adding new elements --- docs/make.jl | 25 +++++++------- docs/src/PRAS/capacity-credit.md | 2 +- docs/src/PRAS/introduction.md | 22 ------------- docs/src/PRAS/results.md | 4 +-- docs/src/PRAS/simulations.md | 19 +++++++++-- docs/src/PRAS/{inputs.md => systemspec.md} | 18 +++++++++-- docs/src/PRASCore/api.md | 36 +++++++++++++++++---- docs/src/PRASFiles/api.md | 1 + docs/src/SystemModel_HDF5_spec.md | 24 +++++++------- docs/src/changelog.md | 11 +++++++ docs/src/contributing.md | 16 +++++++++ docs/src/{PRAS => }/extending.md | 4 +-- docs/src/images/genstorexamples.pdf | Bin 41131 -> 35257 bytes docs/src/images/inputoutput.pdf | Bin 54087 -> 54588 bytes docs/src/images/networkflow.pdf | Bin 50804 -> 41059 bytes docs/src/images/resourceparameters.pdf | Bin 62566 -> 56499 bytes docs/src/index.md | 28 +++++++++++++++- docs/src/resource-adequacy.md | 6 ++-- 18 files changed, 149 insertions(+), 67 deletions(-) delete mode 100644 docs/src/PRAS/introduction.md rename docs/src/PRAS/{inputs.md => systemspec.md} (93%) create mode 100644 docs/src/changelog.md create mode 100644 docs/src/contributing.md rename docs/src/{PRAS => }/extending.md (99%) diff --git a/docs/make.jl b/docs/make.jl index 645c2a95..1d94d2df 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,24 +7,27 @@ using PRASCapacityCredits makedocs( sitename = "PRAS", format = Documenter.HTML( - prettyurls = get(ENV, "CI", nothing) == "true", + prettyurls = true, canonical = "https://nrel.github.io/PRAS/stable" ), modules = [PRASCore, PRASFiles, PRASCapacityCredits], pages = [ "Home" => "index.md", - "Installation instructions" => "installation.md", - "Resource adequacy" => "resource-adequacy.md", - "Quick start" => "getting-started.md", - "System model specification" => "SystemModel_HDF5_spec.md", - "PRAS" => [ - "Introduction" => "PRAS/introduction.md", - "Input System Specification" => "PRAS/inputs.md", + "Resource Adequacy" => "resource-adequacy.md", + "Getting Started" => [ + "Installation" => "installation.md", + "Quick start" => "getting-started.md", + ], + "PRAS Components " => [ + "System Model Specification" => "PRAS/systemspec.md", "Simulation Specifications" => "PRAS/simulations.md", "Result Specifications" => "PRAS/results.md", - "Capacity Credit Calculation" => "PRAS/capacity-credit.md", - "Extending PRAS" => "PRAS/extending.md", + "Capacity Credit Calculation" => "PRAS/capacity-credit.md", ], + ".pras File Format" => "SystemModel_HDF5_spec.md", + "Extending PRAS" => "extending.md", +# "Contributing" => "contributing.md", + "Changelog" => "changelog.md", "API Reference" => [ "PRASCore" => "PRASCore/api.md", "PRASFiles" => "PRASFiles/api.md", @@ -32,12 +35,10 @@ makedocs( ] ], checkdocs = :exports, - warnonly = true, ) deploydocs( repo = "github.com/NREL/PRAS.git", devbranch = "ssh/docgen", push_preview = true, - versions = nothing ) \ No newline at end of file diff --git a/docs/src/PRAS/capacity-credit.md b/docs/src/PRAS/capacity-credit.md index 5e4a6b74..8edbfbd2 100644 --- a/docs/src/PRAS/capacity-credit.md +++ b/docs/src/PRAS/capacity-credit.md @@ -1,4 +1,4 @@ -# Capacity Credit Calculation +# [Capacity Credit Calculation](@id capacitycredit) Resource adequacy paradigms premised on adding resource capacities together to meet a planning reserve margin require the quantification of a "capacity credit" (sometimes called "capacity value") diff --git a/docs/src/PRAS/introduction.md b/docs/src/PRAS/introduction.md deleted file mode 100644 index 07fc1266..00000000 --- a/docs/src/PRAS/introduction.md +++ /dev/null @@ -1,22 +0,0 @@ -# Basic PRAS Structure and Usage - -As illustrated in Figure 1, PRAS maps a provided representation of a power system to a probabilistic description of operational outcomes of interest, using a particular choice of operations simulation. The input system representation is called a "system model", the choice of operational representation is referred to as a "simulation specification", and different types of operating outcomes of interest are described by "result specifications". - -![PRAS model structure and corresponding assessment function arguments](../images/inputoutput.pdf) - -*Figure 1: PRAS model structure and corresponding assessment function arguments* - -PRAS is written in the Julia programming language, and is controlled through the use of Julia scripts. The three components of a PRAS resource adequacy assessment (a system model, a simulation specification, and result specifications) map directly to the Julia function arguments required to launch a PRAS run. A typical resource adequacy assessment with PRAS involves creating or loading a system model, then invoking PRAS' `assess` function to perform the analysis: - -```julia -using PRAS - -sys = SystemModel("filepath/to/mysystem.pras") - -shortfallresult, flowresult = - assess(sys, SequentialMonteCarlo(), Shortfall(), Flow()) - -eue, lole = EUE(shortfallresult), LOLE(shortfallresult) -``` - -More details on running PRAS via Julia code will be provided throughout the remainder of this report. In particular, the [Inputs](inputs.md) section will detail the information contained in a system model input, the [Simulations](simulations.md) section will explain the built-in simulation specification options in PRAS and the various modelling assumptions associated with each, and the [Results](results.md) section will outline PRAS' available result specifications. The [Capacity Credit](capacity-credit.md) section will cover how PRAS can calculate the capacity credit of specific resources based on the results of resource adequacy assessments, and the [Extending](extending.md) section will provide information on extending PRAS beyond its built-in capabilities. \ No newline at end of file diff --git a/docs/src/PRAS/results.md b/docs/src/PRAS/results.md index 8debfb6f..fde98111 100644 --- a/docs/src/PRAS/results.md +++ b/docs/src/PRAS/results.md @@ -1,4 +1,4 @@ -# Result Specifications +# [Result Specifications](@id results) Different analyses require different kinds of results, and different levels of detail within those results. PRAS considers many operational decisions and @@ -12,7 +12,7 @@ simulating with many samples. The current version of PRAS includes six built-in result specification families, with additional user-defined specifications possible (see -[Custom Result Specifications](extending.md#custom-result-specifications)). These families can be classified into regional +[Custom Result Specifications](@ref customsimspec)). These families can be classified into regional results (**Shortfall** and **Surplus**), interface results (**Flow** and **Utilization**), and unit results (**Availability** and **Energy**). diff --git a/docs/src/PRAS/simulations.md b/docs/src/PRAS/simulations.md index 463e5d18..a6bdd7f1 100644 --- a/docs/src/PRAS/simulations.md +++ b/docs/src/PRAS/simulations.md @@ -1,4 +1,4 @@ -# Simulation Specifications +# [Simulation Specifications](@id simulations) There are many different simplifying assumptions that can be made when simulating power system operations for the purpose of studying resource @@ -15,7 +15,7 @@ when simulating operations in order to assess the resource adequacy of the study system. The current version of PRAS defines the **Sequential Monte Carlo** specification, -with additional user-defined specifications possible (see [Custom Simulation Specifications](extending.md#custom-simulation-specifications)). The remainder of this +with additional user-defined specifications possible (see [Custom Simulation Specifications](@ref customsimspec)). The remainder of this section describes the methods and underlying assumptions of each of these built-in simulation specifications. @@ -27,7 +27,20 @@ The Sequential Monte Carlo method simulates the chronological evolution of the s The Sequential Monte Carlo method simulates unit-level outages using a two-state Markov model. In each time period, the availability state of each generator, storage, generator-storage, and line either changes or remains the same, at random, based on the unit's provided state transition probabilities. The capacities from each available generator (or line) in a given time period are then added together to determine the total available generating (transfer) capacity for a region (interface). Storage and generator-storage units are similarly enabled or disabled based on their availability states. -Like with the Non-Sequential Monte Carlo simulation specification, pipe-and-bubble power transfers between regions are possible, subject to interface and line transfer limits, and there is a small penalty applied to transfers in order to prevent loop flows. +Each set of sampled parameters is used to formulate the "pipe-and-bubble" network flow problem shown below, in which local demand in each region is satisfied (or not) using a combination of local generation, imported power, and unserved energy. Regions with surplus capacity can export that power to their neighbours if transmission limits allow, with a small transfer penalty applied to prevent loop flows. Any demand that cannot be supplied under the randomly drawn generation and transmission limits is considered unserved. + +```@raw html +
+Example three-region network flow problem to be solved + by the Non-Sequential Monte Carlo simulation specification. Any + load that cannot be served within the sampled generation + and transmission constraints goes unserved. +
Example three-region network flow problem to be solved + by the Non-Sequential Monte Carlo simulation specification. Any + load that cannot be served within the sampled generation + and transmission constraints goes unserved
+
+``` The Sequential Monte Carlo method is unique in its ability to represent energy-limited resources (storages and generator-storages). These resources are dispatched conservatively so as to approximately minimize unserved energy over the full simulation horizon, charging from the grid whenever surplus generating capacity is available, and discharging only when needed to avoid or mitigate unserved energy. Charging and discharging is coordinated between resources using the time-to-go priority described in [Evans et al. (2019)](#references): resources that would be able to discharge the longest at their maximum rate are discharged first, and resources that would take the longest time to charge at their maximum charge rate are charged first. Cross-charging (discharging one resource in order to charge another) is not permitted. diff --git a/docs/src/PRAS/inputs.md b/docs/src/PRAS/systemspec.md similarity index 93% rename from docs/src/PRAS/inputs.md rename to docs/src/PRAS/systemspec.md index 2570e01b..32c64871 100644 --- a/docs/src/PRAS/inputs.md +++ b/docs/src/PRAS/systemspec.md @@ -1,4 +1,5 @@ -# Input System Specification +# [System Model Specification](@id system_specification) + Assessing the resource adequacy of a power system requires a description of the various resources available to that system, as well as its requirements @@ -107,7 +108,12 @@ opposite state according to unit-specific state transition probabilities. Like maximum available capacity, these transition probabilities are represented as time series, and so may be different during different time periods. -![Relations between power and energy parameters for generator, storage, and generator-storage resources.](../images/resourceparameters.pdf) +```@raw html +
+Relations between power and energy parameters for generator, storage, and generator-storage resources. +
Relations between power and energy parameters for generator, storage, and generator-storage resources
+
+``` ## Storages @@ -173,7 +179,13 @@ A generator-storage in the unavailable state can neither charge nor discharge its storage, nor send energy inflow to the grid. Like storage, it does retain its state of charge during outages (subject to carryover losses). -![Example applications of the generator-storage resource type](../images/genstorexamples.pdf) + +```@raw html +
+Example applications of the generator-storage resource type +
Example applications of the generator-storage resource type
+
+``` ## Interfaces diff --git a/docs/src/PRASCore/api.md b/docs/src/PRASCore/api.md index 5f3840af..4cb5426c 100644 --- a/docs/src/PRASCore/api.md +++ b/docs/src/PRASCore/api.md @@ -1,19 +1,41 @@ # PRASCore API reference ## Systems -```@autodocs -Modules = [PRASCore.Systems] -Order = [:function] +```@docs +PRASCore.Systems.SystemModel +PRASCore.Systems.Regions +PRASCore.Systems.Generators +PRASCore.Systems.Storages +PRASCore.Systems.GeneratorStorages +PRASCore.Systems.Lines +PRASCore.Systems.Interfaces ``` ## Simulations ```@autodocs Modules = [PRASCore.Simulations] -Order = [:function] +Order = [:function,:type] ``` ## Results -```@autodocs -Modules = [PRASCore.Results] -Order = [:function] +```@docs +PRASCore.Results.LOLE +PRASCore.Results.EUE +PRASCore.Results.NEUE +PRASCore.Results.Shortfall +PRASCore.Results.ShortfallSamples +PRASCore.Results.Surplus +PRASCore.Results.SurplusSamples +PRASCore.Results.Flow +PRASCore.Results.FlowSamples +PRASCore.Results.Utilization +PRASCore.Results.UtilizationSamples +PRASCore.Results.GeneratorAvailability +PRASCore.Results.GeneratorStorageAvailability +PRASCore.Results.GeneratorStorageEnergy +PRASCore.Results.GeneratorStorageEnergySamples +PRASCore.Results.StorageAvailability +PRASCore.Results.StorageEnergy +PRASCore.Results.StorageEnergySamples +PRASCore.Results.LineAvailability ``` diff --git a/docs/src/PRASFiles/api.md b/docs/src/PRASFiles/api.md index 7a3faf0e..607c4be2 100644 --- a/docs/src/PRASFiles/api.md +++ b/docs/src/PRASFiles/api.md @@ -1,4 +1,5 @@ ```@autodocs Modules = [PRASFiles] Order = [:function,:type] +Private = false ``` diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index a636d15f..dd5bb28e 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -1,19 +1,21 @@ -_Note: A useful reference for HDF5 file structure concepts is the -[HDF5 Glossary](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary). -This document contains links to glossary entries to explain HDF5 terms when used -for the first time._ - # `SystemModel` HDF5 representation specification This document specifies a representation of the PRAS `SystemModel` data -structure in terms of -[objects](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary#HDF5Glossary-Object) -in an HDF5 file. This specification is version-controlled in the same +structure in terms of objects like +[groups](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_g__u_g.html#subsec_group_descr), +[datatypes](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_t__u_g.html#sec_datatype), and +[datasets](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html#sec_dataset) +in an [HDF5 file](https://support.hdfgroup.org/documentation/hdf5/latest/_l_b_file_org.html). This specification is version-controlled in the same repository as the `SystemModel` source code: any time the `SystemModel` definition is changed, those updates are expected to be reconciled with this document as appropriate. The version of this specification should therefore be taken as the version of the package containing this file. +_Note: A useful reference for HDF5 file structure concepts is the +[HDF5 Glossary](https://support.hdfgroup.org/documentation/hdf5/latest/_g_l_s.html). +This document contains links to documentation entries to explain HDF5 terms when used +for the first time._ + ## Filename extension By convention, HDF5 file representations of a PRAS `SystemModel` struct are @@ -34,7 +36,7 @@ to generically as "resource collections". ### Root group attributes The HDF5 file must define seven -[attributes](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary#HDF5Glossary-Attribute) +[attributes](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_d_m__u_g.html#subsubsec_data_model_abstract_attr) on the [root group](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary#HDF5Glossary-Rootgroup). There can also be additional attributes describing the system, including data descriptors used @@ -139,7 +141,7 @@ take: ### Resource / resource collection data The file may define the following six -[groups](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary#HDF5Glossary-Group) +[groups](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_g__u_g.html) as children of the root group. At least two groups are mandatory. The file must include: @@ -169,7 +171,7 @@ paragraphs. Each group contains one `_core` dataset providing static parameters and/or relations for the group entities, in the form of a vector / one-dimensional array of -[compound datatype](https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary#HDF5Glossary-Compounddatatype) +[compound datatype](https://support.hdfgroup.org/documentation/hdf5/latest/_g_l_s.html) instances. These datasets may use HDF5's automatic compression features to reduce filesize. diff --git a/docs/src/changelog.md b/docs/src/changelog.md new file mode 100644 index 00000000..cd80f272 --- /dev/null +++ b/docs/src/changelog.md @@ -0,0 +1,11 @@ +# Changelog + +## [Unreleased] +- Initial changelog created. + +## [0.7], 2024 - December +- PRAS codebase refactored as a monorepo, and subpackages `PRAS.jl`, `PRASCore.jl`, `PRASFiles.jl`, and `PRASCapacityCredits.jl` available through the Julia General registreies. +- Removed `Convolution` and `NonSequentialMonteCarlo` simulation capabilities to simplify codebase + +## [0.6], 2021 - May +- Initial release of PRAS in Julia. Installation available from the NREL Julia registries or through source code available in the [`master`](https://github.com/NREL/PRAS/tree/master) branch of the PRAS github repository. Documentation for this version is available [here](https://docs.nrel.gov/docs/fy21osti/79698.pdf). diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 00000000..73684a89 --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,16 @@ +# Contributing to PRAS + +Thank you for your interest in contributing to the Probabilistic Resource Adequacy Suite (PRAS) project! + +## How to Contribute + +- **Report Issues:** If you find a bug or have a feature request, please open an issue on the GitHub repository. +- **Submit Pull Requests:** Contributions are welcome via pull requests. Please ensure your code is well-documented and tested. +- **Documentation:** Improvements to documentation are always appreciated. Feel free to suggest edits or add new content. +- **Code Style:** Follow the existing code style and conventions used in the project. + +## Getting Help + +If you have questions or need help, please open an issue or start a discussion on GitHub. + +We appreciate your contributions to PRAS! diff --git a/docs/src/PRAS/extending.md b/docs/src/extending.md similarity index 99% rename from docs/src/PRAS/extending.md rename to docs/src/extending.md index 2a01b0f2..31520f44 100644 --- a/docs/src/PRAS/extending.md +++ b/docs/src/extending.md @@ -1,4 +1,4 @@ -# Extending PRAS +# [Extending PRAS](@id extending) PRAS provides opportunties for users to non-invasively build on its general simulation framework by redefining how simulations are executed, augmenting @@ -12,7 +12,7 @@ structures. Julia's multiple dispatch functionality can then identify and use these newly defined capabilities when the `assess` function is invoked appropriately. -## Custom Simulation Specifications +## [Custom Simulation Specifications](@id customsimspec) Custom simulation specifications allow for redefining how PRAS models system operations. In addition to the data structures and methods listed here, diff --git a/docs/src/images/genstorexamples.pdf b/docs/src/images/genstorexamples.pdf index 40e5ae03b0a5465a32e531aec66c6b3556fa3816..522d95d82d2fe13932f06133ee697a308a1c608f 100644 GIT binary patch delta 2409 zcmbuB3s4hx9>i6-ue*v0xy{#$*G*t8Cf> zay=ChMGCbrTIs|1rWFxwMTe@?6A^l9>$4o{wPcV!WbRta{g)?B^?@*#YoyX7JXj4*E$0lq}fecDBb5E*_=no4LXJfA}B+J zpi(L2067@k2!#aTaz(iasv>Qa-KryPfaT#8H@Z$X;Xpk4qC|pbSSej5NrN1KLYg3# zMdG8!6F-p}GZvdHAXhd`2Q&q{s{WUsu`%%I94z z{1lX#9)+h?V*qC@RY*FE3i7j%R@&g@oGOEl+2l~MAjh!8`P?Vd)R>xyz?uN%qpf9EflcE*RrJX3A?N%sB3aW5hx@ zdbF#KHtab!4jY zrtyMy1Fv|WC$~`+nF1mUnI<& z`lzs-N$G#3@&bCSFHZSjCzdkXpKiJDdZ7PlNEf`QCH5BCdHU-YM?O`zM0b0J%x^c` zCRQd>8Grt!$el`TeXafL^R6lvKA2gy?n2+x^qZDn13h`MBemx*ckWdYhd!DgmB(M* zaHHshw%u9hkL=0XG0Wq3EB5{22dUYvWwPF+Lyk};c3tn}w&Yp!uV-$ueAF0mscvA~ zwY@bjFBwd~eYm=`Z+qDXixrnW_KxItMlAP4+xt$t3*PG-wwR5-4jTiuIAT$v`ly2wobbM=>Z4?53QOtCeq%3N>l-}iA>(6#AV z{tX$ypP-@4{h$z=JL+M})Ss(vDHjToPW#PTJ^$d`D}xm)ztA3?ay7fI?$z4DHKOBD zJJMR-bf$h{FFmm}a(8I)eaQ+=^YPs&9Svlym3l!McBsSLUs%cUq=n_+Qd@38nOb@8 z^Ck^`C&00`a>E-5K|PWOBc;_b>myQAXmhpzf97bov6DO9y>GEN*^r~h!DB>v=0hcYP~`!*&%VZ{s`^@r9X z7iY`2%b#1A9Dapa9}^Xrf`x2uSDWoan|foy-yI;2XE?Gw=nK`o|2px_EJNhY7aL8^ z4S3PKjS5GP{7T=9f%4k&ixvGdTQ}$I?DUB450C7*xb?3S+HT}WZcKdVXU~-{LuyvM z;mkD#goYjPtKnx~la{1Zb!S9(GADAPa}Ol!ef5;&yQpi~(}tPy{w!@(-i;s6L?7(A zHKf>#jnk0W8R_eu-bt+@^AI%ItS3jOCN75UKGU$C1UPKbt3VD8xBzEI07cONXDb-a zSa#?Fob7JxMhIFYB2C-IWtMNCL}5&&)fj|mLp{Z|nR zp8j8D`nkiCol7IuOzf`vAuVLu@*}ajcKO8RN4S}fmN>AsQ*#r_g@O8Z_uYm!|E;gZ t%4XJYI8*Ys&;InOWA-l{mjfM-W3tg2EA6mCFg!lN=OT0FB&92m{{ZGKc)|bx delta 8330 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 L8dN9W7q9;ZGVe)y diff --git a/docs/src/images/inputoutput.pdf b/docs/src/images/inputoutput.pdf index 77ebb585ac71f845da40e9ff8932c92622e2c8ce..ef7702319c6795db0ec16fac6422bc51098b82ce 100644 GIT binary patch delta 1274 zcmah}eQXnD7~dG(%xxjlY-E3EcoS^bS$1E&yRN!4+qFHI?xR^NjFg34+qYX;+dJ;A zFafDwb5Xmvfzn8XWDW=*E+KBwL^6sDFp9DnOcXTy(JlM|WC1fknZ~zW>qjJddGq9+ z=l$LD{O1%v&ZO^|!p9 z7i0*CjyB&G=+`j99rJ0~h#)BujL6t5g2D)w$Jv1kp)hO}BM=yIA{2>>-B2Y$Q8}hb zF%4N<4g_m*P#4;4jYWJ=0r{_+qCv?K@@t?DF=)pKo|pQ7mqd=)$^nY3>%@q)iWHLp zy98*5suWZFPz4zcoPF9_wxm@LXQKATOn$$Jtj&fNGI_OFGflGCNmKE3oXS+m zi|JCNK+KPb84+I(>_D0`Bu-lpbvqJDlh6(d=iQJLb!4g<9Z%CF&60H#Louv{wAPYb zHAz+@T#FR=Pe>eLJc=mGFaQWa4686NXe=D|iP30=jHf500<@M$tpV$yqN3WsjH80A zmF8G;Esb+|wpos#IkXLe3@u`v6oEbkZm$8ovZ(c_Pz2j@88{uz;8e}tk(o-Q)zX=x zBX?`)j9USR4mzZ$8Za||N=IAie>7U>P-ELNs=R;xx5|0LU>JwJjuL3rPB{h2%G~`FuCDu+zL>t4no6B7n<`6`Edp+J`tZu~ua`|VH(dO(?_}cT i+iyNnRG{wFdH=12s)>r$r=Y)Q8Pr{vUhixZus;CByRqN^ delta 852 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 diff --git a/docs/src/images/resourceparameters.pdf b/docs/src/images/resourceparameters.pdf index dc90a2acee88258b8c931887d190aefadb3b062b..d5a65d1886e664389f219cdf7c72d30f282b67e6 100644 GIT binary patch delta 2496 zcma)82~<;88fFn;o}yGM1J=T`NCAc9y_c1xph?(d2~EOQ;CKQ&B#`8BlE=~tMy)95 zsBM*@9_xmv1t*kUX|T$Kkti@Mg|cbIjtIzd1hL9Yk-1?xWllL~cqiwbcklh~_y70% z|Ns7ZHe_5;W2~|d;rY0r6eeWf+VPKWhz=t#5t{^gctF%ZT)vk~glVqu!UIu#BvKMr zz*HZpn8bN_91)L0o}Q4BRN!J6l+nB6DJDV;I9!t$yNz}xG2Au6?5EL`td?l5Nq%O@ zPKtrFaCJ3=%i|Yz;3|2%-W94Mrk zC-Ijj5Ijj73A2GC0*K1t5E*b30tT*31ZL2Y7>MetAW~Cc#ymi$%$Q9J7cjgNYE9E5jDuUDKf z4L9*y8j*#7FoB`PL|88Bi`Hpu+V2@qVV8Zta5*-;tSe!|*vJyLAA7A0BbV__FYZd% zXb2NyF6xBBECi!7me9MIUrAqv9@EEbCG;3jp7A?9gF&M+m(WiiIU`j4(R)lE>P31G z;`r1!kco~UK}C23s6;wK!B`+yxuB#-0<3`P#i4|d^YmHf$aBLGjDfIGI!b4-P{ajc zIv|Jxzy%TUOCYLcF(QRHB?XTMWh|B|@x?kyl}cm9a=G3aQKCc%gWtSU&TtqgAz&M( zQGh{)E5>BdTrdiA(c3v6;Xp|m4(r{b`VlfbR)MEG!K&mGF`1~u#cNl1cH4+iP3Pi%#fgk4#SLc?rVWX1Q9N*y|)>}6Zbj^ByBQ*~Cu z`^vWb(J*<$_tM!l*+#c3yM|50H~Np4S@k?*%+8GUdT`7J+{VnTB~{-&9#0xDJZi8i zeXG$EWlr5`&+)obUpT`#F%}e^&iJ60O@r=8qnVekzwz!nTXQVDbXG?V`wwXhZyC+v zL$&+IN{6+(jaBaz)ucr9Q;->CHAEN6UYdIBMeqmJT&=r5xuO9ztFH?qrKCE z-nU+CTJQ60kIeVO9owJUd_DEe-@jxGyR{Xf3|i2?`_@^!4{;w_uT zI<>mz8@K{ZR+%=PcJRCHRJ3Evur&Q1CG@2H=7BvmhNrZxVr|=BarWi|cO$AUl_x*s zuP&~2DB=)5rp>6-&-txp8#cW1%Z-$s`G(=V|3SeUlWWYw#!)Rd|?mw?B`5JOjNW>=TrD6(_v+6;wLV<->j8esSLfWE(~_Q{9^N}$)5ZC zzqF=~IN8UPl~yaHBNI7Uv(`y*cK!R-`!&i>SSC(3ziy>*c6}A45o@&*Z*2z#f1T;$ z|4Z|sSHA4@^;viS%j{sm8@fN|LV#fE{I+ZdOh`zSZp+$!gk+eB(feg|K2N82-gy7*c6o=R-1O zt^oDV&!s=ywF#`dJk<8&>fmatmgwfjnCY7%Z_V=st6#Y?v8L@s)9uJq2i9m?I`HwY z6lSG!*VGZZ*nank!J!Y@?-!PTzuWRZ8h*Xzp8Lfs6|B4m6{^C}rn0@iSZZb_`8fp* z!@buZi)~ptqjzk@>z}5V9-Z8l#wu>P*=_u(rKa&>tg2eqVgh?u8$7vhn{&6}$tZC? zB-cO_30*3G&)BB@TwWlVjaYvat}%M(HD!N$D*4z&?OUCoc4NoIdwjM#besP2+6Rrz zeJ8if8tyyoI|8YewEFpS$Mo%O@%me6^#VKrqWa6@@wuLh(Lu8nN8C`L=8T delta 8586 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 diff --git a/docs/src/index.md b/docs/src/index.md index a11514ce..1983ea68 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,4 +1,6 @@ -The Probabilistic Resource Adequacy Suite (PRAS) provides an open-source, research-oriented collection of tools for analysing the resource adequacy of a +# PRAS + +The Probabilistic Resource Adequacy Suite (PRAS) provides an open-source, research-oriented collection of tools for analysing the [resource adequacy](@ref resourceadequacy) of a bulk power system. It allows the user to simulate power system operations under a wide range of operating conditions in order to study the risk of failing to meet demand (due to a lack of supply or deliverability), and identify the time periods and regions in which that risk occurs. It offers high-performance sequential Monte Carlo methods supporting multi-region composite reliability assessment, including simulation of energy-limited resources such as storage. PRAS is developed and maintained at the US @@ -6,4 +8,28 @@ PRAS is developed and maintained at the US To get started on using PRAS, see the [installation](./installation.md) and [getting Started](./getting-started.md) pages. +## Basic usage + +PRAS maps a provided representation of a power system to a probabilistic description of operational outcomes of interest, using a particular choice of operations simulation. The input system representation is called a "system model", the choice of operational representation is referred to as a "simulation specification", and different types of operating outcomes of interest are described by "result specifications". + +```@raw html +
+PRAS model structure and corresponding assessment function arguments +
PRAS model structure and corresponding assessment function arguments
+
+``` + +PRAS is written in the Julia programming language, and is controlled through the use of Julia scripts. The three components of a PRAS resource adequacy assessment (a system model, a simulation specification, and result specifications) map directly to the Julia function arguments required to launch a PRAS run. A typical resource adequacy assessment with PRAS involves creating or loading a system model, then invoking PRAS' `assess` function to perform the analysis: + +```julia +using PRAS + +sys = SystemModel("filepath/to/mysystem.pras") + +shortfallresult, flowresult = + assess(sys, SequentialMonteCarlo(), Shortfall(), Flow()) + +eue, lole = EUE(shortfallresult), LOLE(shortfallresult) +``` +More details on running PRAS via Julia code are available in this documentaion. The [System Model Specification](@ref system_specification) page details the information contained in a system model input, the [Simulations Specifications](@ref simulations) page explains the built-in simulation specification options in PRAS and the various modelling assumptions associated with each, and the [Results Specification](@ref results) page will outline PRAS' available result specifications. The [Capacity Credit](@ref capacitycredit) page covers how PRAS can calculate the capacity credit of specific resources based on the results of resource adequacy assessments, and the [Extending](@ref extending) page provides information on extending PRAS beyond its built-in capabilities. diff --git a/docs/src/resource-adequacy.md b/docs/src/resource-adequacy.md index 8d20e63c..1107264b 100644 --- a/docs/src/resource-adequacy.md +++ b/docs/src/resource-adequacy.md @@ -1,4 +1,4 @@ -# Resource Adequacy Background +# [Resource Adequacy Background](@id resourceadequacy) An electrical power system is considered resource adequate if it has procured sufficient resources (including supply, transmission, and responsive demand) @@ -20,7 +20,7 @@ through to chronological simulations of system dispatch and power flow over the full operating horizon. The resulting outcomes can then be used to calculate industry-standard -probabilistic risk metrics [NERC Probabilistic Assessment Working Group, 2018](#references): +[probabilistic risk metrics [1]](#references). **Expected Unserved Energy (EUE)** is the expected (average) total energy shortfall over the study period. It may be expressed in energy units @@ -51,4 +51,4 @@ resource adequacy assessment. ## References -NERC Probabilistic Assessment Working Group. (2018). Probabilistic Adequacy and Measures. North American Electric Reliability Corporation. \ No newline at end of file +1. de Mijolla, G., Bello, M., Danti Lopez, I., Entriken, R., Hytowitz, R., Lannoye, E., Ranola, J.A., Roark, J., Tuohy, A., & Wang, Q. (2022). Resource adequacy for a decarbonized future: A summary of existing and proposed resource adequacy metrics. Tech. Rep. 3002023230, Electric Power Research Institute (EPRI). \ No newline at end of file From 75fa976fcf9716871817fa1067e5fc4f8a8d04e0 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Tue, 2 Sep 2025 16:11:25 -0600 Subject: [PATCH 14/25] Add example, minor changes with doc structure, refs etc. --- PRAS.jl/examples/example1.jl | 75 +++++++++++++++++++++++++++++++ docs/Project.toml | 3 ++ docs/make.jl | 23 ++++++++++ docs/src/PRAS/results.md | 83 +---------------------------------- docs/src/changelog.md | 54 +++++++++++++++++++++-- docs/src/getting-started.md | 4 +- docs/src/index.md | 2 +- docs/src/resource-adequacy.md | 7 ++- 8 files changed, 162 insertions(+), 89 deletions(-) create mode 100644 PRAS.jl/examples/example1.jl diff --git a/PRAS.jl/examples/example1.jl b/PRAS.jl/examples/example1.jl new file mode 100644 index 00000000..ffeac106 --- /dev/null +++ b/PRAS.jl/examples/example1.jl @@ -0,0 +1,75 @@ +# # Additional Examples + +# This section provides a more complete example of running a PRAS assessment, +# with a hypothetical analysis process making use of multiple different +# results. + + +using PRAS + +# Load in a system model from a .pras file. +# This hypothetical system has an hourly time resolution with an +# extent / simulation horizon of one year. +sys = PRAS.rts_gmlc() + +# This system has multiple regions and relies on battery storage, so +# run a sequential Monte Carlo analysis: +shortfall, utilization, storage = assess( + sys, SequentialMonteCarlo(samples=100, seed=1), + Shortfall(), Utilization(), StorageEnergy()); + +# Start by checking the overall system adequacy: +lole = LOLE(shortfall) # event-hours per year +eue = EUE(shortfall) # unserved energy per year + +# Suppose LOLE is below the target threshold but EUE seems high, suggesting large +# amounts of unserved energy are concentrated in a small number of hours. What +# do the hourly results show? + + +# Note 1: LOLE.(shortfall, many_hours) is Julia shorthand for calling LOLE +# on every timestep in the collection many_hours +# Note 2: Here results are in terms of event-hours per hour, which is +# equivalent to the loss-of-load probability (LOLP) for each hour +lolps = LOLE.(shortfall, sys.timestamps) + +# One might see that a particular hour has an LOLP near 1.0, indicating that +# load is consistently getting dropped in that period. Is this a local issue or +# system-wide? One can check the unserved energy by region in that hour: + + +shortfall_period = ZonedDateTime(2020, 8, 21, 17, tz"America/Denver") +unserved_by_region = EUE.(shortfall, sys.regions.names, shortfall_period) + +# Perhaps only one region (D) has non-zero EUE in that hour, indicating that this +# must be a load pocket issue. We can also look at the utilization of interfaces +# into that region in that period: + + +utilization["1" => "2", shortfall_period] +utilization["2" => "3", shortfall_period] +utilization["3" => "1", shortfall_period] + +# These sample-averaged utilizations should all be very close to 1.0, indicating +# that power transfers are consistently maxed out; neighbouring regions have +# power available but can't send it to Region D. + +# Transmission expansion is clearly one solution to this adequacy issue. Is local +# storage another alternative? One can check on the average state-of-charge of +# the existing battery in that region, both in the hour before and during the +# problematic period: + + +storage["313_STORAGE_1", shortfall_period-Hour(1)] +storage["313_STORAGE_1", shortfall_period] + +# It may be that the battery is on average fully charged going in to the event, +# and perhaps retains some energy during the event, even as load is being +# dropped. The device's ability to mitigate the shortfall must then be limited +# only by its discharge capacity, so given that the event doesn't last long, +# adding additional short-duration storage in this region would help. + +# Note that if the event was less consistent, this analysis could also have been +# performed on the subset of samples in which the event was observed, using the +# `ShortfallSamples`, `UtilizationSamples`, and +# `StorageEnergySamples` result specifications instead. diff --git a/docs/Project.toml b/docs/Project.toml index 1814eb33..521027c6 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,8 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" +LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" +Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" [compat] Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl index 1d94d2df..e7b41616 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,6 +2,28 @@ using Documenter using PRASCore using PRASFiles using PRASCapacityCredits +using Plots, Literate + +@info "Building example problems..." + +# utility function from https://github.com/JuliaOpt/Convex.jl/blob/master/docs/make.jl +fix_math_md(content) = replace(content, r"\$\$(.*?)\$\$"s => s"```math\1```") +fix_suffix(filename) = replace(filename, ".jl" => ".md") +function postprocess(cont) + """ + The source files for all examples can be found in [/examples](https://github.com/NREL/PRAS/examples/). + """ * cont +end + +example_path = joinpath(@__DIR__, "..","PRAS.jl","examples/") +build_path = joinpath(@__DIR__, "src", "examples/") +files = readdir(example_path) +filter!(x -> endswith(x, ".jl"), files) +for file in files + Literate.markdown(example_path * file, build_path; preprocess = fix_math_md, postprocess = postprocess, documenter = true, credit = true) +end + +examples_nav = fix_suffix.("./examples/" .* files) # Generate the unified documentation makedocs( @@ -25,6 +47,7 @@ makedocs( "Capacity Credit Calculation" => "PRAS/capacity-credit.md", ], ".pras File Format" => "SystemModel_HDF5_spec.md", + "Examples" => examples_nav, "Extending PRAS" => "extending.md", # "Contributing" => "contributing.md", "Changelog" => "changelog.md", diff --git a/docs/src/PRAS/results.md b/docs/src/PRAS/results.md index fde98111..893af5d7 100644 --- a/docs/src/PRAS/results.md +++ b/docs/src/PRAS/results.md @@ -243,85 +243,4 @@ variants are available for selecting the category of energy-limited resource sample-level disaggregation. Energy is always disaggregated by timestep and may also be disaggregated by unit (get the state of charge of a single unit) or aggregated across the system (get the sum of states of charge -of all storage devices in the system). - -## Additional Examples - -This section provides a more complete example of running a PRAS assessment, -with a hypothetical analysis process making use of multiple different -results. - -```julia -using PRAS - -# Load in a system model from a .pras file. -# This hypothetical system has an hourly time resolution with an -# extent / simulation horizon of one year. -sys = SystemModel("mysystem.pras") - -# This system has multiple regions and relies on battery storage, so -# run a sequential Monte Carlo analysis: -shortfall, utilization, storage = assess( - sys, SequentialMonteCarlo(samples=10000, seed=1), - Shortfall(), Utilization(), StorageEnergy()) - -# Start by checking the overall system adequacy: -lole = LOLE(shortfall) # event-hours per year -eue = EUE(shortfall) # unserved energy per year -``` - -Suppose LOLE is below the target threshold but EUE seems high, suggesting large -amounts of unserved energy are concentrated in a small number of hours. What -do the hourly results show? - -```julia -# Note 1: LOLE.(shortfall, many_hours) is Julia shorthand for calling LOLE -# on every timestep in the collection many_hours -# Note 2: Here results are in terms of event-hours per hour, which is -# equivalent to the loss-of-load probability (LOLP) for each hour -lolps = LOLE.(shortfall, sys.timestamps) -``` - -One might see that a particular hour has an LOLP near 1.0, indicating that -load is consistently getting dropped in that period. Is this a local issue or -system-wide? One can check the unserved energy by region in that hour: - -```julia -shortfall_period = ZonedDateTime(2020, 8, 21, 17, tz"America/Denver") -unserved_by_region = EUE.(shortfall, sys.regions.names, shortfall_period) -``` - -Perhaps only one region (D) has non-zero EUE in that hour, indicating that this -must be a load pocket issue. We can also look at the utilization of interfaces -into that region in that period: - -```julia -utilization["Region A" => "Region D", shortfall_period] -utilization["Region B" => "Region D", shortfall_period] -utilization["Region C" => "Region D", shortfall_period] -``` - -These sample-averaged utilizations should all be very close to 1.0, indicating -that power transfers are consistently maxed out; neighbouring regions have -power available but can't send it to Region D. - -Transmission expansion is clearly one solution to this adequacy issue. Is local -storage another alternative? One can check on the average state-of-charge of -the existing battery in that region, both in the hour before and during the -problematic period: - -```julia -storage["Battery D1", shortfall_period-Hour(1)] -storage["Battery D1", shortfall_period] -``` - -It may be that the battery is on average fully charged going in to the event, -and perhaps retains some energy during the event, even as load is being -dropped. The device's ability to mitigate the shortfall must then be limited -only by its discharge capacity, so given that the event doesn't last long, -adding additional short-duration storage in this region would help. - -Note that if the event was less consistent, this analysis could also have been -performed on the subset of samples in which the event was observed, using the -`ShortfallSamples`, `UtilizationSamples`, and -`StorageEnergySamples` result specifications instead. +of all storage devices in the system). \ No newline at end of file diff --git a/docs/src/changelog.md b/docs/src/changelog.md index cd80f272..207094bb 100644 --- a/docs/src/changelog.md +++ b/docs/src/changelog.md @@ -3,9 +3,57 @@ ## [Unreleased] - Initial changelog created. +## [0.8.0], 2025 - September + + ## [0.7], 2024 - December -- PRAS codebase refactored as a monorepo, and subpackages `PRAS.jl`, `PRASCore.jl`, `PRASFiles.jl`, and `PRASCapacityCredits.jl` available through the Julia General registreies. -- Removed `Convolution` and `NonSequentialMonteCarlo` simulation capabilities to simplify codebase +- PRAS codebase refactored as a monorepo, and subpackages `PRAS.jl`, `PRASCore.jl`, +`PRASFiles.jl`, and `PRASCapacityCredits.jl` available through the Julia General registries. +- Removed `Convolution` and `NonSequentialMonteCarlo` simulation capabilities to simplify codebase. +- Bump Julia version required to `v1.10` +- Add results serialization capability for `ShortfallResults` ## [0.6], 2021 - May -- Initial release of PRAS in Julia. Installation available from the NREL Julia registries or through source code available in the [`master`](https://github.com/NREL/PRAS/tree/master) branch of the PRAS github repository. Documentation for this version is available [here](https://docs.nrel.gov/docs/fy21osti/79698.pdf). +- Major updates to the results interface, including for capacity credit and SequentialMonteCarlo. +- Refactored and simplified metric types. +- Added and tested new modular result specifications. +- Updated capacity credit calculations and de-duplicated specification keyword defaults. +- Added tests for savemodel and support for exporting .pras files. +- Replaced Travis CI with GitHub Actions for continuous integration. +- Improved compatibility with HDF5.jl and ensured non-negative storage state of charge. +- Enforced interface-level limits and forced outages for storage and generator-storage. +- Removed unused test files and updated the README with a code coverage badge. + +This version is availabe at the NREL Julia registries or through source code available +in the [`master`](https://github.com/NREL/PRAS/tree/master) branch of the PRAS github +repository. Documentation for this version is available [here] +(https://docs.nrel.gov/docs/fy21osti/79698.pdf). + + +## [0.5], 2020 - November +- Major refactor of simulation specs and result types. +- Added support for sequential and nonsequential simulation methods. +- Improved modularity of result specifications and metrics. +- Added support for capacity credit and spatiotemporal result specs. +- Improved documentation and test coverage. + +## [0.4], 2019 - July +- Added support for storage and generator-storage modeling. +- Improved network flow and copperplate simulation methods. +- Added new result types and improved performance. +- Refactored codebase for better modularity and maintainability. + +## [0.3], 2019 - April +- Added support for network result types and transmission modeling. +- Improved simulation performance and result extraction. +- Added new tests and documentation. + +## [0.2], 2019 - August +- Added tests and improved SystemModel constructor. +- Improved compatibility with Julia 1.0+. +- Added Travis CI integration and coverage reporting. + +## [0.1], 2018 - March +- Initial public release of PRAS. +- Basic resource adequacy simulation and result extraction. +- Initial documentation and test coverage. diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index 9734e44f..5b07b30d 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -1,6 +1,6 @@ -# Getting Started with PRAS +# [Getting Started with PRAS](@id quickstart) -Once you have PRAS [installed](./installation.md), this page provides a brief overview to help you start running PRAS quickly. +Once you have PRAS [installed](@ref Installation), this page provides a brief overview to help you start running PRAS quickly. ## Parallel Processing diff --git a/docs/src/index.md b/docs/src/index.md index 1983ea68..9d74ab96 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -6,7 +6,7 @@ bulk power system. It allows the user to simulate power system operations under PRAS is developed and maintained at the US [National Renewable Energy Laboratory](https://www.nrel.gov/) (NREL). -To get started on using PRAS, see the [installation](./installation.md) and [getting Started](./getting-started.md) pages. +To get started on using PRAS, see the [installation](@ref Installation) and [quick start](@ref quickstart) pages. ## Basic usage diff --git a/docs/src/resource-adequacy.md b/docs/src/resource-adequacy.md index 1107264b..2a1f22a0 100644 --- a/docs/src/resource-adequacy.md +++ b/docs/src/resource-adequacy.md @@ -51,4 +51,9 @@ resource adequacy assessment. ## References -1. de Mijolla, G., Bello, M., Danti Lopez, I., Entriken, R., Hytowitz, R., Lannoye, E., Ranola, J.A., Roark, J., Tuohy, A., & Wang, Q. (2022). Resource adequacy for a decarbonized future: A summary of existing and proposed resource adequacy metrics. Tech. Rep. 3002023230, Electric Power Research Institute (EPRI). \ No newline at end of file +1. de Mijolla, G., Bello, M., Danti Lopez, I., Entriken, R., Hytowitz, R., + Lannoye, E., Ranola, J.A., Roark, J., Tuohy, A., & Wang, Q. (2022). + [Resource adequacy for a decarbonized future: A summary of existing and + proposed resource adequacy metrics] + (https://www.epri.com/research/products/000000003002023230). + Tech. Rep. 3002023230, Electric Power Research Institute (EPRI). \ No newline at end of file From 4e2fcabe381ccebfa662b3e455860cb6ded5c868 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Mon, 8 Sep 2025 22:20:33 -0600 Subject: [PATCH 15/25] Add Generator docstring that got dropped during rebase --- PRASCore.jl/src/Systems/assets.jl | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/PRASCore.jl/src/Systems/assets.jl b/PRASCore.jl/src/Systems/assets.jl index c3aea7cb..f4a11d6e 100644 --- a/PRASCore.jl/src/Systems/assets.jl +++ b/PRASCore.jl/src/Systems/assets.jl @@ -37,6 +37,27 @@ function Base.show(io::IO, a::AbstractAssets) end +""" + Generators{N,L,T<:Period,P<:PowerUnit} + +A struct representing generating assets within a power system. + +# Type Parameters +- `N`: Number of timesteps in the system model +- `L`: Length of each timestep in T units +- `T`: The time period type used for temporal representation, subtype of `Period` +- `P`: The power unit used for capacity measurements, subtype of `PowerUnit` + +# Fields + - `names`: Name of generator + - `categories`: Category of generator + - `capacity`: Maximum available generation capacity in each timeperiod, expressed + in units given by the `power_units` (`P`) type parameter + - `λ` (failure probability): probability the generator transitions from + operational to forced outage during a given simulation timestep (unitless) + - `μ` (repair probability): probability the generator transitions from forced + outage to operational during a given simulation timestep (unitless) +""" struct Generators{N,L,T<:Period,P<:PowerUnit} <: AbstractAssets{N,L,T,P} names::Vector{String} From 7252e9d4581d2390ca28fec600089287bcf9c4a9 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Tue, 23 Sep 2025 23:38:30 -0600 Subject: [PATCH 16/25] Update PRAS run through example with plots and outputs --- .../{example1.jl => pras_walkthrough.jl} | 80 ++++++++++++++++--- PRASCore.jl/src/Systems/SystemModel.jl | 4 +- 2 files changed, 70 insertions(+), 14 deletions(-) rename PRAS.jl/examples/{example1.jl => pras_walkthrough.jl} (50%) diff --git a/PRAS.jl/examples/example1.jl b/PRAS.jl/examples/pras_walkthrough.jl similarity index 50% rename from PRAS.jl/examples/example1.jl rename to PRAS.jl/examples/pras_walkthrough.jl index ffeac106..87744cfb 100644 --- a/PRAS.jl/examples/example1.jl +++ b/PRAS.jl/examples/pras_walkthrough.jl @@ -1,19 +1,75 @@ -# # Additional Examples +# # Quick PRAS walk-through # This section provides a more complete example of running a PRAS assessment, -# with a hypothetical analysis process making use of multiple different -# results. - +# using the [RTS-GMLC](https://github.com/GridMod/RTS-GMLC) system +# making use of multiple different results. +# Load the PRAS module using PRAS - -# Load in a system model from a .pras file. -# This hypothetical system has an hourly time resolution with an -# extent / simulation horizon of one year. -sys = PRAS.rts_gmlc() - -# This system has multiple regions and relies on battery storage, so -# run a sequential Monte Carlo analysis: +using Plots + +# ## Read and explore a SystemModel + +# You can load in a system model from a .pras file if you have one like so: +# ```julia +# sys = SystemModel("mysystem.pras") +# ``` + +# For the purposes of this example, we'll just use the built-in RTS-GMLC model. +sys = PRAS.rts_gmlc(); + +# We see some information about the system by just typing its name +# (or rather the variable that holds it): +sys + +# This system has 3 regions, with multiple Generators, one GenerationStorage in +# region "2" and one Storage in region "3". We can see regional information by +# indexing the system with the region name: +sys["2"] + +# We can find more information about all the Generators in the system by +# retriving the `generators` in the SystemModel: +system_generators = sys.generators + +# This returns an object of the asset type [Generators](@ref PRASCore.Systems.Generators) +# and we can retrieve capacities of all generators in the system, which returns +# a Matrix with the shape (number of generators) x (number of timepoints): +system_generators.capacity + +# We can visualize a time series of the total system capacity +# (sum over individual generators' capacity at each time step) +plot(sys.timestamps, sum(system_generators.capacity, dims=1)', + xlabel="Time", ylabel="Total system capacity (MW)", legend=false) + +# Or, by category of generators: +category_indices = Dict([cat => findall(==(cat), system_generators.categories) + for cat in unique(system_generators.categories)]); +capacity_matrix = Vector{Vector{Int}}(); +for (category,indices) in category_indices + push!(capacity_matrix, sum(system_generators.capacity[indices, :], dims=1)[1,:]) +end +areaplot(sys.timestamps, hcat(capacity_matrix...), + label=permutedims(collect(keys(category_indices))), + xlabel="Time", ylabel="Total system capacity (MW)") + +# Similarly we can also retrieve all the Storages in the system and +# GenerationStorages in the system using `sys.storages` and `sys.generatorstorages`, +# respectively. + +# To retrieve the assets in a particular region, we can index by the region name +# and asset type (`Generators` here): +region_2_generators = sys["2", Generators] + +# We get the storage device in region "3" like so: +region_3_storage = sys["3", Storages] +# and the generation-storage device in region "2" like so: +region_2_genstorage = sys["2", GeneratorStorages] + +# ## Run a Sequential Monte Carlo simulation + +# We can run a Sequential Monte Carlo simulation on this system using the +# [assess](@ref PRASCore.Simulations.assess) function. +# Here we will also use three different [result specifications](@ref results): shortfall, utilization, storage = assess( sys, SequentialMonteCarlo(samples=100, seed=1), Shortfall(), Utilization(), StorageEnergy()); diff --git a/PRASCore.jl/src/Systems/SystemModel.jl b/PRASCore.jl/src/Systems/SystemModel.jl index e5a0b1bd..25b51ccf 100644 --- a/PRASCore.jl/src/Systems/SystemModel.jl +++ b/PRASCore.jl/src/Systems/SystemModel.jl @@ -203,12 +203,12 @@ function Base.show(io::IO, sys::SystemModel{N,L,T,P,E}) where {N,L,T<:Period,P<: print(io, "SystemModel($(length(sys.regions)) regions, $(length(sys.interfaces)) interfaces, ", "$(length(sys.generators)) generators, $(length(sys.storages)) storages, ", "$(length(sys.generatorstorages)) generator-storages,", - "$(N) $(time_unit)s)") + " $(N) $(time_unit)s)") end function Base.show(io::IO, ::MIME"text/plain", sys::SystemModel{N,L,T,P,E}) where {N,L,T,P,E} time_unit = unitsymbol_long(T) - println(io, "\nPRAS system with $(length(sys.regions)) regions, and $(length(sys.interfaces)) interfaces between these regions.") + println(io, "PRAS system with $(length(sys.regions)) regions, and $(length(sys.interfaces)) interfaces between these regions.") println(io, "Region names: $(join(sys.regions.names, ", "))") println(io, "\nAssets: ") println(io, " Generators: $(length(sys.generators)) units") From d658283413133bf3c93b677567b2108a7e7f8e5f Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Wed, 24 Sep 2025 18:52:10 -0600 Subject: [PATCH 17/25] Update walk through and reorg docs --- .github/workflows/docs.yml | 2 +- PRAS.jl/examples/pras_walkthrough.jl | 122 ++++++++++++------ PRASCore.jl/src/Systems/SystemModel.jl | 3 + PRASCore.jl/src/Systems/Systems.jl | 2 +- PRASCore.jl/src/Systems/assets.jl | 4 +- docs/make.jl | 10 +- .../{capacity-credit.md => capacitycredit.md} | 0 .../PRAS/{systemspec.md => sysmodelspec.md} | 3 + docs/src/SystemModel_HDF5_spec.md | 2 +- docs/src/changelog.md | 3 +- docs/src/index.md | 4 +- .../src/{getting-started.md => quickstart.md} | 2 +- ...source-adequacy.md => resourceadequacy.md} | 0 13 files changed, 99 insertions(+), 58 deletions(-) rename docs/src/PRAS/{capacity-credit.md => capacitycredit.md} (100%) rename docs/src/PRAS/{systemspec.md => sysmodelspec.md} (98%) rename docs/src/{getting-started.md => quickstart.md} (98%) rename docs/src/{resource-adequacy.md => resourceadequacy.md} (100%) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8d354733..097db93d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,7 +11,7 @@ on: jobs: docs: name: Documentation - runs-on: ubuntu-latest + runs-on: macOS-latest permissions: contents: write steps: diff --git a/PRAS.jl/examples/pras_walkthrough.jl b/PRAS.jl/examples/pras_walkthrough.jl index 87744cfb..6cdeddf4 100644 --- a/PRAS.jl/examples/pras_walkthrough.jl +++ b/PRAS.jl/examples/pras_walkthrough.jl @@ -1,16 +1,17 @@ -# # Quick PRAS walk-through +# # [PRAS walkthrough](@id pras_walkthrough) -# This section provides a more complete example of running a PRAS assessment, +# This is a complete example of running a PRAS assessment, # using the [RTS-GMLC](https://github.com/GridMod/RTS-GMLC) system -# making use of multiple different results. -# Load the PRAS module +# Load the PRAS package and other tools necessary for analyses using PRAS using Plots +using DataFrames +using Printf -# ## Read and explore a SystemModel +# ## [Read and explore a SystemModel](@id explore_systemmodel) -# You can load in a system model from a .pras file if you have one like so: +# You can load in a system model from a [.pras file](@ref prasfile) if you have one like so: # ```julia # sys = SystemModel("mysystem.pras") # ``` @@ -22,11 +23,22 @@ sys = PRAS.rts_gmlc(); # (or rather the variable that holds it): sys +# We retrieve the parameters of the system using the `get_params` +# function and use this for the plots below to ensure we have +# correct units: +(timesteps,periodlen,periodunit,powerunit,energyunit) = get_params(rts_gmlc()) + # This system has 3 regions, with multiple Generators, one GenerationStorage in # region "2" and one Storage in region "3". We can see regional information by # indexing the system with the region name: sys["2"] +# We can visualize a time series of the regional load in region "2": +region_2_load = sys.regions.load[sys["2"].index,:] +plot(sys.timestamps, region_2_load, + xlabel="Time", ylabel="Region 2 load ($(powerunit))", + legend=false) + # We can find more information about all the Generators in the system by # retriving the `generators` in the SystemModel: system_generators = sys.generators @@ -69,55 +81,81 @@ region_2_genstorage = sys["2", GeneratorStorages] # We can run a Sequential Monte Carlo simulation on this system using the # [assess](@ref PRASCore.Simulations.assess) function. -# Here we will also use three different [result specifications](@ref results): -shortfall, utilization, storage = assess( +# Here we will also use four different [result specifications](@ref results): +shortfall, surplus, utilization, storage = assess( sys, SequentialMonteCarlo(samples=100, seed=1), - Shortfall(), Utilization(), StorageEnergy()); + Shortfall(), Surplus(), Utilization(), StorageEnergy()); # Start by checking the overall system adequacy: -lole = LOLE(shortfall) # event-hours per year -eue = EUE(shortfall) # unserved energy per year - -# Suppose LOLE is below the target threshold but EUE seems high, suggesting large -# amounts of unserved energy are concentrated in a small number of hours. What -# do the hourly results show? +lole = LOLE(shortfall); # event-hours per year +eue = EUE(shortfall); # unserved energy per year +println("System $(lole), $(eue)") +# Given we use only 100 samples and the RTS-GMLC system is quite reliable, +# we see a system which is reliable, with LOLE and EUE both near zero. +# For the purposes of this example, let's increase the system load homogenously +# by 1000MW in every hour and region, and re-run the assessment. -# Note 1: LOLE.(shortfall, many_hours) is Julia shorthand for calling LOLE -# on every timestep in the collection many_hours -# Note 2: Here results are in terms of event-hours per hour, which is -# equivalent to the loss-of-load probability (LOLP) for each hour +sys.regions.load .+= 700.0 +shortfall, surplus, utilization, storage = assess( + sys, SequentialMonteCarlo(samples=100, seed=1), + Shortfall(), Surplus(), Utilization(), StorageEnergy()); +lole = LOLE(shortfall); # event-hours per year +eue = EUE(shortfall); # unserved energy per year +neue = NEUE(shortfall); # unserved energy per year +println("System $(lole), $(eue), $(neue)") + +# Now we see a system which is slightly unreliable with a normalized +# expected unserved energy (NEUE) of close to 470 parts per million of total load. + +# We can now look at the hourly loss-of-load expectation (LOLE) to see when +# when shortfalls are occurring. +# `LOLE.(shortfall, many_hours)` is Julia shorthand for calling LOLE +# on every timestep in the collection many_hours lolps = LOLE.(shortfall, sys.timestamps) -# One might see that a particular hour has an LOLP near 1.0, indicating that -# load is consistently getting dropped in that period. Is this a local issue or -# system-wide? One can check the unserved energy by region in that hour: - - -shortfall_period = ZonedDateTime(2020, 8, 21, 17, tz"America/Denver") -unserved_by_region = EUE.(shortfall, sys.regions.names, shortfall_period) - -# Perhaps only one region (D) has non-zero EUE in that hour, indicating that this -# must be a load pocket issue. We can also look at the utilization of interfaces -# into that region in that period: - - -utilization["1" => "2", shortfall_period] -utilization["2" => "3", shortfall_period] -utilization["3" => "1", shortfall_period] - -# These sample-averaged utilizations should all be very close to 1.0, indicating -# that power transfers are consistently maxed out; neighbouring regions have -# power available but can't send it to Region D. +# Here results are in terms of event-hours per hour, which is equivalent +# to the loss-of-load probability (LOLP) for each hour. The LOLE object is +# shown as mean ± standard error. We are mostly interested in the mean here, +# we can retrieve this using `val.(lolps)` and visualize this: +plot(sys.timestamps, val.(lolps), + xlabel="Time", ylabel="Hourly LOLE (event-hours/hour)", legend=false) + +# We see the shortfall is concentrated in a few hours and there are many +# hours with LOLE = 1, or which means that hour had a shortfall in every +# Monte Carlo sample. + +# We can find the regional EUE for the entire simulation period, +# and obtain it in as a DataFrame for easier viewing: +regional_eue = DataFrame([(Region=reg_name, EUE=val(EUE(shortfall, reg_name))) + for reg_name in sys.regions.names], + [:Region, :EUE]) + +# We may be interested in the EUE in the hour with highest LOLE +# the unserved energy by region in that hour: +max_lole_ts = sys.timestamps[findfirst(val.(lolps).==1)]; +println("Hour with first LOLE of 1.0: ", max_lole_ts) + +# And we can find the unserved energy by region in that hour: +unserved_by_region = EUE.(shortfall, sys.regions.names, max_lole_ts) +# which returns a Vector of EUE values for each region. + +# Region 2 has highest EUE in that hour, and we can look at the +# utilization of interfaces into that region in that period: +@printf "Interface between regions 1 and 2 utilization: %0.2f \n" utilization["1" => "2", max_lole_ts][1] +@printf "Interface between regions 1 and 3 utilization: %0.2f" utilization["2" => "3", max_lole_ts][1] + +surplus["1",max_lole_ts][1] +surplus["2",max_lole_ts][1] +surplus["3",max_lole_ts][1] # Transmission expansion is clearly one solution to this adequacy issue. Is local # storage another alternative? One can check on the average state-of-charge of # the existing battery in that region, both in the hour before and during the # problematic period: - -storage["313_STORAGE_1", shortfall_period-Hour(1)] -storage["313_STORAGE_1", shortfall_period] +storage["313_STORAGE_1", max_lole_ts-Hour(1)][1] +storage["313_STORAGE_1", max_lole_ts][1] # It may be that the battery is on average fully charged going in to the event, # and perhaps retains some energy during the event, even as load is being diff --git a/PRASCore.jl/src/Systems/SystemModel.jl b/PRASCore.jl/src/Systems/SystemModel.jl index 25b51ccf..c9091e9e 100644 --- a/PRASCore.jl/src/Systems/SystemModel.jl +++ b/PRASCore.jl/src/Systems/SystemModel.jl @@ -183,6 +183,9 @@ unitsymbol(::SystemModel{N,L,T,P,E}) where { isnonnegative(x::Real) = x >= 0 isfractional(x::Real) = 0 <= x <= 1 +get_params(::SystemModel{N,L,T,P,E}) where {N,L,T,P,E} = + (N,L,T,P,E) + function consistent_idxs(idxss::Vector{UnitRange{Int}}, nitems::Int, ngroups::Int) length(idxss) == ngroups || return false diff --git a/PRASCore.jl/src/Systems/Systems.jl b/PRASCore.jl/src/Systems/Systems.jl index dc4989b4..6b4cd8b1 100644 --- a/PRASCore.jl/src/Systems/Systems.jl +++ b/PRASCore.jl/src/Systems/Systems.jl @@ -21,7 +21,7 @@ export unitsymbol, unitsymbol_long, conversionfactor, powertoenergy, energytopower, # Main data structure - SystemModel, + SystemModel, get_params, # Convenience re-exports ZonedDateTime, @tz_str diff --git a/PRASCore.jl/src/Systems/assets.jl b/PRASCore.jl/src/Systems/assets.jl index f4a11d6e..04ee3469 100644 --- a/PRASCore.jl/src/Systems/assets.jl +++ b/PRASCore.jl/src/Systems/assets.jl @@ -138,7 +138,7 @@ end """ Storages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} -A struct representing storage-only devices within a power system. +A struct representing storage devices in the system. # Type Parameters - `N`: Number of timesteps in the system model @@ -295,7 +295,7 @@ end """ GeneratorStorages{N,L,T<:Period,P<:PowerUnit,E<:EnergyUnit} -A struct representing generator-storage combination resources within a power system. +A struct representing generator-storage hybrid devices within a power system. # Type Parameters - `N`: Number of timesteps in the system model diff --git a/docs/make.jl b/docs/make.jl index e7b41616..c6e163fe 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -35,19 +35,19 @@ makedocs( modules = [PRASCore, PRASFiles, PRASCapacityCredits], pages = [ "Home" => "index.md", - "Resource Adequacy" => "resource-adequacy.md", + "Resource Adequacy" => "resourceadequacy.md", "Getting Started" => [ "Installation" => "installation.md", - "Quick start" => "getting-started.md", + "Quick start" => "quickstart.md", ], "PRAS Components " => [ - "System Model Specification" => "PRAS/systemspec.md", + "System Model Specification" => "PRAS/sysmodelspec.md", "Simulation Specifications" => "PRAS/simulations.md", "Result Specifications" => "PRAS/results.md", - "Capacity Credit Calculation" => "PRAS/capacity-credit.md", + "Capacity Credit Calculation" => "PRAS/capacitycredit.md", ], ".pras File Format" => "SystemModel_HDF5_spec.md", - "Examples" => examples_nav, + "Tutorials" => examples_nav, "Extending PRAS" => "extending.md", # "Contributing" => "contributing.md", "Changelog" => "changelog.md", diff --git a/docs/src/PRAS/capacity-credit.md b/docs/src/PRAS/capacitycredit.md similarity index 100% rename from docs/src/PRAS/capacity-credit.md rename to docs/src/PRAS/capacitycredit.md diff --git a/docs/src/PRAS/systemspec.md b/docs/src/PRAS/sysmodelspec.md similarity index 98% rename from docs/src/PRAS/systemspec.md rename to docs/src/PRAS/sysmodelspec.md index 32c64871..787d1ef4 100644 --- a/docs/src/PRAS/systemspec.md +++ b/docs/src/PRAS/sysmodelspec.md @@ -74,6 +74,9 @@ and their associated resource collections (regions or interfaces). *Table: PRAS resource parameters. Parameters in italic are fixed values; all others are provided as a time series.* +The [system model exploration](@ref explore_systemmodel) section in the PRAS walkthrough +example shows different ways to retrieve and visualize information from these assets. + ## Regions PRAS does not represent the power system's individual electrical buses. Intead, PRAS **regions** are used to represent a collection of electrical buses diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index dd5bb28e..ee0d3eb5 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -1,4 +1,4 @@ -# `SystemModel` HDF5 representation specification +# [`SystemModel` HDF5 representation specification](@id prasfile) This document specifies a representation of the PRAS `SystemModel` data structure in terms of objects like diff --git a/docs/src/changelog.md b/docs/src/changelog.md index 207094bb..acc22738 100644 --- a/docs/src/changelog.md +++ b/docs/src/changelog.md @@ -7,8 +7,7 @@ ## [0.7], 2024 - December -- PRAS codebase refactored as a monorepo, and subpackages `PRAS.jl`, `PRASCore.jl`, -`PRASFiles.jl`, and `PRASCapacityCredits.jl` available through the Julia General registries. +- PRAS codebase refactored as a monorepo, and subpackages `PRAS.jl`, `PRASCore.jl`, `PRASFiles.jl`, and `PRASCapacityCredits.jl` available through the Julia General registries. - Removed `Convolution` and `NonSequentialMonteCarlo` simulation capabilities to simplify codebase. - Bump Julia version required to `v1.10` - Add results serialization capability for `ShortfallResults` diff --git a/docs/src/index.md b/docs/src/index.md index 9d74ab96..87242090 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -10,7 +10,7 @@ To get started on using PRAS, see the [installation](@ref Installation) and [qui ## Basic usage -PRAS maps a provided representation of a power system to a probabilistic description of operational outcomes of interest, using a particular choice of operations simulation. The input system representation is called a "system model", the choice of operational representation is referred to as a "simulation specification", and different types of operating outcomes of interest are described by "result specifications". +PRAS maps a provided representation of a power system to a probabilistic description of operational outcomes of interest, using a particular choice of operations simulation. The input system representation is called a "[system model](@ref system_specification)", the choice of operational representation is referred to as a "[simulation specification](@ref simulations)", and different types of operating outcomes of interest are described by "[result specifications](@ref results)". ```@raw html
@@ -31,5 +31,3 @@ shortfallresult, flowresult = eue, lole = EUE(shortfallresult), LOLE(shortfallresult) ``` - -More details on running PRAS via Julia code are available in this documentaion. The [System Model Specification](@ref system_specification) page details the information contained in a system model input, the [Simulations Specifications](@ref simulations) page explains the built-in simulation specification options in PRAS and the various modelling assumptions associated with each, and the [Results Specification](@ref results) page will outline PRAS' available result specifications. The [Capacity Credit](@ref capacitycredit) page covers how PRAS can calculate the capacity credit of specific resources based on the results of resource adequacy assessments, and the [Extending](@ref extending) page provides information on extending PRAS beyond its built-in capabilities. diff --git a/docs/src/getting-started.md b/docs/src/quickstart.md similarity index 98% rename from docs/src/getting-started.md rename to docs/src/quickstart.md index 5b07b30d..2dfc15a7 100644 --- a/docs/src/getting-started.md +++ b/docs/src/quickstart.md @@ -1,6 +1,6 @@ # [Getting Started with PRAS](@id quickstart) -Once you have PRAS [installed](@ref Installation), this page provides a brief overview to help you start running PRAS quickly. +Once you have PRAS [installed](@ref Installation), this page provides a brief overview to help you start running PRAS quickly. A more detailed example with analyses is available at [PRAS walkthrough](@ref pras_walkthrough). ## Parallel Processing diff --git a/docs/src/resource-adequacy.md b/docs/src/resourceadequacy.md similarity index 100% rename from docs/src/resource-adequacy.md rename to docs/src/resourceadequacy.md From 099f8d1687a92cc00f30afe448653434afe110ac Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 00:08:10 -0600 Subject: [PATCH 18/25] Add docs dataframes dependency --- docs/Project.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Project.toml b/docs/Project.toml index 521027c6..51068456 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -3,6 +3,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" +DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" [compat] Documenter = "1" From 6efc88289e9ae724658ae280535394df4bbe166a Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 00:51:16 -0600 Subject: [PATCH 19/25] Wrap up walk through example --- .github/workflows/docs.yml | 2 +- PRAS.jl/examples/pras_walkthrough.jl | 48 ++++++++++++++++------------ docs/make.jl | 2 +- 3 files changed, 30 insertions(+), 22 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 097db93d..cbcfbe7e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,4 +35,4 @@ jobs: - name: Build and deploy docs env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: julia --project=docs/ docs/make.jl deploy=true + run: julia --project=docs/ --threads auto docs/make.jl deploy=true diff --git a/PRAS.jl/examples/pras_walkthrough.jl b/PRAS.jl/examples/pras_walkthrough.jl index 6cdeddf4..37f24a66 100644 --- a/PRAS.jl/examples/pras_walkthrough.jl +++ b/PRAS.jl/examples/pras_walkthrough.jl @@ -94,7 +94,7 @@ println("System $(lole), $(eue)") # Given we use only 100 samples and the RTS-GMLC system is quite reliable, # we see a system which is reliable, with LOLE and EUE both near zero. # For the purposes of this example, let's increase the system load homogenously -# by 1000MW in every hour and region, and re-run the assessment. +# by 700MW in every hour and region, and re-run the assessment. sys.regions.load .+= 700.0 shortfall, surplus, utilization, storage = assess( @@ -122,17 +122,18 @@ plot(sys.timestamps, val.(lolps), xlabel="Time", ylabel="Hourly LOLE (event-hours/hour)", legend=false) # We see the shortfall is concentrated in a few hours and there are many -# hours with LOLE = 1, or which means that hour had a shortfall in every +# hours with LOLE = 1, which means that hour had a shortfall in every # Monte Carlo sample. -# We can find the regional EUE for the entire simulation period, +# We can find the regional NEUE for the entire simulation period, # and obtain it in as a DataFrame for easier viewing: -regional_eue = DataFrame([(Region=reg_name, EUE=val(EUE(shortfall, reg_name))) +regional_eue = DataFrame([(Region=reg_name, NEUE=val(NEUE(shortfall, reg_name))) for reg_name in sys.regions.names], - [:Region, :EUE]) + ) +# So, region "1" has the highest overall NEUE, and has a higher +# load normalized shortfall # We may be interested in the EUE in the hour with highest LOLE -# the unserved energy by region in that hour: max_lole_ts = sys.timestamps[findfirst(val.(lolps).==1)]; println("Hour with first LOLE of 1.0: ", max_lole_ts) @@ -142,26 +143,33 @@ unserved_by_region = EUE.(shortfall, sys.regions.names, max_lole_ts) # Region 2 has highest EUE in that hour, and we can look at the # utilization of interfaces into that region in that period: -@printf "Interface between regions 1 and 2 utilization: %0.2f \n" utilization["1" => "2", max_lole_ts][1] -@printf "Interface between regions 1 and 3 utilization: %0.2f" utilization["2" => "3", max_lole_ts][1] - -surplus["1",max_lole_ts][1] -surplus["2",max_lole_ts][1] -surplus["3",max_lole_ts][1] - -# Transmission expansion is clearly one solution to this adequacy issue. Is local -# storage another alternative? One can check on the average state-of-charge of -# the existing battery in that region, both in the hour before and during the -# problematic period: +utilization_str = join([@sprintf("Interface between regions 1 and 2 utilization: %0.2f", + utilization["1" => "2", max_lole_ts][1]), + @sprintf("Interface between regions 3 and 2 utilization: %0.2f", + utilization["3" => "2", max_lole_ts][1]), + @sprintf("Interface between regions 1 and 3 utilization: %0.2f", + utilization["1" => "3", max_lole_ts][1])], "\n"); +println(utilization_str) + +# We see that the interfaces are not fully utilized, meaning there is +# no excess generation in the system that could be wheeled into region "2" +# and we can confirm this by looking at the surplus generation in each region +println(@sprintf("%0.2f",surplus["1",max_lole_ts][1])) +println(@sprintf("%0.2f",surplus["2",max_lole_ts][1])) +println(@sprintf("%0.2f",surplus["3",max_lole_ts][1])) + +# Is local storage another alternative for region 3? One can check on the average +# state-of-charge of the existing battery in region "3", both in the +# hour before and during the problematic period: storage["313_STORAGE_1", max_lole_ts-Hour(1)][1] storage["313_STORAGE_1", max_lole_ts][1] -# It may be that the battery is on average fully charged going in to the event, +# It may be that the battery is on average charged going in to the event, # and perhaps retains some energy during the event, even as load is being # dropped. The device's ability to mitigate the shortfall must then be limited -# only by its discharge capacity, so given that the event doesn't last long, -# adding additional short-duration storage in this region would help. +# only by its discharge capacity, so increasing the regions storage +# capacity by adding more storage devices may help mitigate some shortfall. # Note that if the event was less consistent, this analysis could also have been # performed on the subset of samples in which the event was observed, using the diff --git a/docs/make.jl b/docs/make.jl index c6e163fe..b327a212 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,7 +2,7 @@ using Documenter using PRASCore using PRASFiles using PRASCapacityCredits -using Plots, Literate +using Literate @info "Building example problems..." From 6be39b9d4812cdee0273421f1413b0766219ca69 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 08:59:58 -0600 Subject: [PATCH 20/25] Make changes to runners, some docs outputs, add docs instructions --- .github/workflows/docs.yml | 1 - .github/workflows/docsCleanup.yml | 33 ++++++++++++++++++++++++++++ PRAS.jl/examples/pras_walkthrough.jl | 11 +++++----- docs/README.md | 12 ++++++++++ docs/make.jl | 14 +++--------- 5 files changed, 54 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/docsCleanup.yml create mode 100644 docs/README.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cbcfbe7e..e94c4723 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,7 +3,6 @@ name: Documentation on: push: branches: - - ssh/docgen - main tags: '*' pull_request: diff --git a/.github/workflows/docsCleanup.yml b/.github/workflows/docsCleanup.yml new file mode 100644 index 00000000..7a91c13b --- /dev/null +++ b/.github/workflows/docsCleanup.yml @@ -0,0 +1,33 @@ +name: Doc Preview Cleanup + +on: + pull_request: + types: [closed] + +# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time +concurrency: + group: doc-preview-cleanup + cancel-in-progress: false + +jobs: + doc-preview-cleanup: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout gh-pages branch + uses: actions/checkout@v4 + with: + ref: gh-pages + - name: Delete preview and history + push changes + run: | + if [ -d "${preview_dir}" ]; then + git config user.name "Documenter.jl" + git config user.email "documenter@juliadocs.github.io" + git rm -rf "${preview_dir}" + git commit -m "delete preview" + git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")" + git push --force origin gh-pages-new:gh-pages + fi + env: + preview_dir: previews/PR${{ github.event.number }} \ No newline at end of file diff --git a/PRAS.jl/examples/pras_walkthrough.jl b/PRAS.jl/examples/pras_walkthrough.jl index 37f24a66..359de2ce 100644 --- a/PRAS.jl/examples/pras_walkthrough.jl +++ b/PRAS.jl/examples/pras_walkthrough.jl @@ -154,16 +154,17 @@ println(utilization_str) # We see that the interfaces are not fully utilized, meaning there is # no excess generation in the system that could be wheeled into region "2" # and we can confirm this by looking at the surplus generation in each region -println(@sprintf("%0.2f",surplus["1",max_lole_ts][1])) -println(@sprintf("%0.2f",surplus["2",max_lole_ts][1])) -println(@sprintf("%0.2f",surplus["3",max_lole_ts][1])) +println("Surplus in") +println(@sprintf(" region 1: %0.2f",surplus["1",max_lole_ts][1])) +println(@sprintf(" region 2: %0.2f",surplus["2",max_lole_ts][1])) +println(@sprintf(" region 3: %0.2f",surplus["3",max_lole_ts][1])) # Is local storage another alternative for region 3? One can check on the average # state-of-charge of the existing battery in region "3", both in the # hour before and during the problematic period: -storage["313_STORAGE_1", max_lole_ts-Hour(1)][1] -storage["313_STORAGE_1", max_lole_ts][1] +println(@sprintf("Storage energy T-1: %0.2f",storage["313_STORAGE_1", max_lole_ts-Hour(1)][1])) +println(@sprintf("Storage energy T: %0.2f",storage["313_STORAGE_1", max_lole_ts][1])) # It may be that the battery is on average charged going in to the event, # and perhaps retains some energy during the event, even as load is being diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..47d61030 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,12 @@ +# Updating and pushing documentation + +These are some steps to follow when making changes to documentation. +1. Checkout a new branch from `main` (e.g. `git checkout -b docupdate`). +2. Instantiate the environment in the `docs` folder by running `] instantiate` in the Julia REPL. +3. Make changes to the documentation files in the `docs` folder and/or the example scripts in the `examples` folder. +4. You can iteratively make changes and build documentation to serve locally by running the `serve.jl` script in the `docs` folder by running + ```bash + julia --project=. serve.jl --threads auto + ``` +5. Once you push to origin (github.com/NREL/PRAS) and create a pull request, the documentation will be built and served at https://nrel.github.io/PRAS/PR{#}. Once the changes are merged to `main`, the documentation will be available at https://nrel.github.io/PRAS/dev. On tagging a PRAS version for release, the documentation will be available at https://nrel.github.io/PRAS/stable and https://nrel.github.io/PRAS/vX.Y.Z (where X.Y.Z is the version number). +6. More instructions on version tagging and release can be found in the [Documenter.jl](https://documenter.juliadocs.org/stable/man/hosting/#Documentation-Versions) instructions. \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl index b327a212..f1a61963 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -4,23 +4,16 @@ using PRASFiles using PRASCapacityCredits using Literate +# Building examples was inspired by COSMO.jl repo @info "Building example problems..." -# utility function from https://github.com/JuliaOpt/Convex.jl/blob/master/docs/make.jl -fix_math_md(content) = replace(content, r"\$\$(.*?)\$\$"s => s"```math\1```") -fix_suffix(filename) = replace(filename, ".jl" => ".md") -function postprocess(cont) - """ - The source files for all examples can be found in [/examples](https://github.com/NREL/PRAS/examples/). - """ * cont -end - example_path = joinpath(@__DIR__, "..","PRAS.jl","examples/") build_path = joinpath(@__DIR__, "src", "examples/") files = readdir(example_path) filter!(x -> endswith(x, ".jl"), files) for file in files - Literate.markdown(example_path * file, build_path; preprocess = fix_math_md, postprocess = postprocess, documenter = true, credit = true) + Literate.markdown(example_path * file, build_path; + documenter = true, credit = true) end examples_nav = fix_suffix.("./examples/" .* files) @@ -62,6 +55,5 @@ makedocs( deploydocs( repo = "github.com/NREL/PRAS.git", - devbranch = "ssh/docgen", push_preview = true, ) \ No newline at end of file From 6ebb0a95a5c0483c885b7b8310295b92629514f2 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 09:18:46 -0600 Subject: [PATCH 21/25] Add new docs badges, correct a docs bug --- .gitignore | 3 ++- README.md | 3 ++- docs/make.jl | 2 ++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 542f2276..c725c05e 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,5 @@ Manifest.toml PRASFiles.jl/test/PRAS_Results_Export/ docs/build/ -docs/site/ \ No newline at end of file +docs/site/ +docs/src/examples/ \ No newline at end of file diff --git a/README.md b/README.md index d50441bd..a4021a86 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ [![PRASCapacityCredits.jl Tests](https://github.com/NREL/PRAS/actions/workflows/PRASCapacityCredits.jl.yml/badge.svg?branch=main)](https://github.com/NREL/PRAS/actions/workflows/PRASCapacityCredits.jl.yml) [![codecov](https://codecov.io/gh/NREL/PRAS/branch/main/graph/badge.svg?token=WiP3quRaIA)](https://codecov.io/gh/NREL/PRAS) -[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://nrel.github.io/PRAS) +[![docsstable](https://img.shields.io/badge/docs-stable-blue.svg)](https://nrel.github.io/PRAS/stable) +[![docsdev](https://img.shields.io/badge/docs-dev-blue.svg)](https://nrel.github.io/PRAS/dev) [![DOI](https://img.shields.io/badge/DOI-10.11578/dc.20190814.1-blue.svg)](https://www.osti.gov/biblio/1557438) The Probabilistic Resource Adequacy Suite (PRAS) is a collection of tools for diff --git a/docs/make.jl b/docs/make.jl index f1a61963..801de9cd 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,6 +7,8 @@ using Literate # Building examples was inspired by COSMO.jl repo @info "Building example problems..." +fix_suffix(filename) = replace(filename, ".jl" => ".md") + example_path = joinpath(@__DIR__, "..","PRAS.jl","examples/") build_path = joinpath(@__DIR__, "src", "examples/") files = readdir(example_path) From e9a5f9378782e3d86507d32ae449330990de80aa Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 09:53:55 -0600 Subject: [PATCH 22/25] Small docs/README change and remove old docs yaml --- docs/README.md | 2 +- docs/_config.yaml | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) delete mode 100644 docs/_config.yaml diff --git a/docs/README.md b/docs/README.md index 47d61030..84be7859 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,5 +8,5 @@ These are some steps to follow when making changes to documentation. ```bash julia --project=. serve.jl --threads auto ``` -5. Once you push to origin (github.com/NREL/PRAS) and create a pull request, the documentation will be built and served at https://nrel.github.io/PRAS/PR{#}. Once the changes are merged to `main`, the documentation will be available at https://nrel.github.io/PRAS/dev. On tagging a PRAS version for release, the documentation will be available at https://nrel.github.io/PRAS/stable and https://nrel.github.io/PRAS/vX.Y.Z (where X.Y.Z is the version number). +5. Once you push to origin (github.com/NREL/PRAS) and create a pull request, the documentation will be built and served at https://nrel.github.io/PRAS/previews/PR{#}. Once the changes are merged to `main`, the documentation will be available at https://nrel.github.io/PRAS/dev. On tagging a PRAS version for release, the documentation will be available at https://nrel.github.io/PRAS/stable and https://nrel.github.io/PRAS/vX.Y.Z (where X.Y.Z is the version number). 6. More instructions on version tagging and release can be found in the [Documenter.jl](https://documenter.juliadocs.org/stable/man/hosting/#Documentation-Versions) instructions. \ No newline at end of file diff --git a/docs/_config.yaml b/docs/_config.yaml deleted file mode 100644 index 3c0d055c..00000000 --- a/docs/_config.yaml +++ /dev/null @@ -1,4 +0,0 @@ -theme: jekyll-theme-cayman -title: PRAS -description: The Probabilistic Resource Adequacy Suite -show_downloads: false From 6e5e51e78d437843326e7837a53897ed7d9abc95 Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 10:22:30 -0600 Subject: [PATCH 23/25] Typo corrections --- docs/src/quickstart.md | 4 ++-- docs/src/resourceadequacy.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/quickstart.md b/docs/src/quickstart.md index 2dfc15a7..5ef5dea2 100644 --- a/docs/src/quickstart.md +++ b/docs/src/quickstart.md @@ -12,7 +12,7 @@ export JULIA_NUM_THREADS=36 ## Power System Data -The recommended way to store and retreive PRAS system data is in an HDF5 file that conforms to the [PRAS system data format](./SystemModel_HDF5_spec.md). Once your system is represented in that format you can load it into PRAS with: +The recommended way to store and retrieve PRAS system data is in an HDF5 file that conforms to the [PRAS system data format](./SystemModel_HDF5_spec.md). Once your system is represented in that format you can load it into PRAS with: ```julia using PRAS @@ -86,7 +86,7 @@ period_eue_a = EUE(shortfalls, "Region A", ZonedDateTime(2024, 4, 27, 13, tz"EST ## Capacity Credit Calculations -Capacity credit calcuations build on probabilistic resource adequacy assessment to provided capacity-based quantifications of the marginal benefit to system resource adequacy associated with a specific resource or collection of resources. Two capacity credit metrics (EFC and ELCC) are currently supported. +Capacity credit calculations build on probabilistic resource adequacy assessment to provide capacity-based quantifications of the marginal benefit to system resource adequacy associated with a specific resource or collection of resources. Two capacity credit metrics (EFC and ELCC) are currently supported. ### Equivalent Firm Capacity (EFC) diff --git a/docs/src/resourceadequacy.md b/docs/src/resourceadequacy.md index 2a1f22a0..e2546579 100644 --- a/docs/src/resourceadequacy.md +++ b/docs/src/resourceadequacy.md @@ -3,7 +3,7 @@ An electrical power system is considered resource adequate if it has procured sufficient resources (including supply, transmission, and responsive demand) such that it runs a sufficiently low risk of invoking emergency measures (such -as involuntary load shedding) due to resource unavailablity or deliverability +as involuntary load shedding) due to resource unavailability or deliverability constraints. Resource adequacy is a necessary (but not sufficient) condition for overall power system reliability, which considers a broader set of system constraints including From 845b1497a1ecb8f0716be90f42d2d141113cad1d Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Thu, 25 Sep 2025 12:20:57 -0600 Subject: [PATCH 24/25] Use SVG images --- docs/src/PRAS/simulations.md | 2 +- docs/src/PRAS/sysmodelspec.md | 4 +- docs/src/images/genstorexamples.pdf | Bin 35257 -> 0 bytes docs/src/images/genstorexamples.svg | 110 ++++++++++++++ docs/src/images/inputoutput.pdf | Bin 54588 -> 0 bytes docs/src/images/inputoutput.svg | 203 +++++++++++++++++++++++++ docs/src/images/networkflow.pdf | Bin 41059 -> 0 bytes docs/src/images/networkflow.svg | 93 +++++++++++ docs/src/images/resourceparameters.pdf | Bin 56499 -> 0 bytes docs/src/images/resourceparameters.svg | 68 +++++++++ docs/src/index.md | 2 +- 11 files changed, 478 insertions(+), 4 deletions(-) delete mode 100644 docs/src/images/genstorexamples.pdf create mode 100644 docs/src/images/genstorexamples.svg delete mode 100644 docs/src/images/inputoutput.pdf create mode 100644 docs/src/images/inputoutput.svg delete mode 100644 docs/src/images/networkflow.pdf create mode 100644 docs/src/images/networkflow.svg delete mode 100644 docs/src/images/resourceparameters.pdf create mode 100644 docs/src/images/resourceparameters.svg diff --git a/docs/src/PRAS/simulations.md b/docs/src/PRAS/simulations.md index a6bdd7f1..e4acc070 100644 --- a/docs/src/PRAS/simulations.md +++ b/docs/src/PRAS/simulations.md @@ -31,7 +31,7 @@ Each set of sampled parameters is used to formulate the "pipe-and-bubble" networ ```@raw html
-Example three-region network flow problem to be solved +<img src= diff --git a/docs/src/PRAS/sysmodelspec.md b/docs/src/PRAS/sysmodelspec.md index 787d1ef4..f92d1a8f 100644 --- a/docs/src/PRAS/sysmodelspec.md +++ b/docs/src/PRAS/sysmodelspec.md @@ -113,7 +113,7 @@ time series, and so may be different during different time periods. ```@raw html
-Relations between power and energy parameters for generator, storage, and generator-storage resources. +Relations between power and energy parameters for generator, storage, and generator-storage resources.
Relations between power and energy parameters for generator, storage, and generator-storage resources
``` @@ -185,7 +185,7 @@ its state of charge during outages (subject to carryover losses). ```@raw html
-Example applications of the generator-storage resource type +Example applications of the generator-storage resource type
Example applications of the generator-storage resource type
``` diff --git a/docs/src/images/genstorexamples.pdf b/docs/src/images/genstorexamples.pdf deleted file mode 100644 index 522d95d82d2fe13932f06133ee697a308a1c608f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 35257 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
  • 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ⅆ7lIB!A7q57_4Z$yO7UlP$E&mcIRFF3;pk1& z6PJUN#@G`JnnDgmanRM|Roa{WwdyyZd#^qN zTz}ON9p}a3AarVm{+quU|Jd&NC94o_EQj$w!R#zuXw7re{NK&LC}0rH2%~imRZ{8i zNL)5``@P*<^KT;0bt-jyb@J=!dO{k#)njH|ReIC9(L3n&@!cz* zVxZ1U#UJ0vOC;qI)E_dxFBRLuWvITZQ|tN9&R*$Kd#5iB@DW>^;;u{oxIIN(ha=L> zH$x!aPS5G=O*Nt8uPp9n?IK-Fbf0xK%?8EQ*sQMudj>Wpdn3$2h>tN{z?01!xLnP& zTFY&hI4l~0hYRLPjeJknJALg(gR$v?ayzW3V|SL=Fa$_EX^2vI>1iYN_1}$Rq$*T{ zT8O=_#llQeg^Fs%?NU};Mf!_z$?hAJf;o8Jh1X3i`N8pwuVB}Flyo9jC0ecd?*Rhu zs|@nTCGqXdIK#fAT$swGLBFvE6aW+x^i6W4I#J1uS)3xA{NrW=3RF4G>$TE?G? ze`?~Z(CDvS5Q2!cP3`at@>WP3ntAwi+hpv*3uT9&>ox^q_=$cIKv>4S^f5b2-EDQ+fL=Y$&nJL4@GRv@;$1Qwc31-fv3#I$L?hl zJbVvt%hg@arEdFu=b~>L_Rg}5+}E`Dw4|q@;{2I?a~iwWT`J3zjxESum@W3?`9|&H zr1g677dPK9W&gD2rNFhfthSR1f$=Krz_{}E;TCsY?th^No}YTf$iJ)Q%G2(yAITe|^9BZP`8CzdGfaqs|6a zxQfg=b9FZ75BH3Bhok=1zUSf#`>}?DMaN)458GnPNAu50bnX+5`Mjd6x={a|tNFHz z9uh)5K}LErbj;30g!`_(bh0MDI;?u})Q4A<*Y9PD2EyHZWwF}f;@3V!9Xj>eQ+xib zXFpdix3QlUy5TsFeRla!d32XaeDMrN@B5JB9eqY#!_R1CCQ!B`Jy zpQ)vhnW?d^k)9dMv0x`E_+*x)Du7(2?~$LInpBipuBnh+kXVvYoSLXm1~tJ<&qU8q z6Lk4>YF-NHCUR4xzzC@q}bQvlvs?Uq?oT%uqKzr9+)+`>o!0zi^E zB|zuuyX64G#3eO3KP46ETI-5iOGBdbFB^!|onLQ}Z{V11ojFO&*JJOROsL z^5-Q*Z8qu4Dc?|k-qQ2(BHm8+DJ~n&KmEM3=D1*i$3puCMwh)3EbSJO4FU!ZGdTh$ z6di~cX`Aps|ETG#uP*u)w!Ak!?F>5btY|Hhnc33trR5i#&#Z2U)l4rl3+DTqebDD= zRNoo>9gj6UKFl%jk!LE|{-XUu%GZy{yf)j_?x&tQbX)8HzL4#*7vFx&n=$W!WteAv zK=Y%r)xMS!;||_F**>A&@O^Mg;hD#L{`U(0vAs=G`#=5UrBkbdEH|vwkx4U&pLe%x z`R+v#CpRsLm?r&};lA3k?;m_4+ufb7xNfKrP%FH`x!Y4(=T2}>!OHm}7iPYhd~?;* zQ2Y1(4>nG!dpxCOxvkr!x1~otXa6sFZa(Glq19Q7Pkk@Q%lY>`hqb>#C8(#NyrO>o zsf8Yg&&-;m;R?^@(@bYAN8qI_j1!3{_Ao@V#yz4a4}HgqbE&1wnp zcz$eYqTxf&*VU99)`Mg6|X z&mJEyUCsOYvWN5PIuY5m$x@p;RQ5P#8(zBheBs-R;yaJ}^`(5BvUwa@B5$GNI9J7{-L4$J$(lof02H22=C@Ng9}c%`Cg9Vn5U z&%Lv(U9bO@H?x(e(Df=688#mS{@#Njd8HqFuBZSVl)5XRBJ!=i@}w(2_dJr$6uYN2 zKewUQuuQw#t>UuF^~Vx#TBo<3YkMlSvp0Iqski1YzW-lxZekbX?z`z?-Hx+=zrB8y ze`;W3Lu?MKfZ#fYsV0#(ohp4MTnvysRlg@%Hg=u$s+a?IuVrpV3V&~X8j&<1?e3Su zvg1gh3>S$SW<)?B?QX> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hydro Reservoir + + + + + + + + + +UpstreamInflow +Turbine +Pump + + + + +Battery + + + + + + + + + +PVPanel +[Bidirectional]Inverter + + + + + +Heat Reservoir + + + + + + + +CSPHeat +Turbine + + + + + + + +Fuel Stockpile + + + + + + + +FuelDelivery +Combustion + + + + + + + diff --git a/docs/src/images/inputoutput.pdf b/docs/src/images/inputoutput.pdf deleted file mode 100644 index ef7702319c6795db0ec16fac6422bc51098b82ce..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 54588 zcmafZQ*@?5*JW(md1H2L+qP}nwrxA=u z7`m8>m>S!gn8NV!!8p4(nHt){cx=!dF{v;B2?>MiDl3EQ3M+>m>CpMk>Ij3U`_u~1 z0U20BD8QK7nf#CczutdhG5$X>RXiO`0rVR3MpmZAE->`Uu0}5Z9TBs4vi%qSAO6>a z5r$qtMO1_CA0JaWLt9e-B^|w`t)aQ8GrgsqgR6_ZtII#6b1*TZ`X5h)e?R41ZH@l1 z|38x@?ab^&ER9_N9RCO?!O#l{*?R!A8U7i}oNNF_1`b^qdT}RvR|f#=|8`I^b+&hP zGB$Mv{6`*94;OJ|mw!6^*D_@I??+hhKg$~%{=sU%kD4_{TKg-hK)rPsYtpu1|zlS^EBNgAZ#D@9$qMkA%lv{J0w|_)A!jV_X7s zdOmt@4~3)g8`dmS&Ve>n!9I4de`cRuQwdL1T|V%RBhnTQ!`=?71$AHGD|zyt5?-v@ ze7`;T&I`?L3u;fv)W00#EbpP-JJRh|;U8*!wjOR=d37&+++i#8rG4A$xN+1vpG;>L zH<>^Qh3xbHvm*3A;ptmDE%;(l`qA=bqWGj7mUhP@Zh1PN*z1o*R7 zn>(xpj92k{`Fb(QSBHkj^uwaayu&Hy&Nq}3@c{^4W5g3);CrZ?gYYuI7rOknS9|vN zcS1k7MFlKk<6x7tbzM@$|*#e6Mai^M1y_ zcl2>I+PCmcbf8A^@nRcEXTOdtmJ!%4?syq~n9=(&{^Ix3VyEwl#OL!kR#zkjm zjX1yGCc-W>X9~zQzkD=mr_670$_jQp#upvjKgtz-HpYt z2@CQ+7sVV!;xEno;Yad*wqri}_8GmOuHIr^1UIMb4iY`Ryzfv`*tBoN#yo!4VX(8@ z_ow}zZ=dM_PapYpl(sLmMrisvFA3ot@v{%`ukT;Zu`_;MVzYIlYXp}&pYLq1KRNLl zn)tBJ(qrYoFCKzs!qj(f5%&pzU7Rk!nnP+2=2UUzsx_yi`}HwfexSF$pBTD)RZUP> zNChW+ybmQ-8B(mE9)+J=txj5oiimjAP-=?9#W}lKLv{Aiz=5q%kvK7YM4Gr#uujf$ zbDkbqcX}gEo~eTzUp$ZR?qA(UzlSpzM_-4`JL}nI^}Uj#b(%-)&i4*JN&>E>ShIL* zw1cl+-eUOH&o?jD1bT?4;hKGdrE2yijNR8qtXaH6BSaxQZ$(+!msLpKw0X*#3q$^s zqHLmiK8$TX3)e4I4lSuy)h&v07>{owPJhEGlpDlD2HKN(Tx-8HZn45t^FIpMY7 z586VSv`m&zkKvs`B_3(Z4|Bgrr84Gcl@L4Z?z*Gkofu~q9eV4G)?IPvE=pMb5;+6> z^3o6tp|}qU3$*P1-pN{_Ux(FK3G$)3=)|4?2*ON>y&Xbz^@|HJclaSs+CwpXxF9nZ z?xm%%fU#z{Fwg1_gK0mpy1G3N^27KFRA348ZOr@f{723Wop`Qngh@CldET0j3Nohl z23$2$5b5qMD%uE`;uk&U59}WdjQ0Ik(+s640 zik^qM1{kJQQl^hIE34{6yAK9<=6NOMBzw`&vhMU&G!P-F6*tgmd$M*krhm0qR9HZ1 z{{Z>IUnF6kHz*1>p12Ik68;*ytr2>3n@8zxs#UM&pXPUX6GqVX7u0pHbn^8rtxTlz z*Sa3jr;WoTR2zPH5Ki_$FL^tex4ZpJk|iX0B-ga0_e4&)rET~tgaP&|7$%GL^)XCj zts1nhU2uuMoiFwe4_2g=Wa|JW^kD`qqNeX)fLEf^gxjEQN62`P5==aHofeX>-ZeO0 zVLwo^l}&vgbt=m^10zQF(JH*c2BZCvri&}NvQ)5J1H;MVxpp@K6XUP%>7i8tP@Z~T znoI4Z7~W6g9igi&l@!YpUic-v6SxJ-#hNqkkE(ssqZ&C#eX$+kofJu(j9|icb-Rs_ zo^Ple+hbmqsrp}7SUrh}FA7h1mPfp#8ots)Z^0l)@wb`i{K|3u32;zhO{+)HirhcO2J!An!9=-VK-O9S@~(ZGTQZaG4yY`MKSf4?s8|ykhOd zn>4JZ_J33#q{+JfqUw$FlKOLh{P{Bojo3&$@DZWFg?;VEcDdsh{b)9L?e{%KKNGgC z{dHCsw*A$chq7%QgQm1L8f?EIt^(1!&OrI|0pz)O2$f7K!EEF6Am3!sJ>|)3;=ToV z<&_8_?j|TQ)LXxGvGDK(4~Epdb8<46a{~Tw4YbkGvyEYYgUS|usVY7Dw%*3z^WeI& zmE(a$VhBA{?w&Et*oDQxNjpuV%$@&y_6XSbV&=mr zDe@=C97z~1b*Iq^rOc(Qw!wL;yI@QPV2(K`+%Zt5L^9y+uvtK)5BF3%DNqEI#BP;& z?_jAyVIuJebUrkU_JfdM#&HxV2QLjMrs!hlAeCU?G;6ZNICs@a{|zCE;Iv}#q9SJ~ z?;^6f0qobPXvhgly$z?|xrO>2Z1x*QH+(a5vHupNlT@geX!QG#eb;G`p3g1HxVuZe z)YAX#qC^q)-rJPQdKBFFK;jp_b;SP&%dXW4%3QPnk8WT$@8m#z6f+7DO`@47 z{csh=x&m+)+X%yH6D8VvI9Vv%9}ie{)iAshPY%p>??mVNb@JCSRG-B64lgu&aR!a! z!r{bRP3y>>I(12|XuHQ}6R|PiP}~QM>u|XGXsmuE(}8`NB%tz-mdkJcsQNG-qwgl{ z6~N}YxSA=(z`L8VjeR@+VXoKa5~(~wAyFI`cM#_qqBz3y_cP|Tvao40AU*Ag@#MlY z2spzM28MtQPX&gkegw3Fh|teXUgDlQQ%%78iozyriepF&=`C?gTGc;uMaCjl7LhlEKwKVtW;y z2@#Ob$4M#E)|)~7TJ6&qxRpRIPqk|UVDGX4{7~8g*e~blc5MojzW)UF@RN18lQ68I ziB*>_9(UeBnK>A-kyAEk$tZp%o$Qgg)k93=`VcUk5=l$jm!wUJSkGe)^Z0y49a9h~ z2~IMW+v`ZD%D~_wEtNRqQd5qfu#P}j1Z%LCDmC*Ad~12Mq2-H6wdc&hqw+{pe$F8Y za;{4C(!cvHK*Eosk&Z}8ZRKZ4?Fjcnz;S`?6)(%jl{B@4mofj*Mec@9$_>4Zl}!9~ zWT?(nPI4L#(IKdQ%mY~Ro?oJ7A8kHqBgWe+(03t_mf(6L8hu(=4<-5RsLqp{dP_~i z&ZU*9BGxpA^nB1hX=k&4s=8;uMi#jR%1EmRHeL_u;Ml)RECSN{e3Tf zw;$8&Fk@d%80K;CY!pXls3FczTg|7Ap#F2J1+&&SxP|E50`c|~ZV+Z(S-ejyWnjRi zh3aF{H(|pLmRf)!J{J=Lu5mo_0p*(q~`p5K0B?QJnDW0DVlGs6W!%JwtKW9e{c_ETAJ3_=hgYm2w=l7 zv53^j&k|P{n2#ayX0!%-E#Ag-LK@~PjG4#jyY^%$uy#Ns?JF`bOtQvhama3F8mSS9 z?2i-Sa)tyci(DnEl!dph1ZMCTt0^2#83`yetP1CSuYGjb11G9>)Oi!z>a9{t&i|Dy@Lqe6!{ zZFvJl%8qcAHExU_oOz@Z4ijOp>#TtiMC|H$rkHoQ6?(GfjG(V0^Y{G?+FCq}eQ+iN9{1zHMDmLr@rxy7#snCQl&|j@y^m5KJf4`eh^t zU!((fqSRI^QX?)L9znbv5-DTtdIsb>`HCqOkM`cYJ~FOv=&9N z35Aq}v}U8(=ZM1;E&r_hxe3Fxp4Eq*-B}ed_%BwafBDuOJzy=N%khDN%)32f)1o2( z!o|C{Egh(`GuTPF9~ax-j>ozqrERAZf%?Wk30NswK@EkK)YiVWH-D z%Oxa+7}@ncY>;vYN(U9>MfXYmDaOhiK5$!o2k*P_SCbv z@I#8-GO(mQ+^6=363#fV}o z3koFjZl7XvY;jhfBI{uV2EkHHu@(cwzbWGp(s;{3E4Cwwwn|7zHh?&*d1kh_2?T?K z3N4k}Ze zO9+r%z^+)V9h=FUL>EN5FClSZIj9hj4x}V=U5FrxgCPY|5=A&ULRtT}EZ#C3Q(jtq zQ^ODVS zh}(fu4V#bm5uONM|5J)0``bD8cd1$AG=qP-KJ-!hepGA*T(YqntfE?hdZ<) z`+|xt%0K%|aKenMYf-~n{A)wMdvQIZgtK7BqD+6X6hfFh)d12sp|$;x>JlWEOmCPh?FQ1S<#xp7cwq83~lH4)*&h_$`Cm1P2a0h$K-?9 zklqf}XbTv^YQ{e2a%FB}_-<_8O?>`hmw`5k(6AdD7Eo!8pJs(>Q-;QC5?3Kp+-0@d z0BjNx3(NhZBx+rEQ(9Qe5LdVRWiR>UDob6yC~9$clnvOI7YKs zm@GFa`^>68IRjt3_&5x)$V307wN#&LVcZja%BMBnJU<{LKz?+J8wu;?A1>@ghu~@6 zus;1~#H)W9J?TZeabh(mKdf>eyjU3k5Imr;XwWBUl1A&!G!u{{xyLmx^X|OBi%Ou! zRhoX&3O~(*AXAVk8$OfB^pAwpfF$_7KaW505`umUaJ7*X0JCVDxWLAqO`TB#4bfI? zDPE^~CptT3Z5b7Y64+l{E%#-Niwm!*f1uLCYmk}ijD(2}j<@$fh({1%OSFxx(&#`~ zBcH!#IC~(+lE^J`VUdodp^f%VtsXD#4`Fx41*a|c1z^v?!C?(({1Wle8p^aek!Hio zSNg)u{)$Qhn)Uzr;MaFIKX5Bh_D`Y z7p4Syor&;{n?Li&FHCVb3?T+!S9d;o7k7?IQ~L7n`iFNHXQ2gOxXw?flPq(<-B?A0 z0Z)3!e=xcB&F6yTc%qNqs3(w!kUmViI4~^`fhH%a;M){%;B)~|YZwpJM+mP%0R#l| z8}=nU&BD`5H5_AQ!L6Afu#{^gn_dAxILJ&4AMexK+W5#hr@00p2+E`#sKq>J@z+zs z;3T|wbM*UV5E#9^HWEs%Lbfi6GoC!>$avj2%fca+@u@8c_Rl-UgqjDlnNX(7G%?A% z?2_S2=ja%6KK6r0K$}_l(y5+ABw^!`W6F<5iLc)wbdO>$ey%z;uU6kolni+J-Uc?r z0e@H7q{?vLZI#io%d!bW_1Q*7K98j7I(NPI>0HkTa2);VYq0#Mhc()IReP5tj+|NL zww8|>ZJ=&_Vs7td1^v^;0H+#U{5dS+g%k!<-O1ibV26kU{>^BkqLyc_TyzpD`lYaAp%!~qZ8J$Rpwiu++OvVTO~i^AOxp`B!^$N(AsCc2vfCsCWWxl zTV;0|A;HI?h@AJFsRF2i#7N4rTzt4Ei9$3yDI?wxzypJrML!)43?iy+uu3uQhn?aO zoS#OgzQ?&Gejs!WjRH1t;LJ3E{FJqTt+#OS1EX36MWG8| zu}1~Y5=M(>?~1s4fpU`?R@RRNrOCu12>Vd*=VE~o7VLsY6C&$E`%#UV`QS*mVA?p{ z|Hcp%2QeBXDY)l2&uhQ?=4a@S!o4nD;eYw}fM5!thSi$RVY+kjQ9G;MutemEhvHv4 z#3X2`pr3;bKsrk6seZzcTqt;6}Bg6Fl5I8G*6=EtN^8wGq|^M9dk} z1|zw*uyE!<;wf8~lQ0K6@rp*Awq@=OM<=Fup1Sj59F+~Q^7!@O3^Zo8239emGpBPn zn^#PO`r^kCDZL2|5u7mu;HlE-9$ z>S!Q^0$*t!6Nw1`q*mZwJ>lM`vaXLvA}L&9q*`hUuC0Q$=B~Te>az~ru`KoWg^j;4 zX_7;QGF2!s@4OVNERh#ukGXCLLuAF*%$UdsDJ>O)xfQAGrzBl4{DSGiygNA*LWi=Z zcTi#t9$#*;rfHdxXz)V=qNwPSQZY-{sF_qXbitKk%Z93Vo-i(dt7;aav9YGx)uj6v z>U4uO#kZ-+z-8{=Pv;VtRXk`mQ?P+x&+95J=09ijgD#1wL%n3 z#BCAl>bq@BJ9m5lX$Xoe+lmddzY(^b!d_4%;_{x3%y2P!F`oD}zKU^829-m!f=Nc0 z%-;yO@^Zv|q4j=XOM8`$3Rn83TP2hvbj9eUv-9!?>t+*?Z)5~^66Bxa*9>(ODv(*9 zT0CP9JbpGkt9Ug<(%4j9*)@T)IaSKx7E>P~ousKoDdfS*sr{ws}G=z6DCFyBm z7;vH@NNjZEyb*jdlT0ZndOq<|3%6jxkLG5qWX-hfpaZH&-RrH?D3j%|xXZyS84Ehc zK-Mo*?GW;tf@Ao&q-+!$*1>5Rj^Ev@;Be6=wQanBnCPxw*`QON{KJ(tY!U1G=K;OG zf*Jl`SD%KRHPpb_laQ;74vg4iX4V1=4kyG08c1uFQgAQ-r2Fcn)IdQm_kIJ!zT4!+ z4STf0B4~By0@l>i!G6s>+bCj`g)Nd$zcv&^G5GY~#StB=g8Et!_Rv(dla1&s&E;7( zbf!-EDJisY&aGL)C?IPZe+PsA&?Gx&&oZsM zMY|fY^t$<3&9S*5EqJ5Bz{7sQu4uui$@hbz{=!Z$a5U+JkT4rTcsLl8b=6Dzw-oR z+F{nv+23@DFW>8k$<{k`Y%wO`FzI}CZC^T(K8}qThJBr!FC)91z%#&0PQ_LDMGgX* zmW}E3wd(!YmNmOW9Npc#D_nlC;OZ}#EL}ByAToPCQMfd8YM|!y_?V4feL8={&$(vfr!3I)$V-3*h+@IQWl&2PYDgr@$PF8PF4%l*1s%9@Hh7J zR?|-UOEBM`LjNA3CaL}c*J}a93!8@bFxx2CO;Ee;JxS`BD1P(nj^SJ|qoAI@2HR z#D!)Xm@p9dwH1Ug2sAtT$b7+cd@gtnO?SD&S0_oTQK`T}TF#d30iq)Zlm*Z21;_@a zpQHvQe)i+r1S=@yV*<$!880Agn%G(FbtC~v%Ywct2n45sqA$HpK_ zNSR&uhHij_+TQSWU`BdO;-6hZR|2coFEWDyqcW`NlZ)K$XWH_kY!&2bn6n)gYh0;%A(6W3T2su18wivp11W1`+vrqmu1oy^{2Cwn|;BW!CflJ zvQH4RlfcNk1&}@weqGEwu6en#W$RFuxw5GbmqRPKeG%GxMnnsLk;p>*r&;{mV!zyPyY%w6E)aa3ztzBjw9srip-}sK zhf9~;wuXX#ChUdznMX5yI5MqHfz4=NF(D&*1`{(o@PwwMfk_gL1qMBJQM&MGj#E(y z2FXGR+c~V3E)cb_5&LSH)aoABuJ6JOs zA-SDQ`B4<`)?H7==1e1dmybOH3w*s{!(yM;$%w1PPSBlDppHb)S ziF-Hb=LgFkf_Ev>pZ0xw1PbMZvf&prpf*Xqc$61b2HCrdiYkuB-GlJKfofbFo2JMG z=8&9*>jcUp9QEwg7iok9IjAPG3Wl?x>S)NiwFEXz^zH58tk;(GA^=Qjr^x{nVQ2_e`>5?O6b9~qXq1Axht59f9QlsT z!q(0b#^Pr_2y0t{;Z@>4$6n-wiE$F!mOl1+0xh6DmZhy-9N@*talMg@Md;0ZzH{a= zlH(n1KuI@x?OG6AJpq^x7E(`vLS-l7v`-)WM+&r)(Mxm z)gGFB4D>?~r!Q`v)U;l9r6M~`ZfpMQN6eFeG6!{So5A9+6&6bPycFSX%VO3I1K&1s z02s9wz-5^CYPGLswBFbaMMN7j18utrHqY5U4|8%!j&cO9byDpw>8uvt?21a??Sz=h zP0E6XO!I4cy|1+b54ccei#A%H?fPKql#K*=FfA7NiuMT^B12O95B>YTdqG~rIelcH z6`L`)Fw!sOpZUIDas3)BT#0u52h&T|RM`3FW#-K`zoJ0MIjNDr<6pzU9gBFpp z)FF}}ibE(nv1K;qGiBo`v4NT!z7d9AjF<&HQ~9j8em#R_HoaY-P?sYMuCZm+`pxtH z=@%&>)ll`D%{=gVeK}}qg=^}~Achko8j978`HV^MH}KkQ?^C+9h2;Fbd-}VNG`CJ` zTc=p{=a@X_mp>)vQZES0jx6Lq-sN-T9wha$U7C1H-KwNT48EA=(0us(NtTR8gWAuo zu8viDF2(Z2-tCwtg}8x-g}@-nEUZhANaAF}l-IgT`m;VR9D=djZK7K+BIMXwNWDg; zaMftz9kunA=9#TwGVYIIPEZbN9mKX0K_EwH2|h)X9nZd!Z45b$qKMUo`XWty5kTrr zvz9!etdbpUrf~IY<{lM{%FEmzbM40iq^EcsRoCzwMA_dywp=Q@t6?8wrpIvZfs@`Z zanNh4h@2mKalzcuP7Me*`^(D=-`Vv+gRq)Ud`3rV`+4`U3N6W8KVHgNwDU53AL(m& z&PU1gWVIa=xApHPQ+?2W?eIO;V99Q_s3YhSDT4)9JB9(IQb-(8VsJ%}b;xy}j7|JM zjBB&RDK%+W{kD_Xs^O*|?7zSevwRYKL)DRrn!jB;Ae!1@i_N}+?CwFV0(a>hgUBK&}ndZ(xAjFDmz)Fg78MkXMj1$4HK zDS(Q=LV+S;X|M0P+y9^hVy#jBdYQj;B?W0Hr^OobX@VC>fsh3=0^pP=LME%T2(uA^ z6`jQj4AG+oMx6FISf)BtLmBOME$Sqhk|3RCX48(y@>38+=$dxJ2`>4u2q19>%(e*2 zkb^lc1{PoJh`~V>iD(NUWgc$2Nw7Ff01Kwd@+{5dxN{6%t~Q zLWd1DGGc1KsI?uX23K~_9%jl?-Q)8A;7PQlQXaC^=r}gMateVcQYpAWI!0FtzMf?U z>$i5idBfeP!k@E*=}YBP1BDV{0kiU?U-<7CNUsFXQM!P6;4IDrhb}Z&-iS(QxOgWq zD)Jzqa52I~dff855k+{=#O{r)#O+t|Vmjnw#xiZlXWWj%NV6kl{J|Agg^pj(aU*Ci zWFdB89JGzj9Cxs=yTV!QymP@$3rN`|-Ym0H(GiJqHf4+uxDvH&+>h_?#$xfKwE|cP z`iSmxgXCp+qa98-B_qnKc|lrM?bc7YUi%Z~$TWzv*va!8m#i^( z*BjS9sZiePiMti>t+1oA81L{vz4lqpu9dI?gn0qteeBUyb&PjBD!T)br{nONv5}_* zD$dS7(@^yiq`8PwbT4%G+XkK#xsFIwv_G&nH`Q^N(klnToaRvASO_d{!f2*3{rUNo z{=K znJ`6F%3W%>!qqSH1)VsFm1C8CFf&sL9Ul-NS{YoKJ`$7FWLJJ}ugMj;cgd^t`M@JJoNkjFL&Bs-q8GFaQGRn#%s)=@pv4 zW(-quA?G3}&v1YIiaY!B82gZo`>BgO7!T*wq*_YAW~?_T2%^L?{$-Y8Rzu8^dxYTy z9T)=c7pXN~H^=ekG22ZSPCFvjb78_?WfD1gtqV0yWul4Mz)6S4+RkG>X5ljCpqZ!f zX0j1Duj3Eq5dVdc0S**nqw z=IHdttG6$)V<|og%Gy3c{)W;$r-BVa5x0K4QsM~!&y^E}!br)2t1kfQazMQ;UsE-?zXIZG?4r|Wkp-jo zX@IDQ{m-p}Q0N#pKKBQ8j(UT>Fdf6FDB}cqC=+;u{@^jIIDWJP&ktxUDOwBAQme(mMcq^S;`xJO3eUTA*q`9c;;8& zsj6Ceu4bAv6OE{Z!MyUS#2QnEb8z9*-V;CyWmpYI91xH6C1k|LsrSl4u0r;vmaHoj z_$TWkSaiXodFmI~=e{Tkb0*7e>hv+WP)Chf%@{s*U`?^cMT5IYxq8c_gEX{VY^D|D zv8uRmV2h6@c}{Dl-{is0(pe%P1#ZBRV!HAi}CH{&^R3 z#-K#I6YRbdPXrjJJ{4}McIjg(u5Qy3)*!+DgJ+-2PD+$(+X2?ZpaYeASPLRHG&Q(r z4SgYFlyR5|GU8$e&1~xa%7ucY?5_E6L(8H8Dz}uMeTudHJO3VxseJu&1i}NJc3Pcz z7rxV2w-zm3!l2ES-53~np+=KLCL3s@dtK0U!%`@W-W6n|$&?@@yNGfekC*X4b9B%2WHC$`dMj<@`BpM5^tDa{Ss_zE69!l| z6i8R3Y`y0+pPmK^Ni&peq?{>**L&w~Dpy8Wj3? z3t|JcCd*}g7F0V+zb7fyT3B<9JNT0I%357Nzo3Dqd6+wa*=8X^m;+nLYC+5^^2$ll zxHd^)h(}sZ%9t(`=Nn47!ClsAzzj6Z^vW)lpf*X7lKVU8h3@3S_7qA#(f$#oGf2VZt4n=m>jusrqp*s*;9ELi{06?QEdxJA#E+af z$^>|7s#O>STlM04 zOhfSSS7OW=f&<8jJUrK6Y;%k)s)ckq!GdF_=#&2Y-F0c4C8$N_>t9{Gachwx+CuK%B*jFP;bQer@rbakVmZI}+RSrzMjY0WRiPcaw85tA z()c1kSBQ;91`9k#&U5$_a8CbHo0Opd6UXb??zsw=Oy6_V2l7jzb$IZ{?sFd+#dsuj&O)Zg`VcJde|R7=ml9-b*rAt2Jl z)jk+v+FfgA6I1hfbxA!R&kSJHe0h5WiKn|`dkrlqs0vhx-Np<9zO59Vv z=K&eQ3aO>I6kh6WQujmVHuQ8K?{C7Lssq6j@r-#`gxr5NNJflYZ^R+ileRs$E7SEW zbFp2X@-&sF$^MA;a(-_5@G4{VM?`;AYZ7e1V@?(m8-&tFn0EDb^!L#Q_j1Uoo5HYI z@YP|Qo4Y4RyL)2tfif9xG2&4 z`n%5b!!{Dj-4^{m_8d)EO9KxI?P@MCt?COdfh2WJlHV^+Pr{G|;e)88($Ss>9$Z7E z#iz#R#Nv^kZM0;Z73!BT@G2zWxMxL7!VU8*Zi_2CQK>K1>G*7e2W?S*@41QNb;dn& zku7+9BfQt!-}-ZCXoQUR=?VH$t?fIy(pOK8)~9-AYW{FZ4l195j{j^nj+0b<`*h=k z`7Lzk>LFKxM1uWdfo z5=#MRU=c`fv3Hh(dJDfQtr0rUS;JN_JFXwhv-B~?=Q$Vv>39c5 zQD4u7Y2A+O>x0};n>Z~+up9QB-*|V?)-{^!{Cs+GU&eDH8>DhqqQS85=Y+^8n|ncu zN=V&;*2IPl=?_N5o%89OJ3NrHs;U)J8Xwd}mq#^gYds%ir@$*ZX9~Ak=$oh$Sr?|k zaJLB+pubg*?oz0Gk*cASN6jMD)nzi=4Iom{@~b=mWAuuR$4z!s<>CjwVRNDB>AtPM z*z3oN{A=WoMQ*cjntbkVlub&RMi~YbwFj5}(dK&7)!fjYyhN@*i?={0fBUcvgztNA zL9S}ru7~S~32fnOhM}1=x(-QxQ< zn?gTkxfHA-e88&rx)n$;c-kF&R>*|%#H{qQ_0=bqT~=3{IEBR8FV&8}HcB)+*i2`y zX1;J^%eHv>YdX^%=ne~WNX--UC#?eIIO{2pWtOL0tYwyF>H@L^Mfm6a1>D1Q?t%q{ zzeTVs6dM1$3d~fi7a@*%9;)ppa4q4+>QEL2SS98YQ-P`1f^0%_E`f=YWi!d*FtbKk z&s!KJVs)7OTz2;?{Z5@M?0$tHU{ZWCSd<)ga6Xo=)DiO-Q(rvp7hI`Edn2Zb(1$m? zAuLc&D=djIDW!VCA9S)lIG_5B1Bp>Ep^d^8&Z@Q96Nop!rH1$0@wZbZScr=SJ0g49 zR{!;R@_6}$9Gw}F0Qzr_X*lonk|^eH<9neC7pAP(u8Xc3_9-GOj%4BH)o<;=$+2h* zC{ZoXRnAL&N7u@>>U4XSm=9miVab~ISJh`%Sjb@;6+5DtXv1l0EPuzWDIIMlg84rd zkPB1VCJ5P{lfb~)o;!+9Wtr|aT+>}8mM6bBJeeNmvbkCe(cle>@t7WOo2&bT zd1+z2F3xAb_b#@*aJoj%x%tv7%9dJ&s|;V+A1gVwa;2Bk^jHiU<7IfK2z;l&fzw(_ zdn20f^;S#Y6+;+}S}y$7y)t^VY%jn)7wJo~WRqI-*v3`{XBU@1o#*~N8s@V-%r!hG zZC2mYq`DLc&Op{ZXn1OR?(JWw_8ux#YpdzSRpwOM4}Q;PdaP)3TC!tG;kig6_gAmkt z1QVF8&;bhWA)z?Oh$&$BG}gtZ(yr2wUF5{y>Z*n9^i`iU>2TGwHzS*P9yM4VGWgJ{ zy^*s2Al3FcFW?Hdt>CfoK8*7=|G-${WA95PVktbQng=2LjV1aS|AoCi;>wf1(%rK^vGNZ%CJV2o~mswFN_C1JYi^NCem zF{pyvBNiC0y-OX<+@aV8s^vq0Q2-3!X!*|LVj^aByNb$%n(B#57Fw1M9Y|M;8_oxQfjfy-3RrM&`^GNiyr#qis;t z2q#a%e31d}>|~f0Tve$}KNk_Dr(1o?eCi!k_er~~dm?Tft6%53tddGml!>J>V!3|P zAE2vjsUh<>CAilK0XLK5LV0-5i&vKPx7cSe!o${Gd=0wp4=t#8ng-flfFrUKOoSVS+J2 z0dPb|Q1U`GRLIvG`6NEKx=6GQ+&7_$E@`lKVEEh?49`P)UII_Ts7|8Tj|Ke|TA8rZ zqh|qcj9y1;U2dqua(4VHl}z}z^>SVHg_tx24whh;k*~zO^@v30FR-$_8U*lS(c<(&Fh8_pF9hmpf@_Pl=C_?1q>+; zY5V{t{2#X5RR*@m0oCy9x+M*`HJUb(AC5e+Sc*a=`f}?Au8U!*b*bSZcNGJt+sevA zU|E8c8N>pJUVO@At5XBK8(a)|Cu4{sbQzf@F~3Lg6pH{ZC+0) z-GSjMp24>TXo9EbcCd}2cm%Em$iEBwP*9kaI5w3R8$)0nJ6qc1y;hC7n)>aXXU>0O7qdXcpjhrWfO(bPT-D;HsJby}xA42mgY?8ftb7ukGs=pQE zVv`WQp0Bi4Y^_RG4Szq`;wvKfXlseo@2NDX5sv%H$8hVmIV3Z*C^F@T-$|`i>|IbVpX$$K93DQM4Wp>~F)v!hPSTC%oNNnp%^!Heaj|lp zAqm!iuIG1Ad;6hV!+*SXPDcffAKlLG#xkw3fJu_H9nvD*I$@@l)}Ltqpexj}x-A ze{q5N3mf%wS21W{x&UOvpALz5-z3`49&Cg=pEdj7*6;rdS3s!0&Wwa$Xx?a+Mgvx) z{hjK)8T5Aok)daVbwPjz`IBdZukH;;zFxUm137=n=VpH=8nj{D2$<*Lhvm4zNv$Ui zOmdI@4oDRsJL{X2zmqLBR~zKmKWL9y{@|nGu+ShTC1#=7-^qskoAI65vqApO>o@L* z8t(6}p}zx?J97v%d1Tk&VlW&?%r@N}khnRxET}MIn!Oz~aIaH*EGLn?PB;PM)XnY= zCY`KrxWUN--wC$(;2|V}{^F}h1kv7T=~OVG+tQ~vwGCN5#Ysr5wgUti;i@AyVG;g9 zc>hhj%hKN3Nl1tIf8$xS86xp61n*;kPHRwEK7mHzdWMk{Xcbk>sbiB(jC^FvCC(f! z^bpo3o<NTC%jH7 z4S5tXl;nD+fK*jf9)-{oO&-N*S)U$7OeK^&{Rz~%hXKo!(J72PQ@kffw&ut#RTip3 zATF+HLtz%#q^2NMg{6(9QD2R;>FS)JIFk#94n>d`haTu{lN;%i4dG85{5flshD8(4 zAFutwn2GgT3(Jgd7?QLI1R1*@a-unTb#i}?9EyN|Q4z?YI2ov*DT#qTCk#0_6rXE| zDWGr5>KBsCFq3u)T@4D2M^alg*9P$_l?T)JgtM^h4-=xuD{~X9u@7QSXIBY?$?M!L z?$m5!x>^OOey&SZe1y5U~1fo;aJd zgkMva4NP8EI%H05(vE(8J+@mPmd(H$k)6nW`ktLyz0A!^*b#|f{yKJr_v8Ki=6$hz zKTq^)JRf&c&ZDd0%Exup)dAL=kM~ZvpZoQK9=UTy93|gn-d$h!f-JExC4a8L*^jTT zTFcjKXfwb1G4}tQ4&fQfwT-B3$PnAfniv0SV9iS;yy+YhqB1P~5hIQ?@_l&$G5_6V zPn=5V*SeS67>0thNHRAeWkaG#N})jbtAUA^ za|UNpgXg#350+ z;%q=qPJdufr`GE&Hl9tI;3ijd;7(Fa75EbLq0MQOmBaP#a5f*26^DDu`&D@YG1-%q zlvPC`$(Dj&4LVr(x6u^urOm|uq*olD@<++YEFAWm$*D^f2ACAgu#`~&bZ4Aw>ZUaBsOELlB0f^z6k1$c-IU78YSK3aBi(K#Vo4>+wUF;rk0^h8 zF+=5N?=3BqtzGQ(3kExs=OBmKqfx(9r-*)Jc<1lD|IJ@2K zx9~a-#zlM$lp=-Nx&xR&-wecjCMq(JfnMzQQ{WUu)MC#6?0eWiEXq)7bY(v8-I5m|HAK? z)FY=pUJ8}yV!WMtLzrQEv*TFpY zbgb?V^WyZ21emHSB}Twhqu(1tOW#Y!Q#`H$UB+m*>EYDn}d_{Pvcsk{PARsjzec+|4%E1XQ6$$p(#n%!q6`w<|5(2!QY2*S3a8e8>UMe_1 zUMKKUwfuNlowYcg=A>$|8OH0CUZDU}m9}-;h^d%X-T=#|a<^I&WU5w2s|A^=)pZE4 zDk|!Qv(7+cLRm}9Y0Jt`dt#<)wS>tI$tSLXK_$<=%po(5FjMh)E7d2K0K-XU=>pH_ z$Qw@EmPRNjd@RsZJ*}MqnyQKr2{c9Wun_|7fP|Zhk!EO)U9XPR2{#o}$+E!Yv+A0`ME_m+Gy$jT zc=5y0#2Ds;M8s)aH?Kb|J;qqL|9AURIRRs%j|t+?NR}!ESWZPs&YqmGyJId z=LAw{bT*Kpyb_nda@`JCTq+RK=mQjDf_<(`d`3mz@SN8trWc) zeiI?UpbQt!4&exYP%ln_7td{f%}MyelW;ClmP5Dk1d>zO)ljwTw(&TmpgWINGxVor zQV~m?c;Mz8>*~C9_x`>!;S{o%r0uJ!xycr&w;ezu5^nf+hpmaq8e_IKOuoM!4YF10 z?IVbYWD-Vp+dB2mI-I~=G}qGN>id`-LK41B*sr66N+;m>46mmM3_|+%rcd;hs@>N+~bWR#0*^ zPD&}mr9F943d^C!DjC#giwE?QLc!3GVn2O(Qb!MNy#!|BiU$XPD01&zXL+EUG3(lo z%3{}%c|XzN7#&f0y2ZX4X3S(!^1)5yllxn6Y($AOyrbd9Q4ztCLCvWl!%GM64RRus z^m~&$aH6pgF^cpLY?hmI{}2VQrw`*miEdV*!_b>R->HC+Zpxa3=~P6V^XesF_rhn{Rok;Q+?Tl5m3sDdPR- z` zX9BeNGkYhATk0IYtGLP2F}#^Jb7_(6T#2+=r}-wLB5sp?xrbMhqOSb+zp=wNl`bAvOZ ztXFW`#MH$C>^vT+-8@BrQ%6Z{1wMF43f1tCGP=5D%fd?5F)&K`T}nS_m!=2DK!kP2Gl5R(KZx&%oC>L9&xSA47~d-H zrC6bRzp2_^N7Pn4@7-dW%6HOIrxpz2u3Pu2ETeVr)Uh^vcTi(&WZkpQnMThqFqo{uUCTq%>MzDKDO*w0R0QK+wJYU48=kG2$ zF!|JoMN0op`u)jac+y*^0>;-(EyXaHY;{xriZ7{tXS0JF>eurx^^1vviM7m3G+fWI|CaJK3FC=p z155Yf9H(|{Avk$5o^)@VPt>{;tPZ=f@|}b|=o;P3gW5L^5yD9mQobgse1p0#Dc>O4 zy_N4|Jm64-VwTjA4V0B+*EvQJNt5yos-`bA8D==r8Jfl4;>)E-`A$I3Q}^naDe2zH z`jH2fugTQCo2KsFbm(3`iaHSQIktv$C#ZVeK`PgoQ534)_`3GGh?C&N^wZ_;@)rsrFkdoC5q3?O38H$ z-R!H_$stENSaNR7J9)&rRPW@bDXHE~CFei%A>EtOjjDIDMpmlc$=b+Ly;El&QT5J? z5{0@~Qs_$Gc`|iG)oUSS-8-4dk?xHl#Q{t!R|<7Hl`mMjTKP`GA1#uSlE4CeNc(c> zOe{@?&987>ni zUUfU`0jZBlwPbCae22OWnqHlFRTX6EG#AK$i!m`-pyH$HaE-3gMtjsN9Zd3AO#V+y zKrKGkXf7Xm)G3^AxhtF%B7N7%!%KoiPTG46DymD3omggkT^(d~$?_pn_Ck3*4Hc@! zf-(8r&d{YPO1q>7RYpuCmc?PMkl_%Oh4l(ru>KaSpigX^-qMZ<{E+y)9*m4xs!uyR zl=y?AQe-uW$Gjr(Y>5$|Y=?#`0q6Gg+;R$3~~M9JCDLu$JS5sBI6grg$!m(P1n5QM8ryA{({t#mqjPj#Mq1sfbkZ%N(il zXX|H|r& ztbPX1D~gZWv8vb&cV(=KrHCmY7gVfeXMFbQC>Cmzj|^2U9>8g9*(9yy#rpfSmV;o9 zj@B}^N$yb9Dmztx2RKpCb=F+FGgPG=l`@A>Q~i2{s-mI2ub#Jz<@nU`ic|&NGEx;3 zdxT(zNn6XCrnS6jo$gp$MymXxj8wTBGv>S*-Npx!Tgo zS(j}S1gaKm!=<^*gSliaujaSvC@xXS_@X&?l5n(^*JW=rp9>95Yk9Fsg{?ew8&OIJW**ZuVP`i$jVa15=x>{WQj(k3XjT2)skgx zV_CB!V>x6?#eK zJAL#kmG7h^*2||YC23y@=zZ0CyyC&u;xs81#kb$P(ntyQD=O7*(o(;hhWcF@LcChO zDOF`!N$%C@P?bNxp(=l#FOG4&em7eEc&ai^Sb>wrJS$YSM_dY+C!1ISPgwU>z}#fF z_2jfAhFF!#VOzzr;@noiJYCdRd)})f-;|4ItZH@t7z#LzIINkZ#LY>A*E=>lI97#Y z=hjOBcPmOL;6YS^6!1t8#bk$-NJ6Y?5ua-XJZ(2h0Z%J$DBwxPmIB@ew7zaR$}E1W zjC`EqMMw@M4F$Y_5v2kq51jW)7*5_L1w5U*xvI~POBKwcUPvBGUMB-qt2?EzbWq>L z>JqZgm59pny@#?~n!-`BK11O93Zc$)V><6L#$V+Imu*kpAt?r9f$P1!<&zW832E z8fq-)+|*8}x5d)%QB8hpCf*lm6wQ2V4Kj zdzAjoOc3<%;O3i*R_P2&E8uR-6_2cxUY7#qW)&;o&MGL1R%xoX0`3-uP{7?dAPFT= zDY9T&I!4o-OMn8F>`MjA`LO~Xb_Jnf2lxD@v#FLp&nqh2uT#u)%pj*RlH~aEi8y0mgMvKojNSaqk(xSYt)})beUpx3sDaVA z=^rni-tK2J(B@I+`tB<`1~(x)e%KoQnO{a{HotqZHvgNv@7K7j$}M3U*2RpHM;+%v z`#eQRl&ZrjIcbX_TTd!U4|}5@;2Rnb^7hZ$_4#y2ud1W{csxcVFlOaAweWA)E$c(RNQLpUWe9JQ(uh`c6dcOv~j;9}{mA`y;qhdF4>}EL=y~M*w zle~HO;o?CD%OJ*R`9L*BLo9eTfMkv+gfPfuC`9ptn9tv{r}u02#yjnro!_&^Ji_ss zy~Lk{clOcHAfTvvA?3TB>5@{wQA|!<2F5uxJ+Z<1w*HQg1_@m}rLQ_A@SLf;ySsw9 zyEAYLwn`c1xx1a;#Y`P3)n0SQqtA2hx-nFoyY74|5yfbjLaVmhJ=}9Avb?^}4P*M} zU%Bu)&sKcRT~Dyv+@15>-7h?wzRzAsOdY@PtYiP8VJY}=4H|mCOkivGroH&=_@MPM z?UPXxtIeTk(*GVRzWd0rRM$Mxx1AX}0MQ^{!c%h_3j>vOIiD{d)bi>X*JAeEp`ic%R>85ChUU%k z-jPyH!>aVb<+ONuHE_jX1fouaptBf)a#~hu49b~%1qP{^BOodV0Q6y}faFZ28;{keYF zU!IQ35nNB;PE#WAQ3|mA$NmNDyZTW(H>o#edJ;WpWMlWU$+z7f(vr`^Gb%i*ToF@{ z%<7$acgtB-S2zWgUGoG`4Ha(nn>+&?-?sXmlgomIlYRsnKqa%HHfR0%t6>f|1c^`z zxBh~RDs75{bKsFf;e8to`$X-YTHn{>_9K6OTMWx#Ew>+VfrryHCChG0wG7`bOBWue3bQbyz{fKc z$czHs&ulx)?5K#-oKgr1sWB%N@NrBzRLtPOR&iw&a%h}ZNZwsqP?N_kDzlL6;oN>S zC@N`&yJ#1l<4q}k!G^=>1w5`-C-{p_FUeppCX!)##9qp9xc}mZ!{2a@AsXts^70Ly zP?8}?1*GZ6n`WAUB-5Pe`E9tBbt%tLQ>G!vbel!WX_i#G8M{@w0rbm{j$%4}ysUYg zGSuGJk@TVMj`K-AT!m}lL(lV>W#Y`APdWlOEsejd{Rdg0CzWPeWSNcQ$n zjv+tC83=stPD$kO?4K*9u^$h!=kD36ZP(7M3B$CCrDdN_sODrgJV$Mc3QaF1UVe{Oxe$PP(LLhhjS8}+RKGB zr*$}8PcvvxIA&G?FTaY@66hHd50RHBJSr;F5=F=5C@%r2Qn{n7U0bL*HGx6w-MNXP zbFP$|@OsJQ1Q)>J>;yPuUT+a6a?3z9gf!u5>rPNepr$wS)3c@&MNv^Ohwwsx?|5a- zQC{|bzLCo3rOx4>eb?}h(yzq{P5Ec_{N|8G<(u`rp`^nWBr2Muz3x4n7BRVv6HLFH zVyCsfG7PCTy_l0t4~>}A^w5@375310W>C6li#s{&qbX|-q{GygbGFMVEbf|Y~Nkb=?yB0eHbkklmKi>@+9{-$U=cnh;>g9)r z-hI=|xbx|$MH!<0j)>RX5dcpudUUx1zNKnw?WXUwz4J;FHhWNW%dGpDnJs)mbr1M` z)lRLye>a2^#2+7f{HnJ*dwlhJ4Zr&4xv3v}n&aEd>?crY>q{r9x)hg@B*g>h>LL=J1<`?)^y;k4DET|eno)se_Ij8y0DOL=9r+k%kSR(TwR8XiWt^M3sNwmkOZw+Vu!cRPB= zm6~KP!05eNVAANkD|>A?t?T8qMSZ7rr_&bInqsS+-L^{1KzeQQaokT_HH(Nj$!n{_ zh);QKWa1;;Hq2@|ZRU`4+A7`cl`Q9t=EKzSvO@QD_-yesCLHA203j(*4sWCPw9I3Y|)@(7&HS*F&=i> zP>}0>Ic@dM3IY=xlKxn2-b5*XEgD{sv7o&>a+12=N!8kfM~AzHqtEVi*GL{Of6X@- zDE4ZAyH>ra6yB2GCU@%Cy^+7g&Zal!k4bN>ve0~9zYX62V%y`k-8B!i-=DKoJq_3O z=AWDKal30e3eNsoP2W@QT1Bx>d28kfd296+SS0;5)Ja?EuiMeF0H+Ph zZKcy@d73^O=gv+W1oGPZ#4uG%Kges-ROR)Nq0RF{ot(tE|M$19f7JhVramXw<*M&w z5-ZNVb4gcy<&v)Y$|Yfb<1ojxY_IxCCVh}x$8L}j&)*7~aMf?gB)wSvfqNxG)xAzT zRo``Ne?u+nbZxz)?@DSlud3_x<_K9W*C}HW;jwZR@6W_4ilanJd#$2tZ^YJhg;W5+ zyJ{|YIiDA8y2T=O7zlP|aKyb+gK}6$NJfK(0??kIBUgP@Lny?DIx_loT|2P-b8l+J z;~$>5XiA=BtSf6&jabt!lCZwr0G7xf!}0T=SDoMc*|Pnn z<;@>-W|ylpS@W(m#s;ZQ$w6m!d8J$5?FKlAD{Fwv*VFA^9{GCtpX z@;m8Ho_aS#cncIkmT-wK<aOxeKkn%-3%kWu@Ss#6F7|>4sZcSTFy1cs zTSN#!5;57(nS_fsb!Nc*e_vnxIG|>)kvqicUtJloMPG+Ebj7CdHz`Rqv@wGF!ujiz zYr_a63zBUrhpll9@AizH;TQ+_vuQOxBQ+T1k0c4kHBILn_7n}7k-*hEcOt;Qh&gVr zP2$m@4Sw;=AWs%Xf)%yN=DSac17D9WP3{!O(-{lnPI2&1&&qe`+nKwx3Jzp`<43P< zHOuQgV~H9^0o}Q09OFo*)N|CCqJks%$^Tp>LtEekF^`cKx>-!7B=*CgVj=H#9 zscQ=-qNJZYFo_>RKgUtv^$07-3@Sna6A)6D};Be-p;=t z2!QDnB(!Cj6fBLFMOFNDMZsHNzFS7bTgiHk^4Fu3Hrc$2kC?>=n75sFPBv59P!k}u z<(6kpUGdfe=4!q`DhFM80=b$}*lxlnW;(0A0zaZDfVqaMdM$>ok<%zp)1?UTu=!b+ zI2v4U0G*j1oJR6^f6M$}RsY;0F|(krhH5&kjh%by-5%+w3N(tzT+S9ro}MgG1M?RnkwI$qbA^xr>+?0G$0+voi9 zKHoj-bNgMSX~0f>2st7SP|QaSY?#kCWqS0^{g&W9cJ#;$kiR4|_x{p-yUc~cUqH^F0!n+2spKXDp&kmt$oEE-fn(|FKxkakET#`KVKt<@EtW|Wtk zz|G`{pcRP|*WJw+0O+Ipa(obZhfUI*I$kaCr|z~ZBk=Jr!jYiUGR7mr9gMM zFKPL9q5eX2p!c*B;defyY6B^1eK*!Tv=?#5`EF2O8Y%fOVz=9SW5_bMLB#Xoq!HIS zEr9Rt8nQ@{-#oZ(a$mpsZ+TT*V8=MIFowO1qLCHJ~sdQg1 zHe#rCw4}lfqU;pTeSO>f6bCVhW^~#>IfD#r`7Gv^4yXb-K>x1b*|J-}oSB{esf_giFVQY-n z6e!^wG&3Aii?Fj~9#>Fd`AUnEhP{*shVlk&z(=IWypfTjo5x&cr0C`emHG4TMA4R3 z?NotGtpe3gXf?^H(&#_mEkp9G5lI^-IfAiSky5duo9AUBt-4;Ta7kb!5Vv>@YZ<|F z3}MK^A6PZFV+#IOMA=xuO!7e?l!#Wmgx75b(#aXfncZ264EEivJ=64R&COIgjkgav z@Q69wtfkhIy;_DT8{hq`l*6^_(06Smr?q(VSgO3P%sTblH${)b8UIrLk3Gu@^9G2`#Dlje??^^du>PBBTX0?~BxN`CC9Z8%TNtN$KShAn? zQm@yzr~F@bOd$UkEeeMv@9A)g*?1axjIiWARiPPC$E2F?J;#no#!p+%nB+ZO(MK`K zTSYDvle}4%(_x}}<@P2Co1RfG+|bY54y8f#`8^CuVi2c;l9+)Vll2Dz_dCzy}|M@+!;#tvV^5*zNHDofT_e81ghPk&+_O4T>Xw3GW`^c#H`pANpAtn3p z^Wo;bNNVM-5WD?E|D0Z=pPo)8-=0pW`z9B)@9oZB7~NrIIkjro*unp=v3J*%WLMh6 z{CtYG1^kUnGMOaZaRdmEF_J0BT2gC6SlgI!^!lp!Eb#%5sa(m z``(bDUq^n@K5!b+@{!Ys?M|o}+Qn{x%5b~4%>C_06PjHp`4h;-- z4PEYp#LeSX16U^5L1VHG`I3gFiVgYST%J>1S~1zkO9ViG}nZr2Fl^A&gb0OD;w zJFi(i;pDF`dE=Eg&`X;QaDCz1l;%N=tGT(Uakax0ZhIP=*ji$Sx!mE&*OexX_l5uKUc9JrKT{pa00uXlKE3^wB2i zL(T|K>L=xk@QhU6h6Bh8yc7oZRDnQzdPNc5=xBF>!PSsX-6PgBbN`W2yAqTMdH3BN zbiTiNOt5uT-N6w6CxYs~(w0ZN$wJ6+zQ z=YZeM%CCk&?BQ@HiM$2f`JV3oz`nNhiOXH5aJY~{d!dH4_Wj)SDhFE@Q=IQCbAE)R zKQjYsh+!)t{aEl~*sDQP+e6ab``U{6CN9LdBuIGBxea}Vqi`G4uyocP)}`aUrS@fC z=$A?uVK99ef5?COl{$f7PyJdI3WI(1%oi+zwl###-mmL0_Ou;Y*`d!<+2Nr{nZdCy zWye21kAF~vhX$Oyk@d2tT>nOc6hpX?p_<>ik+E>*b|Z@_pi1i>$6AFy6VdLsl1~9Y zV}Cm9y)I-ul?A$x_4EYAg{(Jc`p1Rr1K}QXFAq%*qqey&fJllzm!7W@0P(ER}k)iJ7o1w60 zE*RX%qUvVP8=02fWIKv1K6xRFEu7nhY}ISjg)B-+-s?ivi_?%ohFRe4U)vDl=W&Ji zoh)jr&izi-Yi9nyiK>oagUo@Nk8g>_`t6#D{6TYKGTg~}N))=2VI8OMWY~mjUCQ3k zpNFJbF{VpdEd9MMWvmtIOIdF=QHoFZ2GX0CvVOm1KUzsPOB*7r&HJvb45j(*c}k28Nw!*W!PEM*y%`&@OL2(AfWoH09-hEZiyFCD zg4qL5py(uOmbT90bWu>bm;<->AB=Qo={y;|ZvH8KBt2?8RtyjViQLYeMUt^+#o|G{ zdw*}R8UEo1am&f|OKqChclg4}vP?vB@U;nA_B*nkPxvu9?%vIZZHL9 zHmn$1zumX_Y($kGPdQm5v#ji3vdzQclWV*fNtES!^Ew=Dt2grv__{O68NiuN+oNSs zNkvvf%d>QOqq%!bXahOpk<1q>!nZTmmAlX79BGfiYI|(j3=KUsd7Rts{;t_hM^`L3 zEN(BTHfOsINEbLWnVL~cp{g0x)hHnOW{ow;#Zl91#VlQ@J;+~&9eUgusUd4l%!Mw_ zxLc3rv2?Dw#v)NP8Z=ZbglP!;Bt|n0kydJ?(#y|v`}FH?u^R_kk&nL@cZHf80Oi7jLS zm{QkfUrgr8U#mDdM6dB4aKw zfn9M1?;!Tn3Gk^a#=;do)6-|DaFINHT(fk&4$q6N_rQgWu`n6)*b>Ybi%&uqw2zJ% zgExqvec2$-1xg%$fv>7q^^t|qL_UW+sKim`=@dO%!}>*lPREaJoTt52#na*{TNd}9 zr!(~9=onnwe`|@uxOWciANV?tm7{p_}0KczdmY)OpT8 z`qj{$x(;~%o!saM=sg&4WP&n&UzZ#n?^W7a$9pv(S&ClnIhXf*nEbR3w?^f|y=OB} zP~``nzOaAZshXlDd1mR)@UZF5&}bm9-yv2+SqwH zdMJ3^Tz2wsB-&s(KB~daE%CMrIfNNt7S~0&=?H~dNi4a5K$vq;lap5q!EaJ_9|790~<`4T<$FE{z(n@8l%M!U;!&usi zIWw-5h&UaOLrg4Zs(WIp086Tp5=?nzZ+T&2zHWI%-7id>S?zqR!KJ)1)3;Q|?8yY_ zlvkqRS^|q|_qaQTYHr$!`J}xC!+8|n!Bdlv4wXyz^2|LMq{<`td_=DJ+g?eH%nSY4 zT5N5_w0+e(Gvufp0&~DUW#nvdnH&tB!dJ-5$bx}_O>hS!?UkPmOV0qL{NBQ7v_PNH zP7V|;*Zwvl8M1HrGV9weqO(RuF5)af&xXApsQTxHD%Dj`MySEdSxh%Z+~&)vnyU1F zVS~Z}-WoQt8-2VfBcnl9{Ad8U=x%@;-96Z_=x$lHUWo4Ho$l@p!1nS+cip|wFTW1- z%%Kr?bLd9)n4MGM1mb<;G%f50R7&=?l+60rnfY$6POw@yKi*)?<;=1eI@+=_`rwcK zBBQS#Ybnp)3%_&hM)zoVtFYn*Z{~rPi_srzd(S%&0AJvhH0UWnURbvg@eY{-;_WXC z@f%3ezBjnL>Kat){IEOi*Z%d;CTwGSuD*|*_upuk31fCBx1?N9F}d57zAuzZU>Ehhp(e^49Fk&qH6-7Zb4Xiw9Kijk?jq9R-|uI&?ZJ83{W?DSyiOMf zcjVb?pNI8!3Bt+w);+2h;C5E4%vtMe_5HBc?XbRqI;(X*t4F@>wWyzmwWbe0*0S!= z&>s8gN~h8AR#3+cZ`=8t+y4IZgPaF}pN?^8h(B|~q)-r`ys;}GssD|l0|{)L8myou zl&`Gi>{+#|;Mbi6j`j3G>`uP=Wcp!u{KcMp$!WW`+1Eq}nN=j-#`uURXXU+1zO8r{dbe_?Z!oMqn%HN?E|1zK<; z^eI3UsHJ!i17b7+uX^RZ0#r_DB!c$cvpK*^2|zoSYbf`O`+s<8_xGRePQReF8H5A7 z^(u4YJ&!wwDBYUIaw!t_9yv70=!r+^isiZG4+cY){Q9&&?Cz(75cv6ASm+r(R{pP> z@j5EkwS}*~w&!xpJb?f{jR9;wVa7bwf${U z^&FXKzK5PX;;Q*`GKotnxXa64Q#ibKAE2SPoumqbsacV?k2g>=sae1mEaFPfX0Ag` zdzRKopZ7ZI>dG~)xyIrUS27%L3mektzcqyQ9!Nt|%3Y09siyMhZyWssEN7-MD65K& zXIHG8K_1b7TLujTq^J!V{flb)(CClDL=U9cpLN!xURA?3x3UYfY>=lIm!}wK2gm9F zJTEQsapcP96@@66V*i?2S?(Ns`B>XtQiU(HD6+9%V-3tGRkj-hetgoOc0<7v`5^L* zlWwc(?#%nQK6YkwCkAseac++F^!3|wIn%2Zb3M}$3WI1_Mr6%*RR#iBGcz^5KR25mNA&bWtkXyxO8*3{^xqrG^DAHO6!)_GMM}?1 z;9l0)$OSy~W$^#x62UjJs;3#p*i#>Wqd{dr*=bhJ#1~0-k8MOFQ_y1v#_sF8gPL#_ zr00U*?IV|KIF$^SGr#WT&YJYxjIo<%;^#|F@b)EhujL(X1<)i7d!oBEH<`CcF9D4l zK>4nM&#$r&6a=Edy0FQ$DwG4}!>J-m`Lr1vvyqCoa5frDh;Y~RV02r%rmKbHHW%PX zi+_N!GwMDW4ejmmnET7My!UM@Bsuyt?Z;hk11Suz1|Y@EQ`M$Af1Bq_B_|H`bb?;e zfZ;&I%d1kU(+jFrP(5R~J`5IptjI*{$yv6iVI`r#Klj@43(cMfZk_vQ&r68eJ$vFpfK>6tr~t04hge(XNWA$Jk%zMP7gjXd^c|OS zV@p}#a!u>?QQkTq$}w_XNAB!4GJ!Vt|Dba((pT=hqrp+WlylE9_l<^;e)0j~N=QHX zQs|Ap9Oa`$-Xl*1WOwg4{iXbV%UK)^^1=4=X=C5DaIo9J5PTpzxS-zLfVUoF~yW9RcVek8fWYwH#nyclT1Z!rX^Y zMFF+^flRu(+?RAP*X15d=%8ip*5u{B)L$QHkHb+imjoTk%c{OHgj~*&f|aN?0@H&X zxI2`@Elz8ocFUAuIiVE3Vv8p;-tjn+^xg%s3M4Kwhjx!&Yg2sO22(pRw|am#CEE&WI?{bjSCOJ>f)DOu0k$X85(T(tEh9IR7nad=sw#PB;*ah#hp*~iIZW6XrM!OAukxVabEnnWbw$sv zo$Bja^W;m+m8@rv75NZ%i!z+0IIQXczClNc5#5;UB%;>5AoJ&n8ztg5UWjtTnlu%+ zPI&v>as{(|H@ijwhfGftFv=qY8a_8+7N)zwb`msKO6ToB-tWC3ZUYBCAf4pNL!>j= z{JyGH#ao!kyw>r5GQ;-P}BUY$Z_0K0u zdGQ$MuebYLSqbgwJ{JwT$b^ceAiaKCBPy+#8Hio#$;d`MKAmSW9OwcR5{RQJ!MU%F z^<-w}c~Zeon1^BN_s$F*l)SRgHy!AT(~sN#CK{Ohmkx9>SXHWldc9tbN7KFL)evLP z=TbJ)gDyb2;oF0*plU+13tfN^ALv5ogEZX@0toTBd)kE# z!<#lm9GuRxB_)W4ElUAruhM0cYpqM3^wkxalT$Z|y`#=279XHYJ-HX;27WAV;Fn!H ze06`XaLZCxe%D^!K*}Gh0WNgg>tTM*y&f9?l0a?0CN44|KdefH~HlbljsP6Dy^QC@`(y26s%>$J(g5J(7NGMKFOU)0|VA>INrkj)u+zao_>n z=nV}+Wqj8$oF%lNQUWE(!QVfOwhEpSppI7;Wg9M_ipR*E#oNIoY>)D)U&{m=0=E+2 z4$)vkC3}A4$s6KSfV|;>J7q{DE0>{XUP&Qct-QauNi#F=VVJ)ck@62jpzGwwc)4a$ zAI@W>z+9mqWOpH()!{Wao{jXOKDi9nN;85rQ+zfk=7AQ`M4aKQYR+})R`E-V$np@| zV;Q2a3*02D5_l!kl+DpTcHoAY%Lp?mX&62>0@gFODjOVc`w%JS=JryTd0H-NwcB}v z6m6t~=C~KQDB5c9Y7EPt$LfDkw4V9r#~Pd|TB>Vxi&Gs1`^9{tWj8_9X1|z0U{BzQ zhUFew>a8+&mq?DBhA!p3%!U&QJM(phTW9yD4~SA*ouX$gt#+g4(3gg;K6?!LcQy#q z4oO#h5*#a8l`VsJmAS7N} z>S7OkGbVi!yBGaarhofr3SOvsm)!st4J+aY zChFc62ZXzNTgc+h6PfsR+43<`R1>sk*68-{xE|cZdtyBw^B0f4ag@Uz1FP| zeQNyy-qdsP_I96+-wRD*fV!@QH}M8aOxYSPzkJx6*uAGa@%Hu5$ZTVSNWI2RhH(7z z15*Qchr@>C;iQHsm#({~il7pdoox)2=l1?)HeyCH9KD>@dyOgR`W`btl2yoAKp-AVTrVLm_M+?wume^TpIW$PzJh~mPv*^lq)@dpP3_@7b#E6 zI)_ur<(5haQnZCe>Mgz81>Iu+{fg`dTKSKJs?wD7J?x-fZH1%BnOAKMRL zLtU>!IlA|LvI8*PcKPlelq#0$mZQNiN-Eex7%K!bX>I-m;;!m|i1kr7RGjw$94|LQXB<%^%p4u>w*CF$w{#*)eQfe0-`p z2-fE2vE3GrwL!eLH|t}1)Hb9BSN>X`Fn>cBXgFcEr z=WS5{4tb*xn9{LG$Sv`O^d+Htt;Zryw_Pnryl$y&7InL6t}^xGRwZq`ZK5>oysdeM zvOo2=OJp2US12nOBY$&goztIP7sgT z$Dw+iv&e2v)epm(HZWQ&~UG-VrxtxRiaY$KfXaZ#= zXTz%OlfPhTpX`pMee!F0G49u!qZJ3c?Akp=7b)#D+4Wcob-!&ttL!}!GnKW@DDAUB z(r_bVD0;i~TzOlfwoib}8RObMr8CBFu(nTta$bNru(KBZGLuKH)tb+bfc1OaGoR_> zO4N%qwDb)PT|s~sJpiCHU7&4ps|CmNnHj%dn|jOiP3peuxbx@EuM@NdqhZj9)QGPJ z=^5dd{miW9bMfag)YwI8C9;KI%WE}u0k)sk+zIPW7Cst@H5VOIM(~W%vu>fT;Qg{T z95)@H4G0f3Jw1(PHL-MFw5MXY0rM6Y<$X3#+(QkM<$cf}eYkW6a2`{Y)vwIU!l{Lw zQ1{P%zFkgZo$hp#dZrTQ>UJ6lqVL^dYc((_PByTL4nTf6sM8~lm8A)ZmaOjsXz5TQ zEApGV@EJ~;>gSIXJbKyHfU<8JQ1o%dUwC8=^`OFx4XeJ7e=%6!$K4I+R{XW$3OpK3 z%3~aB7WnaGmIXcLTE_ld_5{B^n8!c`ezcP7>r-Juz3;mqP3Myy4N%xe{%CsLMM%yw z9ZV~-5+_G>Q6^8~e(@B7f{JSc?ijMJbhsEBt^a7Ceuzt0PY$EBxS~^7YH-*cE@!-3go9V2K~ib&ND4#c@!P zj35%RbVGq|V<%zFD5N+mSU$AphpY>U1L^g&8g6YWQ;fh9?wP*DjwEpKPZ_N76Yy9* z4gGYMD>*g9)aX;&L_#k4;6Ar`%NBI|&rdlZM1$Lr{!;4pENZ0KvX0afgLag{%)~S@ z1t6a=2bT3ac`r7eMx90?x}Nh)t=F9_TvYV=y~VY?pd#&0*k=0UupZrw z`=cdbR8fEI=SW0LaCP45ZhGl&Nf{za`_-~VvG=~02?n@_mi3-VWP`N!Zm|>IlnJL2 zcx#9|S%1r(<=&I{>Enlpqedpm>5(U8jikbLk1dO(US^oc!n{%1-aaU8Z%Jt}mX?&Z zk2g>=X-R3J&+eI^kSoy~KkSuid(~Hu&8ysqT}z=I`@UycbHm8!vef|ZAf)bQ8dn5e zBCmMcE*kO0RYnGAxvGH!ZSP&L*d5Dy0OPw#i9^84nipRA`*%yj>dGcf`7Y0zMJTmw zQ@gXCaW*)m`ok_1#lWSz>0Y?4Z3aMc?eBB|#LnFIT=Udc0~|{FiebFE``;9lE7mX8QRJ4V4kcFVrnst$$i@IxRTqZV~Vr>keuzb+80PXlTjBrk%9ORi@4(D$Shy>*!@_&vT_IX;R=o9l{JQNL=zcSM=<7C%aA+yHPBU2@7D0PAz%j3Z*VT!%)A32+@6k2A&N4j(J0z!j-4M|1K5 zFr484K`vEG$5J6rbNH&C$Fb&Rp#ruelh(2!Fx;`|D$0qL~kA3qV`XqWm2OW(hGC0pn9KwrcH1uo;u&+ecIGfnVrMkWWuqD^kW;Vs{@yziU#zb)K;1(ll=0^uwCzRh=Dj5r32L_`Q3J8d z8V_5;a+RDklpf|N(~(@ds?IFw09HL)W*Y^<3rtqchUF^h*To&xdooXbUA$Ez6W`^) zcTY*@xlK+TS*Z6nN=8KtKn{tBj~#5em!d1cvc!rF)LhE@T#NJOB2#Vlzm}@(Rl;*{ zUg%8Ht9w23@a}SzGV`uuIIGn*ZYcH}BZDY3p%3}J%#3?6e<|ihJ;#^4DWk#7x>iGE ziucQXo6eqo%O4lpEO}D}Ppw-8#bZr(=fc@Q=CxqN3C?PN0fh7btq-d(zR-XWpob#* z3)H!UUSX#DfF$tQ?Al3hgTOqREQ7qxmfi*wq$a~(?fdWoc&=s)f>832;vTvkA|@_ zk4%<-IgEfU6AB4GTb2(OVcW&F_93=4D-(D&S{{|Yx?absz41d2%%`$tQZbUbe|}Ku zKSx~&su}26S4wLIdd^9$mI6KJ+{J}SuC)R^BW?4U^1>vWoC@@u@Q&O_TTf4I$Y(1d z5i~(c`8+ek$~mBAC5+cc&p^*f4xYhbGhCDAiu0V~O-VEdu`1&{=cK{h&nIijD9&?E zxj$u`=bQ-lbDU>n=f0}rJiU$?=a~%|=ee~seouKW5a&6kcU#xx_?(a-yvFAAU7vdS zIWx>hi<`-%PR-s0IwsfJCIK3cW~X#H6sj5UxdJ(7&$!Us3s~c}=Ta?n@5S-ny)`Ky zAKgBmP@-+1gzIdeT7JEbIM11qULuln34!o+meBAi8}`%4yVS7T3T^_jTuWU!r!`2j z+Qrtlx<3!&iNidrlDZFvc}9cmbfIPmPRXwdSscEe zsl`)FR6SEts%MrAj+IH!M{sZGgKttUsm}SFVv;`#xh981!jVH>!JXR)P;lp*8DeWKL_zLcv(^Puc5B(vv!82d&RLBKg&Y1D8r%rp}G!E}*dM0U=ZmpxOdrn2l{3MzoE zN(meJwk6}oJ_OajZEB%$!wnn8wf6+&6$zlnLczB3y#WbRzNZ+9hB_A>GRsHeVY6LL zl@j(AAfjG3GBy{UHZHDw)ng4#hPNEOv9Yey^AOqVd$RceU5k1UYW~=v*GuVZG?{gh zV_l#QRk6XAlPwHR%e5#jhT^p$Vm?Dee76SnP5wSz4UZ}E!nciFJz z^#NEN-*gZ@muwhtOP78?EyJ5OkOy^dxQ^}Rs?n=!TH>~Ehm^LBES6v!d7+8;pP$$o z2uv@A4S|OKqKI3ut}zYw@51`31eRg)N;)y06p9Xj}9J1;%uJRm^d!(ew%7~J(swgJ zx$ZFfC>kJoD*7m3-8xzaq(V@XRO@xqv6azB0V;s!u7IR?QuI-@NcV*KUAK=n=BF&r zIlpK?0rmA9#?|$`1ZPA{-?5G-5t5vFrz>;b0E z>wHK8HM4I!Y@x0M-4WFQ5c?3(M}{2NvfyX<&5S-$-(N)HD;3p@%~^?C$)qn|b;rfW$PMDf=?u(Si^o(Mxwsu> zc&~h?G_kfu8T{AttF&W(`{Y)x-WB{5^Z+13G>A6~q$By>QuO<~FSN8{o(~Y~G$&d! za~+ZX0Q`*oP^7qgX=QXL2q|C#z42@~sB!k&d0MTsUt>|JNS^jAAx&D)t-M=fk(P?I zB&$4;(kxJRV)~U5c$-0$wrgWY5byLE=`y6>&m!zX@-=B}Uzg^3F=L!Q4Z(-rv zU|vU~V+KwDTh9zc0y4M97i1&*7`f^=4CxV+XNA!KA7_aN?&Em9PMmVSt`oN!aN+`_ z{sbqk)GSU%G><%-Pg^H0@`lQnr2>+po=#lJXigltQhaJ~`Io?SfkNF!@1Moc zoe!So?t{01Ja}w4Qb^F+`rv8p*V)kC_~>Zse6YB+n}p`Q-+wTk^?GqJXLnzGa^vV7 z#yqOZjhO4~t$epe<4J82&YsYoXOEar?O=wp=ToDz_kOBy_C62VpW`J~|MGwT+yDIf zr#;Us^Vk1(oWK5;*MI--@qhfEuh#R||8?BI{?}js?br3|eEpCA|Ml-7m;FYA`Mt+-jgr4Nz*Kf{KMZjO53*kS10s=|6Uw~gLLdVDeRn%{Ip z8{Yievb}zO!?iEaVg2gHa;Yio zTGt)E_AesDmKU{&_rg!@N8dn{pC8ofyv-{d>|dnmAxHl=;O7Z2iWz?ce4U$zaf~l0 zE@v+&$XNs~;8APf`VrS~713JTR(a2tn{4Od-beqSg;Wn=WB8V@#D~LtjAci8_}+@85lztQn7I{w18jSCcKF6 zS4R!>tw(LChjS4=G`t$EeRwkQPiM%;)4Xr64`FHpiETRzS;Zo9(?cGKmmka~Jbj|$ zAq?d@#7c55=;<}Iz>iCR6FXi9M~_$>?qPyngz_}>$@OFD1nk=Dz;qUHd>CP~ptv}H zZE#>fX9?PX`h|{93}Hsh6@L6$tAI!D+5?1-Jv)JdXTP^Sq&41q7#8ptk&fwuysP+e zI9ETE9y;xz53#E=_BSy7*2aWpDNe%mIxL+=j5srVweexsNqqoC?|s0K9w%{@gt)3- z$JS8!Tu!5jl}AKWj~OGWG0;SJFme{XKo);k^v$`3Qz-#i;XD~ZpOI|gt%z& z9o?I;88>^VlokFY4IU(M0P)lKCpro?7huS|VOzvEd9o*he}hB}PBUWt z491VUY4QO$^qvouyDtb-LMg9k-g=m#6QhV*T0Cv|ZOr3wS!7zDqGvb=M;JigzI&Mj zY7{_5@D{?r>(}H5x{41zs(qv}4NxD9Lfd+B?$Oc2<`1Tbj~%btID!%IfUN=$JYUEDwRcX9u4BY)%muZE5L$0jfCADgjp{};G%|L{Iv-2Vl= zasP2|+&_TD{m1>z{o^Zd+&>x?_aAlV{xQIf`;WSFf6m3+Kk#F5|4}#Y9}Bj)e_+ba z{bO-A?jPXd{tF`aUobpZ%Fg|x<2UXf4axnrYvle2e%QFb_fWog^^N=cn40^?qAczo zCu(v3*tDJdkNb`L$JQ+FAJE4A$Gvg?2$fmf-%xV@)lm84jr&KpJNFM{S=>KHv~hn^ z5_A7iH|}qWM1JpeF!zr|+qgeABe{Q^sGa-A>08`?l%4y(5nFQqPx|}kkYO)oRpQPz zB(Q@^e$&!*bKo>ZotODh1VQyj5Dl|##|R)I$pV1eUHeT| zD{4f4g_z=rUcq#f4?7|1D-1Vgg8q&Mox(t)1)IU@_dh^hj}f<2U*v&YBOCJfTD%W% z``BFP+Az4pTmKJh+hF-HGwP#H?u&$q2b?8vk&1L^KOZHTCRLA3gq1UPrjpAQ{8(6F zV`De)McrIEwx{<+AOnbn8^E6rZ25D*hmV3$*k=bllVU>z1h9uQX!sc z+rOZw8$xxuc?p}8CcE6*De0)L=BKZ9z666U&)pS zqpu%Sj1h)KMUbaCShVrS@;RJ!?Zn{qfX{R>r66z&N{>&I)W|yEVy4L8g5Rn@#v1!y zCi5raHgK~TJU|9TQo_xnK0iPTU*EFmgtYZ2+j)ZsfP$bG*=-Za4SP?gK*f0Yws7_Z z^=>E@YLt~cED}u{!I=LGC%^9!vzkY)^~tdFY!8qk8WFr8>>&< za4w8pelT9ia}Rmzl!)J$KdE}EK`tkYeXND3xUoG_kgh-#YIK1@fw4&z**uPY{CKu{AWC+QMvt+0#ylK^V;@ zcY|(&ARZiiI8{AF7tQVZ-Ew9$M*_7OV|P>Z2K$ru6_!`dR;0}t!x%#=adHDb9}@)m zRYA(UHVA?@!6T>r&*y3Ub9B19cC7KgzYGHHq2dd3-A`~{f#|BqWogEHR*y$gR$pdAy=ES#2E$eHH6^IZgTEma5B}5BOj;S=(!{F>d@|!wQ ztV7&I4=P1tnUF=MGeZH><@DjTuQ;fk0UDk6A86&VQ&0jfa1QJ2Yp%mTpXU;)C75h( zq;iI832?P?Bq$Fu-vFA#Rf&ku9tGAH+)KlQ%2;1%LP)H?X$#WR8#0&<@wllFkFdL2 z7ot$QAcGF>KoRK{BjVLX(4>Gb_{Kj-`A`Ca>^Njii442C=Y*EN(RzJ@-1L^0Rvw<) zx6}vVgVd)t=s5CfjhtNbDXrjF>uK0!P)6Z_u1HNXR!0Pl4f#<+C3-k*i z!FRs1pi~(FuDnj+Ri80-d|;2O6hZiIvGNH+g34s!($K`7u^wTPcX*lynhAsZ zEecHq0c4-s)d67OzEuT60IzX|tCYnPI({q{eTC;*=833y$d^|Rh-U!_D-!zBjWmx= z%#_CpuU?c$)$gR|S*HsZ-21R$yjPwf?xP!I95xfhc7CcHifLS4`sx>C>^ zR`7Ek27Y=2V1b4m zt$=xqQ6stgH=hFpn%(3?x4Js|m@7LoCH`&+joC^N9;`Z7C zW+V^b_#k&Cz|f<1IAj6DkIA_LgyRD<`UDs+giWFY>T*Lc;SeHzak)8Rq zlo)&;FugLZ4dxnVnVEA9f6IqCfv{{3th&$bpW}8-?c)(Jl+P?E5c@Fsx<}ur4`bGM zfETRG;gFZ$z|G=oZwNZbx1q|7iz<3QVMd^fD;nqy5ZX2jCV2BRKqoQSjw?E27Kjy8 z4Ua^Ehwc|d0vS)VFcFLXkOct?XweAmdVtUsJ3Km;7S=*P?_5Y~L9tD7Zl9reA?)MC z@8h)qY4)i=8U{YVcL6^h$gKIWDki|FRTb-WR=~mEl>eKZOC!z<>u6}S`ClB4Y&Y?< z1Eb|^m~!Kiq2Xb~*fzO1uh)}*a-m=YRLLu>3)w-mVpG_VO=WxSuZ7|3~UI~*>)dCs57qzhQ0 z3QWEWdSj&eGjoN2s*}NS*w2BV2PxqO@>~^dAfGB)9$UzB`bSJ2pFTA|8iKg70m$(%73HNQ^xEr-g*#~0 z!mfcik^pr;I(8sOkr021nvq_0N>TZPVhRJw+~ou^n9uBzT=p>aM1V-x6o)?eX)jWj z6ZxUnNYaL+$cu7PblgW0=KNzlr||zUrDcH7?>Z?)G~DC@ad!bYi+!5}9%M28dEC0Z zVez?G#~%$3UHjh}kdP5Dv0@BPAW-TVK3y>ZI=%%(04T3CLQh!T#gVI)@sBk zFX$$3gZwp2vg>&Wo`-zgu+pT)k}hyzoOJG*03Y(-U~3!5WTl^ zxd2bnd&nt3EN;k?h-tPR&ht?lhh7Vu(IwRJgjt&5*q+D6<6JbN{X>!9>iYf31q?an z5{ZlXp9HP9XT^d`g-lf4;*yvqm$nTQBUFQy4c3A@@MP|;12mSM5zrt*Y8QDOxPM67}aoWEi=x^f>BJTXm*#$ zJwUD`!&=c0Ax{`1mnPK6C+_62aJbc_ye&UgFvA8=10Ds?9llCksXw9t>c4#4-(C$p z)Yf%}0?l9UEa2^N(RF4UH@poj#|QKj3hFJvXR6GH8jgJ-`@WE?Vdq7kco?Y3qasH5 z^X@cghU1K1m>ZEd6SE8fCcsCy7PvKdJQMW>&2K==10ZhLLff!?-1jCcgz;m48aaF{ zDcFK>k?h7AFl^D1LZ7}Hh1j-%Uf^ut3L{z6vG8glH~KS`2`m~WeMYq|yUViptVd2tJbK1T{CvI;)R2*$IU(6|a%pGOnQEG5Z=sELPmJ0keAs+(v^2%f&6eRmSxjAeUYQ2~M?ScThgSx^nX# zSQj`IaJw}~NLGXNBnRMGNb)8g2l-ga4|y3%HU-$Bpgt$Z2bJu_V%(bkyf^708tUBN z2z^3li0wOV!d+k;h6m~OxZpUnLS`TLjbhHIBscRK7D&5<~mil6H&QR4A8bf4K;R> z<#e_`HZC~NO%Dc+A@=fyEo8%v8@hr{CKF)XNWp9dz^hz`;TTkf?IM3rIf)DU^b2OR zd%Ng{6_e-+(d4pK^U_(aDL7UA9K6pd*|n+R>nV^wm%!%d2q`(mrQdMq>(}wmPrM?k$$wV*0ym_3 zAUt{*Uh&be=?nDIlJeclT4}xX*|5uKpS{HJ9{R8^s+J8rPtwB<9Zm#!Y+Qma>%m6i zrhUm6n>?x0YdUY-%Hf#L2cvJON(c}h02>Qs!NuS+I7gFM%hH@1XjEWB5Q7U$gwBu#%jT0ho{%Dt&%`l1_N~QpzVvcSz?p zD0n`L=XOTQ`8flK^Xt4ON{5L6eora{Q{Mz8s{N|BYefCXd?eI=iG_Wp9_sJqmPCE>t4j!;@q}F%Z7DEXGRMCXpk-r z>HMjq3MELu&vw8j8OSqJh4O5PIyCNf~F%EqH^nyTDvp|+)a>JWW=o8CAM_s74W}cwXF4y0T=zV0AWXY3GSC0T8J2DtN zK!!HUC`l)taBqX54ob$(DoC%3i8(3&UWjvtXtTguM#*fzX~f&;{en@l&_4d8 zd4pwsLM>IejW9}f`Xgbmbd-|d4XmIm-B?J_s8b>mw6vX78YNLoQdn@(-v>rV$zaXO zyXUqS2%q0vNG5{EHpMAbDNXI`#P2(7H{l9|k)O2220w?sO?I4%831S?Z8S>8I-NA+ z!0G16UA^fJ%CryPY-kU&L~uCBmhiwfc3`v*`j;L9c!M6#bL^9wFiPJ3lM990QDgE( ztRq9>PZ%XDuencJdl@Gh-_l7eL)k2Lu-Yh@EjO3F5}!bB0-VT&AO`#(QC@#!@W+1XUB_Yi}U}P=g1aaAN;TAoCOXF*xfGW$Sd&8%~jTNo4JOV8@eAuc8gK7t1gYpd28*Xplnf$zbvxd*JB% z<{6#r&0Y!ElV($0%&c9<`oUwq4ec8?p*UL+7p9T#lV0W7>b)8~wB}!b*@ZBcT=dCi z)|G#0ynLF|?tG&`u?#bvkwBMzXl0%?%0Tj#=iy!Ks_7 zig*j=B2VV$0^eF&q$Hm)^oRMfg4NJ# z1E|vFAA^Mjl25MdT+66^IC+GjmY3$jhbXsAXH1HV?Xfnwo}7yMlG_pV7L@a0fxZ~P z0SB-T1SFPDsx2wM{=0tjs5Cjcn2;Hodz8E)6s1OhUiKUTENu^O8d7LlkmA2yHTs|{$d{Zz9!Abx0HI^_F{J-S-yJ&c{g~E72b{ys`dI56_9BF^lLaC) z=!3U`cGM~Klrv+Dx39u)_|m}pI-Dez0?1tTD+k0c+^^BU(+>Q(s1^PmD5D($yE zmYVB2wpt4|VBHm)@yPuK5@pM^k(k!x{n4OAP&O%S3I`8OGk*`O1-$~l(a^{fLX^Pw zdghh85Y53$z-9j(6n2RDhioqQphQ;2&u+-dXus{b1+0hD2iIIogAU4_c~Ai{zg$Q_ z2`)O64RpV$vE@gyYSlPTRvmjWhj_L2Vj~ol=IupDZbs4O4`lBc@`SjVy=}RC$zH-z zR#;45@HXjV>`ZDzL;bk|EC z4SeOVz0j`)s@~PH8d6~Hidy;6u)bvd>PHKF@Ws@#fdsKL^I@Pm9XafJ-y&84EfX!| zZ4z8=%DtT_6NK1bXh2lXEk{1m_5dT{ZouFdw{qWJk}cG5343rdCP3Wz?)2dr%u5^t z6hEMd91TE(krN=K7#n%KbcQhLY0q#sI*@e|?^~Dtt|%ME*8^01VVD9I$RY}Acw777 z$f1vhwSns7N5f!E7CXAUA%+}X-cfmcqVoJi<@pnp$0sU}PgI_ts62n7^7w(uwq={4 zg{^#JXMC z1%Tvdj15SBmLRFnkuBzD(_%XL*(7>Dn-5T&GBY$~+ap6eI6Nw`HoNz1$C#C zP%t6qpi(zXd%l?2Kg7dM1q8x)40e@w-x_eS9!0)v9YhCkZ&ab%Q3$7^Ypt2_JUCOM z^&Yx6Uj<{d9lg=(rt<#K>5CW>s~2;|7X4hAVChE0x*`E$?DxUcuD2FZ7zm%e!PrtH zhNZP%$H#6bH^@P0^ZXbc;@ff0A3ma*UC{`@3r5LtBPUENoxv!t_X1+r`x## zeB9{iozJUcL#1&Z)fz2()>Y6LsjT6w!RKJy<5LmLT|2BPCe?>D{iOew66KylyEyMn zBNF>YmG_`8TUrZ@bxp>DYL69~BAWIB!mA16ZGB6#FWb#D9_t64mWkH17gAoz&ab@4 zv|K3jKm z=CuPb6Zs+*Et1Dw&rYqBw3@{O0h0L9-?MS=C4^}DG@^BRD>WXv^#;sP)MLKWrY}2! z)Vy7YTv3rBWY)zIdW3OP;^{eFULPXC1@D<2Ysnvjtx*C=SEA+La?6*^KcFbw z73YVfj*k_?I`qAexbnI5GbRG`W$THVx09{QrAXUCSEmGP`m%j&+#h&0C>u|aFI)HB z%-F$1Pp4_2H0*^pwfU-@X@-9k=g51q{JbVGZbp~UZKU4Jw@EHJXY zvyWs_hxYLqx;+7ud@JXw%)@=z14sx65v^N!2Zxor?s%-IjzNE!E?+haNZooSi)YN7 zw>^h1o3!!oI3!=T54<9(NhZ`i#|?R{8N*3cJ{q=rj$g`q&g#}HoiBYfZ1+28f0G|tof|_|D~J(i%anKaCFjJI9n)vPoXo0l#>$oRX#DFOPk7!#B@Yy$Hqd# zx287==$)=KL}NH{8gyZqt)an}%?TUmbB5lS(OvH9GwlI(-7!xI9)OU3381{nsXC;O zwaRo`s`PA^C(lV=HcOo!7J~6DyT5%*B zp8hFai%>c|Yi6prw)u#M#e5eN#%k1cAf`3f`|?(j>LE`dsk7?bpygF1H;?8wDSO3D zk9}`fCx2U-LXS++%KT7@A33%411qK=YiVWH%}gt&&wE`F26p`VSopv0#UD6&y(=f& zkY{vOTYx_rc-v+J?|hB^xsg?HKVUbV0@eY$abMe>ON53@IdA&1EtzvF>yf)>@}ABp z-vB3HSE%}A)=7D0906ZkILHl?S(%phU^0WGF91_!0m|4LXvXE1$VeYR{%^QJGGuOzYFQb530jp-rC3jn<|!341Ld*(To9-~40hE~&jzjrec3*-jHOhSI+5vovw^mYZx*Ype}iH2 zR;kM)8e%#qjTy;fY3x8D&Cb_vms5qyG1Dvs2#@80G+^~=%6(7x3oY=tTt7hEHp5o} zMBJ;BIN^Cj`7m47@r{;9UtLv?u`!D!h93}ub_!F>VKnT0vJ59;aO2fuO+|@MR1);z zIs=M0YuF*UEO?b^E&+!JZKZY9B|snC<2Hzy;Ie_+@~x_zZ#%`ZobXw`bMpr5qj1Q& zu{(pFy3DVSLW9f@&p|4|I5Ks*+T~P^comp@n0r2Q38ShaQ~N)YOYqPym<>n3h+ASd z?*K0*0%gY0SZ_p4-I!;9oq3W`hj@XfYC5W+vNA6n?{dMJHU4piLVTQ?$FhqY+mV=~ z{LN*X>+>wc8tcu$kj>TeV1f9DDXFl`+G zrgIqwS^8$f4UAxEWMrgzZcS+_cCCrBl+)!iUVk#7h<57*-gVo|!X#AN<8iaPM#w+` zi)LuH_qHf=omWk z?%XP^5iKVX9aD`(831FjSh8C8Q^j1SK_tVCG+=E+$RPoOQB;rqQgV6bbi*cLqi@v8 zHN=7z3uYBy22#?+mmrxKQ{CayH<7IJ`HdPPtf3Jwyx^H|m%qoMg*$avflVktjtW9m7|FHhSUKT=vpw%(n4Qc1Lb7Ayz(tuB#G#AQi!dQ!fGGB)Oke?n zq3ZmUi;8c!X0z0)_}uB@q{x_ERqy}}1vI=A4d_ku1GF`@3$}zEt zteg`fIQHr!ZT9j?MMM6$)AV9>=Y@VFuU2)BzsN^QFk8Of&hK`2jI}Nx({W; zH!@CQ|3TTKGBXALB{8oC<`;~Hiz(W0AB0@c4p5dA~X0>I+zaWWQouiu|-yA>2> z1~PoO;bw`31;%qiiBkY6wz47`8dM2NlM6SnhiZ6K{p~wbW8?);u5p2xYhSB>lLgWi z5)DFFZ;r$ry^9nCtM5B&b>PzoYGv7}N^rJ);5XANnPKvZ4UX7$P_hjhj(r{Pw{f(AEzm zQ$8Rtot$|c>&`G&CKx^fz9>|ZWp$s!>YwWXmCD`;Mczq6NV|RL*XK0Hh`BtheDaqD zFRI_z;Um_sqW~_ZcVa*4fBHfdV6QScXEGz=7y&Mz)PitIBinprktl} zX_Vf$5D!Je>*U+q0_L{`%sqd&gN20j(uRdyXHb*fwx&eDKoF&VAP|%)ND4`i-b0n% zi;zGl0-=Nw5fD&%QwUWQ1Suayx`PM4OT3}80L&p>*1|BdLR`>Jx5B7LG@#ageab1bc zJG5QAVqf&M9bxfhJZS?j!djSDRleGzZWpSN-#>iWoDws`?XpM}I@K9?&f58jE>D*u z_j$L57ZG_+9pKOAVWqQ~V94W;n$GLN*F9EHwFU-4EAlF|3S0_y9QnE{a2UFYK;_p_ zxtJydtt0jdAR1T)->l%99UAHR@MBcD97FDwMY^+N-94Rd&RKaa))Ibrvwh4 zPwJ6yjh&<;xqPpIa$_*8jjAg>SBM?wF$JP4t)X=X_!QGOV+8bLW^N5)&%w(YI5Ags3EEqsA26U+OrbU0`Ye>V;9(i!h2gzk}_A0pJ{I zMq?jj9BeINKYd2c9t$}Sf}d^325R@6F?i_&np9KMC!8v{N4|AV#-^foV;ChTQ^j?y zyo#eQ4924+3Pt@!@P(`v1R0!4=571Qq#Hn|VS$ZXM-zg~ckj_Zy}y7S6ghimd>?$! z^3j#5A9zRUuOIql#80BGcf2@URs6)Z)c$^T?coo=86coySxT&XXxMyskGp7`Vf)2p z$<-MOeT@AN1zLes%UImwbdwhSiQeJ)k*}OC5akT{JI^lnDa{_OM?Gj#M%chh$V^|S z$V?gG8y!BAI-C)XMseIs#Txxl;0OIUvOnmDO1IRb(=x6>fk5#`6)=8(OlX4)t5@i z)KNdVw*%KX7{w;O_wefTWz+LJdH!_N8A@jPupC2Qt90@t*aDfuA!}lF#swP(a%`)J zGn6zFUIk1)=gK&gfEg$#4?=Sf`2W(Ho6E9j&Vnh3CGDJ(9iJ8GH7nZpf?cG(b~Gze zZLQ?3*nM=?EZ=1NM72-E+F(CMz+_$4B)@@G@d&MD7Ar8rVJxwG?wf9Vy19JCrM}DZ ztzzRGk21elx-JzRyy@v%jj?4eDAP~(1o|havz0e-nsJ%Ny zSD!?w&m;#I^ryyGqE60oH^+yF9`TX#*HBiLn)?LqPdijO3y8ja#Fd7u!{}0X^8wC~ zdjPRj+Hdb;d!p1ORZJ+^NiiXszY}(2fweJdWtgXO?yW{4_p_BJHKzKcI?;A@E5&8A z@zI(R6d7??AP^BW{F46jX$RL0iK>3a2Tk^msx!yp;MVLFwI0997OLH5(bG|R4AxpuM*g|`Y9QWMNMZ3@R-JcrcW zdzId=vGrz~dP=<3iP^W!3Q1NuMc+k9$@19jdBr}BJTfo7l=kisa7i6U>)x%JY!h&F z^56-=$A4Vn zJWP#Pq;*tobCJ#~LZz+B3naKad9rq}6e;%7U!^BPZpO^cD>d9mdAheO zedemCB4ns^ND;dy*{F4~)e^Cp5i6&WS?t5oN?o81)zv1SWf*B%rdBrr_Qu3MUuk2h z%W#881>MF|nSJej*jda9#op;ztpmRq)mNVHoJ+2|siyIMsk2b3RRzjPl!=)a$`wS+ zcdmTtp4Xz?`iNcM>1cByf5i>8g;6{hosYaBFy&U$+O&sqTn6~;@}AH9r={Y8y}EB8 z{VScwsEbTQ=i#4#K?NNF5P7!*JsNOy18TW&q@ zI~w}Sn3pv44Bsl1P~9{h3T-lS#uFWgr4J4b?}ny7I`yg86%sEFcj*`AD^c4zJnCEi zl{oNILP)KUcpAPG@SEmyrWXnm9l4zS+^vn@9AVwz)=7C;6UR!>#=zs}K6oBf!!MZ- z)ZcD$ZTXIq{iEU$Bc~TfvviZPZKj-&N?J8(EAG8Ip9jeRSv+cm%Lk8=sm^=|@;H%` z7cfux7$##z8u6(vn3{a8TQ3Zk%WENzT$@hK3%Ht*$Gr;YluLfJ?(6El8gz6CD)$$a zJTjcu+S5NWOlj-LwKF3Y=GrM(;B1dnygEn7rXeA&9wV=vUmhsvh zyxN%4XKN$sqlvGS3pW*+x-V|a2^G6~cnYswF}4rZ(X^b3xo(8paq)nNOGuFYe$GBS zi0zLII4Wl`bqb-f54M`p=vqwL;HPkB-E4YEbN8(19PsZOXxgK~WO zB!5g$>d2qOttcNqrb`Kaf+#`zuCkORCnr)I=AH$N$lh>&v&sqp1?`A*RmV!@cqfg; zi+OvFg1&b zLQC^%`TdJ}A~=4sPwdW%G|LUeO$o)o(igYYx{QXJkjj zc$tcu{d$k!$LlWYaH22DADKXIi_S(ZXkO#&KJMSHj4O%gxRQLr6J`-B(k_$b9Q9H+ zn>sj~E=Cu{kovNVKH2iY!$IRhz1|%J;w!)~7I})+&y#0!X8H1UE7rGp>I}4 zSHhrMIZan;Q)=}FKv=c*dF@ZDYVjI4< zttZK3U6S^w2V*@_#B#W@OFumhy#ibGW!g;ix(;hW-xMY;X5U1TuQs_OLT61m6R#wv zbhN@ODx~hm96LWxlV#BZ^=b6sQPZ)ANCbbu3azcp8KbWb%eU9>UaNHB_bsqCLz6k>iOcpCQbM%m+<3*IAHxtyJ11c8F*E>&~*EFN@S|E z)8_jn`il_*E3fOeG;_pazt}rCub-8Dm8f&9w zsAP+1 z;1{EG#nygZS-`UTESR-;J2snFS^Z7SzP$RWjlzs%N;}?s&VlFJ(H?MGxShh zw;XQuR?)us+DU6+Rl-HUu>JaYo9Jj|u5zfe6(3t?Y*u9A&!*a-(#)WoWOR+eXM(vW z%Zp9mJx>=6Miyl&TG8Un*&A4U-RGjL&v4E?HH#TJUt(VAPy=(KZ#DAp9+F0%nPc}s z0BWP8!}U~DgmIdu$mqu#cnZ{HUx;0sVYUs3*t#`*V0ywlAN=zPn`3FLyR2Z8BZsFt z5Am{15`UU};IBlt=+M-b41tH-#Bv`F`S0UA z%Nbp&VeL$OzIgRrp!M=F=VuR)7$N52r3L-O_VJc$WvDfF1J)iUAlYWd;jlpR;(3yGe{$aNs+7jOucIMUJ+yMIjTWO8+Zzj;ZM8O{2`hS(FX6| zzC>x3i|7p-C2{R&RDWboy)l7#C#(eB*q{^cJ2RY`4tm2}U#7!roB-KUuHjj7u|%FV zPRP2Ixq8>Ot--479M-7$Gv%(WuygmqT|R2aref2vX(I!y0X-ud%)6ytZS=iCnS;t` zFUj0DtnA2>$fLJi0G+(8j%3;kRRCKvfev=nt0_Z_ynV;E3rqS$zT&xwcjeDCWeHEB z!Z{Kd9-hNiC$q(;N=Cic8{$5GX0x!FV|QM%P7YMo@rlSJtznyNW~0BJ>~Q6B$+3`i zUoVprGs)A5J%L-HLBFoKTyJ}Ff*$5_Gi&jlEoI-E+ZZRpQblB68hOO-ke{CyiHpe> z<9?6l<|13_$ZZyS9| z&aRZ z*2Qst2))1Ptpf|os$39&^i=L6W~^092B9FO^QB3l$hXZVF#o=AI9qArnqM>v=fh5z z&7AXHvTFDzJtr`$_lCfS$L-feKkpxq*Ec6r$LeDaycjerJ4`ZP#%pbw=WBF=+s_Bf zn<}?@u{Uf47K);!=I5ajf`-R=qr@b+gXfU>j`W&i!s+z#Z|2|SYt29$-i;6xh{O2) zvHY+%fiNf-3jSj#D+3{>fqrhmuDC$3q`#ZHCC>ILOcnu^h099;AzHLWL4LFu+VFo| zFF(9CCI|s01zUx}V#B3$YBu`1|ABzz{UXhk&Dj zu+*`YMF;!%U@>_7A1s!hUIZ}h{Wm5Vur)4_KuZmllcnWDD!@@lxvOwl)PKPK3nJLa zD+CArg9@VO=ZnJz;zFgs-u{>%PXZ1D4*6#Xlq^CPCIwVg{SO*ACNnnkDg^z_NRkyjqSMLoRzS`>r)@ z_wC0r6RIcYBe4<{_g7qv#F^1ems8LO*9|?|vI~|yP$#%?))c?)7Gq>*DoItYQ`6t6 zNum@X+>D~Gp2nyu+}>yk;PbRnVpYgke$XB14}7v`F?tfXYI(b|S=i3zTfA2OY6`H~ z*MOUiX%%rkk?U_goOmOmi{~hdqc?fr$MT!1cl0{+onblm148ffecXEu*pMvVVUO=( z?tdSiQd2?|TRzx(=bD2)c3#swv*#|opL!~)Bj}tS?_c)+s1x>o4#d_R=MIGE3p<|EK``-(}$H;&S+QaBQTz zulqGyA6p9BDHwHmxs->4%+P0~J~B+KPl?`6Vqv5sWS(*Ozl;!qFo8kDKpF=~1WkQF LF) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/images/networkflow.pdf b/docs/src/images/networkflow.pdf deleted file mode 100644 index 5842bd290d3dac8635a9764c2f0ebea1891695d0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 41059 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%0D@~RekBZ<5cko@m|6{{!Dqx(4P᫓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 diff --git a/docs/src/images/networkflow.svg b/docs/src/images/networkflow.svg new file mode 100644 index 00000000..2cc6ab5c --- /dev/null +++ b/docs/src/images/networkflow.svg @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +A + + + +B + + + +C + + +0 < g +A +< G +A + + +0 < g +B +< G +B + + +0 < g +C +< G +C +F +BA +< f +AB +< F +AB + + + + + + + + + + + + + + + + + + + + +Load + + +Load + + +Load + + diff --git a/docs/src/images/resourceparameters.pdf b/docs/src/images/resourceparameters.pdf deleted file mode 100644 index d5a65d1886e664389f219cdf7c72d30f282b67e6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 56499 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 D_g%TN diff --git a/docs/src/images/resourceparameters.svg b/docs/src/images/resourceparameters.svg new file mode 100644 index 00000000..222b3a0f --- /dev/null +++ b/docs/src/images/resourceparameters.svg @@ -0,0 +1,68 @@ + + + + + + + + + + + + + + + + + + + +1 + + + + + + + + + + + + + +4 +5 +3 +2 +6 +GeneratorStorage +Inflow Capacity (1) +ChargeCapacity(2) +Discharge Capacity (3) +GridInjection Capacity (4) +GridWithdrawalCapacity (5) +Energy Capacity (6) + +Storage +Charge Capacity (1) +Discharge Capacity (2)Energy Capacity (3) + + + + + + +3 +1 +2 + +Generator +Generation Capacity (1) + + +1 + + + + diff --git a/docs/src/index.md b/docs/src/index.md index 87242090..0c0f515d 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -14,7 +14,7 @@ PRAS maps a provided representation of a power system to a probabilistic descrip ```@raw html
    -PRAS model structure and corresponding assessment function arguments +PRAS model structure and corresponding assessment function arguments
    PRAS model structure and corresponding assessment function arguments
    ``` From 71591c6ae4a2c38338255d6d64b3d9abab012fab Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Tue, 7 Oct 2025 19:28:01 -0600 Subject: [PATCH 25/25] Change stable docs pointer to original PRAS website for now --- README.md | 2 +- docs/Project.toml | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a4021a86..5183ca5d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![PRASCapacityCredits.jl Tests](https://github.com/NREL/PRAS/actions/workflows/PRASCapacityCredits.jl.yml/badge.svg?branch=main)](https://github.com/NREL/PRAS/actions/workflows/PRASCapacityCredits.jl.yml) [![codecov](https://codecov.io/gh/NREL/PRAS/branch/main/graph/badge.svg?token=WiP3quRaIA)](https://codecov.io/gh/NREL/PRAS) -[![docsstable](https://img.shields.io/badge/docs-stable-blue.svg)](https://nrel.github.io/PRAS/stable) +[![docsstable](https://img.shields.io/badge/docs-stable-blue.svg)](https://nrel.github.io/PRAS/) [![docsdev](https://img.shields.io/badge/docs-dev-blue.svg)](https://nrel.github.io/PRAS/dev) [![DOI](https://img.shields.io/badge/DOI-10.11578/dc.20190814.1-blue.svg)](https://www.osti.gov/biblio/1557438) diff --git a/docs/Project.toml b/docs/Project.toml index 51068456..4f3c2baa 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,9 +1,12 @@ [deps] +DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" +PRASCapacityCredits = "2e1a2ed5-e89d-4cd3-bc86-c0e88a73d3a3" +PRASCore = "c5c32b99-e7c3-4530-a685-6f76e19f7fe2" +PRASFiles = "a2806276-6d43-4ef5-91c0-491704cd7cf1" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" -DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" [compat] Documenter = "1"