Skip to content

About

Open Python simulator for hybrid dry-cooler and chiller cooling systems, validated against TRNSYS 18

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HeatTrack-Py

Hourly simulation of three-stage dry-cooler / chiller cooling systems, validated against TRNSYS 18.

License: Apache 2.0 Python 3.11+ Version 3.0.0

HeatTrack-Py simulates hybrid industrial cooling plants in which dry coolers reject as much heat as the ambient air allows and air-cooled chillers remove the rest, over a full year at hourly resolution. It reimplements the TRNSYS 18 component models used in the HeatTrack project (dry cooler Type 511, air-cooled chiller Type 655, pump Type 114, controllers Type 165, weather reader Type 15) on a graph-based engine with a TRNSYS-compatible successive-substitution solver.

  • Fast and scriptable: one configuration-year takes about 5 s; hundreds of configurations run from one text file.
  • Validated: for 20 reference configurations the hourly results match TRNSYS 18 to about 10⁻⁴ K for temperatures and better than 0.001 % for annual energy totals (see Validation).
  • Open: pure Python, Apache-2.0, results as pandas DataFrames and CSV files with TRNSYS column names.
  • Three ways to use it: command-line batch runner, Python API, and a browser-based web interface.

Developed in the HeatTrack project at Mälardalen University (RESILIENT research environment).


The system

 process water          Stage 1               Stage 2                 Stage 3
 67 °C, 145 kg/s --> Np1 dry coolers --> Np2 dry coolers      --> Mp3 chillers --> return (target ≤ 50 °C)
   + pump            in parallel,         and Mp2 chillers
                     Ns1 in series        sharing the flow
                          ^ fan speed staged by two controllers (30 °C / 40 °C) on the return temperature

A configuration is defined by five integers Np1 Ns1 Np2 Mp2 Mp3. The design list CoolingSystem_Topologies.txt contains 703 configurations; Reference_20_Topologies.txt contains the 20 reference configurations that were also simulated in TRNSYS 18. Design capacities are 460 kW per dry cooler and 1,750 kW per chiller.


Weather file (required, not included)

The reference cases use the Meteonorm weather file SA-Riyadh-Old-404380.tm2 (Riyadh, Saudi Arabia). It is part of the TRNSYS 18 distribution and is not redistributed with HeatTrack-Py (see NOTICE). To run the examples:

  1. Find the file in your TRNSYS 18 installation, by default C:\TRNSYS18\Weather\Meteonorm\Asia\SA-Riyadh-Old-404380.tm2
  2. Copy it to Weather/Meteonorm/Asia/ in this folder.

Any other TMY2 / Meteonorm .tm2 file can be used instead (pass it with --weather, or upload it in the web interface). Only the dry-bulb temperature is used. If the file is missing, HeatTrack-Py stops with a message explaining where to get it, and the tests that need it are skipped.


Installation

Requirements: Python 3.11 or newer (the web interface additionally needs Node.js 18+).

Simplest: double-click a launcher (see Quick start). On first use it creates a private Python environment (.venv) and installs the packages; this needs an internet connection once.

As a Python package:

cd HeatTrack-Py          # the unzipped release folder (or your clone of the repository)
python -m venv .venv
.venv/bin/python -m pip install -e ".[plots,test]"            # Windows: .venv\Scripts\python

Optional extras: plots (Matplotlib, for the parallel-model plots), test (pytest, httpx), web (FastAPI, SQLAlchemy, Uvicorn for the web interface).


Quick start

1. Batch runner (no programming)

Windows macOS / Linux
double-click run_windows.bat open run_mac.command (first time: right-click → Open)

The runner asks for two files; press Enter to accept the defaults:

  • Topology input file — CoolingSystem_Topologies.txt (all 703 configurations, about one hour) or your own file;
  • Weather file — the Riyadh file in Weather/Meteonorm/Asia/ or the path to your own .tm2.

From a terminal, the questions can be skipped:

.venv/bin/python run_simulation.py --input Reference_20_Topologies.txt \
    --weather Weather/Meteonorm/Asia/SA-Riyadh-Old-404380.tm2

Options: --output-dir FOLDER (default results/), --hours 48 (shorter period; default 8760).

