Merge pull request #24 from NREL-Sienna/jm/fix_docstrings

Add docstrings and make them available in documenter.jl build
NREL-Sienna · Nov 20, 2024 · fa0a8b2 · fa0a8b2
2 parents 03c2134 + 9caab91
commit fa0a8b2
Show file tree

Hide file tree

Showing 25 changed files with 567 additions and 101 deletions.
diff --git a/docs/make.jl b/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",

diff --git a/docs/src/api/internal.md b/docs/src/api/internal.md
@@ -1,6 +1,6 @@
 # Internal API
 
 ```@autodocs
-Modules = [PRASInterface]
+Modules = [PRASInterface, PRAS]
 Public = false
 ```
diff --git a/docs/src/api/public.md b/docs/src/api/public.md
@@ -1,6 +1,34 @@
 # Public API Reference
 
-```@autodocs
-Modules = [PRASInterface]
-Public = true
+```@docs
+PRASInterface
+generate_pras_system
+PRAS
+SystemModel
+assess
+SequentialMonteCarlo
+Shortfall
+Surplus
+Flow
+Utilization
+StorageEnergy
+GeneratorStorageEnergy
+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!
+ShortfallSamples
+SurplusSamples
+FlowSamples
+UtilizationSamples
+StorageEnergySamples
+GeneratorStorageEnergySamples
+GeneratorAvailability
+GeneratorStorageAvailability
+LineAvailability
 ```
diff --git a/src/PRAS2PSY.jl b/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

diff --git a/src/PRASBase/SystemModel.jl b/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}

diff --git a/src/PRASBase/read.jl b/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)

diff --git a/src/PRASInterface.jl b/src/PRASInterface.jl
@@ -1,14 +1,56 @@
+"""
+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
+# ResultSpecs
+export Shortfall
+export ShortfallSamples
+export Surplus
+export SurplusSamples
+export Flow
+export FlowSamples
+export Utilization
+export UtilizationSamples
+export StorageEnergy
+export StorageEnergySamples
+export GeneratorStorageEnergy
+export GeneratorStorageEnergySamples
+export GeneratorAvailability
+export StorageAvailability
+export GeneratorStorageAvailability
+export LineAvailability
+
+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 +70,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 +90,32 @@ 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.ShortfallSamples
+import .PRAS.Surplus
+import .PRAS.SurplusSamples
+import .PRAS.Flow
+import .PRAS.FlowSamples
+import .PRAS.Utilization
+import .PRAS.UtilizationSamples
+import .PRAS.StorageEnergy
+import .PRAS.StorageEnergySamples
+import .PRAS.GeneratorStorageEnergy
+import .PRAS.GeneratorStorageEnergySamples
+import .PRAS.GeneratorAvailability
+import .PRAS.StorageAvailability
+import .PRAS.GeneratorStorageAvailability
+import .PRAS.LineAvailability
+
+import .PRAS.SystemModel
+
 include("util/definitions.jl")
 include("util/runchecks.jl")
 

diff --git a/src/PSY2PRAS.jl b/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};

diff --git a/src/ResourceAdequacy/metrics.jl b/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
 

diff --git a/src/ResourceAdequacy/results/availability.jl b/src/ResourceAdequacy/results/availability.jl
@@ -11,8 +11,14 @@ getindex(x::AbstractAvailabilityResult, name::String, ::Colon) =
 getindex(x::AbstractAvailabilityResult, ::Colon, ::Colon) =
     getindex.(x, names(x), permutedims(x.timestamps))
 
-# Full Generator availability data
+"""
+    GeneratorAvailability
 
+Generator availability represents the availability of generators at timestamps
+in a GeneratorAvailabilityResult with a (generators, timestamps, samples) matrix API.
+
+No averaging occurs.
+"""
 struct GeneratorAvailability <: ResultSpec end
 
 struct GeneratorAvailabilityResult{N, L, T <: Period} <: AbstractAvailabilityResult{N, L, T}
@@ -30,8 +36,14 @@ function getindex(x::GeneratorAvailabilityResult, g::AbstractString, t::ZonedDat
     return vec(x.available[i_g, i_t, :])
 end
 
-# Full Storage availability data
+"""
+    StorageAvailability
+
+Storage availability represents the availability of storage resources at timestamps
+in a StorageAvailabilityResult with a (storages, timestamps, samples) matrix API.
 
+No averaging occurs.
+"""
 struct StorageAvailability <: ResultSpec end
 
 struct StorageAvailabilityResult{N, L, T <: Period} <: AbstractAvailabilityResult{N, L, T}
@@ -49,8 +61,14 @@ function getindex(x::StorageAvailabilityResult, s::AbstractString, t::ZonedDateT
     return vec(x.available[i_s, i_t, :])
 end
 
-# Full GeneratorStorage availability data
+"""
+    GeneratorStorageAvailability
 
+Generator storage availability represents the availability of generatorstorage resources at timestamps
+in a GeneratorStorageAvailabilityResult with a (generatorstorages, timestamps, samples) matrix API.
+
+No averaging occurs
+"""
 struct GeneratorStorageAvailability <: ResultSpec end
 
 struct GeneratorStorageAvailabilityResult{N, L, T <: Period} <:
@@ -73,8 +91,14 @@ function getindex(
     return vec(x.available[i_gs, i_t, :])
 end
 
-# Full Line availability data
+"""
+    LineAvailability
+
+Line availability represents the availability of lines at timestamps
+in a LineAvailabilityResult with a (lines, timestamps, samples) matrix API.
 
+No averaging occurs.
+"""
 struct LineAvailability <: ResultSpec end
 
 struct LineAvailabilityResult{N, L, T <: Period} <: AbstractAvailabilityResult{N, L, T}