Add docstrings and make them available in documenter.jl build

docs/make.jl

@@ -10,7 +10,7 @@ pages = OrderedDict(
 )
 
 makedocs(
-    modules=[PRASInterface],
+    modules=[PRASInterface, PRAS],
     format=Documenter.HTML(prettyurls=haskey(ENV, "GITHUB_ACTIONS")),
     sitename="PRASInterface.jl",
     authors="Surya Dhulipala, Joseph McKinsey, José Daniel Lara",

docs/src/api/internal.md

@@ -1,6 +1,6 @@
 # Internal API
 
 ```@autodocs
-Modules = [PRASInterface]
+Modules = [PRASInterface, PRAS]
 Public = false
 ```

docs/src/api/public.md

@@ -1,6 +1,20 @@
 # Public API Reference
 
-```@autodocs
-Modules = [PRASInterface]
-Public = true
-```
+```@docs
+PRASInterface
+generate_pras_system
+PRAS
+SystemModel
+assess
+SequentialMonteCarlo
+Shortfall
+LOLE
+EUE
+val
+stderror
+generate_outage_profile
+generate_csv_outage_profile
+add_csv_time_series!
+add_csv_time_series_single_stage!
+make_generator_outage_draws!
+```

src/PRAS2PSY.jl

@@ -1,5 +1,5 @@
 """
-generate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)
+    generate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)
 
 Process the assess results to get timeseries of generator status and include
 this timeseries data to the corresponding component in PSY System and exported
@@ -126,7 +126,7 @@ function generate_outage_profile(
 end
 
 """
-generate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)
+    generate_outage_profile(pras_system,num_runs,psy_sys,num_scenarios,location)
 
 Process the assess results to get timeseries of generator status and include
 this timeseries data to the corresponding component in PSY System and exported

src/PRASBase/SystemModel.jl

@@ -1,3 +1,16 @@
+"""
+    SystemModel
+
+SystemModel is the primary data structure for Probabilistic Resource Adequacy Studies (PRAS).
+
+You can also load a `SystemModel` from an appropriately-formatted HDF5 file on disk.
+
+# Examples
+
+```julia
+pras = SystemModel("path/to/pras.pras")
+```
+"""
 struct SystemModel{N, L, T <: Period, P <: PowerUnit, E <: EnergyUnit}
     regions::Regions{N, P}
     interfaces::Interfaces{N, P}

src/PRASBase/read.jl

@@ -1,8 +1,3 @@
-"""
-    SystemModel(filename::String)
-
-Load a `SystemModel` from an appropriately-formatted HDF5 file on disk.
-"""
 function SystemModel(inputfile::String)
     system = h5open(inputfile, "r") do f::File
         version, versionstring = readversion(f)

src/PRASInterface.jl

@@ -1,14 +1,39 @@
+"""
+PowerSystems Interface for Probabilistic Resource Adequacy Studies (PRAS)
+
+# Key Functions
+
+  - [`generate_pras_system`](@ref): convert PSY to PRAS model
+  - [`assess`](@ref): assess PRAS model
+
+# Key PRAS Types
+
+  - [`SystemModel`](@ref): PRAS data structure
+  - [`SequentialMonteCarlo`](@ref): method for PRAS analysis
+  - [`Shortfall`](@ref): PRAS metric for missing generation
+  - [`LOLE`](@ref): PRAS metric for loss of load expectation
+  - [`EUE`](@ref): PRAS metric for energy unserved expectation
+"""
 module PRASInterface
 #################################################################################
 # Exports
 #################################################################################
 export generate_pras_system
+export PRAS
+export SystemModel
+export assess
+export SequentialMonteCarlo
+export Shortfall
+export LOLE
+export EUE
+export val
+export stderror
 export generate_outage_profile
 export generate_csv_outage_profile
 export add_csv_time_series!
 export add_csv_time_series_single_stage!
 export make_generator_outage_draws!
-export PRAS
+
 #################################################################################
 # Imports
 #################################################################################
@@ -28,6 +53,17 @@ const PSY = PowerSystems
 # Includes
 #################################################################################
 
+"""
+    PRAS
+
+Module for Probabilistic Resource Adequacy Studies (PRAS).
+
+Re-exported in PRASInterface
+
+# Source
+
+https://github.com/NREL/PRAS.jl
+"""
 module PRAS
 using Reexport
 const PRAS_VERSION = "v0.6.0"
@@ -37,6 +73,15 @@ include("ResourceAdequacy/ResourceAdequacy.jl")
 include("CapacityCredit/CapacityCredit.jl")
 end
 
+import .PRAS.assess
+import .PRAS.LOLE
+import .PRAS.EUE
+import .PRAS.val
+import .PRAS.stderror
+import .PRAS.SequentialMonteCarlo
+import .PRAS.Shortfall
+import .PRAS.SystemModel
+
 include("util/definitions.jl")
 include("util/runchecks.jl")
 

src/PSY2PRAS.jl

