-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added dump from GE helper docs (#29)
* Added dump from GE helper docs * Added reused JSON examples via include_relative, use of example.com as example URL * simplify some string definitions * reusing `#/components/schemas/description` without a linter error from the owasp rules is more trouble than it is worth; ETag should be opaque anyway --------- Co-authored-by: Christopher Atkins <christopher316@gmail.com>
- Loading branch information
1 parent
1677c62
commit c245ef6
Showing
22 changed files
with
409 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: TROLIE Concepts | ||
| nav_order: 3 | ||
| --- | ||
|
|
||
| # TROLIE Concepts | ||
|
|
||
| Before reviewing examples, users may benefit from a basic understanding of the key constructs used by the TROLIE APIs. Definitions of these concepts are included here. | ||
|
|
||
| ## Transmission Facilities | ||
| A Transmission Facility is a logical part of the electrical network that may have a rating, whether simply seasonal or an AAR. This most often represents a transmission line, but could also include transformers and other large pieces of equipment, or perhaps even logical points on the network such as interfaces. Most importantly, these are points at which transmission providers need rating values to operate against. | ||
|
|
||
| Rating snapshots are always done against Transmission Facilities. Transmission Facilities include one or more Segments. The Transmission Facilities included in TROLIE are typically pre-coordinated ahead of time, often through a modeling process. | ||
|
|
||
| ## Segments | ||
| Segments represent a component of some Transmission Facility that may affect its overall rating. All Transmission Facilities must have at least one Segment. In terms of TROLIE, ratings providers are obligated to provide rating data, in the form of Proposals, against segments. On jointly owned lines or tie lines for example, each stakeholder in the line (the Transmission Facility) will be responsible for submitting Proposals against a different Segment in the model allocated to that stakeholder. | ||
|
|
||
| ## Proposals | ||
| Proposals are forecasted or real-time ratings values submitted to TROLIE against a particular Segment. They are referred to as "Proposals", as they are inputs to the limit "clearing" process internal to TROLIE server implementations that will integrate them into a final in-use rating set. In-use limit Snapshots are a distinct data set from Proposals. Proposals may be queried as well as submitted, so that the rating provider's original input data is always kept separately from the in-use ratings. | ||
|
|
||
| ## Snapshots | ||
| As implied above, Snapshots are generated in TROLIE server implementations based on proposals and other inputs to generate in-use ratings for each Transmission Facility. TROLIE allows for ratings providers to fetch the latest snapshot, aka the latest "version" of the ratings data. | ||
|
|
||
| ## Monitoring Sets | ||
| Monitoring Sets are arbitrarily defined sets of transmission facilities that may be used to filter ratings and limits returned by queries against these APIs. Defining the contents of these monitoring sets may vary, and is up to TROLIE server implementations. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: Daylight Savings | ||
| nav_order: 5 | ||
| --- | ||
|
|
||
| # Handling Daylight Savings Transitions in TROLIE | ||
|
|
||
| Daylight savings transitions are a notorious problem in software systems. Specifically in data exchanges, data formats must contend with two challenges: | ||
|
|
||
| * Both transition days don't have 24 hours. The Spring transition of course has 23, the Fall transition 25. | ||
| * The day of the Fall transition has two unique hours that are both referred to in local clocks as "1 AM", one before and the other after the transition. | ||
|
|
||
| The first problem (non-24 hour days) does not create any particular problem for the TROLIE data formats. The second problem of the "duplicate hour" however is explicitly handled by the consistent use of the standard [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) date time format. This format assumes that the server can understand time universally, typically by using internal references in UTC. In the API, RFC 3339 date times must include explicit operating time zone offsets from UTC. Therefore, the difference between the "1 AM" hours is always visible in the timezone offset. | ||
|
|
||
| For example, in central US time in 2025, the Fall transition day would begin with the following hours: | ||
|
|
||
| {% highlight none %} | ||
| 2025-11-02T00:00:00-05:00 | ||
| 2025-11-02T01:00:00-05:00 | ||
| 2025-11-02T01:00:00-06:00 | ||
| 2025-11-02T02:00:00-06:00 | ||
| 2025-11-02T03:00:00-06:00 | ||
| {% endhighlight %} | ||
|
|
||
| Note that the two 01:00:00 times are uniquely distinguished with the -05:00 and -06:00 offsets. |
File renamed without changes.
File renamed without changes.
60 changes: 60 additions & 0 deletions
60
docs/example-narratives/examples/forecast-ratings-proposal-patch.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| { | ||
| "ratings": [ | ||
| { | ||
| "segment-id": "segmentX", | ||
| "periods": [ | ||
| { | ||
| "period-start": "2025-11-02T01:00:00-05:00", | ||
| "values": [ | ||
| { | ||
| "type": "normal", | ||
| "value": { | ||
| "mva": 160 | ||
| } | ||
| }, | ||
| { | ||
| "type": "emergency", | ||
| "value": { | ||
| "mva": 165 | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "period-start": "2025-11-02T01:00:00-06:00", | ||
| "values": [ | ||
| { | ||
| "type": "normal", | ||
| "value": { | ||
| "mva": 162 | ||
| } | ||
| }, | ||
| { | ||
| "type": "emergency", | ||
| "value": { | ||
| "mva": 167 | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "period-start": "2025-11-02T02:00:00-06:00", | ||
| "values": [ | ||
| { | ||
| "type": "normal", | ||
| "value": { | ||
| "mva": 162 | ||
| } | ||
| }, | ||
| { | ||
| "type": "emergency", | ||
| "value": { | ||
| "mva": 167 | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| --- | ||
| title: Querying in-use Limit Forecast | ||
| parent: Usage Examples | ||
| nav_order: 2 | ||
| --- | ||
|
|
||
| # Ratings Provider Querying in-use Limit Forecast from the Transmission Provider | ||
|
|
||
| Assuming a MonitoringSet "my-monitoring-set" that contains TransmissionFacilities of interest, then the current in-use forecasted limits may be fetched with the following command: | ||
|
|
||
| ```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" | ||
| ``` | ||
|
|
||
| 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: | ||
|
|
||
| ```json | ||
| {% include_relative examples/forecast-limits-slim.json %} | ||
| ``` | ||
|
|
||
| The above example assumes the next 240 hours as determined by the computer clock where TROLIE server is running. Given that there are edge cases in time and the user’s clocks are likely slightly off from the TROLIE server's clock, it is recommended to specify the times more explicitly to ensure that users are getting what is expected. This may be done by specifying the "offset-period-start" parameter, like in the following example: | ||
|
|
||
| ``` | ||
| https://trolie.example.com/rating-proposals/forecasts?monitoring-set=my-monitoring-set&offset-period-start=2025-11-02T02:00:00-06:00 | ||
| ``` | ||
|
|
||
| **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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| --- | ||
| title: Submitting Forecast Ratings | ||
| parent: Usage Examples | ||
| nav_order: 1 | ||
| --- | ||
|
|
||
| # Ratings Provider Submitting Forecast Ratings to the Transmission Provider | ||
|
|
||
| For most transmission owners (rating providers in TROLIE terminology), the most important operation will be to regularly (at least hourly) send forecasted AARs to SPP. This is done by updating that TO’s forecasted rating Proposal. More specifically, this may be achieved using the [patchRatingForecastProposal](../spec#tag/Rating-Proposals/operation/patchRatingForecastProposal) operation in TROLIE. | ||
|
|
||
| For the purpose of this example, the JSON listing below may be assumed to be in a file called `input.json`. The input consists of an array by segment, which then contains an array of ratings for each forecast period. Note this example also cross the Fall daylight savings transition in the central timezone, thus providing an example of dealing with the notorious "duplicate" 1 AM hour: | ||
|
|
||
| ```json | ||
| {% include_relative examples/forecast-ratings-proposal-patch.json %} | ||
| ``` | ||
|
|
||
| ## Pushing input.json to TROLIE | ||
| Given input.json, run the following command to send it to the TROLIE server: | ||
|
|
||
| ```bash | ||
| curl -d @input.json \ | ||
| -X PATCH \ | ||
| -H "Content-Type: application/vnd.trolie.rating-forecast-proposal.v1+json" \ | ||
| -o output.json \ | ||
| "https://trolie.example.com/rating-proposals/forecasts" | ||
| ``` | ||
|
|
||
| On success, output.json will container a copy of the data just uploaded, with additional metadata on update time and status. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,6 @@ | ||
| --- | ||
| title: Home | ||
| nav_order: 1 | ||
| --- | ||
|
|
||
|
|
||
|
|
||
Oops, something went wrong.