Merge pull request #114 from getorymckeag/rt-examples

Added RT examples, concepts, milestone release

docs/Gemfile.lock

@@ -223,7 +223,7 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.24.0)
+    minitest (5.24.1)
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri

docs/_data/openapi-split.yaml

@@ -42,7 +42,7 @@ info:
 
     <img src="images/TROLIE Ratings Provider interactions.excalidraw.png" alt="TROLIE Interactions by Ratings Provider" />
 
-  version: 1.0.0-wip-forecasting-stable
+  version: 1.0.0-wip-realtime-stable
   contact:
     name: TROLIE Maintainers
     email: maintainers@trolie.energy

docs/community-events/20240701-RealTime-API-stable.md

@@ -0,0 +1,57 @@
+---
+title: "Milestone: Real-Time API Stable"
+parent: Community Events
+---
+
+# Real-Time API Stable
+
+## Summary
+
+<img src="../images/TROLIE-summer.jpg" style="float:right;padding-left:5px;box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.3)" width="280" height="280"/>
+
+The specification of the [Real-Time Operations](/spec#tag/Real-Time) in
+TROLIE OpenAPI specification is now considered stable, closing the [associated
+milestone](https://github.com/trolie/spec/milestone/2). Specifically, no further
+changes are anticipated to the media type schemas and resource semantics--the
+HTTP verbs, paths, and status codes--for submitting ratings and retrieving
+in-use limit snapshots.  We are naming this release `1.0.0-wip-realtime-stable` to
+reflect that fact that the specification is still under development, but we
+believe the real-time operations effectively address the use cases that have
+been identified over the last several months.
+
+This is effectively similar to the previous announced [Forecasting](20240330-Forecast-API-stable) 
+milestone as an incremental step towards TROLIE 1.0.0.
+
+## Stable Use Cases
+
+Implementors should consider the specification stable in its support of the following use cases:
+
+* Submitting Real-Time Ratings Proposals
+* Obtaining Real-Time Ratings Proposal Status
+* Obtaining Real-Time Limits Snapshots, including:
+  - "Slim" snapshots that provide just the determined limits
+  - Detailed snapshots that provide all of the inputs used by the Clearinghouse
+    Provider to determine the limits, including all proposals and overrides.
+
+## Improved and Expanded Documentation
+
+We continue to improve the documentation at [trolie.energy](/). In preparation
+for this release, we have:
+
+* Continued additions to the [TROLIE Concepts](../concepts) exposition
+* Added example guides for real-time API usage [Querying in-use Real-Time Limits](/example-narratives/in-use-realtime-limits) and [Real-Time Rating Submittal](/example-narratives/submitting-realtime-ratings)
+
+## Looking Ahead
+
+[Future
+milestones](https://github.com/trolie/spec/milestones) will include handling
+temporary AAR exceptions, seasonal ratings, and defining the [peering
+profile](https://github.com/trolie/spec/issues/65#issuecomment-1994413248) which
+will specify how TROLIE implementations will integrate using only some
+simple configuration.
+
+The specification will be updated accordingly **without** a version change until
+the next milestone is completed, remaining at `1.0.0-wip-realtime-stable` 
+even as future milestones is completed. However, any necessary
+changes to the forecasting operations will result in a version change and
+another announcement.

docs/concepts.md

@@ -27,7 +27,32 @@ for TROLIE is that a Limit satisfies the most limiting of any provided
 reliability criteria. Limits for Transmission Facilities are determined by the
 Clearinghouse after considering all Ratings Proposals for the Power System
 Resources associated with that Transmission Facility during a particular Period
-of an Operational Window.
+of an Operational Window.  TROLIE defines limits and ratings (described below) in 
+3 distinct time horizons, including near term "forecasts", real-time and (in future 
+releases) seasonal limits.  
+
+### Forecast Limits
+
+Forecast limits refer to the 240-hour-ahead forecasted AAR data set
+mandated by FERC order 881.  While this is a forecast of limits as they would be
+in real-time, in practice these are often used for various processes involved in 
+near-term planning of transmission services, including day-ahead markets and other 
+look-ahead resource commitment processes, transmission scheduling and outage 
+coordination.  
+
+### Real-Time Limits
+
+In addition to forecasts, TROLIE may also be used to exchange ratings within the 
+current hour, either as an alternative or supplement to traditional telemetry 
+protocols such as ICCP.  
+
+These are assumed to be "real-time" limits, based on measurements
+of ambient conditions as opposed to forecasts.  These limits will be 
+used by Transmission Providers in real-time grid operations processes, 
+such as state estimator and real-time markets.  The clearinghouse for real-time ratings
+may be run more frequently than the one for forecast ratings to adapt to real-world 
+conditions.  
+
 
 ## Rating
 

docs/example-narratives/examples/realtime-proposal-status-complete.json

@@ -0,0 +1,11 @@
+{
+  "ratings-provider": {
+    "provider": "UTILITY-A",
+    "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+    "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
+  },
+  "incomplete-obligation-count": 0,
+  "incomplete-obligations": [],
+  "invalid-proposal-count": 0,
+  "proposal-validation-errors": []
+}

docs/example-narratives/in-use-forecasts.md

@@ -11,7 +11,7 @@ Assuming a MonitoringSet "my-monitoring-set" that contains TransmissionFacilitie
 ```bash
 curl -H "Accept: application/vnd.trolie.forecast-limit-set-slim.v1+json" \
 -o output.json \
-"https://trolie.example.com/rating-proposals/forecasts?monitoring-set=my-monitoring-set"
+"https://trolie.example.com/limits/forecast-snapshot?monitoring-set=my-monitoring-set"
 ```
 
 This will return the current version of the in-use ratings for the next 240 hours into output.json.  See the following for an example:

docs/example-narratives/in-use-realtime-limits.md

@@ -0,0 +1,32 @@
+---
+title: Querying in-use Real-Time Limits
+parent: Usage Examples
+nav_order: 4
+---
+
+# Ratings Provider Querying in-use Real-Time Limits from the Transmission Provider
+
+Assuming a MonitoringSet "my-monitoring-set" that contains TransmissionFacilities of interest, then the current in-use real-time limits may be fetched with the following command:
+
+```bash
+curl -H "Accept: application/vnd.trolie.realtime-limits-slim-snapshot.v1+json" \
+-o output.json \
+"https://trolie.example.com/limits/realtime-snapshot?monitoring-set=my-monitoring-set"
+```
+
+This will return the current version of the in-use real-time limits into output.json.  
+This data should include *all* limits in-use by the Transmission Provider, whether 
+they were submitted through TROLIE, through ICCP, or derived by the Transmission Provider 
+through some other means.  See the following for an example:
+
+```json
+{% include_relative examples/realtime-limit-set-slim.json %}
+```
+
+**NOTE**: This query is an example of an HTTP GET.  In addition to curl, the same URL may also be placed in a web browser to see the data.  
+
+## Conditional GETs
+
+While this example is appropriate for learning the API and trial usage, real applications 
+will likely need to query these limits quite frequently.  Clients should use the pattern
+for "conditional" GETs described in this [article](../articles/conditional-GET).   

docs/example-narratives/submitting-realtime-ratings.md

@@ -0,0 +1,95 @@
+---
+title: Real-Time Rating Submittal
+parent: Usage Examples
+nav_order: 5
+toc: true
+---
+
+
+This article assumes some familiarity with HTTP in general and RESTful
+APIs in particular ([background](../articles/trolie-for-ems-and-ot)).  It also 
+follows very similar patterns to the concepts for forecast ratings, so the examples
+on [forecast](submitting-forecasts) ratings may be helpful for background.  
+
+
+
+## Simplified Example: Transmission Owner Sends Ratings with `curl`
+
+If a Transmission Owner is their own Ratings Provider, they must regularly send
+real-time ratings to their Transmission Provider. TROLIE provides the
+[postRealTimeProposal](../spec#tag/Rating-Proposals/operation/postRealTimeProposal)
+operation for this purpose.
+
+
+Assume the Transmission Owner creates a file called `input.json` containing
+their ratings measurements. An example of the required format for the file is given below.
+
+```json
+{% include_relative examples/realtime-proposal.json %}
+```
+
+The format is one of TROLIE's supported media types named
+`application/vnd.trolie.rating-realtime-proposal.v1+json`.
+
+
+### Pushing `input.json` to TROLIE with `curl`
+
+Given the above `input.json`, run the following command to send it to the TROLIE server:
+
+```bash
+curl -d @input.json \
+-X POST \
+-H "Content-Type: application/vnd.rating-realtime-proposal.v1+json" \
+-H "Accept: application/vnd.trolie.rating-realtime-proposal-status.v1+json"
+-o output.json \
+"https://trolie.example.com/rating-proposals/real-time"
+```
+
+If this submission is successful, `output.json` will contain the contents of the
+response from TROLIE. The format of the response is defined by another TROLIE
+media type: `application/vnd.trolie.rating-realtime-proposal-status.v1+json`. An
+example of this response format is given below:
+
+```json
+{% include_relative examples/realtime-proposal-status-complete.json %}
+```
+
+## Invalid Ratings for Individual Resources Should be Tolerated
+
+The TROLIE spec supports allowing some individual ratings to be
+invalid without rejecting the entire proposal, much like with forecasts.  
+The pattern for incomplete and invalid proposals is similar to the 
+one described for forecasts illustrated in [Forecast Submittal](submitting-forecasts).
+
+### `incomplete-obligation-count` as a Monitoring Function
+
+The use of the proposal status in realtime will differ somewhat from the usage
+with forecast ratings.  The forecast obligation always applies to a particular 
+window.  Real-Time ratings, in contrast, are always simply updated against the current time.
+The real-time Clearinghouse may run more frequently than once an hour, and
+rating proposals may be run even more, or less frequently than the Clearinghouse.
+
+In addition to flagging data that is missing, the `incomplete-obligation-count` 
+also flags data that is considered too "stale" to use.  The definition
+of what is considered stale is ultimately up to the Clearinghouse 
+implementation.  If supported by the Clearinghouse, `incomplete-obligation-count` 
+may also consider obligations for resources that would normally not have 
+their ratings submitted as TROLIE proposals, but rather through other means, such as ICCP.  
+
+Therefore, clients should rely more on asynchronous use of 
+[getRealTimeProposalStatus](../spec#tag/Rating-Proposals/operation/getRealTimeProposalStatus)
+as a way to monitor whether the Clearinghouse considers their ongoing data stream
+healthy.  
+
+## Jointly-Owned Facilities
+
+In a jointly-owned facility there may be one or more Ratings Providers for a
+given facility. This is expected to be fairly typical on seams. The pattern is 
+nearly identical to the way this works for forecasts, with the exception that the 
+Clearinghouse may run much more frequently.  From a submittal
+perspective, this is inconsequential: Each Ratings Provider simply submits their
+own Ratings Proposal for their Ratings Obligation using the appropriate
+`resource-id`. As with all `resource-id` uses, the TROLIE spec is agnostic as to
+which kind of Power System Resource is nominated by the identifier, but it will
+typically be a Segment in the case of a Jointly-Owned Facility with multiple
+Ratings Providers.

docs/index.md

@@ -22,8 +22,8 @@ class="fa-solid fa-envelope"></i>](https://lists.lfenergy.org/g/trolie-general).
 
 > **Latest Updates** <i class="fa-solid fa-bullhorn"></i>
 >
-> The TROLIE maintainers are pleased to announce that the [Forecasting API](/spec#tag/Forecasting) specification is stable.
-> Read more in the [milestone announcement](./community-events/20240330-Forecasting-API-stable).
+> The TROLIE maintainers are pleased to announce that the [Real-Time API](/spec#tag/Real-Time) specification is stable.
+> Read more in the [milestone announcement](./community-events/20240701-RealTime-API-stable).
 >
 > If you are new to the project, consider watching the replay of the [Intro to TROLIE webinar](./community-events/20240221-Intro-to-TROLIE)