CAMBER

Commissioning, Analytics & M&V for Building Energy Re-tuning

A vendor-neutral Python toolkit for analyzing Building Automation System (BAS) trend data — fault detection & diagnostics (FDD), measurement & verification (M&V), and retro-commissioning (RCx) — across any building, independent of the BAS vendor.

The core idea: points are mapped to a small vocabulary of vendor-neutral roles (HEAT_VALVE, SUPPLY_AIR_TEMP, OAT, …), and every diagnostic is written against those roles. Map a building's tags once and the whole rule set runs on it — one rule, all equipment, any BAS.

Documentation

yroussev.github.io/camber — the rendered docs, with search. Everything below is a summary of it.

A look at the output

Fault-annotated trends (Visualization)	Drift against a frozen baseline (Chiller drift)	M&V savings with uncertainty (M&V)

All three are drawn by CAMBER's own chart code on synthetic data; scripts/docs_figures.py renders every figure in the docs.

What it does

Full API-level detail — every capability, its flags, and the standard it cites — is in docs/CAPABILITIES.md (on the site).

• Ingest — per-point and wide/tabular CSV, a long/tall adapter, named vendor profiles and a multi-format timestamp/value parser (ISO / US / EU-dayfirst / BAS / epoch / Excel-serial), a Project-Haystack hisRead client, SQL/historian readers, and read-only network adapters (Modbus, MQTT/Sparkplug, BACnet incl. experimental BACnet/SC, OPC-UA) — read-only by construction, lazy-imported, historian-first (SECURITY).
• Semantic model — a vendor-neutral Role vocabulary + mapping provider, a site/equipment/point entity model with completeness validation, a served-by topology populated from Brick, Haystack or naming, and interop both ways with Brick, Haystack tags and ASHRAE 223P.
• FDD — ASHRAE Guideline 36 AFDD (operating states, FC#1–15, trim-and-respond resets) and PNNL Building Re-tuning diagnostics; an 11-rule central plant & hydronic library; packaged/DX and refrigerant-side rules (RTU, heat-pump/VRF, DOAS, FCU); a Sequence-of-Operations conformance engine with a packaged G36 clause library; cohort/peer and topology-scoped fleet rules.
• Drift detection — the complement to "is this value wrong?": has this equipment been drifting away from its own frozen baseline? Six families — chiller, condenser, evaporator, pump/hydronic, AHU air-side and VAV zone-terminal — each comparing at matched load or duty, each rolling up to one localized verdict, and each driveable from a config or camber drift (CLI).
• Trim-and-Respond / G36 reset analytics — does the plant's reset logic do what G36 intends? Reset compliance and effectiveness, plus a rogue-zone census (which zone monopolizes the reset) and its common-mode twin, cohort starvation. See TR-RESET.md.
• Data trust — sensor faults are not equipment faults: physical bounds, cross-sensor consistency, sensor drift vs an external reference, and mapping confidence, wired as a gate so a rule that cannot trust its inputs declines to fire rather than reporting a false fault.
• M&V — IPMVP Options A / B / C / D: change-point models (2P–5P + zero variants), LBNL TOWT, G14 fit statistics and fractional savings uncertainty, CUSUM, weather normalization, normalized annual savings, non-routine adjustment, retrofit isolation, variable-base degree-day, and a 1R1C/2R2C grey-box calibrated to metered energy (OPTION-D). CalTRACK-aligned.
• Commissioning — RCx/MBCx: functional-test scoring, before/after persistence checks, and a measure register grading each fix to verified / regressed / inconclusive.
• Money & compliance — a native tariff engine + OpenEI URDB, bill validation, ECM NPV/IRR/SIR, demand & peak analytics, per-fault dollar economics, and BPS / EUI compliance checks.
• Grid & carbon — demand response and flexibility quantification, carbon-aware load timing, hourly/marginal Scope-2, and OpenADR export.
• Domain analytics — Std-55 comfort, CO₂/62.1 ventilation, cost, carbon, water, load profiling and disaggregation, schedule inference, PV (+ pvlib), psychrometrics (+ PsychroLib), lighting.
• Weather — two keyless providers (NASA POWER's global grid, NOAA/ISD's real stations) plus a geocoder, so you can fetch outdoor conditions by address (WEATHER).
• Advisory & synthesis — impact prioritization, root-cause grouping, fault-lifecycle tracking, advisory setpoint/sequence suggestions (ASO), action plans, and a building health scorecard.
• AI-assist (advisory, provider-agnostic) — assisted point mapping and grounded explanation and Q&A over the deterministic layers, citing the rule and data behind every claim. Fully useful with no LLM wired; no vendor named, no SDK, no network (AGENT).
• Reporting & visualization — ASHRAE/ACCA Standard 211 audits, a portfolio rollup ranked by recoverable dollars, ten chart patterns where every rule renders its own evidence, a self-contained HTML dashboard with cross-panel brush linking, and a live web UI.
• Storage & platform — a partitioned Parquet store with rollups, retention and a cached catalog (validated to portfolio scale), a plugin API, findings → CMMS + notifiers, a read-only HTTP API, and a one-way edge forwarder for cybersecure edge→cloud collection.
• Validation — accuracy scored against labeled public data and CI-gated, plus camber validate, a single credibility dossier. Honest about its limits: VALIDATION.md states per detector family which claims rest on real data and which are synthetic-only.

Install

Python 3.10+ and numpy 2 (numpy 1.x is not supported). The PyPI distribution name is camber-toolkit (it imports as camber).

pip install camber-toolkit             # from PyPI
pip install "camber-toolkit[brick]"    # + rdflib, for robust Brick-model parsing (optional)

The core is dependency-light (numpy / pandas / pyarrow / matplotlib). Everything else is an optional extra, lazy-imported so the core never pays for it: brick, haystack, modbus, mqtt, bacnet, opcua, pv, psychro, tariff, ml, energyplus, yaml, docs, dev. Install what you use.

pip install -e .            # the package (editable)
pip install -e .[dev]       # + pytest / ruff / mypy, for development

Quickstart

python -m pytest -q                 # run the test suite
python examples/synthetic_demo.py   # data-free FDD demo on generated trends

To learn on open building datasets in a browser, run camber lab: Using the lab walks through a first session, from picking a dataset to reading its report.

CAMBER installs a camber console script. A whole analysis is one JSON config (source → mapping → equipment → rules → report) and one command:

camber run    config.json --out out/   # discover equipment, run the rules, write findings.json
camber report config.json --out audit.html
camber ask    "which building is worst?" --config config.json   # grounded, cited
camber serve  ./store                  # read-only API + live dashboard at /ui

Drift detection needs a frozen reference, so it has its own verbs — see docs/CLI.md and the runnable examples/drift/ walkthrough:

camber drift freeze config.json        # establish the baselines (the only create path)
camber drift run    config.json        # score the current window against them

Usage

Everything runs on role-named frames — a DataFrame whose columns are vendor-neutral Roles. Map a building's tags to roles once, then every diagnostic and model runs on it.

Fault detection — run a diagnostic, get a structured Finding:

import numpy as np, pandas as pd
from camber.model.roles import Role
from camber.rules.simul_hc import SimultaneousHeatCool

idx = pd.date_range("2025-07-07", periods=24 * 7, freq="1h")
frame = pd.DataFrame(
    {
        Role.OAT: 90 + 10 * np.sin((idx.hour - 9) / 24 * 2 * np.pi),
        Role.COOL_VALVE: 70.0,  # cooling all day
        Role.HEAT_VALVE: np.where(
            (idx.dayofweek < 5) & idx.hour.isin([11, 12, 13, 14]), 40.0, 0.0
        ),  # midday reheat — a fault
    },
    index=idx,
)

f = SimultaneousHeatCool().analyze("AHU_1", frame)
print(f.severity, f.metrics["simultaneous_hc_pct"])  # -> fault 36.36

Measurement & verification — fit a change-point baseline and score it:

import numpy as np
from camber.mandv.models import best_model, N_PARAMS
from camber.mandv.stats import fit_stats

oat = np.linspace(35, 100, 120)
energy = 50 + np.clip(oat - 65, 0, None) * 3 + np.random.default_rng(0).normal(0, 2, 120)
m = best_model(oat, energy)  # picks the inverse model
st = fit_stats(energy, m.predict(oat), N_PARAMS[m.kind])
print(m.kind, round(st.r2, 2), f"{st.cv_rmse:.0%}")  # -> 3PC 1.0 2%

Your own building — map point names → roles in a small JSON config (or derive it from a Brick model with camber.interop.brick), then resolve() assembles the role-frames. See examples/ for end-to-end runs on public datasets.

Reproducible runs — describe a whole analysis in one JSON config and run it without a script: camber run config.json (or python -m camber.config config.json). Add a drift section and the same command scores baseline-vs-current drift alongside the rules.

Tunable thresholds — every rule threshold can be set from the config's params. camber rules params [RULE] lists each one with its default, where that default comes from, and how to calibrate it from your own data, plus a ready-to-paste config snippet. Configs may be YAML (pip install "camber-toolkit[yaml]") so a calibration note can sit beside its value; JSON needs nothing extra. See docs/THRESHOLDS.md and Tuning thresholds with your own data.

Docker

docker build -t camber .
docker run --rm camber               # runs the test suite as a clean-build proof
docker run --rm -it camber bash      # interactive shell

Mount a building's CSV export at /data to run analytics on real trends.

Learn re-tuning with CAMBER

The re-tuning workbook (on the site) is a hands-on course that follows PNNL's free Building Re-tuning training. Each exercise pairs a PNNL chapter or guide, linked and never copied, with an open dataset from the catalog: read the guide, open the building in camber lab, and find the faults it teaches you to look for, with the steps given both in the lab and on the command line.

camber lab                     # open the URL it prints, Fetch & ingest lbnl-sdahu
camber datasets config lbnl-sdahu --exercise air-economizer --store lab_store --out econ.json
camber run econ.json

A separate instructor page holds the answer keys. Every answer on it is pinned by the test suite, on synthetic stand-ins and (with pytest -m network) on the real data, so the workbook cannot silently drift from what CAMBER reports. The first worked example is a stuck outdoor-air damper; the curriculum map lists the rest.

Public datasets

The toolkit is data-agnostic. Two open sources are wired as runnable examples (referenced + fetched, not bundled):

• LBNL Fault Detection and Diagnostics Datasets (CC-BY) — labeled equipment data. examples/lbnl_fdd/ maps its point names to roles, validates completeness, round-trips through the Parquet store, and scores the detector suite across five wired subsets: single-duct AHU, fan-coil unit, dual-duct AHU, the VAV fan-power-unit set (--fpu) and the chiller-plant set (--chiller). Which detectors each subset can honestly test — and which stay synthetic-only — is stated in VALIDATION.md.
• Building Data Genome Project 2 (CC-BY-SA 4.0) — 3,053 whole-building hourly meters. examples/bdg2/ fits the G14/IPMVP change-point engine to the publisher's cleaned meters (textbook 3PC on cooling energy, R² 0.70–0.88) and ingests the portfolio into the store.

Both are also in the dataset catalog (camber datasets, DATASETS.md), which links each dataset exactly as published and lists every problem found in the published data — with its evidence, the documentation it contradicts and how CAMBER handles it.

Each example has a fetch.py (downloads to the git-ignored examples/_data/) and a runnable script. See the per-example READMEs.

Contributing

Contributions are welcome — new diagnostics, ingest adapters, M&V models, ontology interop, docs, and fixes. See CONTRIBUTING.md for the dev setup and conventions, docs/CAPABILITIES.md for a full capability reference (API + option flags per feature), docs/ARCHITECTURE.md for the layered design, ROADMAP.md for what's planned and where to help, docs/ECOSYSTEM.md for the OSS-integration strategy, and the Code of Conduct. Security reports: see SECURITY.md.

Community & support

Usage questions and ideas: GitHub Discussions. Bugs and concrete feature requests: Issues. Please keep everything vendor- and site-neutral — describe scenarios generically and never post a real client site name or raw building data.

Provenance

This is a clean-room implementation. Algorithms are reimplemented from public standards — ASHRAE Guideline 36, Guideline 14, Standard 55, Standard 211; IPMVP; PNNL Building Re-tuning; NIST APAR. No third-party source code is included.

License

Apache-2.0. See LICENSE and NOTICE.

Status: pre-release (v0.x). The public surface is settled and locked by a snapshot test, and changes follow the deprecation policy in docs/API-STABILITY.md — but until 1.0 it can still move.