moncenterlib.station_power_simulator.power_balance module

Energy balance simulator for autonomous stations.

The module evaluates whether a set of energy sources (solar panels, wind turbines, etc.) can support a constant load, optionally including battery storage simulation.

class moncenterlib.station_power_simulator.power_balance.PowerBalanceAnalyzer

Bases: object

Energy balance simulator for autonomous stations.

The class evaluates whether a set of energy sources (solar panels, wind turbines, etc.) can support a constant load, optionally including battery storage simulation.

calc_power_balance(input_df: DataFrame, load_power_w: float, path_protocol: str = '') → tuple[DataFrame, dict]

Evaluate whether generation covers a constant load.

The method compares hourly generated power with a constant load and calculates deficit, surplus and system coverage metrics.

Parameters:

  • input_df (pd.DataFrame) – DataFrame containing generation time series. Must contain a datetime index and a column with power values.

  • load_power_w (float) – Constant load power (W).

  • path_protocol (str, optional) – Path to a text file where the summary report will be saved.

Returns:

  • DataFrame: Hourly balance table containing generation, load, deficit, and surplus.

  • dict: Summary metrics describing system performance.

Return type:

tuple[pd.DataFrame, dict]

Example

>>> analyzer = PowerBalanceAnalyzer()
>>> df_station = analyzer.combine_power([solar, wind])
>>> df_balance, metrics = analyzer.calc_power_balance(
...     df_station,
...     load_power_w=1.5
... )
calc_power_balance_with_battery(input_df: DataFrame, load_power_w: float, battery_capacity_Wh: float, initial_soc_Wh: float | None = None, charge_efficiency: float = 1.0, discharge_efficiency: float = 1.0, min_soc_Wh: float = 0.0, path_protocol: str = '') → tuple[DataFrame, dict]

Simulate power balance of a station with a battery storage system.

The method performs an hourly simulation of station operation, considering generation, constant load and battery charge/discharge behavior.

Battery state-of-charge (SOC) is updated at each time step and system shutdown events are detected when generation and battery energy are insufficient to cover the load.

Parameters:

  • input_df (pd.DataFrame) – DataFrame containing station generation time series with a datetime index and a “power” column.

  • load_power_w (float) – Constant station load (W).

  • battery_capacity_Wh (float) – Total battery energy capacity (Wh).

  • initial_soc_Wh (float, optional) – Initial battery state of charge (Wh). If None, the battery starts fully charged.

  • charge_efficiency (float, optional) – Battery charging efficiency. Defaults to 1.0.

  • discharge_efficiency (float, optional) – Battery discharging efficiency. Defaults to 1.0.

  • min_soc_Wh (float, optional) – Minimum allowed battery state of charge. The battery cannot discharge below this level.

  • path_protocol (str, optional) – Path to a text file where the summary report will be saved.

Returns:

  • DataFrame: Hourly simulation results including generation, load, battery state-of-charge, and system status.

  • dict: Summary metrics including battery usage statistics and system shutdown events.

Return type:

tuple[pd.DataFrame, dict]

Example

>>> analyzer = PowerBalanceAnalyzer()
>>> df_station = analyzer.combine_power([solar, wind])
>>> df_sim, metrics = analyzer.calc_power_balance_with_battery(
...     input_df=df_station,
...     load_power_w=1.5,
...     battery_capacity_Wh=35
... )
static combine_power(sources: list[SolarPanelPower | WindTurbinePower]) → DataFrame

Combine power generation from multiple energy sources.

The method takes a list of power source objects (e.g. solar panels, wind turbines), extracts their hourly power time series, and returns the total generated power.

Each source must contain a DataFrame df with a column named “power” and a timezone-aware datetime index.

Parameters:

sources (list[SolarPanelPower | WindTurbinePower]) – List of energy source objects that already executed their calculate() method.

Returns:

DataFrame containing total station power generation with a datetime index.

Return type:

pd.DataFrame

Raises:

  • ValueError – If the source list is empty or if a source does not

  • contain valid power data. –

Example

>>> solar.calculate()
>>> wind.calculate()
>>> df_station = PowerBalanceAnalyzer.combine_power([solar, wind])