Battery model with thermal modeling and degradation

[jaredthomas68]

SimSES Battery Performance Model with Degradation

This PR adds SimSESBatteryPerformanceModel, an H2Integrate storage model built around SimSES’s stateful battery and converter. H2I adds calendar and cyclic degradation, container thermal dynamics, HVAC control, solar heat gain, battery-temperature interlocks, and a stateful simulation callback for Pyomo dispatch windows.

Example 38 demonstrates the model with a two-year, 15-minute simulation and a 24-hour optimized-controller horizon. The controller applies Exclusive Control Months during December through March and bill minimization in other months. An electricity feedstock provides charging availability. The default horizon is two years because longer examples run too slowly for routine use.

The package minimum is raised to Python 3.12 to satisfy SimSES 2.1.1.

Type of Contribution

• Feature Enhancement
  • Framework
  • New Model
  • Updated Model
• Bug Fix
• Documentation Update
• CI Changes
• Other

Draft PR Checklist

• Open draft PR
• Describe the feature that will be added
• Fill out TODO list steps
• Describe requested feedback from reviewers on draft PR
• Complete Section 8: New Model Checklist

TODO

• Add a changelog entry and PR link once the PR number is available.
• Run validation on Python 3.12 when that interpreter is available.
• Decide whether EOL replacement should physically reset the simulated battery state or remain a finance projection.

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback: Review the separation between the SimSES model, H2I thermal/HVAC additions, and storage-controller callback.

Implementation feedback: Review the degradation scaling, thermal assumptions, Exclusive Control Month setup, and projected versus physical EOL replacement behavior.

Other feedback: Confirm the Example 38 feedstock-only setup and its synthetic LMP and demand profiles are appropriate.

General PR Checklist

• PR description thoroughly describes the feature.
• New model checklist has been completed.
• Tests
  • All tests pass locally
  • Added tests for new functionality
  • Modified tests have been outlined in Impacted Areas.
• Documentation
  • Docstrings are up-to-date
  • Related documentation has been added and linked in the TOC
  • Documentation has been rebuilt successfully
  • Examples have been updated
  • No changes required
• CHANGELOG.md
  • Add a complete sentence describing the changes and link it to this PR after its number is assigned.

Related Issues

N/A

Impacted Areas of the Software

New Files

• h2integrate/storage/battery/battery_with_degradation/simses_battery.py
  • Implements SimSESBatteryPerformanceModel and its configuration.
• h2integrate/storage/battery/battery_with_degradation/container.py
  • Implements the container thermal, HVAC, and thermostat models.
• h2integrate/storage/battery/battery_with_degradation/test/test_simses_battery.py
  • Tests component behavior, notebook-aligned outputs, and H2I integration.
• examples/38_battery_degradation/
  • Adds the two-year optimized-control example and its runner.
• resource_files/solar/
  • Adds solar/weather resources used by Example 38 and the integration tests.

Modified Files

• h2integrate/storage/battery/__init__.py and h2integrate/storage/battery/battery_with_degradation/__init__.py
  • Export and register the SimSES-specific model name.
• h2integrate/control/control_strategies/storage/plm_optimized_storage_controller.py
  • Supports the timestep range and multiyear horizons required by the example.
• h2integrate/feedstocks/feedstocks.py and storage base classes
  • Support feedstock availability and stateful storage dispatch windows.
• examples/33_peak_load_management_heuristics/plm_storage/
  • Aligns shared storage/controller configuration.
• examples/test/test_all_examples.py
  • Adds the Example 38 seasonal-controller integration test.
• docs/_toc.yml and storage documentation index
  • Link the new SimSES battery documentation page.
• pyproject.toml, .github/workflows/, .readthedocs.yaml, and environment.yml
  • Raise the supported Python floor to 3.12 and align CI/documentation environments.

Additional Supporting Information

• The default Example 38 horizon is 70,080 steps (dt = 900 seconds).
• The electricity feedstock supplies charge availability; it does not represent a priced grid purchase or export.
• eol_soh_capacity currently drives projected replacement scheduling and finance calculations; it does not physically reset the SimSES state during the run.

Test Issues

• Renamed battery test module: 9 passed, 31 subtests.
• Example 38 and Example 34 controller integrations: 2 passed, 11 subtests.
• Optimized-controller tests: 32 passed, 437 subtests.
• These tests ran under Python 3.13. Python 3.12 was unavailable locally.
• The docs-consistency check sees an unrelated untracked examples/09_wind_farm_layout_hybrid directory in this workspace.
• The branch diff check reported trailing whitespace in the new container model.

New Model Checklist

• Model Structure
  • Follows established naming conventions.
  • Configuration class is SimSESBatteryPerformanceModelConfig and uses attrs.
  • Implements initialize(), setup(), and compute() using the storage performance base.
• Integration
  • Exports and registers the model for H2I configuration lookup.
• Tests
  • Adds pytest unit/regression coverage and an H2I integration test.
• Example
  • Adds Example 38 and tests it through test_all_examples.py.
• Documentation
  • Adds docstrings and a storage model page.
  • Adds the page to docs/_toc.yml.

Release checklist

N/A — not a release PR.

[coveralls]

Coverage is 62.925% — batt-deg-merged into nonannual. No base build found for nonannual.

[abhineet-gupta]

FYI, the github link to SimSES does not work.

[jaredthomas68]

Good catch, thank you! I just updated it.