pyCaRM-BHE 0.1.0__tar.gz

pycarm_bhe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessio Tollin, Angelo Zarrella
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycarm_bhe-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: pyCaRM-BHE
+Version: 0.1.0
+Summary: Python library for simulation of borehole heat exchanger systems
+Author: Alessio Tollin, Angelo Zarrella
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BETALAB-team/pyCaRM
+Project-URL: Documentation, https://betalab-team.github.io/pyCaRM/
+Project-URL: Repository, https://github.com/BETALAB-team/pyCaRM
+Project-URL: Bug Tracker, https://github.com/BETALAB-team/pyCaRM/issues
+Keywords: borehole heat exchanger,ground source heat pump,geothermal,BHE,GSHP,thermal simulation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: shapely
+Requires-Dist: networkx
+Provides-Extra: dev
+Requires-Dist: pygfunction; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: openpyxl; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinxawesome-theme; extra == "docs"
+Provides-Extra: coolprop
+Requires-Dist: CoolProp; extra == "coolprop"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/CaRM_logo.jpg" width="200"/>
+</p>
+
+# pyCaRM
+
+[![PyPI version](https://img.shields.io/pypi/v/pyCaRM-BHE.svg)](https://pypi.org/project/pyCaRM-BHE/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyCaRM-BHE.svg)](https://pypi.org/project/pyCaRM-BHE/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**pyCaRM** (CApacity Resistance Model) is a Python library for the simulation of 
+borehole heat exchanger (BHE) systems. It models the transient thermal response 
+of the ground and borehole, supporting single and multi-borehole configurations 
+with surface boundary conditions.
+
+> 📖 **Documentation:** https://betalab-team.github.io/pyCaRM/
+
+## Features
+
+- Single and multi-borehole field configurations
+- Supported BHE types: single U-tube, double U-tube, coaxial, helical
+- Ground stratification support
+- Surface boundary conditions (solar radiation, sky radiation, convection)
+- Voronoi-based field decomposition for multi-borehole layouts
+- Finite Line Source (FLS) thermal interference model
+- Parallel and series borehole connection modes
+- Heat flux mode: drive the simulation from a heat pump-side thermal load and
+  supply temperature, with heat pump COP/EER performance accounted for
+- Time-variable grout thermophysical properties driven by soil moisture
+  content (irrigation/precipitation input)
+
+## Installation
+
+Install from PyPI:
+```bash
+pip install pyCaRM-BHE
+```
+
+Alternatively, clone the repository and install from source:
+```bash
+git clone https://github.com/BETALAB-team/pyCaRM.git
+cd pyCaRM
+pip install .
+```
+
+**Developers:**
+```bash
+git clone https://github.com/BETALAB-team/pyCaRM.git
+cd pyCaRM
+pip install -e ".[dev]"
+```
+
+## Optional Dependencies
+
+- [CoolProp](http://www.coolprop.org) — for computing fluid thermophysical properties. Install with `pip install pyCaRM-BHE[coolprop]`. See [Fluid Properties](https://betalab-team.github.io/pyCaRM/fluid_properties.html) for usage.
+
+## Documentation
+
+Full documentation is available at **https://betalab-team.github.io/pyCaRM/**.
+
+## Examples
+
+Complete working scripts for all supported configurations are available in the
+`examples/` folder. See also the [documentation](https://betalab-team.github.io/pyCaRM/)
+for detailed usage guides.
+
+- `SingleUtube_multi_parallel.py` — multi-borehole field, parallel mode
+- `SingleUtube_multi_series.py` — multi-borehole field, series mode
+- `SingleUtube_multi_series_heat_flux.py` — multi-borehole field, series mode, heat flux (COP/EER) mode
+- `SingleUtube.py` — single borehole, single U-tube
+- `DoubleUtube.py` — single borehole, double U-tube
+- `Coaxial.py` — single borehole, coaxial
+- `Helical.py` — single borehole, helical
+- `Helical_variable_properties.py` — single borehole, helical, time-variable grout properties from soil moisture
+
+## Authors
+
+Developed at **BETALAB** – Department of Industrial Engineering, University of Padova.
+
+- Alessio Tollin
+- Angelo Zarrella
+
+## Citation
+
+If you use CaRM in your research, please cite:
+```
+[Citation will be added after publication]
+```
+
+This library is based on the following works:
+
+- De Carli, M., Tonon, M., Zarrella, A., Zecchin, R. (2010). *A computational 
+  capacity resistance model (CaRM) for vertical ground-coupled heat exchangers.* 
+  Renewable Energy, 35(7), 1537–1550. 
+  https://doi.org/10.1016/j.renene.2009.11.034
+
+- Zarrella, A., Scarpa, M., De Carli, M. (2011). *Short time step analysis of 
+  vertical ground-coupled heat exchangers: The approach of CaRM.* 
+  Renewable Energy, 36(9), 2357–2367. 
+  https://doi.org/10.1016/j.renene.2011.01.032
+
+- Zarrella, A., De Carli, M. (2013). *Heat transfer analysis of short helical 
+  borehole heat exchangers.* Applied Thermal Engineering, 61(1-2), 34–47. 
+  https://doi.org/10.1016/j.applthermaleng.2013.08.011
+
+- Zarrella, A., Capozza, A., De Carli, M. (2013). *Analysis of short helical 
+  and double U-tube borehole heat exchangers: A simulation-based comparison.* 
+  Applied Energy, 112, 358–370. 
+  https://doi.org/10.1016/j.apenergy.2012.09.012
+
+- Najib, A., Zarrella, A., Narayanan, V., Grant, P., Harrington, C. (2019). *A revised 
+  capacitance resistance model for large diameter shallow bore ground heat exchanger.* 
+  Applied Thermal Engineering, 162, 114305. 
+  https://doi.org/10.1016/j.applthermaleng.2019.114305
+
+- Claesson, J., Javed, S. (2011). *An analytical method to calculate borehole fluid 
+  temperatures for time-scales from minutes to decades.* 
+  ASHRAE Transactions, 117(2), 279–288.
+
+- Cimmino, M., Bernier, M. (2014). *A semi-analytical method to generate g-functions 
+  for geothermal bore fields.* International Journal of Heat and Mass Transfer, 70, 
+  641–650. https://doi.org/10.1016/j.ijheatmasstransfer.2013.11.037
+
+- Cimmino, M. (2018). *pygfunction: an open-source toolbox for the evaluation of 
+  thermal response factors for geothermal borehole fields.* 
+  Proceedings of eSim 2018, Montréal, Canada, 492–501.
+
+- Bell, I.H., Wronski, J., Quoilin, S., Lemort, V. (2014). *Pure and pseudo-pure fluid
+  thermophysical property evaluation and the open-source thermophysical property library
+  CoolProp.* Industrial & Engineering Chemistry Research, 53(6), 2498–2508.
+  https://doi.org/10.1021/ie4033999
+
+- Chung, S.O., Horton, R. (1987). *Soil heat and water flow with a partial surface 
+  mulch.* Water Resources Research, 23(12), 2175–2186.
+  https://doi.org/10.1029/WR023i012p02175
+
+- de Vries, D.A. (1963). *Thermal properties of soils.* In W.R. van Wijk (Ed.), 
+  Physics of Plant Environment. North-Holland Publishing Company, Amsterdam.
+
+- Ruhnau, O., Hirth, L., Praktiknjo, A. (2019). *Time series of heat demand and 
+  heat pump efficiency for energy system modeling.* Scientific Data, 6, 189. 
+  https://doi.org/10.1038/s41597-019-0199-y
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

pycarm_bhe-0.1.0/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="docs/CaRM_logo.jpg" width="200"/>
+</p>
+
+# pyCaRM
+
+[![PyPI version](https://img.shields.io/pypi/v/pyCaRM-BHE.svg)](https://pypi.org/project/pyCaRM-BHE/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyCaRM-BHE.svg)](https://pypi.org/project/pyCaRM-BHE/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**pyCaRM** (CApacity Resistance Model) is a Python library for the simulation of 
+borehole heat exchanger (BHE) systems. It models the transient thermal response 
+of the ground and borehole, supporting single and multi-borehole configurations 
+with surface boundary conditions.
+
+> 📖 **Documentation:** https://betalab-team.github.io/pyCaRM/
+
+## Features
+
+- Single and multi-borehole field configurations
+- Supported BHE types: single U-tube, double U-tube, coaxial, helical
+- Ground stratification support
+- Surface boundary conditions (solar radiation, sky radiation, convection)
+- Voronoi-based field decomposition for multi-borehole layouts
+- Finite Line Source (FLS) thermal interference model
+- Parallel and series borehole connection modes
+- Heat flux mode: drive the simulation from a heat pump-side thermal load and
+  supply temperature, with heat pump COP/EER performance accounted for
+- Time-variable grout thermophysical properties driven by soil moisture
+  content (irrigation/precipitation input)
+
+## Installation
+
+Install from PyPI:
+```bash
+pip install pyCaRM-BHE
+```
+
+Alternatively, clone the repository and install from source:
+```bash
+git clone https://github.com/BETALAB-team/pyCaRM.git
+cd pyCaRM
+pip install .
+```
+
+**Developers:**
+```bash
+git clone https://github.com/BETALAB-team/pyCaRM.git
+cd pyCaRM
+pip install -e ".[dev]"
+```
+
+## Optional Dependencies
+
+- [CoolProp](http://www.coolprop.org) — for computing fluid thermophysical properties. Install with `pip install pyCaRM-BHE[coolprop]`. See [Fluid Properties](https://betalab-team.github.io/pyCaRM/fluid_properties.html) for usage.
+
+## Documentation
+
+Full documentation is available at **https://betalab-team.github.io/pyCaRM/**.
+
+## Examples
+
+Complete working scripts for all supported configurations are available in the
+`examples/` folder. See also the [documentation](https://betalab-team.github.io/pyCaRM/)
+for detailed usage guides.
+
+- `SingleUtube_multi_parallel.py` — multi-borehole field, parallel mode
+- `SingleUtube_multi_series.py` — multi-borehole field, series mode
+- `SingleUtube_multi_series_heat_flux.py` — multi-borehole field, series mode, heat flux (COP/EER) mode
+- `SingleUtube.py` — single borehole, single U-tube
+- `DoubleUtube.py` — single borehole, double U-tube
+- `Coaxial.py` — single borehole, coaxial
+- `Helical.py` — single borehole, helical
+- `Helical_variable_properties.py` — single borehole, helical, time-variable grout properties from soil moisture
+
+## Authors
+
+Developed at **BETALAB** – Department of Industrial Engineering, University of Padova.
+
+- Alessio Tollin
+- Angelo Zarrella
+
+## Citation
+
+If you use CaRM in your research, please cite:
+```
+[Citation will be added after publication]
+```
+
+This library is based on the following works:
+
+- De Carli, M., Tonon, M., Zarrella, A., Zecchin, R. (2010). *A computational 
+  capacity resistance model (CaRM) for vertical ground-coupled heat exchangers.* 
+  Renewable Energy, 35(7), 1537–1550. 
+  https://doi.org/10.1016/j.renene.2009.11.034
+
+- Zarrella, A., Scarpa, M., De Carli, M. (2011). *Short time step analysis of 
+  vertical ground-coupled heat exchangers: The approach of CaRM.* 
+  Renewable Energy, 36(9), 2357–2367. 
+  https://doi.org/10.1016/j.renene.2011.01.032
+
+- Zarrella, A., De Carli, M. (2013). *Heat transfer analysis of short helical 
+  borehole heat exchangers.* Applied Thermal Engineering, 61(1-2), 34–47. 
+  https://doi.org/10.1016/j.applthermaleng.2013.08.011
+
+- Zarrella, A., Capozza, A., De Carli, M. (2013). *Analysis of short helical 
+  and double U-tube borehole heat exchangers: A simulation-based comparison.* 
+  Applied Energy, 112, 358–370. 
+  https://doi.org/10.1016/j.apenergy.2012.09.012
+
+- Najib, A., Zarrella, A., Narayanan, V., Grant, P., Harrington, C. (2019). *A revised 
+  capacitance resistance model for large diameter shallow bore ground heat exchanger.* 
+  Applied Thermal Engineering, 162, 114305. 
+  https://doi.org/10.1016/j.applthermaleng.2019.114305
+
+- Claesson, J., Javed, S. (2011). *An analytical method to calculate borehole fluid 
+  temperatures for time-scales from minutes to decades.* 
+  ASHRAE Transactions, 117(2), 279–288.
+
+- Cimmino, M., Bernier, M. (2014). *A semi-analytical method to generate g-functions 
+  for geothermal bore fields.* International Journal of Heat and Mass Transfer, 70, 
+  641–650. https://doi.org/10.1016/j.ijheatmasstransfer.2013.11.037
+
+- Cimmino, M. (2018). *pygfunction: an open-source toolbox for the evaluation of 
+  thermal response factors for geothermal borehole fields.* 
+  Proceedings of eSim 2018, Montréal, Canada, 492–501.
+
+- Bell, I.H., Wronski, J., Quoilin, S., Lemort, V. (2014). *Pure and pseudo-pure fluid
+  thermophysical property evaluation and the open-source thermophysical property library
+  CoolProp.* Industrial & Engineering Chemistry Research, 53(6), 2498–2508.
+  https://doi.org/10.1021/ie4033999
+
+- Chung, S.O., Horton, R. (1987). *Soil heat and water flow with a partial surface 
+  mulch.* Water Resources Research, 23(12), 2175–2186.
+  https://doi.org/10.1029/WR023i012p02175
+
+- de Vries, D.A. (1963). *Thermal properties of soils.* In W.R. van Wijk (Ed.), 
+  Physics of Plant Environment. North-Holland Publishing Company, Amsterdam.
+
+- Ruhnau, O., Hirth, L., Praktiknjo, A. (2019). *Time series of heat demand and 
+  heat pump efficiency for energy system modeling.* Scientific Data, 6, 189. 
+  https://doi.org/10.1038/s41597-019-0199-y
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

pycarm_bhe-0.1.0/carm/__init__.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+from .properties import (
+    BoreholeProperties,
+    BoreholeGeometry,
+    BoreholeMesh,
+    BoreholeThermalProperties,
+    SingleUtube,
+    DoubleUtube,
+    Coaxial,
+    Helical,
+)
+from .properties import GroundGeometry, GroundMesh, GroundProperties
+from .model import PhysicalModel
+from .simulation import Simulation, HeatFluxMode
+from .fluid import Fluid
+from .external_environment import EnvironmentalProperties, EnvironmentalTimeSeries
+from .field_layout import FieldInput, Field
+
+__all__ = [
+    "GroundGeometry",
+    "GroundMesh",
+    "GroundProperties",
+    "BoreholeProperties",
+    "BoreholeGeometry",
+    "BoreholeMesh",
+    "BoreholeThermalProperties",
+    "SingleUtube",
+    "DoubleUtube",
+    "Coaxial",
+    "Helical",
+    "PhysicalModel",
+    "Simulation",
+    "HeatFluxMode",
+    "Fluid",
+    "EnvironmentalProperties",
+    "EnvironmentalTimeSeries",
+    "FieldInput",
+    "Field",
+]

pycarm_bhe-0.1.0/carm/external_environment.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""
+Environmental conditions module.
+
+Defines the thermal and radiative properties of the external environment
+used as boundary conditions in the borehole heat exchanger simulation.
+"""
+
+from dataclasses import dataclass, field
+
+from typing import Self
+from numpy.typing import NDArray
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentalProperties:
+    """
+    Physical and thermal properties of the external environment.
+
+    Groups all site-specific parameters that characterize the surface
+    boundary condition: radiative exchange coefficients, surface optical
+    properties, and the seasonal air temperature signal.
+
+    Attributes
+    ----------
+    R_ext : float
+        External thermal resistance [W / (K m²)].
+    absorptance : float
+        Surface absorptance for solar radiation [-].
+    eps : float
+        Surface emittance for longwave radiation [-].
+    At : float
+        Annual amplitude of monthly average air temperature [K].
+    tau : float
+        Current simulation time [s].
+    tau_y : float
+        Duration of one year (315,536,000 s) [s].
+    tau_shift : float
+        Time offset to account for the date of minimum surface temperature [s].
+    """
+
+    R_ext: float  # W / (K * m2)
+    absorptance: float  # -, surface absorptance
+    eps: float  # -, surface emittance
+    At: float  # annual amplitude of monthly average air temperature
+    tau: float  # s, time
+    tau_y: float  # 315,536,000 s, time of 1 year
+    tau_shift: float  # s, time to account for the date of minimum surface temperature
+
+    def __post_init__(self):
+        if self.R_ext < 0:
+            raise ValueError("R_ext value must be >= 0")
+        if self.absorptance < 0:
+            raise ValueError("absorptance value must be >= 0")
+        if self.eps < 0:
+            raise ValueError("eps value must be >= 0")
+        if self.At < 0:
+            raise ValueError("At value must be >= 0")
+        if self.tau < 0:
+            raise ValueError("tau value must be >= 0")
+        if self.tau_y < 0:
+            raise ValueError("tau_y value must be > 0")
+        if self.tau_shift < 0:
+            raise ValueError("tau_shift value must be > 0")
+
+
+@dataclass
+class EnvironmentalTimeSeries:
+    """
+    Time series of external environmental inputs.
+
+    Stores the external air temperature and solar irradiance arrays
+    used to drive the surface boundary condition over the simulation period.
+    Instances should be created via the class methods to ensure input validation.
+
+    Attributes
+    ----------
+    Tm : float
+        Mean annual air temperature [°C].
+    T_ext : NDArray[np.float64]
+        External air temperature time series [°C].
+    SolarRad : NDArray[np.float64]
+        Solar irradiance time series [W/m²].
+    water_input : NDArray[np.float64] | None = None
+        Water input series by irrigation or
+        metherological phenomena [m3 / s].
+    """
+
+    Tm: float
+    T_ext: NDArray[np.float64]
+    SolarRad: NDArray[np.float64]
+    water_input: NDArray[np.float64] | None = None
+
+    @classmethod
+    def from_array(
+        cls,
+        Tm: float,
+        T_ext: NDArray[np.float64],
+        SolarRad: NDArray[np.float64],
+        water_input: NDArray[np.float64] | None = None,
+    ) -> Self:
+        """
+        Construct an instance from NumPy arrays.
+
+        All values must be finite (no NaN or Inf).
+
+        Parameters
+        ----------
+        Tm : float
+            Mean annual air temperature [°C].
+        T_ext : NDArray[np.float64]
+            External air temperature time series [°C].
+        SolarRad : NDArray[np.float64]
+            Solar irradiance time series [W/m²].
+        water_input : NDArray[np.float64] | None = None
+            Water input series by irrigation or
+            metherological phenomena [m3 / s].
+
+        Returns
+        -------
+        EnvironmentalTimeSeries
+            A validated instance populated from the arrays.
+
+        Raises
+        ------
+        ValueError
+            If ``T_ext``, ``SolarRad``, or ``water_input`` contain non-finite values.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> T = np.linspace(-5, 25, 8760)
+        >>> rad = np.abs(np.sin(np.linspace(0, 2 * np.pi, 8760))) * 600
+        >>> env = EnvironmentalTimeSeries.from_array(12.0, T, rad)
+        """
+        arrays = {"T_ext": T_ext, "SolarRad": SolarRad}
+        if water_input is not None:
+            arrays["water_input"] = water_input
+
+        invalid = [name for name, arr in arrays.items() if not np.all(np.isfinite(arr))]
+        if invalid:
+            raise ValueError(f"{', '.join(invalid)} may contain invalid values")
+
+        return cls(Tm, T_ext, SolarRad, water_input)
+
+
+@dataclass
+class ExternalEnvironment:
+    """
+    Assembled external environment for simulation boundary conditions.
+
+    Combines physical properties and time-series inputs, and derives
+    the sky radiation temperature from the external air temperature
+    at construction time.
+
+    Attributes
+    ----------
+    envprops : EnvironmentalProperties
+        Static physical and radiative properties of the site.
+    envinput : EnvironmentalTimeSeries
+        Time-varying environmental inputs (temperature and solar radiation).
+    T_sky : NDArray[np.float64]
+        Effective sky temperature time series, derived from ``T_ext`` [K].
+    boltzmann : float
+        Stefan-Boltzmann constant (5.670374419 × 10⁻⁸) [W / (m² K⁴)].
+
+    Examples
+    --------
+    >>> env = ExternalEnvironment(envprops=props, envinput=series)
+    >>> env.T_sky.shape
+    (8760,)
+    """
+
+    envprops: EnvironmentalProperties
+    envinput: EnvironmentalTimeSeries
+    T_sky: NDArray[np.float64] = field(init=False)
+
+    boltzmann: float = field(default=5.670374419e-8, init=False)
+
+    def __post_init__(self) -> None:
+        # T_sky calculation
+        self._sky_temperature_calc()
+
+    def _sky_temperature_calc(self) -> None:
+        self.T_sky = 0.0552 * (self.envinput.T_ext + 273.15) ** 1.5