Feature/battery internal

[paulf81]

This PR changes the battery simple model from a convention where the input value energy_capacity defines the energy capacity of the output (that is after efficiency losses) rather than internally. The reason is that I believe it's more conventional that if a battery is specified as 1 MW / 4 hour, it's assumed the internal size will be sized to ensure the battery can deliver 1 MW for 4 hours.

A follow-on change are the that min_SOC and max_SOC are meant to be deviations from nameplate performance, such that if they are not their default values of 0 and 1, then the battery won't be able to deliver the same 1 MW for 4 hours. These can be used therefore to model impacts of degredation but should not be used to represent a new properly functioning battery. In other words, if the battery has a physical ability to further charge or discharge that can never be accessed, even when the battery is new, we don't count this as min/max SOC.

A new internal variable internal_energy_capacity is defined accounting for this efficiency loss. A new test is added to make sure the convention of specifying the output power is respected. A regression test is updated to this new convention but all remaining tests continue to pass (no impact if RTE=1.0)

I guess one outstanding question is should I have also included min_SOC / max_SOC in defining internal_energy_capacity.

[Copilot]

Pull request overview

This PR updates BatterySimple so configured energy_capacity represents deliverable output energy by sizing an internal capacity that accounts for discharge efficiency.

Changes:

• Adds internal_energy_capacity and uses it for energy limits, initialization, and SOC updates.
• Updates battery usage regression expectations for the new convention.
• Adds a discharge-duration test for non-unity roundtrip efficiency.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
hercules/plant_components/battery_simple.py	Implements internal capacity scaling for BatterySimple.
tests/battery_simple_test.py	Adds a duration invariant test for RTE < 1.
tests/regression_tests/battery_regression_test.py	Updates regression baselines affected by the capacity convention.

Comments suppressed due to low confidence (2)

hercules/plant_components/battery_simple.py:152

• The new deliverable-capacity invariant only holds when min_SOC is 0 and max_SOC is 1. Because E_min/E_max are still set to fractions of this internal capacity, a configuration using the existing 0.1/0.9 SOC window can deliver only (max_SOC - min_SOC) * energy_capacity before hitting the limits, not energy_capacity. If energy_capacity is meant to represent usable deliverable energy, this needs to account for the SOC window; otherwise the API/comment should explicitly say reserves reduce the deliverable duration.

        self.internal_energy_capacity = self.energy_capacity / self.eta_discharge

        # Charge (Energy) limits [kJ]
        self.E_min = kWh2kJ(self.SOC_min * self.internal_energy_capacity)
        self.E_max = kWh2kJ(self.SOC_max * self.internal_energy_capacity)

hercules/plant_components/battery_simple.py:148

• This divides by eta_discharge without validating it is positive. A configured roundtrip_efficiency of 0 (or an invalid negative value that produces NaN) now makes internal_energy_capacity, energy limits, and initial state invalid during initialization, so the model can silently run with infinities/NaNs. Add validation for 0 < roundtrip_efficiency <= 1 before deriving the internal capacity.

        self.internal_energy_capacity = self.energy_capacity / self.eta_discharge

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[paulf81]

Believe this is clarified by changes pushed since this comment made

[paulf81]

This should now be addressed