Energetic

Automated building energy efficiency descriptor generation, model training, and deployment — similar to Mordred for chemical descriptors and Jaqpotpy for model deployment, but purpose-built for building energy analysis.

Features

• 200+ automated descriptors from building geometry, context, envelope, and time-series data
• Minimal input required — pass a GeoJSON, Shapefile, CityJSON, or DataFrame with WKT geometries
• ML model training with XGBoost, RandomForest, LightGBM, and Neural Networks
• Hyperparameter optimization via Optuna
• Model packaging and upload to custom deployment platforms
• Open dataset integration (ASHRAE, Building Data Genome, NYC LL84, OSM)
• Meteorological data enrichment for expanded feature sets

Installation

pip install -e .

# With ML extras (XGBoost, LightGBM, Optuna)
pip install -e ".[ml]"

# Full installation

Quick Start

Generate Descriptors

from energetic import EnergyFeaturizer

featurizer = EnergyFeaturizer(descriptors="all", cache=True, n_jobs=-1)
features = featurizer.fit_transform("buildings.geojson")

print(f"Generated {len(featurizer.get_feature_names())} descriptors")
featurizer.to_csv("features.csv")

Train a Model

from energetic import EnergyFeaturizer, EnergyModelTrainer
import pandas as pd

featurizer = EnergyFeaturizer()
features = featurizer.fit_transform("buildings.geojson")

X = features.drop("building_id", axis=1)
y = pd.read_csv("eui_targets.csv")["eui"]

trainer = EnergyModelTrainer(task="regression", model="xgboost")
metrics = trainer.train(X, y, optimization_trials=50)
trainer.save("model.joblib")

Upload to Platform

from energetic import ModelUploader

uploader = ModelUploader(
    endpoint_url="https://your-platform.example.com",
    api_key="your-api-key",
)
model_id = uploader.upload(trainer, featurizer, metadata, "office_eui_v1")

CLI

# Generate descriptors
energetic featurize buildings.geojson -o features.csv

# Train model
energetic train features.csv targets.csv -o model.joblib -m xgboost

# Show descriptor info
energetic info --descriptors

# End-to-end pipeline
energetic pipeline buildings.geojson targets.csv -o output/

Descriptor Categories

Input Formats

• GeoJSON — .geojson, .json
• Shapefile — .shp
• CityJSON — .city.json
• CSV/DataFrame — WKT geometry column
• Python dicts — list of building dictionaries

Open Datasets

from energetic.datasets import OpenDatasetLoader

loader = OpenDatasetLoader()

# NYC LL84 — live Socrata API (no auth required)
nyc = loader.load("nyc_building_energy", max_records=1000, property_type="Office")

# ASHRAE / BDG2 — Kaggle API (requires ~/.kaggle/kaggle.json)
ashrae = loader.load("ashrae_great_energy_predictor")
bdgp = loader.load("building_data_genome", components=["metadata", "electricity"])

# OSM footprints — Overpass API or OSMnx
osm = loader.load("openstreetmap_buildings", latitude=40.75, longitude=-73.98, radius_m=300)

# Run standardized benchmarks
result = loader.run_benchmark("nyc_site_eui", model="random_forest")
print(result["test_metrics"])

License

MIT