breos 0.3.0__py3-none-any.whl

breos/__init__.py

@@ -0,0 +1,348 @@
+"""
+BREOS - Building Renewable Energy Optimization Software
+
+Python library for PV and battery energy-system simulation and optimization.
+Supports both hourly ('h') and 15-minute ('15min') time resolutions.
+
+Modules:
+--------
+- weather: Weather data fetching and interpolation
+- solar: PV production calculations
+- load_profiles: Load profile management
+- battery: Energy balance and degradation simulation
+- economics: Cost analysis and projections
+- optimization: System sizing and tilt optimization
+- plotting: Visualization utilities
+- emissions: CO2 savings calculations
+
+Usage:
+------
+>>> import breos
+>>> app = breos.App({"location": "porto", "n_modules": 10, "annual_consumption_kwh": 4000})
+>>> app.simulate()
+>>> result = app.result()
+"""
+
+# Version — resolved from the installed package metadata so it always matches
+# the version declared in pyproject.toml (the single source of truth). This is
+# the same mechanism used by breos/cli.py and docs/conf.py, which keeps the
+# literal from drifting out of sync with the distribution version on a release.
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("breos")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+# Public facade
+from breos.app import App
+
+# Battery
+from breos.battery import (
+    BatteryConfig,
+    apply_indoor_temperature_model,
+    compute_cell_temperature,
+    compute_halfcycle_energy_throughput,
+    detect_cycles_rainflow,
+    detect_half_cycles_from_soc_series,
+    k_c_rate_Q,
+    k_c_rate_R,
+    k_doc_Q,
+    k_doc_R,
+    resistance_to_efficiency,
+    simulate_energy_balance,
+    update_battery_resistance_calendar,
+    update_battery_resistance_cyclewise,
+    update_battery_soc,
+    update_battery_soh_calendar,
+    update_battery_soh_cyclewise,
+)
+
+# Constants
+from breos.constants import (
+    A_Q,
+    A_R,
+    B_Q,
+    B_R,
+    C_DOC_Q,
+    C_DOC_R,
+    D_DOC_Q,
+    D_DOC_R,
+    DEFAULT_CHARGE_EFFICIENCY,
+    DEFAULT_DISCHARGE_EFFICIENCY,
+    DEFAULT_INDOOR_CEILING_C,
+    DEFAULT_INDOOR_COUPLING_ALPHA,
+    DEFAULT_INDOOR_FLOOR_C,
+    DEFAULT_INDOOR_SETPOINT_C,
+    DEFAULT_MAX_SOC,
+    DEFAULT_MIN_SOC,
+    LAM_EA_J_MOL,
+    LAM_EXPONENT_B,
+    LAM_K0_FRAC,
+    LAM_SOC_EXPONENT_N,
+    NAUMANN_EA_J_MOL,
+    NAUMANN_EA_R_J_MOL,
+    NAUMANN_EXPONENT_B,
+    NAUMANN_K0_PERCENT,
+    NAUMANN_K0_R_PERCENT,
+    NAUMANN_SOC_EXPONENT_N,
+    R_GAS,
+    T_REF_K,
+    Z_Q,
+    Z_R,
+)
+
+# Economics
+from breos.economics import (
+    CostParams,
+    calculate_costs,
+    calculate_lcoe,
+    calculate_lcoe_from_projection,
+    cost_analysis_projection,
+    cost_params_from_config,
+    find_payback_year,
+)
+
+# Emissions
+from breos.emissions import (
+    EmissionsParams,
+    calculate_co2_projection,
+    calculate_co2_savings,
+)
+
+# Inverter
+from breos.inverter import (
+    INVERTER_PRESETS,
+    InverterConfig,
+    InverterConversionResult,
+    calculate_dc_ac_power,
+    get_inverter_preset,
+)
+
+# I/O (export/import functions)
+from breos.io import (
+    export_cost_analysis,
+    export_monthly_summary,
+    export_results,
+    export_summary,
+    export_yearly_summary,
+    load_results,
+    save_simulation_report,
+)
+
+# Load Profiles
+from breos.load_profiles import (
+    align_load_to_pv,
+    load_profile,
+    scale_to_annual_consumption,
+)
+
+# Monte Carlo (weather + demand uncertainty)
+from breos.montecarlo import (
+    MonteCarloResult,
+    MonteCarloSettings,
+    run_montecarlo,
+)
+
+# Optimization
+from breos.optimization import (
+    OptimizationResult,
+    optimize_battery_size,
+    optimize_system_multi_objective,
+    optimize_tilt,
+    optimize_tilt_brent,
+    size_for_zeb,
+)
+
+# Polysun Degradation (comparison baseline)
+from breos.polysun_degradation import (
+    PolysunDegradationConfig,
+    compute_dod_histogram,
+    compute_miner_damage,
+    predict_polysun_lifetime,
+    simulate_polysun_degradation,
+    woehler_cycles_to_failure,
+)
+
+# PV Module Database
+from breos.pv_modules import (
+    MODULES,
+    get_module,
+    get_module_info,
+    list_modules,
+)
+
+# Solar
+from breos.solar import (
+    PVModuleParams,
+    calculate_multi_array_production,
+    calculate_pv_production_ac,
+    calculate_pv_production_dc,
+    calculate_pv_production_dc_tracking,
+    calculate_pv_production_tmy,
+    dc_to_ac,
+    default_azimuth,
+    estimate_optimal_tilt,
+    zeb_sizer,
+)
+
+# Utils
+from breos.utils import (
+    count_leap_years,
+    get_hours_per_step,
+    get_steps_per_day,
+    get_steps_per_year,
+    is_leap_year,
+    number_of_cores,
+    remap_datetime_index_years,
+)
+
+# Weather
+from breos.weather import (
+    build_battery_temperature_series,
+    csv_15min_to_hourly,
+    csv_hourly_to_15min,
+    extract_ambient_temperature,
+    fetch_tmy_nsrdb,
+    fetch_tmy_weather_data,
+    fetch_weather_data,
+    load_weather,
+    parse_weather_filename,
+    preload_weather_by_year,
+    read_epw_file,
+    resample_tmy_to_15min,
+    resample_to_15min,
+    resample_to_hourly,
+    select_random_year_and_replace_datetime,
+)
+
+# Plotting (try to import, skip if matplotlib not installed)
+try:
+    from breos.plotting import (
+        create_cost_plots,
+        degradation_plots,
+        monthly_graphs,
+        plot_azitilt_ew_1d,
+        plot_azitilt_landscape_2d,
+        plot_azitilt_landscape_3d,
+        plot_battery_soh_timeseries,
+        plot_breakeven,
+        plot_breakeven_comparison,
+        plot_breakeven_two,
+        # Sensitivity analysis
+        plot_calendar_aging_sensitivity,
+        plot_cell_temperature,
+        # CO2 savings
+        plot_co2_savings,
+        # Polysun vs BREOS comparison
+        plot_degradation_methodology_comparison,
+        # Batch comparison
+        plot_grid_independence_heatmap,
+        plot_lifetime_prediction_comparison,
+        plot_location_comparison_delta,
+        plot_loo_cv_summary,
+        plot_loo_param_stability,
+        plot_loo_predictions,
+        # Monte Carlo distributions
+        plot_montecarlo_final_soh_distribution,
+        plot_montecarlo_grid_independence_distribution,
+        plot_montecarlo_npv_distribution,
+        plot_montecarlo_simulation,
+        plot_monthly_balance,
+        plot_monthly_comparison,
+        plot_pareto_front_analysis,
+        plot_resistance_and_efficiency,
+        plot_temperature_sensitivity_comparison,
+        plot_tilt_optimization,
+        plot_timeseries,
+        plot_validation_degradation_split,
+        plot_validation_multi_system,
+        plot_validation_parity,
+        plot_validation_residuals,
+        plot_validation_soh_comparison,
+        plot_weather_annual_ghi_distribution,
+        plot_weather_monthly_comparison,
+        set_presentation_mode,
+        weekly_graphs,
+        yearly_graphs,
+    )
+except ImportError:
+    pass  # matplotlib not installed
+
+
+# Numba kernels (lazy import to avoid slow import at package load)
+def _get_numba():
+    """Lazy import of Numba-accelerated kernels."""
+    from breos import numba_kernels
+
+    return numba_kernels
+
+
+__all__ = [
+    # Public facade
+    "App",
+    # Version
+    "__version__",
+    # Configuration and result objects
+    "BatteryConfig",
+    "CostParams",
+    "EmissionsParams",
+    "InverterConfig",
+    "InverterConversionResult",
+    "OptimizationResult",
+    "PVModuleParams",
+    # Weather
+    "load_weather",
+    "fetch_tmy_weather_data",
+    "fetch_tmy_nsrdb",
+    "fetch_weather_data",
+    "read_epw_file",
+    # Solar
+    "calculate_pv_production_dc",
+    "calculate_pv_production_dc_tracking",
+    "calculate_multi_array_production",
+    "calculate_pv_production_ac",
+    "dc_to_ac",
+    "estimate_optimal_tilt",
+    "default_azimuth",
+    # PV module catalogue
+    "get_module",
+    "get_module_info",
+    "list_modules",
+    # Load Profiles
+    "load_profile",
+    "scale_to_annual_consumption",
+    "align_load_to_pv",
+    # Inverter
+    "get_inverter_preset",
+    "calculate_dc_ac_power",
+    # Battery
+    "simulate_energy_balance",
+    "apply_indoor_temperature_model",
+    # Emissions
+    "calculate_co2_savings",
+    "calculate_co2_projection",
+    # Economics
+    "calculate_costs",
+    "cost_analysis_projection",
+    "cost_params_from_config",
+    "find_payback_year",
+    "calculate_lcoe",
+    "calculate_lcoe_from_projection",
+    # Optimization
+    "optimize_tilt",
+    "optimize_tilt_brent",
+    "optimize_battery_size",
+    "optimize_system_multi_objective",
+    # Monte Carlo
+    "run_montecarlo",
+    "MonteCarloSettings",
+    "MonteCarloResult",
+    # I/O
+    "export_results",
+    "export_summary",
+    "load_results",
+    "export_monthly_summary",
+    "export_yearly_summary",
+]

