CAMBER

CI

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.

What it does

  • Ingest — adapters for per-point CSV exports, wide/tabular CSV, and a Project Haystack hisRead client (behind an injectable transport).
  • Semantic model — a role vocabulary + mapping provider, plus a site/equipment /point entity model with completeness validation (which analytics a building's instrumentation can support). Brick interop: derive the point→role mapping automatically from a building's Brick (.ttl) model.
  • FDD — a rule engine implementing ASHRAE Guideline 36 AFDD (operating states, fault conditions FC#1–15, trim-and-respond resets) and PNNL Building Re-tuning diagnostics (simultaneous heat/cool, reheat penalty, SAT/CHW reset, economizer, boiler lockout, overcooling, setback, OA fraction incl. under-ventilation, leaking valves, static/pump resets). Plus impact prioritization, fault-lifecycle tracking, and an FDD-accuracy benchmark harness (scored against labeled data).
  • M&V — IPMVP / ASHRAE Guideline 14 change-point inverse models (2P–5P plus heating-zero variants) and the LBNL Time-of-Week & Temperature (TOWT) model for schedule-driven loads, CV(RMSE)/NMBE statistics and fractional savings uncertainty, CUSUM savings tracking, weather normalization (TMY/EPW), and rate/energy-aware resampling.
  • Cost & carbon — utility cost accounting (energy + demand + time-of-use, and tiered water/wastewater with marginal vs. average rates) and GHG emissions (eGRID/EIA factors → CO₂e and intensity).
  • Water — irrigation water budgets (ETo / landscape coefficient / efficiency / effective precipitation), cooling-tower makeup (cycles of concentration, gal/ton-hr), and leak detection (minimum night flow, flow duration, leak cost).
  • Load profiling — peak / near-peak / base, base-to-peak ratio, load factor, load-duration curve, and weekday/weekend daily shapes.
  • On-site systems — PV performance ratio, specific yield, and net/self- consumption energy; lighting operational efficiency vs. installed power with controls-fault flags (failed setback, no turndown).
  • Comfort — Fanger PMV/PPD per ASHRAE Standard 55 / ISO 7730.
  • Reporting — ASHRAE/ACCA Standard 211 audit deliverables (benchmark + prioritized findings + ECM table) to text/HTML, and a fleet/portfolio rollup (cross-sectional EUI benchmarking + fleet-wide fault counts).
  • Storage — a Parquet time-series store keyed to the entity model, with tag-filtered reads.
  • Quality — per-point data-quality scoring (robust outliers, flatline/gap detection) with an auditable cleaning trail.
  • Integration — findings → CMMS-ticket records and a pluggable notifier; a read-only HTTP API over the store (python -m camber.api.server <store> [port]: /sites, /points, /history).

Install

Python 3.10+. 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)

From source (for development):

pip install -e .            # the package (editable)
pip install -e .[dev]       # + pytest, for development
pip install -e .[brick]     # + rdflib, for robust Brick-model parsing (optional)
pip install -e .[haystack]  # + a Haystack client (phable / pyhaystack) (optional)

Quickstart

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

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 (source → mapping → equipment → rules → report) in one JSON config and run it without a script:

python -m camber.config run.json     # discovers equipment, runs the rules, writes the report

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.

Public datasets

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

  • LBNL Fault Detection and Diagnostics Datasets (CC-BY) — labeled single-duct-AHU data. examples/lbnl_fdd/ maps its point names to roles, validates completeness, round-trips through the Parquet store, and detects a labeled stuck-damper fault (OAF ~21% baseline → ~100% fault).
  • Building Data Genome Project 2 (CC-BY) — 3,053 whole-building hourly meters. examples/bdg2/ fits the G14/IPMVP change-point engine (textbook 3PC on cooling energy, R² 0.78–0.94) and ingests the portfolio into the store.

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). APIs may change.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.79.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for slona from gravatar.com slona

Credits

Author: The CAMBER authors

License

Apache Software License (Apache-2.0)

Requires

Python >=3.10

Provides Extra

dev docs brick haystack tariff better psychro pv modbus mqtt bacnet bacnet-vendor opcua ml

Tags

BAS HVAC FDD fault detection measurement and verification retro-commissioning ASHRAE energy EMIS

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

camber_toolkit-0.28.0.tar.gz (435.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

camber_toolkit-0.28.0-py3-none-any.whl (556.4 kB view details)

Uploaded Python 3

File details

Details for the file camber_toolkit-0.28.0.tar.gz.

File metadata

  • Download URL: camber_toolkit-0.28.0.tar.gz
  • Upload date:
  • Size: 435.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for camber_toolkit-0.28.0.tar.gz
Algorithm Hash digest
SHA256 8842d8bea58817a7911b050a162d02e2f28ec42b1f6836f00c8942369d6bbc30
MD5 e2ecd7fae755320bb83617e4dbebbf33
BLAKE2b-256 88f2f8d7413fd425926865ebc6870fbb8f290bec25258a52b84273a6fcaa683e

See more details on using hashes here.

Provenance

The following attestation bundles were made for camber_toolkit-0.28.0.tar.gz:

Publisher: release.yml on yroussev/camber

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file camber_toolkit-0.28.0-py3-none-any.whl.

File metadata

  • Download URL: camber_toolkit-0.28.0-py3-none-any.whl
  • Upload date:
  • Size: 556.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for camber_toolkit-0.28.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2a5e5a367d89cf97704274ce3ea2486c187ab5e5e67f414ba3089d3081b410d2
MD5 ca39d0eb4fbf797295475b1579a56aa8
BLAKE2b-256 df28fde2a93f86d1cfb7ee06d872b6b066745ed387b81d43a019a0a70cf82492

See more details on using hashes here.

Provenance

The following attestation bundles were made for camber_toolkit-0.28.0-py3-none-any.whl:

Publisher: release.yml on yroussev/camber

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.79.0

2 files

0.78.0

2 files

0.77.0

2 files

0.76.0

2 files

0.75.0

2 files

0.74.1

2 files

0.74.0

2 files

0.73.0

2 files

0.72.0

2 files

0.71.0

2 files

0.70.0

2 files

0.69.0

2 files

0.68.0

2 files

0.67.0

2 files

0.66.0

2 files

0.65.0

2 files

0.64.0

2 files

0.63.0

2 files

0.62.0

2 files

0.61.0

2 files

0.60.0

2 files

0.59.0

2 files

0.58.0

2 files

0.57.0

2 files

0.56.0

2 files

0.55.0

2 files

0.54.0

2 files

0.53.0

2 files

0.52.0

2 files

0.51.0

2 files

0.50.0

2 files

0.49.0

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.0

2 files

0.43.0

2 files

0.42.0

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.0

2 files

0.31.0

2 files

0.30.0

2 files

0.29.0

2 files

This release

0.28.0 This release

2 files

0.25.0

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.0

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page