diff --git a/cspell.json b/cspell.json index 86229d0..91c7d2b 100644 --- a/cspell.json +++ b/cspell.json @@ -13,10 +13,13 @@ "dictionaries": [], "words": [ "affordance" + ,"affordances" ,"auditability" ,"brotli" ,"CGMES" ,"debuggability" + ,"derate" + ,"derated" ,"devcontainer" ,"ENTSO" ,"excalidraw" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 7ac4355..26f2dc9 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -35,8 +35,9 @@ GEM ffi (>= 1.15.0) eventmachine (1.2.7) execjs (2.9.1) - faraday (2.11.0) + faraday (2.12.0) faraday-net_http (>= 2.0, < 3.4) + json logger faraday-net_http (3.3.0) net-http @@ -211,6 +212,7 @@ GEM gemoji (>= 3, < 5) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) + json (2.7.2) just-the-docs (0.10.0) jekyll (>= 3.8.5) jekyll-include-cache diff --git a/docs/_data/paths/limits_realtime-snapshot.yaml b/docs/_data/paths/limits_realtime-snapshot.yaml index 0bf4e38..c93e79a 100644 --- a/docs/_data/paths/limits_realtime-snapshot.yaml +++ b/docs/_data/paths/limits_realtime-snapshot.yaml @@ -23,7 +23,7 @@ get: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-snapshot" example: - $ref: '../../example-narratives/examples/realtime-limit-set-slim.json' + $ref: '../../example-narratives/examples/realtime-limit-set.json' application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-detailed-snapshot" diff --git a/docs/example-narratives/examples/realtime-limit-set-detailed.json b/docs/example-narratives/examples/realtime-limit-set-detailed.json index db32deb..363f6fc 100644 --- a/docs/example-narratives/examples/realtime-limit-set-detailed.json +++ b/docs/example-narratives/examples/realtime-limit-set-detailed.json @@ -16,7 +16,7 @@ }, { "name": "dal", - "duration-minutes": 15 + "duration-minutes": 5 } ], "power-system-resources": [ @@ -38,8 +38,74 @@ }, "limits": [ { - "resource-id": "line2", - "proposals-considered": [], + "resource-id": "8badf00d", + "period-start":"2025-07-12T15:00:00-07:00", + "period-end":"2025-07-12T16:00:00-07:00", + "proposals-considered": [ + { + "source":{ + "last-updated": "2025-07-12T14:10:12-07:00", + "provider": "UTILITY-A" + }, + "period-start":"2025-07-12T15:00:00-07:00", + "period-end":"2025-07-12T16:00:00-07:00", + "proposal-disposition": "Used", + "continuous-operating-limit": { + "mva": 150 + }, + "emergency-operating-limits": [ + { + "duration-name": "lte", + "limit": { + "mva": 165 + } + }, + { + "duration-name": "ste", + "limit": { + "mva": 170 + } + }, + { + "duration-name": "dal", + "limit": { + "mva": 180 + } + } + ] + },{ + "source":{ + "last-updated": "2025-07-12T14:10:12-07:00", + "provider": "UTILITY-B" + }, + "period-start":"2025-07-12T15:00:00-07:00", + "period-end":"2025-07-12T16:00:00-07:00", + "proposal-disposition": "Used", + "continuous-operating-limit": { + "mva": 150 + }, + "emergency-operating-limits": [ + { + "duration-name": "lte", + "limit": { + "mva": 166 + } + }, + { + "duration-name": "ste", + "limit": { + "mva": 171 + } + }, + { + "duration-name": "dal", + "limit": { + "mva": 175 + } + } + ] + } + ], "temporary-aar-exceptions": [ "2d8c80e8-f533-4be9-85bf-f7f81eb73d67" ], @@ -66,7 +132,7 @@ { "duration-name": "dal", "limit": { - "mva": 180 + "mva": 175 } } ] diff --git a/docs/example-narratives/examples/realtime-limit-set-slim.json b/docs/example-narratives/examples/realtime-limit-set.json similarity index 100% rename from docs/example-narratives/examples/realtime-limit-set-slim.json rename to docs/example-narratives/examples/realtime-limit-set.json diff --git a/docs/example-narratives/in-use-realtime-limits.md b/docs/example-narratives/in-use-realtime-limits.md index c0e93be..0667709 100644 --- a/docs/example-narratives/in-use-realtime-limits.md +++ b/docs/example-narratives/in-use-realtime-limits.md @@ -9,7 +9,7 @@ nav_order: 4 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" \ +curl -H "Accept: application/vnd.trolie.realtime-limits-snapshot.v1+json" \ -o output.json \ "https://trolie.example.com/limits/realtime-snapshot?monitoring-set=my-monitoring-set" ``` @@ -20,7 +20,7 @@ they were submitted through TROLIE, through ICCP, or derived by the Transmission through some other means. See the following for an example: ```json -{% include_relative examples/realtime-limit-set-slim.json %} +{% include_relative examples/realtime-limit-set.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. diff --git a/docs/example-narratives/reconciliation.md b/docs/example-narratives/reconciliation.md new file mode 100644 index 0000000..983449c --- /dev/null +++ b/docs/example-narratives/reconciliation.md @@ -0,0 +1,57 @@ +--- +title: Reconciliation with Limit Snapshots +parent: Usage Examples +nav_order: 6 +--- + +# Reconciliation with Limit Snapshots + +A central concept in TROLIE is the Clearinghouse. [Ratings +Providers](../concepts#ratings-provider) propose ratings, and the [Clearinghouse +Provider](../concepts#clearinghouse-provider) determines operating limits: +**ratings in, limits out**. + +Reconciliation Diagram + +Crucially, the limits determined by the Clearinghouse Provider may differ from +the ratings proposed by any individual Ratings Provider. In this article we +will briefly describe the API affordances that support reconciliation of limits +(produced by the Clearinghouse) with the ratings proposed by the Ratings +Provider. Our example with focus on real-time ratings, but the basic approach +applies to forecast ratings as well. + +We have discussed [Real-Time Rating Submittal](submitting-realtime-ratings) and +[Querying in-use Real-Time Limits](in-use-realtime-limits) elsewhere. Here we +will focus on making use of the provenance information in +`application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json`. For more +details on the different response messages available in TROLIE, see the article +on [Media Types](../articles/media-types#read-requests). + + +#### Request +```bash +curl -H "Accept: application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json" \ + $TROLIE_SERVER_URL/limits/realtime-snapshot?monitoring-set=my-monitoring-set +``` + +#### Response + +Some headers are elided for clarity, but a successful response will start with: + +```http +HTTP/1.1 200 OK +Content-Type: application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json +``` + +Here's an example of the body of the response: + +```json +{% include_relative examples/realtime-limit-set-detailed.json %} +``` + +#### Discussion + +The `proposals-considered` array contains the salient details of the ratings +proposals that were considered. Note that in this example the continuous, +"lte", and "ste" limits were determined by UTILITY-A but the "dal" limit was set +by UTILITY-B. diff --git a/docs/images/reconciliation.excalidraw.png b/docs/images/reconciliation.excalidraw.png new file mode 100644 index 0000000..ebae501 Binary files /dev/null and b/docs/images/reconciliation.excalidraw.png differ