Metadata-Version: 2.4
Name: energetic
Version: 0.0.1
Summary: Automated building energy efficiency descriptor generation, model training, and deployment
Author: Energetic Contributors
License: MIT
Project-URL: Homepage, https://github.com/energetic/energetic
Project-URL: Documentation, https://energetic.readthedocs.io
Project-URL: Repository, https://github.com/energetic/energetic
Keywords: building energy,descriptors,machine learning,urban morphology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scikit-image>=0.21
Requires-Dist: shapely>=2.0
Requires-Dist: geopandas>=0.14
Requires-Dist: pydantic>=2.0
Requires-Dist: joblib>=1.3
Requires-Dist: requests>=2.31
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.66
Requires-Dist: statsmodels>=0.14
Provides-Extra: ml
Requires-Dist: xgboost>=2.0; extra == "ml"
Requires-Dist: lightgbm>=4.0; extra == "ml"
Requires-Dist: optuna>=3.4; extra == "ml"
Provides-Extra: osm
Requires-Dist: osmnx>=1.6; extra == "osm"
Requires-Dist: networkx>=3.1; extra == "osm"
Provides-Extra: context
Requires-Dist: osmnx>=1.6; extra == "context"
Requires-Dist: networkx>=3.1; extra == "context"
Provides-Extra: meteo
Requires-Dist: xarray>=2023.1; extra == "meteo"
Requires-Dist: netCDF4>=1.6; extra == "meteo"
Provides-Extra: datasets
Requires-Dist: kaggle>=1.6; extra == "datasets"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Provides-Extra: all
Requires-Dist: energetic[context,datasets,dev,docs,meteo,ml,osm]; extra == "all"
Dynamic: license-file

# Energetic

Automated building energy efficiency descriptor generation, model training, and deployment — similar to [Mordred](https://github.com/mordred-descriptor/mordred) for chemical descriptors and [Jaqpotpy](https://github.com/jaqpot/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

```bash
pip install -e .

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

# Full installation
```

## Quick Start

### Generate Descriptors

```python
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

```python
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

```python
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

```bash
# 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

| Category | Count | Examples |
|----------|-------|---------|
| Morphological | 60+ | Area, Zernike moments, Hu moments, fractal dimension |
| Contextual | 40+ | Sky view factor, neighbor density, solar potential |
| Envelope | 50+ | Wall-to-floor ratio, WWR, thermal mass, roof type |
| Temporal | 50+ | PRISM parameters, load factor, seasonality, ramp rates |

## Input Formats

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

## Open Datasets

```python
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