2. Python API

from heattrack.projects import heattrack_generic
from heattrack.projects.heattrack_generic_report import build_report_dataframe

case = heattrack_generic.build(
    39, np1=2, ns1=2, np2=2, mp2=2, mp3=2, max_capacity_kw=9760,
    weather_file="Weather/Meteonorm/Asia/SA-Riyadh-Old-404380.tm2")
results = case.sim.run()                       # 8,760 hourly steps, a few seconds
report = build_report_dataframe(results.timeseries, 39, 2, 2, 2, 2, 2, 9760)

print(report[["T_Water_Ret", "Chiller_Power", "COP_Chiller"]].describe())
print(results.metadata["convergence"])         # iteration settings and non-converged hours

results.timeseries holds every output of every component for every hour; build_report_dataframe converts it to the TIME column plus the 26 output columns printed by the TRNSYS decks. Custom networks can be assembled from the component library with heattrack.Simulation, add() and connect() (see tests/engine/test_integration_single_branch.py for an example).

3. Parallel layout (TRNSYS deck 3DC_4CH)

run_parallel.py rebuilds the TRNSYS deck 3DC_4CH: 3 dry coolers and 4 air-cooled chillers in parallel behind a Type 11 diverter (20.5 % of the 145 kg/s stream to the chillers). It runs a full year with the deck's settings and writes hourly, daily and annual results, a convergence log and plots.

.venv/bin/python run_parallel.py --price-file Prices/EL_Price_SaudiArabia_industrial_20270101.txt

Launchers: run_parallel_windows.bat, run_parallel_mac.command. Main options: --n-dc, --n-ch, --diverter, --price-file, --temp-coefficient (ambient = dry bulb × (1 + value); 0.3 in the deck), --load-profile (hourly CSV hour,temperature_c,mass_flow_kg_hr), --start-date, --hours, --max-iterations. Without --price-file the cost results use a placeholder price of 1 per kWh. The Saudi industrial tariff files in Prices/ are built by tools/make_saudi_price_file.py. See documentation/3DC_4CH_comparison.md.

4. Web interface

./setup_web.sh        # once  (Windows: setup_web.bat)
./start_web.sh        # then open http://localhost:5173   (Windows: start_web.bat)
./stop_web.sh         # stop  (Windows: stop_web.bat)

Choose a reference case or a custom topology and a weather file, generate a year of data with one click, see a summary with key figures and charts, and inspect every saved project as code, as a system diagram and as time series. The back end (backend/, FastAPI) uses the same engine; the front end (frontend/) is a React application. Projects and results are stored in data/ (set HEATTRACK_DATA_DIR to store them elsewhere).


Input file format

One configuration per row, five whitespace-separated integers:

Column Meaning Allowed
Np1 Stage 1 dry coolers in parallel ≥ 1
Ns1 Stage 1 dry coolers in series ≥ 0
Np2 Stage 2 dry coolers ≥ 0
Mp2 Stage 2 chillers ≥ 0
Mp3 Stage 3 chillers ≥ 0
# Np1  Ns1  Np2  Mp2  Mp3
    2    2    6    0    1    # ID 195
    3    0    0    0    3    # ID 1

Lines starting with # and blank lines are ignored; # ID n at the end of a row sets the topology ID used in file names. All rows are checked before any simulation starts, and every malformed row is reported at once.

Outputs

For each configuration the batch runner writes:

File Content
results/regular_csv/<case>_results.csv every output of every component, every hour
results/trnsys_csv/<case>_trnsys.csv the HeatTrack KPI columns with TRNSYS names (TIME, T_Air, T_Stage1_Out … T_Water_Ret, Cooling_power_DC, Fan_Power, Chiller_Power, COP_Chiller, Fan_signal, …)

<case> is, for example, ID195_Np1-2_Ns1-2_Np2-6_Mp2-0_Mp3-1_Q6350 (reference cases keep their ID, custom topologies get ID000; Q is the design capacity in kW). Hours that did not converge within the iteration limit are kept, as in TRNSYS, and reported as warnings in the run summary and in the result metadata.


Dataset of the 20 reference configurations

