Thermodynamic cycle architecture

Every model in tmhp is the same closed refrigerant cycle wrapped in a different source / sink pairing. That single piece of shared machinery is what lets one library cover ASHPB, GSHPB, WSHPB, ASHP, GSHP, and every subsystem variant on top — without rewriting the thermodynamics each time. This page sketches the shared structure and shows where each system family plugs into it.

The shared core

Every system reuses the same closed cycle — only the blocks marked source side and sink side swap out per family.

Click a node to see its code mapping and API link.

Topology is fixed · scroll-wheel to zoom · drag empty space to pan

Data flow shared by every tmhp model. Bold blocks are reused across ASHPB, GSHPB, WSHPB, ASHP, and GSHP.

ASHPB system schematic — refrigerant cycle, condenser HX, evaporator HX with outdoor fan, expander, and tank-side flow connections.

Physical wiring view of the ASHPB. The compressor / expander cycle-closure block in the centre reappears identically in the GSHPB, WSHPB, ASHP, and GSHP models.

The cycle solves four refrigerant state points (compressor in / out, expander in / out) plus the evaporator and condenser saturation states. Heat transfer at each heat exchanger is solved with an ε-NTU model. The evaporating temperature is left as a free parameter and chosen by minimizing compressor power, so the cycle closes on a physical optimum rather than on a fitted coefficient.

Per-source mechanics — the outdoor coil for ASHP, the g-function borehole for GSHP, the prescribed water inlet for WSHP — live on each model’s page under Models. The sink side (DHW tank or building load) is documented the same way.

Composed subsystems

The *_stc_* and *_pv_ess variants reuse the same core cycle and add one or more subsystems on the demand side:

  • Solar thermal collector (STC) preheat — STC heats the mains water before it reaches the tank. Reduces the tank-charge duty the heat pump has to deliver.

  • STC with stratified tank — STC charges a separate top node of a stratified tank; the heat pump charges the bottom.

  • PV + ESS — photovoltaic generation feeds an energy storage system that supplies the compressor and auxiliary loads preferentially.

These are documented under Subsystems.

Why the structure matters

Because the cycle is the same code path for every system, a parameter sweep across refrigerants, source types, or subsystem combinations doesn’t require re-implementing the model — it requires picking a different class and a different schedule. The cycle-level invariants (energy balance, COP definitions, failure_reason semantics) therefore hold identically across the family, so a result from ASHPB is directly comparable to a result from GSHPB or WSHPB at the same operating point.