OpenDSM

1.2.7 verified Fri May 01 auth: no python

OpenDSM provides standard methods for predicting building energy usage, supporting hourly, daily, and billing models with clustering and baseline metrics. Current version 1.2.7, requires Python >=3.10, and is actively maintained on GitHub.

pip install opendsm

Common errors

error ModuleNotFoundError: No module named 'opendsm' ↓

cause OpenDSM requires Python >=3.10. If your environment uses an older Python version, installation will fail.

fix

Check Python version: python --version. Upgrade to Python 3.10+ and reinstall: pip install opendsm

error AttributeError: module 'opendsm' has no attribute 'OpenDSM' ↓

cause Using 'import opendsm' and then accessing opendsm.OpenDSM fails because the package does not export classes at the top level when imported as a module.

fix

Use: from opendsm import OpenDSM

error ImportError: cannot import name 'HourlyModel' from 'opendsm' ↓

cause HourlyModel is not in the top-level package; it is in a submodule.

fix

Use: from opendsm.hourly import HourlyModel

error ValueError: Data must have a 'temperature' column when temperature_column is set ↓

cause When adding data, if you specify a temperature column, that column must exist in the DataFrame.

fix

Ensure the DataFrame contains the specified temperature column name.

Warnings

breaking In v1.2.0, the logging interface changed to a modern logger. If you previously configured logging via the old interface, you must update your code to use the new logging module from opendsm.logger. ↓

fix Use from opendsm.logger import logger and configure via logger.setLevel(...) instead of direct logging calls.

breaking Daily and billing models now use BaselineMetrics natively in v1.2.0. If you relied on custom metric calculations, you may need to update your code to use the BaselineMetrics class. ↓

fix Use from opendsm.metrics import BaselineMetrics to access metrics.

deprecated The old 'from_series' method for daily data class instantiation has a bug fixed in v1.2.6. If you were using it before, upgrade to v1.2.6+ to avoid issues. ↓

fix Upgrade to v1.2.6: pip install opendsm>=1.2.6

gotcha Spectral clustering results may not be deterministic across runs unless you set the seed via the clustering settings. Use seed=42 or similar. ↓

fix Set seed in clustering_settings: clustering_settings = {'seed': 42}.

gotcha Data sufficiency can be modified via a settings dictionary but this is intended for R&D; defaults may differ from production standards. ↓

fix Documentation for data sufficiency settings is limited; use with caution.

Imports

OpenDSM
wrong
```
import opendsm
```
correct
```
from opendsm import OpenDSM
```
Direct import of the package does not expose the top-level class; must import specifically.
HourlyModel
wrong
```
from opendsm import HourlyModel
```
correct
```
from opendsm.hourly import HourlyModel
```
HourlyModel is in the hourly submodule, not at package root.

DailyModel

wrong

from opendsm import DailyModel

correct

from opendsm.daily import DailyModel

DailyModel is in the daily submodule.

BillingModel

wrong

from opendsm import BillingModel

correct

from opendsm.billing import BillingModel

BillingModel is in the billing submodule.

BaselineMetrics

wrong

from opendsm.evaluation import BaselineMetrics

correct

from opendsm.metrics import BaselineMetrics

Metrics module is named 'metrics', not 'evaluation'.

Quickstart

Quickstart example loading hourly data and fitting an hourly model.

from opendsm import OpenDSM
from opendsm.hourly import HourlyModel
import pandas as pd

# Create sample hourly energy usage data
import numpy as np
dates = pd.date_range('2023-01-01', periods=8760, freq='H')
energy = np.random.rand(8760) * 100
temp = np.random.rand(8760) * 35
df = pd.DataFrame({'energy': energy, 'temperature': temp}, index=dates)

# Initialize OpenDSM with a project name
project = OpenDSM('my_project')

# Add data
project.add_data(df, energy_column='energy', temperature_column='temperature')

# Run hourly model
model = HourlyModel(project)
model.fit()
print(model.results())