dataset/ contains the hourly results of the 20 reference configurations for a full year: 20 CSV files of 8,760 hours × 26 columns, plus configurations.csv, annual_summary.csv and a data dictionary. The ambient temperature column is left out because it comes from the weather file, which is not redistributed. The data are licensed under CC BY 4.0. See dataset/README.md for column definitions and how to regenerate the files with tools/make_dataset.py.


Validation

All 20 reference configurations were simulated for a full year (8,760 h) in TRNSYS 18 and in HeatTrack-Py with the same weather file and deck settings, and 16 output variables were compared hour by hour:

Quantity Agreement (19 full-precision configurations)
Stage and return temperatures mean absolute error ≤ 1.0 × 10⁻⁴ K
Chiller capacity, load met, chiller power, fan power identical to machine precision
Fan control signal identical in all 175,200 configuration-hours
Annual energy totals largest difference 6.3 × 10⁻⁴ %

The comparison notebook and its tables are in TRNSYS_vs_HeatTrack-Py_comparison/. Re-running it requires the TRNSYS reference results, which are not distributed with this repository. Model derivations, verification status and limitations are documented in documentation/.

Tests

.venv/bin/python -m pip install -e ".[test]"     # or: pip install -r requirements-dev.txt
.venv/bin/python -m pytest

Tests that need the Riyadh weather file are skipped when it is not present; the web back-end tests (tests/backend) run only when the web extra is installed; comparisons against TRNSYS reference files run only when HEATTRACK_REFERENCE_DIR points to the folder that contains their timeseries/ subfolder.


Repository layout

Path Content
heattrack/ the simulation engine (core, components, projects, parser, validation)
run_simulation.py, run_windows.bat, run_mac.command batch runner and launchers
run_parallel.py, plot_parallel.py, run_parallel_* parallel 3DC_4CH model, plots and launchers
CoolingSystem_Topologies.txt, Reference_20_Topologies.txt input files (703 and 20 configurations)
backend/, frontend/, setup_web.*, start_web.*, stop_web.* web interface
Weather/ place for .tm2 weather files (not included, see above)
dataset/ hourly results of the 20 reference configurations (CC BY 4.0)
Prices/, tools/ electricity price files; scripts that build the price files and the 20-configuration dataset (make_dataset.py)
documentation/ equations, numerical validation, known limitations, system reconstruction
TRNSYS_vs_HeatTrack-Py_comparison/ comparison notebook, metric tables and figures
tests/ automated tests (engine, parser, validation, web back end); browser tests in frontend/tests/
pyproject.toml, requirements*.txt package metadata and dependencies

Citing

If you use HeatTrack-Py, please cite the software paper and the version you used (heattrack.__version__; this release is 3.0.0). Citation metadata is also in CITATION.cff.

M. M. Kabir, M. U. Ahmed, S. Barua, S. Begum. HeatTrack-Py: An open Python simulator for hybrid dry-cooler and chiller cooling systems. Submitted to SoftwareX, 2026.

Contact: Md Mohsin Kabir, Mälardalen University (md.mohsin.kabir@mdu.se).

Licence

Copyright 2026 HeatTrack project, Mälardalen University. Licensed under the Apache License, Version 2.0 — see Licence.txt (identical to LICENSE). The data in dataset/ are licensed under CC BY 4.0 (see dataset/LICENSE.txt). Third-party material that is not covered by this licence — the Meteonorm weather file and the TRNSYS reference results (both not included), the sample chiller performance tables used as default chiller data, and the tariff behind the price files — is listed in NOTICE.

Acknowledgements

Developed within the project HeatTrack: Enhanced Reliability, Monitoring, and Diagnostics of Complex Cooling Systems through Advanced Thermal Management (Grant No. 559441–9839), conducted at the RESILIENT Centre, Mälardalen University, Sweden, and funded by the Swedish Energy Agency and Hitachi Energy. We thank Dr. Shia-Hui Peng, Dr. Rebei Bel Fdhila and Dr. Mehrdad Mesgarpour for sharing their domain knowledge and technical expertise.

About

Open Python simulator for hybrid dry-cooler and chiller cooling systems, validated against TRNSYS 18

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages