ONCOR real-time arbitrage decision tool + economics doc (#826)

oncor-arbitrage.sh: LZ_SOUTH RTM price (pluggable source) -> best-action verdict (serve load vs export to Base flat 4c vs RTW counterfactual); JSON out for the KNELPerf batch gate. Verified with override prices. https://projects.knownelement.com/issues/826#note-5
2026-09-06 14:58:45 -05:00
parent b3effbe044
commit 0693739d70
2 changed files with 149 additions and 0 deletions
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# SITER-Solar / KNELPerf — ONCOR-area real-time solar arbitrage decision.
+#
+# Question it answers, per interval: with X kW of solar surplus and a menu of
+# deferrable loads, is it better to (a) serve your own load, (b) export to
+# Base Power at the flat buyback, or (c) hold for later (battery)?
+#
+# Plan facts (Base Power, verified 2026-09-06):
+#   import  = $0.085/kWh flat (through Oct 2028)
+#   export  = $0.040/kWh flat (Base solar credit — NOT real-time wholesale)
+# Therefore: serving your own load ALWAYS beats exporting to Base
+# (8.5c avoided > 4c earned) whenever deferrable load exists. The ERCOT
+# real-time price (RTM, LZ_SOUTH for Pflugerville/Travis, ONCOR wires)
+# matters as a COUNTERFACTUAL: if you switched export to a real-time-
+# wholesale plan, when would exporting have beaten self-consumption?
+#
+# Price sources (first available wins; set via env or /etc/knelerf/ercot.env):
+#   ERCOT_API_KEY       official api.ercot.com public API (developer.ercot.com)
+#   GRIDSTATUS_API_KEY  api.gridstatus.io free tier
+#   RTM_OVERRIDE        manual $/MWh (testing / cache fallback)
+#   RTM_CACHE_FILE      last-known-good price file, refreshed when possible
+# Output: JSON verdict on stdout (consumed by the KNELPerf batch gate).
+set -euo pipefail
+
+IMPORT_RATE=${IMPORT_RATE:-0.085}   # $/kWh, Base Power flat
+EXPORT_RATE=${EXPORT_RATE:-0.040}   # $/kWh, Base Power flat buyback
+SETTLEMENT_POINT=${SETTLEMENT_POINT:-LZ_SOUTH}  # Pflugerville/Travis Co.
+CACHE=${RTM_CACHE_FILE:-/tmp/knelerf-rtm-cache.json}
+
+now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+rtm=""
+
+fetch_gridstatus() { # needs GRIDSTATUS_API_KEY; returns $/MWh
+  [ -n "${GRIDSTATUS_API_KEY:-}" ] || return 1
+  local url="https://api.gridstatus.io/v1/datasets/ercot_spp_real_time_15_min?limit=200"
+  curl -sf -m 30 -H "x-api-key: $GRIDSTATUS_API_KEY" "$url" \
+    | jq -r --arg sp "$SETTLEMENT_POINT" \
+      '[.data[] | select(.settlement_point == $sp)][0].price // empty'
+}
+
+fetch_ercot() { # needs ERCOT_API_KEY (official)
+  [ -n "${ERCOT_API_KEY:-}" ] || return 1
+  # official public API path; shape verified at registration time
+  curl -sf -m 30 -H "Authorization: Bearer $ERCOT_API_KEY" -H "Accept: application/json" \
+    "https://api.ercot.com/api/public-api/np6-905-cd?deliveryDateFrom=$(date +%F)&settlementPoint=$SETTLEMENT_POINT&size=1" \
+    | jq -r '.data[-1].settlementPointPrice // empty'
+}
+
+[ -n "${RTM_OVERRIDE:-}" ] && rtm=$RTM_OVERRIDE
+[ -z "$rtm" ] && rtm=$(fetch_gridstatus || true)
+[ -z "$rtm" ] && rtm=$(fetch_ercot || true)
+src=api
+[ -n "${RTM_OVERRIDE:-}" ] && src=override
+if [ -z "$rtm" ] && [ -r "$CACHE" ]; then
+  rtm=$(jq -r '.rtm_per_mwh // empty' "$CACHE"); src=cache
+fi
+if [ -z "$rtm" ]; then
+  jq -n --arg now "$now" '{ts:$now, ok:false, error:"no price source available (set ERCOT_API_KEY or GRIDSTATUS_API_KEY; see docs/oncor-realtime-arbitrage.md)"}'
+  exit 3
+fi
+
+rtm_kwh=$(awk -v r="$rtm" 'BEGIN{printf "%.5f", r/1000}')
+
+# Decisions (per kWh of surplus):
+#   serve_load_value = IMPORT_RATE  (avoided purchase)
+#   export_base      = EXPORT_RATE  (flat)
+#   export_rtw_plan  = rtm_kwh      (counterfactual, real-time plan)
+verdict=$(awk -v i="$IMPORT_RATE" -v e="$EXPORT_RATE" -v r="$rtm_kwh" 'BEGIN{
+  best="serve_load"; v=i;
+  if (r > v) {best="export_rtw_plan"; v=r}
+  if (e > v) {best="export_base"; v=e}
+  print best" "v}')
+read -r action value <<< "$verdict"
+
+# Batch-load gate (KNELPerf class-3): start deferrable compute while
+# surplus exists AND grid price would not make serving load later cheaper.
+jq -n --arg now "$now" --arg sp "$SETTLEMENT_POINT" --arg src "$src" \
+  --argjson rtm "$rtm" --argjson rtm_kwh "$rtm_kwh" \
+  --argjson import "$IMPORT_RATE" --argjson export "$EXPORT_RATE" \
+  --arg action "$action" --argjson value "$value" \
+  '{ts:$now, ok:true, settlement_point:$sp, source:$src,
+    rtm_per_mwh:$rtm, rtm_per_kwh:$rtm_kwh,
+    import_rate: $import, export_rate_base: $export,
+    best_action: $action, best_value_per_kwh: $value,
+    serve_load_wins: ($import > $export and $import > $rtm_kwh),
+    rtw_would_beat_self_consume: ($rtm_kwh > $import),
+    start_deferrable_load: ($import > $export)}' | tee /tmp/oncor-latest.json
+cp /tmp/oncor-latest.json "$CACHE" 2>/dev/null || true