breos.battery.simulate_energy_balance#

breos.battery.simulate_energy_balance(pv_dc, houseload, battery_config=None, start_time=None, end_time=None, freq='h', temperature_series=None, results_directory=None, initial_fec=0.0, initial_calendar_seconds=0.0, initial_resistance_growth=0.0, initial_cumulative_cycle_deg=0.0, initial_cumulative_cal_deg=0.0, debug=False)[source]#

Simulate energy balance with battery storage and degradation.

This function processes PV DC production and load profiles to calculate grid interaction, battery state, and degradation. It properly handles DC-coupled and AC-coupled battery systems.

Energy flow for DC-coupled (hybrid inverter) systems: - PV -> Load: DC -> Inverter -> AC (one inverter loss) - PV -> Battery: DC -> Battery (charge efficiency only) - Battery -> Load: DC -> Inverter -> AC (discharge efficiency + inverter loss) - Grid -> Load: AC (no conversion)

Parameters:

  • pv_dc (Series) – Series with PV DC power production (W) - before inverter

  • houseload (DataFrame) – DataFrame with electrical load (W) - AC

  • battery_config (Optional[BatteryConfig]) – Battery configuration parameters

  • start_time (Optional[Timestamp]) – Simulation start time (defaults to first index of pv_dc)

  • end_time (Optional[Timestamp]) – Simulation end time (defaults to last index of pv_dc)

  • freq (str) – Time frequency (‘h’ for hourly, ‘15min’ for 15-minute)

  • temperature_series (Optional[Series]) – Battery cell temperature (C), defaults to 25C

  • results_directory (Optional[str]) – Directory for saving results (optional)

  • debug (bool) – Enable debug output

  • initial_fec (float)

  • initial_calendar_seconds (float)

  • initial_resistance_growth (float)

  • initial_cumulative_cycle_deg (float)

  • initial_cumulative_cal_deg (float)

Returns:

  • results_df: Detailed timestep results

  • total_pv: Total PV AC production after inverter efficiency (Wh)

  • summary_df: Summary statistics

  • replacement_cost: Total battery replacement cost

  • n_replacements: Number of battery replacements

  • degradation_df: Daily degradation tracking

Return type:

Tuple[DataFrame, float, DataFrame, float, int, DataFrame]