akkudoktoreos.devices.genetic.battery.Battery

class akkudoktoreos.devices.genetic.battery.Battery(parameters: BaseBatteryParameters, prediction_hours: int)

Bases: object

Represents a battery device with methods to simulate energy charging and discharging.

__init__(parameters: BaseBatteryParameters, prediction_hours: int)

Methods

__init__(parameters, prediction_hours)

charge_energy(wh, hour[, charge_factor])

Charge energy into the battery.

current_energy_content()

Returns the current usable energy in the battery.

current_soc_percentage()

Calculates the current state of charge in percentage.

discharge_energy(wh, hour)

Discharge energy from the battery.

reset()

Resets the battery state to its initial values.

set_charge_per_hour(charge_array)

Sets the charge values for each hour.

set_discharge_per_hour(discharge_array)

Sets the discharge values for each hour.

to_dict()

Converts the object to a dictionary representation.
__init__(parameters: BaseBatteryParameters, prediction_hours: int)
to_dict() → dict[str, Any]

Converts the object to a dictionary representation.

reset() → None

Resets the battery state to its initial values.

set_discharge_per_hour(discharge_array: ndarray) → None

Sets the discharge values for each hour.

set_charge_per_hour(charge_array: ndarray) → None

Sets the charge values for each hour.

current_soc_percentage() → float

Calculates the current state of charge in percentage.

discharge_energy(wh: float, hour: int) → tuple[float, float]

Discharge energy from the battery.

Discharge is limited by: * Requested delivered energy * Remaining energy above minimum SoC * Maximum discharge power * Discharge efficiency

Parameters:

  • wh (float) – Requested delivered energy in watt-hours.

  • hour (int) – Time index. If self.discharge_array[hour] == 0, no discharge occurs.

Returns:

delivered_wh (float): Actual delivered energy [Wh]. losses_wh (float): Conversion losses [Wh].

Return type:

tuple[float, float]

charge_energy(wh: float | None, hour: int, charge_factor: float = 0.0) → tuple[float, float]

Charge energy into the battery.

Two exclusive modes:

Mode 1:

  • wh is not None and charge_factor == 0

  • The raw requested charge energy is wh (pre-efficiency).

  • If remaining capacity is insufficient, charging is automatically limited.

  • No exception is raised due to capacity limits.

Mode 2:

  • wh is None and charge_factor > 0

  • The raw requested energy is max_charge_power_w * charge_factor.

  • If the request exceeds remaining capacity, the algorithm tries to find a lower charge_factor that is compatible. If such a charge factor exists, this hour’s charge_factor is replaced.

  • If no charge factor can accommodate charging, the request is ignored ((0.0, 0.0) is returned) and a penalty is applied elsewhere.

Charging is constrained by:

  • Available SoC headroom (max_soc_wh − soc_wh)

  • max_charge_power_w

  • charging_efficiency

Parameters:

  • wh (float | None) – Requested raw energy [Wh] before efficiency. Must be provided only for Mode 1 (charge_factor must be 0).

  • hour (int) – Time index. If charging is disabled at this hour (charge_array[hour] == 0), returns (0.0, 0.0).

  • charge_factor (float) – Fraction (0–1) of max charge power. Must be >0 only in Mode 2 (wh is None).

Returns:

stored_whfloat

Energy stored after efficiency [Wh].

losses_whfloat

Conversion losses [Wh].

Return type:

tuple[float, float]

Raises:

ValueError –

  • If the mode is ambiguous (neither Mode 1 nor Mode 2). - If the final new SoC would exceed capacity_wh.

Notes

stored_wh = raw_input_wh * charging_efficiency losses_wh = raw_input_wh − stored_wh

current_energy_content() → float

Returns the current usable energy in the battery.