breos/app.py

@@ -0,0 +1,79 @@
+"""
+BREOS public facade - single entry point for PV + battery simulations.
+
+Usage:
+    import breos
+
+    app = breos.App({
+        "location": "porto",
+        "n_modules": 10,
+        "annual_consumption_kwh": 4000,
+        "battery_kwh": 5.0,
+        "cost_preset": "residential_pt",
+        "emissions_country": "PT",
+    })
+    app.simulate()
+    result = app.result()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from breos.app_config import resolve_app_config
+from breos.app_inputs import AppRuntimeDependencies
+from breos.app_results import build_result as build_app_result
+from breos.load_profiles import load_profile
+from breos.runners.app import run_app_simulation
+from breos.weather import build_battery_temperature_series, fetch_tmy_weather_data, load_weather, resample_to_15min
+
+
+class App:
+    """
+    Single entry point for BREOS simulations.
+
+    Parameters
+    ----------
+    config : dict
+        Simulation configuration. Required keys:
+
+        - ``location`` - preset key (``"porto"``) **or** dict with
+          ``latitude``, ``longitude``, ``timezone``.
+        - ``n_modules`` - number of PV modules (int, > 0), unless
+          ``pv_arrays`` is provided.
+        - ``annual_consumption_kwh`` - yearly electricity demand (float, > 0).
+
+        Optional keys include battery size, PV arrays, module selection, load
+        profile, tracking, resolution, projection years, cost and emissions
+        presets, degradation, and inverter assumptions.
+    """
+
+    def __init__(self, config: dict) -> None:
+        self._resolved = resolve_app_config(config)
+        self._cfg = self._resolved.cfg
+        self._result: dict[str, Any] | None = None
+
+    def simulate(self) -> None:
+        """Run the full simulation pipeline."""
+        artifacts = run_app_simulation(self._cfg, self._resolved, self._runtime_dependencies())
+        self._result = build_app_result(self._cfg, self._resolved, artifacts)
+
+    def result(self) -> dict[str, Any]:
+        """
+        Return simulation results as a plain dict.
+
+        Raises ``RuntimeError`` if :meth:`simulate` has not been called.
+        """
+        if self._result is None:
+            raise RuntimeError("Call simulate() before result().")
+        return self._result
+
+    @staticmethod
+    def _runtime_dependencies() -> AppRuntimeDependencies:
+        return AppRuntimeDependencies(
+            load_profile=load_profile,
+            load_weather=load_weather,
+            fetch_tmy_weather_data=fetch_tmy_weather_data,
+            resample_to_15min=resample_to_15min,
+            build_battery_temperature_series=build_battery_temperature_series,
+        )