From 3bf2eaddaefc41e03a9b57399d553fb4710a17c3 Mon Sep 17 00:00:00 2001 From: juflorez Date: Fri, 24 Oct 2025 15:46:59 -0600 Subject: [PATCH 1/7] add dr to spec.md --- docs/src/SystemModel_HDF5_spec.md | 57 +++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index ee0d3eb5..8da196ad 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -26,9 +26,9 @@ will likely have ".h5" or ".hdf5" extensions), and is purely optional. ## PRAS terminology In the following specification, generators, generator-storage units, storage -devices, and lines are sometimes refered to generically as "resources". -Similarly, regions (a grouping of generators, generator-storage units, and -storage devices) and interfaces (a grouping of lines) are sometimes referred +devices, demand response devices, and lines are sometimes refered to generically as "resources". +Similarly, regions (a grouping of generators, generator-storage units, +storage, and demand response devices) and interfaces (a grouping of lines) are sometimes referred to generically as "resource collections". ## HDF5 File Structure @@ -158,6 +158,7 @@ The file must include at least one of: The file may include (optional): - `storages`, containing datasets describing storage devices in the system + - `demandresponses`, containing datasets describing demand response devices in the system - `interfaces`, containing datasets describing collections of lines between regions in the system. This group **must** be included if `lines` is included and **must not** be included if `lines` is omitted. @@ -361,6 +362,56 @@ generator-storage devices: transitions from forced outage to operational during a given simulation timestep, for each generator-storage unit in each timeperiod. Unitless. +#### `demandresponses` group + +Information relating to the demand response only devices of the represented system is +stored in the `demandresponses` group inside the root group. This group should contain +nine datasets, one (named `_core`) providing core static data about each region +and nine providing (potentially) time-varying data. + +The `_core` dataset should be a vector / one-dimensional array storing instances of +a compound datatype with the following fields (in order): + + 1. `name`: 128-byte ASCII string. Stores the **unique** name of each demand response. + 2. `category`: 128-byte ASCII string. Stores the category of each demand response. + 3. `region`: 128-byte ASCII string. Stores the region of each demand response. + +Each demand response in the system corresponds to a single instance of the compound +datatype, so the vector should have as many elements as there are demand response in +the system. + +The `demandresponse` group should also contain the following datasets describing +(potentially) time-varying properties of the system demand resposne devices: + + - `borrowcapacity`, as unsigned 32-bit integers representing maximum available + borrowing capacity for each demand response unit in each timeperiod, expressed in + units given by the `power_units` attribute. + - `paybackcapacity`, as unsigned 32-bit integers representing maximum + available payback capacity for each demand response unit in each timeperiod, + expressed in units given by the `power_units` attribute. + - `energycapacity`, as unsigned 32-bit integers representing maximum + available borrowed load demand response capacity for each demand response unit in each timeperiod, + expressed in units given by the `energy_units` attribute. + - `borrowefficiency`, as 64-bit floats representing the ratio of load + injected into the demand response device's reservoir to load withdrawn + from the grid, for each demand response unit in each timeperiod. Unitless. + - `paybackefficiency`, as 64-bit floats representing the ratio of load + injected into the grid to load withdrawn from the demand response device's + reservoir, for each demand response unit in each timeperiod. Unitless. + - `borrowed_energy_interest`, as 64-bit floats representing the interest borrowed load incurs + across each timestep for each demand response device. A value greater than zero is growth, + while a value less than zero is borrowed load decay. Unitless. + - `allowablepaybackperiod`, as unsigned 32-bit integers representing the maximum number + of time steps a demand response device can hold borrowed load. Any energy still + contained at the end of the period will be counted as unserved load for that hour. + Expressed in units given by the `timestep_unit` attribute. + - `failureprobability`, as 64-bit floats representing the probability the unit + transitions from operational to forced outage during a given simulation + timestep, for each demand response unit in each timeperiod. Unitless. + - `repairprobability`, as 64-bit floats representing the probability the unit + transitions from forced outage to operational during a given simulation + timestep, for each demand response unit in each timeperiod. Unitless. + #### `interfaces` group Information relating to transmission interfaces between regions of the From 60b48c7bae07be49fbf29861e35a6599329d42c2 Mon Sep 17 00:00:00 2001 From: juflorez Date: Fri, 24 Oct 2025 15:48:02 -0600 Subject: [PATCH 2/7] typo fix? --- docs/src/SystemModel_HDF5_spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index 8da196ad..ae8f6032 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -265,7 +265,7 @@ a compound datatype with the following fields (in order): 2. `category`: 128-byte ASCII string. Stores the category of each generator. 3. `region`: 128-byte ASCII string. Stores the region of each generator. -Each generator in the system corresponds to a single instance of the compound +Each storage in the system corresponds to a single instance of the compound datatype, so the vector should have as many elements as there are storages in the system. From 91eb2eaa535c4e3606fe68f5a19e4c6319a47c69 Mon Sep 17 00:00:00 2001 From: juflorez Date: Fri, 24 Oct 2025 16:08:53 -0600 Subject: [PATCH 3/7] fix prior typo part 2 --- docs/src/SystemModel_HDF5_spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index ae8f6032..dca1d642 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -261,9 +261,9 @@ and eight providing (potentially) time-varying data. The `_core` dataset should be a vector / one-dimensional array storing instances of a compound datatype with the following fields (in order): - 1. `name`: 128-byte ASCII string. Stores the **unique** name of each generator. - 2. `category`: 128-byte ASCII string. Stores the category of each generator. - 3. `region`: 128-byte ASCII string. Stores the region of each generator. + 1. `name`: 128-byte ASCII string. Stores the **unique** name of each storage. + 2. `category`: 128-byte ASCII string. Stores the category of each storage. + 3. `region`: 128-byte ASCII string. Stores the region of each storage. Each storage in the system corresponds to a single instance of the compound datatype, so the vector should have as many elements as there are storages in From b39a1eac03c33a3b7ccd739f7da6380d34cbb33f Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Mon, 3 Nov 2025 19:36:58 -0700 Subject: [PATCH 4/7] Update README --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5183ca5d..aa4ad2e2 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,9 @@ [![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 -bulk power system resource adequacy analysis and capacity credit calculation. -The most recent documentation report (for version 0.6) is available +bulk power system resource adequacy analysis and capacity credit calculation. Latest +documentation is available [here](https://nrel.github.io/PRAS/). +The citable documentation report for v0.6 is available [here](https://www.nrel.gov/docs/fy21osti/79698.pdf). # Installation @@ -60,5 +61,5 @@ println("Total system $(EUE(shortfall))") # Total system EUE = 0.00000 MWh/8784h ``` -The [Getting Started](docs/getting-started.md) document provides more information +The [Getting Started](docs/src/quickstart.md) document provides more information on using PRAS. From 90ebf713013165ea420eb177e0628a0439c01efb Mon Sep 17 00:00:00 2001 From: Srihari Sundar Date: Tue, 4 Nov 2025 06:30:36 -0700 Subject: [PATCH 5/7] Point to getting started on docs website rather than md file --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aa4ad2e2..14508eba 100644 --- a/README.md +++ b/README.md @@ -61,5 +61,5 @@ println("Total system $(EUE(shortfall))") # Total system EUE = 0.00000 MWh/8784h ``` -The [Getting Started](docs/src/quickstart.md) document provides more information +The [Getting Started](https://nrel.github.io/PRAS/dev/quickstart/) page provides more information on using PRAS. From 3176a4d2ce11ef5ca9cf065a5c88539a76729cf1 Mon Sep 17 00:00:00 2001 From: juflorez Date: Tue, 4 Nov 2025 09:10:27 -0700 Subject: [PATCH 6/7] simplify borrowed load capacity --- docs/src/SystemModel_HDF5_spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index dca1d642..8b1e9765 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -390,7 +390,7 @@ The `demandresponse` group should also contain the following datasets describing available payback capacity for each demand response unit in each timeperiod, expressed in units given by the `power_units` attribute. - `energycapacity`, as unsigned 32-bit integers representing maximum - available borrowed load demand response capacity for each demand response unit in each timeperiod, + available borrowed load capacity for each demand response unit in each timeperiod, expressed in units given by the `energy_units` attribute. - `borrowefficiency`, as 64-bit floats representing the ratio of load injected into the demand response device's reservoir to load withdrawn @@ -400,7 +400,7 @@ The `demandresponse` group should also contain the following datasets describing reservoir, for each demand response unit in each timeperiod. Unitless. - `borrowed_energy_interest`, as 64-bit floats representing the interest borrowed load incurs across each timestep for each demand response device. A value greater than zero is growth, - while a value less than zero is borrowed load decay. Unitless. + while a value less than zero is decay. Unitless. - `allowablepaybackperiod`, as unsigned 32-bit integers representing the maximum number of time steps a demand response device can hold borrowed load. Any energy still contained at the end of the period will be counted as unserved load for that hour. From 27acc1a78ef20cdb8e62ad6518cd63fc0722d6d4 Mon Sep 17 00:00:00 2001 From: juflorez Date: Tue, 4 Nov 2025 09:12:19 -0700 Subject: [PATCH 7/7] remove borrow/payback efficiency --- docs/src/SystemModel_HDF5_spec.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/src/SystemModel_HDF5_spec.md b/docs/src/SystemModel_HDF5_spec.md index 8b1e9765..898818c5 100644 --- a/docs/src/SystemModel_HDF5_spec.md +++ b/docs/src/SystemModel_HDF5_spec.md @@ -366,8 +366,8 @@ generator-storage devices: Information relating to the demand response only devices of the represented system is stored in the `demandresponses` group inside the root group. This group should contain -nine datasets, one (named `_core`) providing core static data about each region -and nine providing (potentially) time-varying data. +eight datasets, one (named `_core`) providing core static data about each region +and seven providing (potentially) time-varying data. The `_core` dataset should be a vector / one-dimensional array storing instances of a compound datatype with the following fields (in order): @@ -392,12 +392,6 @@ The `demandresponse` group should also contain the following datasets describing - `energycapacity`, as unsigned 32-bit integers representing maximum available borrowed load capacity for each demand response unit in each timeperiod, expressed in units given by the `energy_units` attribute. - - `borrowefficiency`, as 64-bit floats representing the ratio of load - injected into the demand response device's reservoir to load withdrawn - from the grid, for each demand response unit in each timeperiod. Unitless. - - `paybackefficiency`, as 64-bit floats representing the ratio of load - injected into the grid to load withdrawn from the demand response device's - reservoir, for each demand response unit in each timeperiod. Unitless. - `borrowed_energy_interest`, as 64-bit floats representing the interest borrowed load incurs across each timestep for each demand response device. A value greater than zero is growth, while a value less than zero is decay. Unitless.