Savings Estimation

Functions for estimating energy and cost savings from efficiency improvements.

Savings Calculation

better_lbnl_os.estimate_savings(benchmark_input, calendarized, *, floor_area, savings_target=None, location_info=None, address=None, latitude=None, longitude=None, google_maps_api_key=None, country_code=None)[source]

Main entry point for savings estimation.

Parameters:
Return type:

SavingsSummary

better_lbnl_os.estimate_savings_for_fuel(benchmark_data, calendarized, *, floor_area, energy_type, window=12, location_context=None)[source]

Estimate savings for a single energy type.

Parameters:
Return type:

FuelSavingsResult

Module Reference

Savings estimation engine extracted from BETTER’s Django application.

class better_lbnl_os.core.savings.CombinedSavingsSummary(*, current, target, typical, energy_savings_kwh, energy_savings_percent, cost_savings_usd, cost_savings_percent, ghg_savings_kg_co2, ghg_savings_percent, eui_savings_kwh_per_m2, ghg_intensity_reduction_kg_co2_per_m2, component_savings, valid)[source]

Bases: BaseModel

Whole-building savings summary across fuels.

Parameters:
current: UsageTotals
target: UsageTotals
typical: UsageTotals
energy_savings_kwh: float
energy_savings_percent: float
cost_savings_usd: float
cost_savings_percent: float
ghg_savings_kg_co2: float
ghg_savings_percent: float
eui_savings_kwh_per_m2: float | None
ghg_intensity_reduction_kg_co2_per_m2: float | None
component_savings: ComponentSavings
valid: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.ComponentSavings(*, energy_kwh=<factory>, cost_usd=<factory>, ghg_kg_co2=<factory>)[source]

Bases: BaseModel

Component-level absolute savings for energy/cost/GHG.

Parameters:
energy_kwh: ComponentTotals
cost_usd: ComponentTotals
ghg_kg_co2: ComponentTotals
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.ComponentTotals(*, heating_sensitive=0.0, baseload=0.0, cooling_sensitive=0.0)[source]

Bases: BaseModel

Heating/baseload/cooling component totals.

Parameters:
heating_sensitive: float
baseload: float
cooling_sensitive: float
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.FuelSavingsResult(*, energy_type, months, days_in_period, period_label, current, target, typical, energy_savings_kwh, energy_savings_percent, cost_savings_usd, cost_savings_percent, ghg_savings_kg_co2, ghg_savings_percent, eui_savings_kwh_per_m2, ghg_intensity_reduction_kg_co2_per_m2, component_savings, monthly_energy_kwh, monthly_cost_usd, monthly_ghg_kg_co2, valid=True, metadata=<factory>)[source]

Bases: BaseModel

Savings summary for a single energy type.

Parameters:
energy_type: str
months: list[str]
days_in_period: list[int]
period_label: str
current: UsageTotals
target: UsageTotals
typical: UsageTotals
energy_savings_kwh: float
energy_savings_percent: float
cost_savings_usd: float
cost_savings_percent: float
ghg_savings_kg_co2: float
ghg_savings_percent: float
eui_savings_kwh_per_m2: float | None
ghg_intensity_reduction_kg_co2_per_m2: float | None
component_savings: ComponentSavings
monthly_energy_kwh: list[float]
monthly_cost_usd: list[float]
monthly_ghg_kg_co2: list[float]
valid: bool
metadata: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.SavingsEstimate(*, energy_savings_kwh, cost_savings_usd, emissions_savings_kg_co2, percent_reduction)[source]

Bases: BaseModel

Backwards-compatible savings estimate container.

Parameters:

  • energy_savings_kwh (float)

  • cost_savings_usd (float)

  • emissions_savings_kg_co2 (float)

  • percent_reduction (float)

energy_savings_kwh: float
cost_savings_usd: float
emissions_savings_kg_co2: float
percent_reduction: float
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.SavingsSummary(*, per_fuel, combined, metadata=<factory>)[source]

Bases: BaseModel

Top-level savings report.

Parameters:
per_fuel: dict[str, FuelSavingsResult]
combined: CombinedSavingsSummary
metadata: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class better_lbnl_os.core.savings.UsageTotals(*, energy_kwh=0.0, cost_usd=0.0, ghg_kg_co2=0.0, eui_kwh_per_m2=None, ghg_intensity_kg_co2_per_m2=None, energy_components=<factory>, cost_components=<factory>, ghg_components=<factory>)[source]

Bases: BaseModel

Aggregated usage totals for a given coefficient set.

Parameters:
energy_kwh: float
cost_usd: float
ghg_kg_co2: float
eui_kwh_per_m2: float | None
ghg_intensity_kg_co2_per_m2: float | None
energy_components: ComponentTotals
cost_components: ComponentTotals
ghg_components: ComponentTotals
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].