bhtypes 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
bhtypes/__init__.py ADDED
@@ -0,0 +1,38 @@
1
+ """bhtypes: plain data types for a borehole heat exchanger's cross-section.
2
+
3
+ ``Soil``, ``Grout`` and the pipe geometries ``SingleUTube``, ``DoubleUTube`` and ``Coaxial``,
4
+ as frozen dataclasses with units in their field names. No dependencies.
5
+
6
+ Conversions to and from the conventions of pygfunction, bhresist and GHEDesigner live in
7
+ :mod:`bhtypes.convert`, one module per package, kept apart from the types so other packages
8
+ can supply their own.
9
+
10
+ Deliberately out of scope: fluids -- use SecondaryCoolantProps (``scp``), which
11
+ pygfunction, bhresist and GHEDesigner already share -- and borehole geometry -- use
12
+ ``pygfunction.boreholes.Borehole``.
13
+ """
14
+
15
+ from bhtypes.materials import Grout, Soil
16
+ from bhtypes.pipes import (
17
+ COAXIAL_INLETS,
18
+ DEFAULT_ROUGHNESS_M,
19
+ DOUBLE_U_FLOWS,
20
+ DOUBLE_U_INLETS,
21
+ Coaxial,
22
+ DoubleUTube,
23
+ Pipe,
24
+ SingleUTube,
25
+ )
26
+
27
+ __all__ = [
28
+ "COAXIAL_INLETS",
29
+ "DEFAULT_ROUGHNESS_M",
30
+ "DOUBLE_U_FLOWS",
31
+ "DOUBLE_U_INLETS",
32
+ "Coaxial",
33
+ "DoubleUTube",
34
+ "Grout",
35
+ "Pipe",
36
+ "SingleUTube",
37
+ "Soil",
38
+ ]
bhtypes/_checks.py ADDED
@@ -0,0 +1,27 @@
1
+ """Input checks shared by the dataclasses."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from math import isfinite
6
+
7
+
8
+ def positive(name: str, value: float) -> None:
9
+ if not (isinstance(value, int | float) and not isinstance(value, bool) and isfinite(value) and value > 0):
10
+ raise ValueError(f"{name} must be a finite positive number, got {value!r}")
11
+
12
+
13
+ def non_negative(name: str, value: float) -> None:
14
+ if not (isinstance(value, int | float) and not isinstance(value, bool) and isfinite(value) and value >= 0):
15
+ raise ValueError(f"{name} must be a finite non-negative number, got {value!r}")
16
+
17
+
18
+ def wall(inner_name: str, inner: float, outer_name: str, outer: float) -> None:
19
+ positive(inner_name, inner)
20
+ positive(outer_name, outer)
21
+ if not inner < outer:
22
+ raise ValueError(f"{inner_name} ({inner}) must be smaller than {outer_name} ({outer})")
23
+
24
+
25
+ def choice(name: str, value: str, options: tuple[str, ...]) -> None:
26
+ if value not in options:
27
+ raise ValueError(f"{name} must be one of {options}, got {value!r}")
@@ -0,0 +1,38 @@
1
+ """Conversions between bhtypes and other packages' conventions, one module per package.
2
+
3
+ ================================= ==========================================================
4
+ :mod:`bhtypes.convert.pygfunction` ``to_pygfunction``: keyword arguments for pygfunction's
5
+ pipe models; ``pipe_type``: its ``pipe_type_str``
6
+ :mod:`bhtypes.convert.bhresist` ``to_bhresist``: keyword arguments for bhresist's
7
+ ``Borehole.init_*_borehole``; ``init_method``: which one
8
+ :mod:`bhtypes.convert.ghedesigner` ``to_ghedesigner`` / ``*_from_ghedesigner``: GHEDesigner
9
+ input-file blocks
10
+ ================================= ==========================================================
11
+
12
+ Import the functions rather than the modules, so the module names do not shadow the
13
+ packages themselves::
14
+
15
+ from bhtypes.convert.pygfunction import to_pygfunction
16
+
17
+ Extending and replacing conversions
18
+ -----------------------------------
19
+ Every ``to_*`` function is a :func:`functools.singledispatch` function, so it can be
20
+ extended for new types without changing bhtypes::
21
+
22
+ @to_bhresist.register
23
+ def _(pipe: MyTripleUTube) -> dict: ...
24
+
25
+ Dispatch picks the most specific registered type, so a subclass of a bhtypes class can
26
+ get its own conversion without affecting the class it extends.
27
+
28
+ To convert *differently* -- for example when a package adopts bhtypes and maintains its
29
+ own mapping -- write your own function. Do not re-register an existing bhtypes type: the
30
+ registry is shared by every package in the process, so that would change the conversion
31
+ for all of them.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+
37
+ def _unsupported(target: str, obj) -> TypeError:
38
+ return TypeError(f"no {target} conversion for {type(obj).__name__}; register one with .register")
@@ -0,0 +1,90 @@
1
+ """bhresist conventions.
2
+
3
+ ``to_bhresist(obj)`` gives keyword arguments for bhresist's ``Borehole.init_*_borehole``;
4
+ :func:`init_method` names the method for a pipe::
5
+
6
+ bh = bhr.borehole.Borehole()
7
+ getattr(bh, init_method(pipe))(**to_bhresist(pipe), **to_bhresist(grout), **to_bhresist(soil),
8
+ borehole_diameter=0.1524, length=200.0, fluid=fluid)
9
+
10
+ bhresist has no series double U-tube model, so those are refused rather than computed as
11
+ parallel.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from functools import singledispatch
17
+
18
+ from bhtypes.convert import _unsupported
19
+ from bhtypes.materials import Grout, Soil
20
+ from bhtypes.pipes import Coaxial, DoubleUTube, SingleUTube
21
+
22
+
23
+ @singledispatch
24
+ def to_bhresist(obj) -> dict:
25
+ """Keyword arguments for bhresist (see the module docstring)."""
26
+ raise _unsupported("bhresist", obj)
27
+
28
+
29
+ @to_bhresist.register(Soil)
30
+ def _(soil: Soil) -> dict:
31
+ return {"soil_conductivity": soil.thermal_conductivity_w_per_m_k}
32
+
33
+
34
+ @to_bhresist.register(Grout)
35
+ def _(grout: Grout) -> dict:
36
+ return {"grout_conductivity": grout.thermal_conductivity_w_per_m_k}
37
+
38
+
39
+ def _u_tube(pipe: SingleUTube | DoubleUTube) -> dict:
40
+ return {
41
+ "pipe_outer_diameter": pipe.outer_diameter_m,
42
+ "pipe_dimension_ratio": pipe.dimension_ratio,
43
+ "shank_space": pipe.leg_offset_m, # bhresist: borehole axis to leg centre
44
+ "pipe_conductivity": pipe.thermal_conductivity_w_per_m_k,
45
+ }
46
+
47
+
48
+ @to_bhresist.register(SingleUTube)
49
+ def _(pipe: SingleUTube) -> dict:
50
+ return _u_tube(pipe)
51
+
52
+
53
+ @to_bhresist.register(DoubleUTube)
54
+ def _(pipe: DoubleUTube) -> dict:
55
+ if pipe.flow != "parallel":
56
+ raise ValueError("bhresist models double U-tubes in parallel only")
57
+ return {**_u_tube(pipe), "pipe_inlet_arrangement": pipe.inlets.upper()}
58
+
59
+
60
+ @to_bhresist.register(Coaxial)
61
+ def _(pipe: Coaxial) -> dict:
62
+ return {
63
+ "outer_pipe_outer_diameter": pipe.outer_pipe_outer_diameter_m,
64
+ "outer_pipe_dimension_ratio": pipe.outer_pipe_dimension_ratio,
65
+ "outer_pipe_conductivity": pipe.outer_pipe_thermal_conductivity_w_per_m_k,
66
+ "inner_pipe_outer_diameter": pipe.inner_pipe_outer_diameter_m,
67
+ "inner_pipe_dimension_ratio": pipe.inner_pipe_dimension_ratio,
68
+ "inner_pipe_conductivity": pipe.inner_pipe_thermal_conductivity_w_per_m_k,
69
+ }
70
+
71
+
72
+ @singledispatch
73
+ def init_method(pipe) -> str:
74
+ """Name of the bhresist ``Borehole`` method that takes :func:`to_bhresist`'s keyword arguments."""
75
+ raise _unsupported("bhresist", pipe)
76
+
77
+
78
+ @init_method.register(SingleUTube)
79
+ def _(pipe: SingleUTube) -> str:
80
+ return "init_single_u_borehole"
81
+
82
+
83
+ @init_method.register(DoubleUTube)
84
+ def _(pipe: DoubleUTube) -> str:
85
+ return "init_double_u_borehole"
86
+
87
+
88
+ @init_method.register(Coaxial)
89
+ def _(pipe: Coaxial) -> str:
90
+ return "init_coaxial_borehole"
@@ -0,0 +1,147 @@
1
+ """GHEDesigner input-file conventions.
2
+
3
+ ``to_ghedesigner(obj)`` writes a ``soil``, ``grout`` or ``pipe`` block; the
4
+ ``*_from_ghedesigner`` functions read one. Blocks use the input-file keys
5
+ (``conductivity``, ``rho_cp``, ``inner_diameter``, ...). For soil and grout the readers also
6
+ accept GHEDesigner's newer unit-suffixed keys (``thermal_conductivity_w_per_m_k``, ...).
7
+
8
+ GHEDesigner cannot represent diagonal double U-tube inlets, an annulus-inlet coaxial
9
+ exchanger, or different heat capacities for the two coaxial pipes; those are refused.
10
+ Reading a GHEDesigner double U-tube gives adjacent inlets and a coaxial gives a centre
11
+ inlet -- what GHEDesigner itself assumes.
12
+
13
+ This module is a bridge until GHEDesigner reads and writes bhtypes itself.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from functools import singledispatch
19
+
20
+ from bhtypes.convert import _unsupported
21
+ from bhtypes.materials import Grout, Soil
22
+ from bhtypes.pipes import DEFAULT_ROUGHNESS_M, Coaxial, DoubleUTube, Pipe, SingleUTube
23
+
24
+ _DOUBLE_U_FLOWS = {"DOUBLEUTUBEPARALLEL": "parallel", "DOUBLEUTUBESERIES": "series"}
25
+
26
+
27
+ @singledispatch
28
+ def to_ghedesigner(obj) -> dict:
29
+ """A GHEDesigner input-file block for ``obj`` (see the module docstring)."""
30
+ raise _unsupported("GHEDesigner", obj)
31
+
32
+
33
+ @to_ghedesigner.register(Soil)
34
+ def _(soil: Soil) -> dict:
35
+ return {
36
+ "conductivity": soil.thermal_conductivity_w_per_m_k,
37
+ "rho_cp": soil.volumetric_heat_capacity_j_per_m3_k,
38
+ "undisturbed_temp": soil.undisturbed_temperature_c,
39
+ }
40
+
41
+
42
+ @to_ghedesigner.register(Grout)
43
+ def _(grout: Grout) -> dict:
44
+ return {"conductivity": grout.thermal_conductivity_w_per_m_k, "rho_cp": grout.volumetric_heat_capacity_j_per_m3_k}
45
+
46
+
47
+ def _u_tube(pipe: SingleUTube | DoubleUTube) -> dict:
48
+ return {
49
+ "inner_diameter": pipe.inner_diameter_m,
50
+ "outer_diameter": pipe.outer_diameter_m,
51
+ "shank_spacing": pipe.shank_spacing_m,
52
+ "roughness": pipe.roughness_m,
53
+ "conductivity": pipe.thermal_conductivity_w_per_m_k,
54
+ "rho_cp": pipe.volumetric_heat_capacity_j_per_m3_k,
55
+ }
56
+
57
+
58
+ @to_ghedesigner.register(SingleUTube)
59
+ def _(pipe: SingleUTube) -> dict:
60
+ return {"arrangement": "SINGLEUTUBE", **_u_tube(pipe)}
61
+
62
+
63
+ @to_ghedesigner.register(DoubleUTube)
64
+ def _(pipe: DoubleUTube) -> dict:
65
+ if pipe.inlets != "adjacent":
66
+ raise ValueError("GHEDesigner models double U-tubes with adjacent inlets only")
67
+ return {"arrangement": f"DOUBLEUTUBE{pipe.flow.upper()}", **_u_tube(pipe)}
68
+
69
+
70
+ @to_ghedesigner.register(Coaxial)
71
+ def _(pipe: Coaxial) -> dict:
72
+ if pipe.inner_pipe_volumetric_heat_capacity_j_per_m3_k != pipe.outer_pipe_volumetric_heat_capacity_j_per_m3_k:
73
+ raise ValueError("GHEDesigner takes one rho_cp for both coaxial pipes")
74
+ if pipe.inlet != "centre":
75
+ raise ValueError("GHEDesigner models coaxial exchangers with the centre pipe as the inlet only")
76
+ return {
77
+ "arrangement": "COAXIAL",
78
+ "inner_pipe_d_in": pipe.inner_pipe_inner_diameter_m,
79
+ "inner_pipe_d_out": pipe.inner_pipe_outer_diameter_m,
80
+ "outer_pipe_d_in": pipe.outer_pipe_inner_diameter_m,
81
+ "outer_pipe_d_out": pipe.outer_pipe_outer_diameter_m,
82
+ "roughness": pipe.roughness_m,
83
+ "conductivity_inner": pipe.inner_pipe_thermal_conductivity_w_per_m_k,
84
+ "conductivity_outer": pipe.outer_pipe_thermal_conductivity_w_per_m_k,
85
+ "rho_cp": pipe.inner_pipe_volumetric_heat_capacity_j_per_m3_k,
86
+ }
87
+
88
+
89
+ def _key(block: dict, short: str, long: str) -> float:
90
+ """A value under GHEDesigner's input-file key (``conductivity``) or its unit-suffixed key."""
91
+ if short in block and long in block:
92
+ raise ValueError(f"give {short!r} or {long!r}, not both")
93
+ try:
94
+ return block[short] if short in block else block[long]
95
+ except KeyError:
96
+ raise KeyError(f"missing {short!r} (or {long!r})") from None
97
+
98
+
99
+ def soil_from_ghedesigner(block: dict) -> Soil:
100
+ return Soil(
101
+ _key(block, "conductivity", "thermal_conductivity_w_per_m_k"),
102
+ _key(block, "rho_cp", "volumetric_heat_capacity_j_per_m3_k"),
103
+ _key(block, "undisturbed_temp", "undisturbed_ground_temperature_c"),
104
+ )
105
+
106
+
107
+ def grout_from_ghedesigner(block: dict) -> Grout:
108
+ return Grout(
109
+ _key(block, "conductivity", "thermal_conductivity_w_per_m_k"),
110
+ _key(block, "rho_cp", "volumetric_heat_capacity_j_per_m3_k"),
111
+ )
112
+
113
+
114
+ def _u_tube_fields(block: dict) -> dict:
115
+ return {
116
+ "inner_diameter_m": block["inner_diameter"],
117
+ "outer_diameter_m": block["outer_diameter"],
118
+ "shank_spacing_m": block["shank_spacing"],
119
+ "thermal_conductivity_w_per_m_k": block["conductivity"],
120
+ "volumetric_heat_capacity_j_per_m3_k": block["rho_cp"],
121
+ "roughness_m": block.get("roughness", DEFAULT_ROUGHNESS_M),
122
+ }
123
+
124
+
125
+ def pipe_from_ghedesigner(block: dict) -> Pipe:
126
+ """A GHEDesigner ``pipe`` block as the bhtypes pipe its ``arrangement`` names."""
127
+ arrangement = str(block.get("arrangement", "")).upper()
128
+ if arrangement == "SINGLEUTUBE":
129
+ if block.get("num_pipes", 1) != 1:
130
+ raise ValueError(f"SingleUTube holds one U-tube; got num_pipes={block['num_pipes']!r}")
131
+ return SingleUTube(**_u_tube_fields(block))
132
+ if arrangement in _DOUBLE_U_FLOWS:
133
+ return DoubleUTube(**_u_tube_fields(block), inlets="adjacent", flow=_DOUBLE_U_FLOWS[arrangement])
134
+ if arrangement == "COAXIAL":
135
+ return Coaxial(
136
+ inner_pipe_inner_diameter_m=block["inner_pipe_d_in"],
137
+ inner_pipe_outer_diameter_m=block["inner_pipe_d_out"],
138
+ outer_pipe_inner_diameter_m=block["outer_pipe_d_in"],
139
+ outer_pipe_outer_diameter_m=block["outer_pipe_d_out"],
140
+ inner_pipe_thermal_conductivity_w_per_m_k=block["conductivity_inner"],
141
+ outer_pipe_thermal_conductivity_w_per_m_k=block["conductivity_outer"],
142
+ inner_pipe_volumetric_heat_capacity_j_per_m3_k=block["rho_cp"],
143
+ outer_pipe_volumetric_heat_capacity_j_per_m3_k=block["rho_cp"],
144
+ roughness_m=block.get("roughness", DEFAULT_ROUGHNESS_M),
145
+ inlet="centre",
146
+ )
147
+ raise ValueError(f"unknown GHEDesigner pipe arrangement {block.get('arrangement')!r}")
@@ -0,0 +1,96 @@
1
+ """pygfunction conventions.
2
+
3
+ ``to_pygfunction(obj)`` gives keyword arguments for pygfunction's pipe models::
4
+
5
+ gt.pipes.MultipleUTube(**to_pygfunction(pipe), **to_pygfunction(soil), **to_pygfunction(grout),
6
+ borehole=borehole, R_fp=R_fp)
7
+
8
+ Pass ``soil.thermal_diffusivity_m2_per_s`` as ``alpha`` to pygfunction's g-functions, and
9
+ :func:`pipe_type` as ``pipe_type_str`` to ``gFunction.from_static_params``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from functools import singledispatch
15
+
16
+ from bhtypes.convert import _unsupported
17
+ from bhtypes.materials import Grout, Soil
18
+ from bhtypes.pipes import Coaxial, DoubleUTube, SingleUTube
19
+
20
+
21
+ @singledispatch
22
+ def to_pygfunction(obj) -> dict:
23
+ """Keyword arguments for pygfunction (see the module docstring)."""
24
+ raise _unsupported("pygfunction", obj)
25
+
26
+
27
+ @to_pygfunction.register(Soil)
28
+ def _(soil: Soil) -> dict:
29
+ return {"k_s": soil.thermal_conductivity_w_per_m_k}
30
+
31
+
32
+ @to_pygfunction.register(Grout)
33
+ def _(grout: Grout) -> dict:
34
+ return {"k_g": grout.thermal_conductivity_w_per_m_k}
35
+
36
+
37
+ @to_pygfunction.register(SingleUTube)
38
+ def _(pipe: SingleUTube) -> dict:
39
+ """``pos``, ``r_in``, ``r_out`` for ``pygfunction.pipes.SingleUTube``."""
40
+ return {"pos": pipe.leg_positions(), "r_in": pipe.inner_radius_m, "r_out": pipe.outer_radius_m}
41
+
42
+
43
+ @to_pygfunction.register(DoubleUTube)
44
+ def _(pipe: DoubleUTube) -> dict:
45
+ """``pos`` (inlets first), ``r_in``, ``r_out``, ``nPipes``, ``config`` for ``pygfunction.pipes.MultipleUTube``."""
46
+ return {
47
+ "pos": pipe.leg_positions(),
48
+ "r_in": pipe.inner_radius_m,
49
+ "r_out": pipe.outer_radius_m,
50
+ "nPipes": 2,
51
+ "config": pipe.flow,
52
+ }
53
+
54
+
55
+ @to_pygfunction.register(Coaxial)
56
+ def _(pipe: Coaxial) -> dict:
57
+ """``pos``, ``r_in``, ``r_out`` for ``pygfunction.pipes.Coaxial``, radii ordered inlet pipe first.
58
+
59
+ pygfunction's ``Coaxial`` needs the radii as numpy arrays. numpy is imported here only;
60
+ wherever pygfunction is installed, so is numpy. :func:`coaxial_radii` gives plain tuples.
61
+ """
62
+ import numpy as np
63
+
64
+ r_in, r_out = coaxial_radii(pipe)
65
+ return {"pos": (0.0, 0.0), "r_in": np.array(r_in), "r_out": np.array(r_out)}
66
+
67
+
68
+ def coaxial_radii(pipe: Coaxial) -> tuple[tuple[float, float], tuple[float, float]]:
69
+ """``(r_in, r_out)`` in pygfunction's order: the inlet pipe first, then the outlet pipe."""
70
+ first, second = (
71
+ (pipe.inner_pipe_radii_m, pipe.outer_pipe_radii_m)
72
+ if pipe.inlet == "centre"
73
+ else (pipe.outer_pipe_radii_m, pipe.inner_pipe_radii_m)
74
+ )
75
+ return (first[0], second[0]), (first[1], second[1])
76
+
77
+
78
+ @singledispatch
79
+ def pipe_type(pipe) -> str:
80
+ """pygfunction's ``pipe_type_str`` for ``gFunction.from_static_params``."""
81
+ raise _unsupported("pygfunction pipe type", pipe)
82
+
83
+
84
+ @pipe_type.register(SingleUTube)
85
+ def _(pipe: SingleUTube) -> str:
86
+ return "SINGLE_UTUBE"
87
+
88
+
89
+ @pipe_type.register(DoubleUTube)
90
+ def _(pipe: DoubleUTube) -> str:
91
+ return f"DOUBLE_UTUBE_{pipe.flow.upper()}"
92
+
93
+
94
+ @pipe_type.register(Coaxial)
95
+ def _(pipe: Coaxial) -> str:
96
+ return "COAXIAL_ANNULAR_OUT" if pipe.inlet == "centre" else "COAXIAL_ANNULAR_IN"
bhtypes/materials.py ADDED
@@ -0,0 +1,52 @@
1
+ """Ground and grout thermal properties.
2
+
3
+ Plain data with validation. Conversions to other packages' conventions are in
4
+ :mod:`bhtypes.convert`.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+
11
+ from bhtypes._checks import positive
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class Soil:
16
+ """The ground around the borehole.
17
+
18
+ Attributes
19
+ ----------
20
+ thermal_conductivity_w_per_m_k : float
21
+ volumetric_heat_capacity_j_per_m3_k : float
22
+ undisturbed_temperature_c : float
23
+ Far-field (undisturbed) ground temperature.
24
+ """
25
+
26
+ thermal_conductivity_w_per_m_k: float
27
+ volumetric_heat_capacity_j_per_m3_k: float
28
+ undisturbed_temperature_c: float
29
+
30
+ def __post_init__(self) -> None:
31
+ positive("thermal_conductivity_w_per_m_k", self.thermal_conductivity_w_per_m_k)
32
+ positive("volumetric_heat_capacity_j_per_m3_k", self.volumetric_heat_capacity_j_per_m3_k)
33
+
34
+ @property
35
+ def thermal_diffusivity_m2_per_s(self) -> float:
36
+ return self.thermal_conductivity_w_per_m_k / self.volumetric_heat_capacity_j_per_m3_k
37
+
38
+
39
+ @dataclass(frozen=True, slots=True)
40
+ class Grout:
41
+ """The backfill between the pipes and the borehole wall."""
42
+
43
+ thermal_conductivity_w_per_m_k: float
44
+ volumetric_heat_capacity_j_per_m3_k: float
45
+
46
+ def __post_init__(self) -> None:
47
+ positive("thermal_conductivity_w_per_m_k", self.thermal_conductivity_w_per_m_k)
48
+ positive("volumetric_heat_capacity_j_per_m3_k", self.volumetric_heat_capacity_j_per_m3_k)
49
+
50
+ @property
51
+ def thermal_diffusivity_m2_per_s(self) -> float:
52
+ return self.thermal_conductivity_w_per_m_k / self.volumetric_heat_capacity_j_per_m3_k
bhtypes/pipes.py ADDED
@@ -0,0 +1,186 @@
1
+ """Borehole pipe geometries: single U-tube, double U-tube and coaxial.
2
+
3
+ Plain data: every dimension is stored once, under a name that says what it is and in what
4
+ unit, with validation and derived geometry. Conversions to other packages' conventions are
5
+ in :mod:`bhtypes.convert`.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass
11
+ from math import cos, pi, sin
12
+
13
+ from bhtypes._checks import choice, non_negative, positive, wall
14
+
15
+ #: pygfunction's default pipe roughness [m] (smooth plastic pipe).
16
+ DEFAULT_ROUGHNESS_M = 1.0e-6
17
+
18
+ DOUBLE_U_INLETS = ("adjacent", "diagonal")
19
+ DOUBLE_U_FLOWS = ("parallel", "series")
20
+ COAXIAL_INLETS = ("centre", "annulus")
21
+
22
+
23
+ def _ring(radius: float, n_tubes: int) -> list[tuple[float, float]]:
24
+ """Leg centres around the borehole axis, in GHEDesigner's ``Pipe.place_pipes`` order and arithmetic.
25
+
26
+ For each U-tube ``i``: its first leg at angle ``2 i dt + pi``, its second at ``2 i dt + pi + dt``,
27
+ with ``dt = pi / n_tubes``. Using the same arithmetic keeps positions identical to GHEDesigner's.
28
+ """
29
+ dt = pi / float(n_tubes)
30
+ legs = []
31
+ for i in range(n_tubes):
32
+ legs.append((radius * cos(2.0 * i * dt + pi), radius * sin(2.0 * i * dt + pi)))
33
+ legs.append((radius * cos(2.0 * i * dt + pi + dt), radius * sin(2.0 * i * dt + pi + dt)))
34
+ return legs
35
+
36
+
37
+ def _dimension_ratio(inner_diameter: float, outer_diameter: float) -> float:
38
+ """Outer diameter over wall thickness (DR / SDR)."""
39
+ r_in, r_out = inner_diameter / 2.0, outer_diameter / 2.0
40
+ return (2.0 * r_out) / (r_out - r_in)
41
+
42
+
43
+ @dataclass(frozen=True, slots=True)
44
+ class _UTube:
45
+ """Fields and derived geometry shared by single and double U-tubes."""
46
+
47
+ inner_diameter_m: float
48
+ outer_diameter_m: float
49
+ shank_spacing_m: float # gap between the outer walls of the two legs of a U-tube: o<-- s -->o
50
+ thermal_conductivity_w_per_m_k: float
51
+ volumetric_heat_capacity_j_per_m3_k: float
52
+ roughness_m: float = DEFAULT_ROUGHNESS_M
53
+
54
+ def __post_init__(self) -> None:
55
+ wall("inner_diameter_m", self.inner_diameter_m, "outer_diameter_m", self.outer_diameter_m)
56
+ non_negative("shank_spacing_m", self.shank_spacing_m)
57
+ positive("thermal_conductivity_w_per_m_k", self.thermal_conductivity_w_per_m_k)
58
+ positive("volumetric_heat_capacity_j_per_m3_k", self.volumetric_heat_capacity_j_per_m3_k)
59
+ non_negative("roughness_m", self.roughness_m)
60
+
61
+ @property
62
+ def inner_radius_m(self) -> float:
63
+ return self.inner_diameter_m / 2.0
64
+
65
+ @property
66
+ def outer_radius_m(self) -> float:
67
+ return self.outer_diameter_m / 2.0
68
+
69
+ @property
70
+ def dimension_ratio(self) -> float:
71
+ """Outer diameter over wall thickness (DR / SDR)."""
72
+ return _dimension_ratio(self.inner_diameter_m, self.outer_diameter_m)
73
+
74
+ @property
75
+ def leg_offset_m(self) -> float:
76
+ """Distance from the borehole axis to each leg's centre."""
77
+ return self.shank_spacing_m / 2.0 + self.outer_radius_m
78
+
79
+
80
+ @dataclass(frozen=True, slots=True)
81
+ class SingleUTube(_UTube):
82
+ """One U-tube: two legs either side of the borehole axis."""
83
+
84
+ def leg_positions(self) -> list[tuple[float, float]]:
85
+ """``[(x, y) inlet, (x, y) outlet]`` [m], relative to the borehole axis."""
86
+ return _ring(self.leg_offset_m, 1)
87
+
88
+
89
+ @dataclass(frozen=True, slots=True)
90
+ class DoubleUTube(_UTube):
91
+ """Two U-tubes at the same distance from the borehole axis, 90 degrees apart.
92
+
93
+ Attributes
94
+ ----------
95
+ inlets : {'adjacent', 'diagonal'}
96
+ Whether the two downward (inlet) legs sit next to each other or opposite.
97
+ flow : {'parallel', 'series'}
98
+ Whether the U-tubes share the flow or carry it one after the other.
99
+ """
100
+
101
+ inlets: str = "adjacent"
102
+ flow: str = "parallel"
103
+
104
+ def __post_init__(self) -> None:
105
+ _UTube.__post_init__(self)
106
+ choice("inlets", self.inlets, DOUBLE_U_INLETS)
107
+ choice("flow", self.flow, DOUBLE_U_FLOWS)
108
+
109
+ def leg_positions(self) -> list[tuple[float, float]]:
110
+ """``[inlet, inlet, outlet, outlet]`` (x, y) [m], relative to the borehole axis."""
111
+ first_in, first_out, second_in, second_out = _ring(self.leg_offset_m, 2)
112
+ if self.inlets == "adjacent":
113
+ # the second leg of each U-tube in GHEDesigner's ring sits 90 degrees from the first
114
+ return [first_in, first_out, second_in, second_out]
115
+ return [first_in, second_in, first_out, second_out]
116
+
117
+
118
+ @dataclass(frozen=True, slots=True)
119
+ class Coaxial:
120
+ """A centre pipe inside an outer pipe; the fluid goes down one channel and up the other.
121
+
122
+ Attributes
123
+ ----------
124
+ inlet : {'centre', 'annulus'}
125
+ Which channel carries the fluid down.
126
+ """
127
+
128
+ inner_pipe_inner_diameter_m: float
129
+ inner_pipe_outer_diameter_m: float
130
+ outer_pipe_inner_diameter_m: float
131
+ outer_pipe_outer_diameter_m: float
132
+ inner_pipe_thermal_conductivity_w_per_m_k: float
133
+ outer_pipe_thermal_conductivity_w_per_m_k: float
134
+ inner_pipe_volumetric_heat_capacity_j_per_m3_k: float
135
+ outer_pipe_volumetric_heat_capacity_j_per_m3_k: float
136
+ roughness_m: float = DEFAULT_ROUGHNESS_M
137
+ inlet: str = "centre"
138
+
139
+ def __post_init__(self) -> None:
140
+ wall(
141
+ "inner_pipe_inner_diameter_m",
142
+ self.inner_pipe_inner_diameter_m,
143
+ "inner_pipe_outer_diameter_m",
144
+ self.inner_pipe_outer_diameter_m,
145
+ )
146
+ wall(
147
+ "outer_pipe_inner_diameter_m",
148
+ self.outer_pipe_inner_diameter_m,
149
+ "outer_pipe_outer_diameter_m",
150
+ self.outer_pipe_outer_diameter_m,
151
+ )
152
+ if not self.inner_pipe_outer_diameter_m < self.outer_pipe_inner_diameter_m:
153
+ raise ValueError(
154
+ "the inner pipe must fit inside the outer pipe "
155
+ "(inner_pipe_outer_diameter_m < outer_pipe_inner_diameter_m)"
156
+ )
157
+ for name in (
158
+ "inner_pipe_thermal_conductivity_w_per_m_k",
159
+ "outer_pipe_thermal_conductivity_w_per_m_k",
160
+ "inner_pipe_volumetric_heat_capacity_j_per_m3_k",
161
+ "outer_pipe_volumetric_heat_capacity_j_per_m3_k",
162
+ ):
163
+ positive(name, getattr(self, name))
164
+ non_negative("roughness_m", self.roughness_m)
165
+ choice("inlet", self.inlet, COAXIAL_INLETS)
166
+
167
+ @property
168
+ def inner_pipe_radii_m(self) -> tuple[float, float]:
169
+ """``(inner, outer)`` radius of the centre pipe."""
170
+ return self.inner_pipe_inner_diameter_m / 2.0, self.inner_pipe_outer_diameter_m / 2.0
171
+
172
+ @property
173
+ def outer_pipe_radii_m(self) -> tuple[float, float]:
174
+ """``(inner, outer)`` radius of the outer pipe."""
175
+ return self.outer_pipe_inner_diameter_m / 2.0, self.outer_pipe_outer_diameter_m / 2.0
176
+
177
+ @property
178
+ def inner_pipe_dimension_ratio(self) -> float:
179
+ return _dimension_ratio(self.inner_pipe_inner_diameter_m, self.inner_pipe_outer_diameter_m)
180
+
181
+ @property
182
+ def outer_pipe_dimension_ratio(self) -> float:
183
+ return _dimension_ratio(self.outer_pipe_inner_diameter_m, self.outer_pipe_outer_diameter_m)
184
+
185
+
186
+ Pipe = SingleUTube | DoubleUTube | Coaxial
bhtypes/py.typed ADDED
File without changes
@@ -0,0 +1,140 @@
1
+ Metadata-Version: 2.4
2
+ Name: bhtypes
3
+ Version: 0.1.0
4
+ Summary: Dependency-free, shared data types for borehole definitions used in ground heat exchanger software, with converters to pygfunction, bhresist and GHEDesigner.
5
+ Keywords: geothermal,borehole,ground heat exchanger,U-tube,coaxial,pygfunction,GHEDesigner
6
+ Author: Jack C. Cook
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Scientific/Engineering
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.11
21
+ Project-URL: Homepage, https://github.com/KelvinSource/BHTypes
22
+ Project-URL: Repository, https://github.com/KelvinSource/BHTypes
23
+ Project-URL: Issues, https://github.com/KelvinSource/BHTypes/issues
24
+ Description-Content-Type: text/markdown
25
+
26
+ # BHTypes
27
+
28
+ **Plain data types for a borehole heat exchanger's cross-section**: `Soil`, `Grout`, and the
29
+ pipe geometries `SingleUTube`, `DoubleUTube` and `Coaxial`, plus converters to the conventions
30
+ of [pygfunction](https://github.com/MassimoCimmino/pygfunction),
31
+ [bhresist](https://pypi.org/project/bhresist/) and
32
+ [GHEDesigner](https://github.com/BETSRG/GHEDesigner). No dependencies.
33
+
34
+ Each of those packages describes the same pipe differently -- radii or diameters, a wall
35
+ dimension ratio, shank spacing measured edge to edge or from the borehole axis, leg order,
36
+ coaxial radii grouped by pipe or by surface. `bhtypes` stores each dimension once, under a
37
+ name that says what it is and in what unit, and derives the rest:
38
+
39
+ ```python
40
+ from bhtypes import DoubleUTube, Grout, Soil
41
+ from bhtypes.convert.bhresist import init_method, to_bhresist
42
+ from bhtypes.convert.ghedesigner import pipe_from_ghedesigner, to_ghedesigner
43
+ from bhtypes.convert.pygfunction import to_pygfunction
44
+
45
+ pipe = DoubleUTube(
46
+ inner_diameter_m=0.03398,
47
+ outer_diameter_m=0.04216,
48
+ shank_spacing_m=0.03404, # gap between the outer walls of a U-tube's legs
49
+ thermal_conductivity_w_per_m_k=0.4,
50
+ volumetric_heat_capacity_j_per_m3_k=2.07e6,
51
+ inlets="adjacent", # or "diagonal"
52
+ flow="parallel", # or "series"
53
+ )
54
+ grout = Grout(thermal_conductivity_w_per_m_k=2.4, volumetric_heat_capacity_j_per_m3_k=3.4e6)
55
+ soil = Soil(thermal_conductivity_w_per_m_k=3.0, volumetric_heat_capacity_j_per_m3_k=2.6e6,
56
+ undisturbed_temperature_c=12.0)
57
+
58
+ # pygfunction
59
+ gt.pipes.MultipleUTube(**to_pygfunction(pipe), **to_pygfunction(soil), **to_pygfunction(grout),
60
+ borehole=borehole, R_fp=R_fp)
61
+
62
+ # bhresist
63
+ bh = bhr.borehole.Borehole()
64
+ getattr(bh, init_method(pipe))(**to_bhresist(pipe), **to_bhresist(grout), **to_bhresist(soil),
65
+ borehole_diameter=0.1524, length=200.0, fluid=fluid)
66
+
67
+ # GHEDesigner input files
68
+ pipe = pipe_from_ghedesigner(config["pipe"])
69
+ config["pipe"] = to_ghedesigner(pipe)
70
+ ```
71
+
72
+ ## Layout
73
+
74
+ The types (`bhtypes.materials`, `bhtypes.pipes`) are plain data: fields, validation and
75
+ derived geometry, with no knowledge of any other package. Each conversion lives in
76
+ `bhtypes.convert.<package>`:
77
+
78
+ | Module | Functions |
79
+ |---|---|
80
+ | `bhtypes.convert.pygfunction` | `to_pygfunction`, `pipe_type` (`pipe_type_str`), `coaxial_radii` |
81
+ | `bhtypes.convert.bhresist` | `to_bhresist`, `init_method` |
82
+ | `bhtypes.convert.ghedesigner` | `to_ghedesigner`, `pipe_from_ghedesigner`, `soil_from_ghedesigner`, `grout_from_ghedesigner` |
83
+
84
+ Import the functions, not the modules, so `bhtypes.convert.pygfunction` does not shadow
85
+ `pygfunction` itself.
86
+
87
+ ## Extending conversions
88
+
89
+ Every `to_*` converter is a `functools.singledispatch` function:
90
+
91
+ - **New types** -- register a conversion without changing bhtypes:
92
+ ```python
93
+ @to_bhresist.register(MyTripleUTube)
94
+ def _(pipe): ...
95
+ ```
96
+ - **Subclasses** -- dispatch picks the most specific type, so a subclass of a bhtypes class can
97
+ have its own conversion while the parent's is unchanged.
98
+ - **Converting differently** -- write your own function. A package that adopts bhtypes would
99
+ own its conversion (e.g. GHEDesigner's own `from_bhtypes`), and the bridge here would retire.
100
+ Do not re-register an existing bhtypes type: the registry is shared by every package in the
101
+ process, so that would change the conversion for all of them.
102
+
103
+ ## Installation
104
+
105
+ ```bash
106
+ pip install bhtypes
107
+ ```
108
+
109
+ ## Scope
110
+
111
+ - **In:** soil and grout thermal properties; single U-tube, double U-tube (explicit inlet
112
+ arrangement and parallel/series flow) and coaxial pipe geometry; converters.
113
+ - **Out:** fluids -- use [SecondaryCoolantProps](https://pypi.org/project/SecondaryCoolantProps/)
114
+ (`scp`), which pygfunction, bhresist and GHEDesigner already share; borehole geometry -- use
115
+ `pygfunction.boreholes.Borehole`.
116
+
117
+ ## Conventions
118
+
119
+ | Quantity | Field | Derived |
120
+ |---|---|---|
121
+ | Pipe size | `inner_diameter_m`, `outer_diameter_m` | radii, `dimension_ratio` (outer diameter / wall) |
122
+ | Leg spacing | `shank_spacing_m`: gap between the legs' outer walls | `leg_offset_m`: borehole axis to leg centre |
123
+ | Leg positions | -- | `leg_positions()`: inlets first, then outlets (pygfunction's order) |
124
+ | Double U inlets | `inlets`: `"adjacent"` or `"diagonal"` | bhresist's `pipe_inlet_arrangement` |
125
+ | Coaxial flow | `inlet`: `"centre"` or `"annulus"` | pygfunction's radius order and `pipe_type_str` |
126
+ | Coaxial pipes | four diameters, per-pipe conductivity and heat capacity | `inner_pipe_radii_m`, `outer_pipe_radii_m`, dimension ratios |
127
+
128
+ Leg positions are computed with GHEDesigner's own arithmetic, so converted values match
129
+ what GHEDesigner passes to pygfunction and bhresist bit for bit.
130
+
131
+ Converters refuse what the target package cannot represent rather than approximating it:
132
+ bhresist has no series double U-tube model, and GHEDesigner input files have no diagonal
133
+ double U-tube, no annulus-inlet coaxial and no per-pipe coaxial heat capacity.
134
+
135
+ ## Development
136
+
137
+ ```bash
138
+ uv sync
139
+ uv run pytest # GHEDesigner comparisons skip unless GHEDesigner is installed
140
+ ```
@@ -0,0 +1,13 @@
1
+ bhtypes/__init__.py,sha256=xVnQUNvfvFwbXQTD8ATYSS_KXu_lPbawHeje8822360,1067
2
+ bhtypes/_checks.py,sha256=7w0jx0zXT0ihrqrYId_Iy2U2OCTwDpD8Iwt6yL5OP1I,1050
3
+ bhtypes/convert/__init__.py,sha256=vgt758i3zaMFZkdjk4gU37fMZGzFFr-jgqz_fSxI2JI,1857
4
+ bhtypes/convert/bhresist.py,sha256=0Vt2KBB6Xrc9sAwP3SufGuvVEDUXHM--5bLT_NtJe9k,2841
5
+ bhtypes/convert/ghedesigner.py,sha256=MAV8YtCzX2K0Xp6OtSxZ6QDXPOioIVKeGGa4bnR7sZM,6211
6
+ bhtypes/convert/pygfunction.py,sha256=wNTo4trovSAYVr0oS9_bfa1ANv-24vajmwGgZ7bZAGU,3149
7
+ bhtypes/materials.py,sha256=GoxnX62ft74QW0LTwsgptZoBK2wZ381tmlfxo5VKjqo,1669
8
+ bhtypes/pipes.py,sha256=XR0H05WJPCB7KdEPzzu3vX_fRtIGOSJG6dKBmyCrG3k,7141
9
+ bhtypes/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
10
+ bhtypes-0.1.0.dist-info/licenses/LICENSE,sha256=1kzyHlSaESGoDEiHI-WNc_5RAvKEp4MEgQfzDPkmS40,1074
11
+ bhtypes-0.1.0.dist-info/WHEEL,sha256=q5IF0q2xCp3ktUFRCVWsQLjl2ChNlWXBJtnI1LCGdJ8,80
12
+ bhtypes-0.1.0.dist-info/METADATA,sha256=QmJGS5c5WPK0v_MIVfQzuuqD-k9PXJPLEFR814O28AA,6330
13
+ bhtypes-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.11.8
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kelvin Source LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.