An open, curated library of thermodynamic and energy-system models written in the EES language, documented, verified and ready to run in CoolSolve — the open-source, EES-compatible equation solver built on CoolProp.
Status: the library is being bootstrapped. The methodology, structure and tooling are in place and the first model is in; models are added one by one following the roadmap. Open the dashboard
library.htmlto browse the current content.
Decades of teaching and research in thermodynamics produced hundreds of equation-based models — exercises, component models, cycles, research case studies — scattered over personal folders, course websites and software libraries, often redundant, in several languages and for proprietary tools. This library gathers them in one place and makes them:
- organised — a flexible taxonomy (by physical system) with facets for the model kind, complexity level and CoolSolve status;
- harmonised — EES language, SI units (°C, Pa, J), English comments, a standard header and a standard README for every model;
- verified — each import is compared with the results of the original tool (e.g. the solution stored in the EES file) and every runnable model has a regression baseline;
- attributed — every model states its source, authors, link and license;
- built into CoolSolve — each CoolSolve build fetches the latest library
(the
mainbranch of this repository) and embeds it: the Library button of the GUI follows the taxonomy and opens a whole model folder in one click (verified models), and the dashboard served at/library/lists every model, blocked ones included, each with an Open in CoolSolve link. Any model imports the functions and procedures of a library model with$INCLUDE <name>(e.g.$INCLUDE hx_ees_functionfor the EESHXfunction; the Library menu and each model page have a button that copies the line), see CoolSolve support.
The library covers the whole range from introductory exercises to research-grade models, and steady-state, dynamic, optimisation and function-library models — each clearly labelled.
CoolSolve_Library/
├── models/ one folder per model, organised by category (see below)
├── sources/ inventories of the source collections (the backlog)
├── docs/
│ ├── taxonomy.md categories, kinds, complexity levels, status, naming rules
│ └── model_workflow.md how models are triaged, imported, verified and documented
├── templates/model/ README, model.json and .eescode header templates
├── tools/
│ ├── build_index.py validates the library, regenerates the index files
│ ├── library_dashboard.html template of library.html
│ ├── move_model.py moves/renames models by ID (taxonomy changes: git mv,
│ │ previous_paths, link rewrites, new categories, rebuild)
│ └── test_models.py solves the models with CoolSolve, compares with baselines
├── taxonomy.json declared categories (machine-readable)
├── library.html dashboard: models, functions, gaps (generated)
├── library.json the index, read by CoolSolve (generated)
├── redirects.csv old paths of moved/renamed models (generated)
└── roadmap.md work programme and progress log
Categories (taxonomy v0.3, 12 top categories, 57 subcategories of 2–7 models, see docs/taxonomy.md):
models/
├── fundamentals/ properties · property_libraries · tanks_vessels ·
│ piston_cylinders · steady_flow · second_law · combustion
├── heat_transfer/ conduction_radiation · internal_convection ·
│ external_convection · natural_convection · two_phase ·
│ pressure_drop
├── heat_exchangers/ methods · effectiveness_lmtd · plate · zoned_discretised ·
│ condensers_evaporators
├── machines/ reciprocating_compressors · rotary_compressors ·
│ compressor_maps · turbocompressors · turbomachine_design ·
│ steam_turbines · expanders · pumps · fans
├── components/ boilers_burners · nozzles_ejectors · piping_valves · storage
├── power_cycles/ steam_basic · steam_advanced · orc_design ·
│ orc_applications · gas_turbine_design ·
│ gas_turbine_offdesign · jet_propulsion ·
│ supercritical_combined
├── engines/ air_standard_cycles · engine_models · sizing · performance
├── refrigeration_heat_pumps/
│ refrigeration_cycles · refrigeration_systems · absorption ·
│ heat_pump_cycles · heat_pump_systems · high_temperature
├── hvac/ psychrometrics · cooling_coils · air_handling ·
│ cooling_towers · evaporative_coolers
├── buildings/ zone models · greenhouses
├── renewables/
└── energy_systems/
The taxonomy can evolve: models are identified by a permanent ID (CSL-0001),
never by their path, and all index files are regenerated from the folders, so
categories can be split, renamed or re-organised without breaking references.
Every model README starts with three badges:
| Complexity level | Kind | Status in CoolSolve |
|---|---|---|
| 🟢 Level 1 · Introductory — first courses, textbook exercises | ⚙️ Steady-state — algebraic, one operating point | ✅ Verified — runs in CoolSolve and its results were checked; the verification field of each model says how (agreement with an EES file, a re-run of the source code, a publication, balance and plausibility checks…) |
| 🔵 Level 2 · Intermediate — complete cycles, components with correlations | ⏱️ Dynamic — time integration (INTEGRAL) |
|
| 🟠 Level 3 · Advanced — semi-empirical, multi-zone, off-design | 🎯 Optimisation — needs Min/Max (not yet in CoolSolve) | |
| 🔴 Level 4 · Research — calibrated, large research models | 🧩 Function library — reusable functions/procedures | ⛔ Blocked — needs a missing CoolSolve feature · ❌ Failing · 📄 Documented only |
Levels 1–2 form the educational part of the library, levels 3–4 the engineering and research part. The rating rubric is in docs/taxonomy.md §3.
Each model folder is a self-contained CoolSolve project:
| File | Content |
|---|---|
README.md |
Description, problem statement, model equations, how to run, results (tables and a diagram or plot), verification, source and attribution, conversion log, limitations |
model.json |
Metadata: ID, title, kind, level, status, fluids, tags, origin (source, authors, link, license), verification (how the results were checked), CoolSolve gaps |
<name>.eescode |
The model in EES language, starting with a commented introduction and with English comments on the equations |
<name>.initials, coolsolve.conf, <name>-<table>.csv |
Guess values, solver settings, lookup tables (when needed) |
<name>.sol |
CoolSolve solution, also used as regression baseline |
<name>_<variant>.eescode (+ .sol) |
Variants; for a blocked model, <name>_coolsolve.eescode is the verified runnable variant of the native file; each variant with a .sol is regression-tested |
figures/ |
Thermodynamic diagram or plot made with CoolSolve, shown in the README |
Pick the model in the Library menu of the CoolSolve GUI (the whole folder is
loaded: initial values, tables, configuration), open <name>.eescode from a
checkout (companion files are picked up automatically), or run
coolsolve ./<name>.eescode.
The model.json of each model folder is the single source of truth.
tools/build_index.py derives two files from them — never edit them by hand:
library.html, the dashboard (open it in a browser, it works from disk; CoolSolve serves the same page at/library/and then adds an Open in CoolSolve button — and one per variant file — to every model, and shows the README in its documentation viewer). Its landing page, Explore, follows the taxonomy and themodels/folders: one section per category, one card per subcategory with its models, and links to the table. The other views are sortable and filterable tables of the models (ID, title, category, kind, level, status, fluids, size, verification), of every function and procedure of the library (to find reusable building blocks), and of the CoolSolve gaps with the models they block; every view and filter has its own address (library.html#/models?category=components/storage&status=blocked,library.html#CSL-0012), so links can be shared. A click on a model shows its summary, origin, verification, functions, related models, links to its README, and — for a blocked model — the description of each gap, taken from the CoolSolve register (../CoolSolve/docs/model_library_support.md, or--register PATH);library.json, the same index for tools and for CoolSolve, which embeds the library at compile time. Its files must be regenerated and pushed for CoolSolve to see a change: the allow-list of what CoolSolve embeds isEMBED_FILESintools/build_index.py(mirrored in CoolSolve'scmake/embed_library.cmake; the CoolSolve build warns when the file counts differ).
| Source | Content | Inventory |
|---|---|---|
| ULiège thermodynamics collection (S. Quoilin) | 552 EES files (incl. archived copies), 341 distinct models after de-duplication: teaching (applied thermodynamics, thermal machines, internal-combustion engines, HVAC) and research/reference models (ORC, heat pumps, components, ULiège model bank, Laborelec toolkit), 2002–2023 | sources/thermo_models |
| CoolSolve examples | 47 models of the CoolSolve test suite (they stay in CoolSolve and are classified here) — MIT | sources/coolsolve_examples |
| LaboThapPy | 74 candidates: Python components, correlations and cycles of the ULiège/UCLouvain/UMONS thermodynamics labs — Apache-2.0 | sources/labothappy |
| TESPy | 52 candidates: component equations, tutorials and validated example plants (CGAM, SEGS, sCO2…) — MIT | sources/tespy |
| ThermoCycle | Modelica library of the ULiège Thermodynamics Laboratory (665 files, mostly dynamic): 7 steady-state candidates kept — solar collector receiver and loss correlations, empirical expander/pump maps, flow-boiling and in-cylinder heat-transfer correlations — MIT | sources/thermocycle |
Source files are not copied into the library: each model references its
source by path, URL or library name, and credits the authors of the original
model (README and model.json). Models translated from other libraries are
published under the library license with full credits to the original
authors.
Read the model workflow and pick a task from the
roadmap. Importing an EES file relies on the CoolSolve tools
tools/ees_extract.py and tools/compare_solution.py, documented in
CoolSolve docs/ees_import.md.
Before committing, run:
python3 tools/build_index.py
python3 tools/backlog_stats.py # inventories well-formed
python3 tools/test_models.py --coolsolve ../CoolSolve/build/coolsolve # main files and variantsCoolSolve aims to read native EES code: when a model needs a feature CoolSolve lacks, the model keeps its EES syntax (a runnable variant may ship beside it) and the gap is reported in the CoolSolve gap register.
MIT. Models translated or adapted from third-party sources credit
the authors of the original models in their README and model.json.
Maintainer: Sylvain Quoilin — ISES Research Group, Université de Liège.