PyTES

PyTES (Python Thermal Energy Storage) is a library of models and tools for thermal energy storage (also known as heat batteries), built on PyBaMM. What PyBaMM is to electrochemical batteries, PyTES aims to be to thermal energy storage: a set of validated models that share one interface, so that designs compare like for like.

PyTES covers storage in which a heat transfer fluid flows through or around a separate storage medium, such as a phase-change material (PCM) or a sensible solid. Every model is an ordinary PyBaMM model, so PyBaMM's simulations, solvers and plots work on it directly.

Alpha. The model contract may still change; every change is logged in docs/design/findings.md.

📦 Installation

pip install --pre pytes-thermal            # models and toolkit
pip install --pre "pytes-thermal[plot]"    # plus the standard plots (matplotlib)

The package is pytes-thermal on PyPI and is imported as pytes. --pre is needed while PyTES only has alpha releases.

PyTES supports every Python version PyBaMM supports (3.10 to 3.15).

🚀 Quick start

import pybamm
import pytes

model = pytes.PackedBedModel()  # or pytes.SharpFrontModel(), pytes.MushModel()
solution = pybamm.Simulation(model).solve([0, 3600])
print(solution["Outlet temperature [degC]"].entries[-1])

The documentation, with a getting-started guide, the API reference and the example notebooks, is at pytes.readthedocs.io.

🔥 Models

Every model takes options={"storage along flow path": "averaged"} for a faster variant with one storage cross-section standing for the average along the flow, and the packed bed takes options={"storage element": "lumped"} for capsules at a uniform temperature. All models share their outputs (power, energies, inlet and outlet temperatures, all in SI units with °C, kW and kWh twins), their experiments, and an exact energy balance, checked by a common conformance suite.

🧰 Toolkit

• Experiments (pytes.experiments): constant inputs or constant power, with terminations and cycles.
• Post-processing (pytes.energy_between) and standard plots (pytes.plotting).
• Materials and fluids, analytical benchmarks (pytes.validation) and the conformance checks (pytes.conformance), importable for your own PyBaMM models.
• Composition (pytes.ComposedModel): build a model from PyTES submodels, e.g. to try a new heat transfer law.

📓 Examples

Notebooks in examples/: the finned-tube and packed-bed models, the lumped capsule, experiments, composing models, analytical validation, and a design study comparing the two families. They are also rendered in the documentation.

📐 Design

The design decisions, the model contract and the log of changes are in docs/design/.

📖 Citing PyTES

If you use PyTES in your work, please cite it: the metadata are in CITATION.cff, and GitHub's "Cite this repository" button gives the reference in BibTeX or APA. Each release is archived on Zenodo with its own DOI; 10.5281/zenodo.23438443 cites all versions and resolves to the latest.

🤝 Contributing

Contributions are welcome: see CONTRIBUTING.md for the workflow, the conventions and how to add a model.

⚖️ Licence

BSD 3-Clause, see LICENSE.