Why An Iterative Ontology (Not A Grand Schema)

Golden Grid: Playbook for Iterative Home Energy Ontologies
---

We built Golden Grid to solve a simple problem that shows up everywhere in energy work: context is scattered. Data lives in different shapes, policies live in PDFs, and meanings drift across teams. Instead of chasing a universal, one‑shot standard, Golden Grid treats an ontology as a context management tool you evolve as your workflows mature.

This article explains how to use the project pragmatically—starting small, wiring real data, and iterating—so your team can move from semantic clarity to dynamic actions and, ultimately, kinetic workflows that run in production. We stay focused on home modeling first; once the behind-the-meter story is consistent, every future extension (grid exports, program analytics, finance) builds on that shared context.

- [Why An Iterative Ontology (Not A Grand Schema)](#why-an-iterative-ontology-not-a-grand-schema)
- [Energy Time Series + Control: Two Context Channels](#energy-time-series--control-two-context-channels)
- [Tariffs: From Source Payloads To Rates You Can Use](#tariffs-from-source-payloads-to-rates-you-can-use)
- [What The Workflows Show](#what-the-workflows-show)
- [How To Implement This In Your Organization](#how-to-implement-this-in-your-organization)
- [Iteration Loop That Works](#iteration-loop-that-works)
- [Common Anti‑Patterns (And What To Do Instead)](#common-antipatterns-and-what-to-do-instead)
- [Kinetic Workflows (When You’re Ready)](#kinetic-workflows-when-youre-ready)
- [Closing: Ontologies As Context Contracts](#closing-ontologies-as-context-contracts)
- [Appendix: Expanded Guide for Implementers](#appendix-expanded-guide-for-implementers)
  - [Why an Iterative Ontology (Not a Grand Schema)](#why-an-iterative-ontology-not-a-grand-schema-1)
  - [Context Management: Semantic → Dynamic → Kinetic](#context-management-semantic--dynamic--kinetic)
    - [Core Objects and Naming](#core-objects-and-naming)
  - [Timeseries \& Control Channels](#timeseries--control-channels)
  - [Tariffs and Rates](#tariffs-and-rates)
  - [Workflows in the Repository](#workflows-in-the-repository)
  - [Implementation Checklist](#implementation-checklist)
  - [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
  - [Toward Kinetic Workflows](#toward-kinetic-workflows)
  - [Quickstart Recap](#quickstart-recap)

# Why An Iterative Ontology (Not A Grand Schema)

Golden Grid succeeds when the ontology grows at the same pace as your operational questions. Start with the decision you need to support, model only the nouns and actions that touch that workflow, and let additional fields emerge through change management instead of speculative design. As soon as that workflow depends on a system of record (Salesforce, Databricks, internal orchestration), document who can see the data and who can act on it—the ontology and the permission model should advance together. The layer boundaries (raw → clean → transform → ontology) keep physics, tariffs, and finance understandable in isolation; the Appendix walks through the full checklist for teams that need the step-by-step playbook.

# Energy Time Series + Control: Two Context Channels

Think of the platform as two braided streams. The energy time series channel shepherds behind-the-meter telemetry and model outputs into `RawIntervals` so that site load, PV production, batteries, and state of charge flow cleanly through the pipeline. That includes live device telemetry as well as synthesized profiles from tools like EnergyPlus, PVWatts, or ResStock—anything that produces interval energy data slots into the same normalization path. The control channel captures intent—dispatch events, program enrollment, operating constraints—inside `OntologyControlEvent` objects grouped as schedules. Align those streams with your access layers: telemetry might be read-only to most roles, while control schedules demand explicit, auditable permissions in your system of record. Keeping intent separate from telemetry preserves auditability today and leaves room for future market coordination; see [Appendix: Timeseries & Control Channels](#timeseries--control-channels) for adapter specifics.

# Tariffs: From Source Payloads To Rates You Can Use

Tariffs arrive as PDFs, JSON payloads, spreadsheets, or all three at once. Golden Grid keeps tariff definitions distinct from the energy time series feeds that drive them: UtilityAPI and DERAPI supply interval data for meters and assets, while Arcadia and curated regulatory filings provide the rate constructs we translate into `TariffSchedule` objects. By separating those concerns we can produce hourly prices, demand windows, and export logic that line up with your energy flows without baking tariff math into transformation code. Detailed adapter notes and helper utilities live in the appendix section on [Tariffs and Rates](#tariffs-and-rates).

# What The Workflows Show

The repository workflows act as a living smoke test: one wires a solar-only home, another layers in a battery with state-of-charge rules, and a third demonstrates tariff parsing in isolation. Running them (`uv sync` and the relevant `uv run python ...` command) lets you swap in your payloads without touching ontology internals. Appendix entries on [Workflows in the Repository](#workflows-in-the-repository) and the [Implementation Checklist](#implementation-checklist) unpack each script if you want the blow-by-blow.

# How To Implement This In Your Organization

Most teams move through three passes:

1. **Name the essentials.** Align on assets, meters, and the handful of measures that drive value now.
2. **Connect the feeds.** Point adapters at your telemetry, tariffs, and control payloads; keep conversions explicit.
3. **Close the loop.** Validate outputs against a bill, dispatch window, or KPI so future iterations have a baseline.

Each phase maps directly to the appendix checklist, which covers field-level guidance, commands, and governance tips once you are ready for the deeper dive.

# Iteration Loop That Works

Golden Grid is built for incremental proof: introduce one asset or tariff, confirm it, then layer the next source of truth. When you add control schedules or finance metrics, do it because a workflow demands it—not because it might someday. That cadence keeps your ontology nimble while steadily expanding the ground it can cover.

# Common Anti‑Patterns (And What To Do Instead)

Three failure modes show up repeatedly: blending financial math into physics layers, letting units or interval lengths go implicit, and burying control intent inside energy series. Guardrails for each live in the appendix’s [Anti-Patterns](#anti-patterns-to-avoid) section, along with the mitigations we use in production.

# Kinetic Workflows (When You’re Ready)

When analysis graduates into execution, the same ontology gives you confidence to simulate dispatch strategies, compare bill deltas, or export a “home twin” bundle for grid-scale experiments. That’s the moment the model turns kinetic: shared semantics and auditable dynamics powering decisions under real constraints.

Treat each kinetic workflow as a runnable artifact—the CLI workflows under `workflows/` are the first templates. As you promote them into production, make sure your system of record (Salesforce, Databricks, or an internal orchestration tool) captures which roles can view the data, trigger actions, or modify schedules. Permissioning becomes part of the workflow contract just like units or enums.

# Closing: Ontologies As Context Contracts

An ontology is a context contract. It lets teams name things the same way, carry meaning from source to decision, and evolve responsibly. Golden Grid is opinionated about boundaries (behind the meter), explicit about layers, and practical about progress: you only need enough semantics today to support the dynamics you’re about to run—and enough dynamic clarity to go kinetic when you’re ready.

If you want help mapping your payloads or shaping a first OntologyHome, start by running the workflows with your data. From there, we can add just the fields you need, exactly where they belong.

# Appendix: Expanded Guide for Implementers

Use this appendix as the companion reference for the sections above—each heading mirrors the main article but dives into the implementation detail. Golden Grid exists to keep context from leaking between teams. Home datasets, DER telemetry, tariffs, and policies all use different shapes and meanings; we built an ontology that you can evolve as your workflows mature instead of forcing a grand “finished” schema on day one. Think of it as context management: a shared language that moves from semantics (what things are) to dynamics (what they do) to kinetic execution (how they behave inside real workflows).

## Why an Iterative Ontology (Not a Grand Schema)

- Start where you work – model only the nouns and actions your current pipeline needs.
- Keep layers thin – source payloads → clean arrays → engineered values → user-facing objects.
- Govern lightly – add fields when justified; document defaults; avoid breaking changes.
- Separate concerns – physics, tariffs, and finance reference the same home model without entangling each other.

We’re deliberately focused on **home modeling first**: once the behind-the-meter context is coherent, future extensions (grid simulation, control coordination, finance) plug in cleanly.

## Context Management: Semantic → Dynamic → Kinetic

Use ontologies as progressive context layers:

1. **Semantic (nouns & relationships)** – `OntologyHome`, assets, meters, tariff agreements, enrollments, control schedules, financial KPIs.
2. **Dynamic (actions & time series)** – interval pipeline (`Raw → Clean → Transform → Ontology`), AC/DC conversions, site/home loads, dispatch signals.
3. **Kinetic (workflows under constraints)** – control schedule dispatch, program logic, bill-impact simulations, “what if” scenarios.

### Core Objects and Naming

- `OntologyHome` container with identity, meters, assets (`OntologyPVAsset`, `OntologyBatteryAsset`, `OntologyEVSEAsset`, `OntologyHPWHAsset`), `OntologyTariffAgreement`, `OntologyProgramEnrollment`, `OntologyFinancials`.
- Intervals: `RawIntervals → CleanIntervals → TransformIntervals → OntologyIntervals`.
- Bills: `RawBills → CleanBills → TransformBills → OntologyBills` (`OntologyBillPeriod`, `OntologyAnnualBillSummary`).
- Control: `RawControlEvent → CleanControlEvent → OntologyControlEvent` grouped in `OntologyControlSchedule`.

## Timeseries & Control Channels

- **Energy time series** – behind-the-meter telemetry or modeled profiles via adapters such as `TimeseriesAdapter` (mapped from `DataSource.TIMESERIES`) into `RawIntervals`.
- **Control** – intent parsed by adapters such as `ControlAdapter` (mapped from `DataSource.CONTROL`) into `OntologyControlEvent` and `OntologyControlSchedule`.

## Tariffs and Rates

- UtilityAPI Blocks adapter for net/import/export/generation streams.
- DERAPI adapter for solar, battery, consumption intervals (handles `missing`, SoC metadata).
- Arcadia adapters (`RawArcadiaTariff*`, `ArcadiaTariffAdapter`) + optional TOU enrichment + `tariff_to_hourly_rates`.

## Workflows in the Repository

1. `complete_data_flow.py` – full raw→ontology solar example (baseline smoke test).
2. `partial_electrification_flow.py` – solar-only, wires UtilityAPI + DERAPI + Arcadia tariffs, outputs `OntologyHome` and `OntologyControlSchedule`.
3. `partial_electrification_with_battery.py` – adds battery intervals, SoC/power constraints, Arcadia billing.
4. `arcadia_tariff_example.py` – parses tariff + TOU and prints hourly rates.
5. `tools/print_tou_rates.py` – small helper to visualize hourly TOU prices.

Run with Python 3.10+:

```sh
uv sync
uv run python workflows/partial_electrification_flow.py
uv run python workflows/partial_electrification_with_battery.py
uv run python workflows/arcadia_tariff_example.py
```

## Implementation Checklist

1. Clarify nouns (assets, meters, measurement definitions).
2. Map data sources; emit `Raw*` objects with explicit units/intervals.
3. Normalize and derive (Clean/Transform layers).
4. Attach tariffs and build bills (`tariff_to_hourly_rates`, `build_ontology_bills_from_hourly`).
5. Compose `OntologyHome` (`OntologyHome.from_components`/`build_home`).
6. Validate with sample scripts; then plug in your payloads.
7. Govern changes conservatively (document defaults, prefer extensions).

## Anti-Patterns to Avoid

- Mixing billing logic into transform layers.
- Dropping units or interval context.
- Over-generalizing before the workflow needs it.
- Folding control signals into energy math instead of storing them in control schedules.

## Toward Kinetic Workflows

- Simulate dispatch policies using hourly rates and transformed intervals.
- Measure bill deltas with/without control schedule events.
- Export “home twins” for VPP/grid simulation.
- Layer finance metrics once flows stabilize.
- Document permission scopes in your source system (e.g., Salesforce profile, Databricks catalog, internal workflow roles) so every kinetic action has an auditable owner.

## Quickstart Recap

1. Run `workflows/complete_data_flow.py` to confirm the pipeline on sample data.
2. Swap in one of your payloads, extend adapters or enums only where the data demands it, and re-run the flow.
3. Log what changed (fields, units, assumptions) so the next iteration starts with shared context.