@@ -20,7 +20,7 @@ Sienna/Data PowerSystems.jl System is the input and an object of PRAS SystemMode
 # Examples
 
 ```julia-repl
-julia> make_pras_system(psy_sys)
+julia> generate_pras_system(psy_sys)
 PRAS SystemModel
 ```
 """
@@ -879,6 +879,23 @@ function generate_pras_system(
     end
 end
 
+"""
+    generate_pras_system(sys_location::String, aggregation; kwargs...)
+
+Generate a PRAS SystemModel from a Sienna/Data PowerSystems System JSON file.
+
+# Arguments
+
+  - `sys_location::String`: Location of the Sienna/Data PowerSystems System JSON file
+  - `aggregation::Type{AT}`: Aggregation topology type
+  - `availability::Bool`: Availability of components in the System
+  - `lump_region_renewable_gens::Bool`: Lumping of region renewable generators
+  - `export_location::Union{Nothing, String}`: Export location of the .pras file
+
+# Returns
+
+  - `PRAS.SystemModel`: PRAS SystemModel
+"""
 function generate_pras_system(
     sys_location::String,
     aggregation::Type{AT};
@@ -905,4 +922,4 @@ function generate_pras_system(
         lump_region_renewable_gens=lump_region_renewable_gens,
         export_location=export_location,
     )
-end
+end

src/ResourceAdequacy/metrics.jl

@@ -54,8 +54,11 @@ end
 Base.isapprox(x::ReliabilityMetric, y::ReliabilityMetric) =
     isapprox(val(x), val(y)) && isapprox(stderror(x), stderror(y))
 
-# Loss-of-Load Expectation
+"""
+    LOLE
 
+Loss of load expectation metric. Contains a mean and standard error estimate.
+"""
 struct LOLE{N, L, T <: Period} <: ReliabilityMetric
     lole::MeanEstimate
 
@@ -83,8 +86,11 @@ function Base.show(io::IO, x::LOLE{N, L, T}) where {N, L, T}
     )
 end
 
-# Expected Unserved Energy
+"""
+    EUE
 
+Expected unserved energy expectation metric. Contains a mean and standard error estimate.
+"""
 struct EUE{N, L, T <: Period, E <: EnergyUnit} <: ReliabilityMetric
     eue::MeanEstimate
 

src/ResourceAdequacy/results/shortfall.jl

@@ -1,4 +1,12 @@
+
+"""
+    Shortfall
+
+Shortfall metric represents lost load at regions and timesteps
+in ShortfallMatrix with a (regions, timestamps) matrix API.
+"""
 struct Shortfall <: ResultSpec end
+
 abstract type AbstractShortfallResult{N, L, T} <: Result{N, L, T} end
 
 # Colon indexing

src/ResourceAdequacy/simulations/sequentialmontecarlo/SequentialMonteCarlo.jl

@@ -2,6 +2,29 @@ include("SystemState.jl")
 include("DispatchProblem.jl")
 include("utils.jl")
 
+"""
+    SequentialMonteCarlo(;
+        samples::Int=10_000,
+        seed::Integer=rand(UInt64),
+        verbose::Bool=false,
+        threaded::Bool=true
+    )
+
+Sequential Monte Carlo simulation parameters for PRAS analysis
+
+It it recommended that you fix the random seed.
+
+# Arguments
+
+  - `samples::Int=10_000`: Number of samples
+  - `seed::Integer=rand(UInt64)`: Random seed
+  - `verbose::Bool=false`: Print progress
+  - `threaded::Bool=true`: Use multi-threading
+
+# Returns
+
+  - `SequentialMonteCarlo`: PRAS analysis method
+"""
 struct SequentialMonteCarlo <: SimulationSpec
     nsamples::Int
     seed::UInt64
@@ -20,6 +43,22 @@ struct SequentialMonteCarlo <: SimulationSpec
     end
 end
 
+"""
+    assess(system::SystemModel, method::SequentialMonteCarlo, resultspecs::ResultSpec...)
+
+Run a Sequential Monte Carlo simulation on a `system` using the `method` data
+and return `resultspecs`.
+
+# Arguments
+
+  - `system::SystemModel`: PRAS data structure
+  - `method::SequentialMonteCarlo`: method for PRAS analysis
+  - `resultspecs::ResultSpec...`: PRAS metric for metrics like [`Shortfall`](@ref) missing generation
+
+# Returns
+
+  - `results::Tuple{Vararg{ResultAccumulator{SequentialMonteCarlo}}}`: PRAS metric results
+"""
 function assess(
     system::SystemModel,
     method::SequentialMonteCarlo,

src/util/definitions.jl

@@ -1,9 +1,19 @@
-# DEFAULT outage data which is used when outage_flag is set to FALSE
-# Based on ERCOT historical data
+# TODO: OUTAGE_INFO FILE: this should probably be an artifact 
+"""
+    DEFAULT outage data which is used when outage_flag is set to FALSE
+
+Based on ERCOT historical data
+"""
 const OUTAGE_INFO_FILE =
     joinpath(@__DIR__, "descriptors", "outage-rates-ERCOT-modified.csv")
 
-# ACBranch Types
+"""
+    Supported DC branch Types
+"""
 const HVDCLineTypes = Union{PSY.TwoTerminalHVDCLine, PSY.TwoTerminalVSCDCLine}
+
+"""
+    Supported Transformer Types
+"""
 const TransformerTypes =
     [PSY.TapTransformer, PSY.Transformer2W, PSY.PhaseShiftingTransformer]