Added examples and decision for directional ratings

docs/Gemfile.lock

@@ -23,7 +23,7 @@ GEM
     commonmarker (0.23.10)
     concurrent-ruby (1.2.3)
     connection_pool (2.4.1)
-    dnsruby (1.70.0)
+    dnsruby (1.71.0)
       simpleidn (~> 0.2.1)
     drb (2.2.1)
     em-websocket (0.5.3)

docs/decision-log/directional-ratings.md

@@ -0,0 +1,56 @@
+---
+title: Directional Ratings
+parent: Decision Records
+---
+
+## Status
+
+* Status: `proposed`
+* Issue Link: [GitHub Issue](https://github.com/trolie/spec/issues/6)
+
+## Context
+Most lines only require a single set of rating values that apply irregardless 
+of the direction that energy is flowing. However, for some lines, 
+Transmission Providers may require separate "directional" ratings that 
+differ depending on the direction energy is flowing.  
+
+This decision documents strategy for representing directional ratings in TROLIE.  
+
+## Decision
+TROLIE will contain no specific schema elements to represent directional ratings.
+For lines that require directional ratings, TROLIE servers must expose unique
+resource identifiers representing each direction.  
+
+### A Rating Direction as a Resource
+While a rating direction against a particular piece of equipment doesn't map directly
+back to the physical model, it is a natural fit for TROLIE implementations to consider
+each direction as a separate anchor against which TROLIE servers can attach ratings.  Each 
+direction could have its obligation tracked for providing ratings data separately, as it
+is possible that values for each direction could be provided independently.  In addition,
+it is safe to assume that many systems will represent the ratings over time as a time 
+series, both to meet FERC's 5-year history requirement and for other study purposes.  It
+is convenient to simply represent the ratings as a single time series per resource,
+vs a time series per resource per direction.  
+
+An alternative would be to mark each series with explicit directions in the model, 
+including a special value for "both" when directional ratings don't apply.  We feel this
+would add extra complexity to the model to accommodate the minority of devices
+on the system, and is the wrong tradeoff.  
+
+### Directional-Resource Naming
+While directional ratings are supported by many systems involved in grid 
+operations (EMS, Markets, modeling etc), there is currently no consistent approach 
+to how they are represented.  IEC CIM also has no provision for directional
+ratings in the transmission model as of version 17.  So, there is no existing
+standard to gravitate to.  
+
+Much like the [rules on naming](naming.md), TROLIE will need to be flexible in order
+to accommodate the inertia of established software systems, models and methodologies.
+Therefore, TROLIE is not opinionated on how these names are structured.  Some possible
+examples are simply listed in the examples section to provide guidance, as referenced
+below.  
+
+## Consequences
+TROLIE server implementations are responsible for translating resources into rating
+directions, and exposing identifiers that represent each direction.  Some possible
+examples are provided [here](../example-narratives/in-use-forecasts.md) for guidance.

docs/example-narratives/directional-ratings.md

@@ -0,0 +1,40 @@
+---
+title: Directional Ratings
+parent: Usage Examples
+nav_order: 3
+---
+
+# Ratings Provider Submitting Directional Ratings to TROLIE
+Most lines only require a single set of rating values that apply irregardless 
+of the direction that energy is flowing. However, for a some lines, 
+Transmission Providers may require separate "directional" ratings that 
+differ depending on the direction energy is flowing.  
+
+Directional ratings are supported in TROLIE by exposing separate 
+resources, both in terms of `TransmissionFacilities` and `Segments`, to 
+represent different rating directions.  The names used for these resources are 
+ultimately up to the TROLIE implementation.  The following two examples show some 
+contrasting styles for naming these resources.  Both are equally valid, and are 
+provided here only as examples.  
+
+## With "Named Direction"-Style Naming
+One common style, such as that supported by the GE Vernova EMS, is to represent 
+rating directions by specifying an arbitrary `in` and `out` direction on a line, 
+typically representing the most common flow of energy in and out of a load pocket,
+control area or other logical grouping of the transmission network.  
+This is illustrated by the following forecast proposal example:
+
+```json
+{% include_relative examples/forecast-proposal-directional-named.json %}
+```
+
+## With "Point to Point"-Style Naming
+An alternative style could be to name the resources as a concatenation
+of the identifiers on each end, with the order of the identifiers indicating the
+direction of the flow.  Consider two substation buses, with the very simple identifiers
+`BusA` and `BusB`.  These are used to illustrate point-to-point naming in the following forecast
+proposal example:
+
+```json
+{% include_relative examples/forecast-proposal-directional-point-to-point.json %}
+```

docs/example-narratives/examples/forecast-proposal-directional-named.json

@@ -0,0 +1,60 @@
+{
+  "proposal-header": {
+      "source": {
+          "last-updated": "2024-03-5T15:05:43.044267100-07:00",
+          "provider": "X-AMPL-TO"
+      },
+      "default-emergency-durations": [
+          {
+              "name": "emergency",
+              "duration-minutes": 60
+          }
+      ],
+      "power-system-resources": [
+          { "resource-id": "segmentA-in" },
+          { "resource-id": "segmentA-out" }
+      ]
+  },
+  "ratings": [
+      {
+          "resource-id": "segmentA-in",
+          "periods": [
+              {
+                  "period-start": "2025-11-02T01:00:00-05:00",
+                  "period-end": "2025-11-02T02:00:00-05:00",
+                  "continuous-operating-limit": {
+                      "mva": 160
+                  },
+                  "emergency-operating-limits": [
+                      {
+                          "duration-name": "emergency",
+                          "limit": {
+                              "mva": 165
+                          }
+                      }
+                  ]
+              }
+          ]
+      },
+      {
+          "resource-id": "segmentA-out",
+          "periods": [
+              {
+                  "period-start": "2025-11-02T01:00:00-05:00",
+                  "period-end": "2025-11-02T02:00:00-05:00",
+                  "continuous-operating-limit": {
+                      "mva": 161
+                  },
+                  "emergency-operating-limits": [
+                      {
+                          "duration-name": "emergency",
+                          "limit": {
+                              "mva": 165
+                          }
+                      }
+                  ]
+              }
+          ]
+      }
+  ]
+}

docs/example-narratives/examples/forecast-proposal-directional-point-to-point.json

@@ -0,0 +1,60 @@
+{
+  "proposal-header": {
+      "source": {
+          "last-updated": "2024-03-5T15:05:43.044267100-07:00",
+          "provider": "X-AMPL-TO"
+      },
+      "default-emergency-durations": [
+          {
+              "name": "emergency",
+              "duration-minutes": 60
+          }
+      ],
+      "power-system-resources": [
+          { "resource-id": "BusA-BusB" },
+          { "resource-id": "BusB-BusA" }
+      ]
+  },
+  "ratings": [
+      {
+          "resource-id": "BusA-BusB",
+          "periods": [
+              {
+                  "period-start": "2025-11-02T01:00:00-05:00",
+                  "period-end": "2025-11-02T02:00:00-05:00",
+                  "continuous-operating-limit": {
+                      "mva": 162
+                  },
+                  "emergency-operating-limits": [
+                      {
+                          "duration-name": "emergency",
+                          "limit": {
+                              "mva": 165
+                          }
+                      }
+                  ]
+              }
+          ]
+      },
+      {
+          "resource-id": "BusB-BusA",
+          "periods": [
+              {
+                  "period-start": "2025-11-02T01:00:00-05:00",
+                  "period-end": "2025-11-02T02:00:00-05:00",
+                  "continuous-operating-limit": {
+                      "mva": 163
+                  },
+                  "emergency-operating-limits": [
+                      {
+                          "duration-name": "emergency",
+                          "limit": {
+                              "mva": 165
+                          }
+                      }
+                  ]
+              }
+          ]
+      }
+  ]
+}