========
carbatpy
========

.. image:: https://img.shields.io/pypi/v/carbatpy.svg
   :target: https://pypi.python.org/pypi/carbatpy

.. image:: https://readthedocs.org/projects/carbatpy-010/badge/?version=latest
   :target: https://carbatpy-010.readthedocs.io/en/latest/
   :alt: Documentation Status

carbatpy is a Python package for modelling Carnot batteries (thermal energy storage)
based on heat pumps for charging, organic Rankine cycles (ORC) for discharging,
and different storage concepts.

Currently, the main focus is on **steady-state** thermodynamic cycle simulation and
evaluation (efficiency, costs, and optimisation). Time-dependent models are planned.

Documentation
-------------
* https://carbatpy-010.readthedocs.io/en/latest/

Requirements (mandatory)
------------------------
REFPROP is required for meaningful use of the package.

* **REFPROP (NIST)**: a valid license is required.
* Python: >= 3.10

In addition, typical scientific Python packages are used (NumPy, SciPy, pandas, ...);
see ``pyproject.toml`` for the full list.

Optional components
-------------------
carbatpy can optionally interface with additional tools. These are *not* required
to install or import carbatpy. When available, they can be selected explicitly
in various functions (they are **not enabled automatically**).

TREND
^^^^^
If **TREND** is installed and you want to use it for thermodynamic properties,
enable it in ``carbatpy.cb_config.py`` by setting the dictionary ``_TREND``
accordingly (example):

* ``{"USE_TREND": True, "TREND_DLL": "...", "TREND_PATH": "..."}``

In addition, the relevant TREND paths typically need to be available as system
environment variables (see documentation for details). TREND was developed and is 
authored by Prof. Roland Span and his co-workers (Chair of Thermodynamics, Ruhr University Bochum).

Note: currently, TREND support is limited to **thermodynamic properties** (no
transport properties).

Machine models (SPP 2403)
^^^^^^^^^^^^^^^^^^^^^^^^^
Detailed machine models are available as an **external add-on** package
(e.g. ``spp_machines``). This add-on is developed and maintained separately and
may have its own license conditions. It was originally developed in the context
of SPP 2403 and may be available on request, it is authored by Steffen 
Folkers and Prof. Dieter Brillert (Chair of Turbomachinery, University of Duisburg-Essen).

If the add-on package is installed, it can be selected explicitly for the
corresponding components; otherwise, carbatpy falls back to simplified models or
disables the relevant functionality (with a clear error message).

Package structure
-----------------
The main functionality is implemented in the subpackages under ``carbatpy.models``:

* ``cb_fluids``:
  Fluid mixture properties (REFPROP; optional: TREND for thermodynamic data)
* ``components``:
  Models of individual devices such as compressors, turbines, heat exchangers,
  throttles, etc.
* ``coupled``:
  Coupled component models forming thermodynamic cycles and Carnot batteries

Features
--------
* Steady-state calculation of heat pumps, ORCs, and Carnot batteries
* Optimisation of pressure levels and working fluid mixture composition for improved second-law efficiency
* Cost estimation based on correlations from the literature
* Reading cycle configurations and parameters from YAML input files
* Quasi steady-state evaluation of efficiencies and costs

Roadmap / TODO
--------------
* Time-dependent (dynamic) cycle simulation
* Further validation and extended component models

Credits
-------
* This package was created with Cookiecutter_ and the
  `audreyr/cookiecutter-pypackage`_ project template.

Contact
-------
Burak Atakan, University of Duisburg-Essen, Germany

* atakan.thermodynamik.duisburg [at] gmail.com

License
-------
* MIT License

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage