Cascade Heat Pump Thermodynamic Calculation & Optimization Platform

复叠式高温热泵系统热力计算与寻优平台

A web-based platform for thermodynamic cycle calculation and optimization of cascade heat pump systems used in large temperature-lift industrial waste heat recovery. The system performs parametric optimization over intermediate condensing temperature to maximize the overall COP (Coefficient of Performance), and generates publication-quality P-h diagrams and performance curves suitable for SCI journal submissions.

Live Demo: https://cascade.aqeo.dev

---

Features

Thermodynamic Engine

• 27 refrigerants supported via CoolProp — including HFCs (R134a, R245fa), HFOs (R1234yf, R1234ze(E)), natural refrigerants (R717, R290, R744, Water), and hydrocarbons (n-Pentane, CycloPentane, etc.)
• Parametric sweep optimization over intermediate condensing temperature with configurable bounds and step size
• Strict energy balance at the intermediate heat exchanger — high/low stage mass flows are thermodynamically coupled, not independently assumed
• Full 4-point vapor-compression cycle calculation per stage (superheat, isentropic + actual compression, subcooling, throttling)

12 Configurable Parameters (Zero Hardcode)

Parameter	Default	Unit
Heating load	400	kW
High-stage refrigerant	R245fa	—
Low-stage refrigerant	R134a	—
Condensing temperature (high)	140	°C
Evaporating temperature (low)	40	°C
Intermediate HX temperature difference	5	°C
Compressor isentropic efficiency	0.8	—
Superheat degree	5	°C
Subcooling degree	5	°C
Optimization T_mid lower bound	70	°C
Optimization T_mid upper bound	100	°C
Optimization step size	1	°C

Publication-Quality Visualization (Plotly.js)

• P-h diagrams — saturation dome (dense 500-point sampling near critical point), cycle polygon with state markers, process annotations, log-scale pressure axis
• COP optimization curve — total/high-stage/low-stage COP vs. intermediate temperature, optimal point highlighted with star marker
• Academic styling — Times New Roman font, inward-facing tick marks, high-contrast black/white color scheme, clean legends
• Export — one-click SVG and PDF download for direct insertion into LaTeX or Word manuscripts

Detailed Results Output

• System-level summary cards (optimal T_mid, total COP, total compressor work, intermediate heat exchange rate)
• Per-stage breakdown (refrigerant, mass flow rate, compressor power, COP)
• Full state-point tables with T, P, h, s, and phase identification for all 8 thermodynamic states

---

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI 0.115, Pydantic v2, CoolProp 6.6, NumPy
Frontend	Vue 3.5 (Composition API + <script setup>), Vite 6, Tailwind CSS 3.4, Plotly.js 2.35, Axios
Deployment	Docker Compose, Nginx (frontend reverse proxy), Uvicorn (ASGI), Caddy + Cloudflare Tunnel

---

Project Structure

cascade/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI endpoints (/api/health, /api/refrigerants, /api/calculate)
│   │   ├── models.py         # Pydantic v2 request/response schemas
│   │   └── solver.py         # CoolProp-based thermodynamic solver & optimizer
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.vue           # Main layout — sidebar form + tabbed results
│   │   ├── api/index.js      # Axios HTTP client
│   │   └── components/
│   │       ├── InputForm.vue  # 12-parameter dynamic input form
│   │       ├── ResultCards.vue # Summary metric cards
│   │       ├── StateTable.vue  # Thermodynamic state-point tables
│   │       ├── PhDiagram.vue   # Pressure-enthalpy diagram (Plotly)
│   │       └── CopCurve.vue    # COP optimization curve (Plotly)
│   ├── nginx.conf
│   ├── package.json
│   └── Dockerfile
├── caddy/
│   └── cascade.caddyfile      # Caddy reverse proxy snippet
├── docker-compose.yml
├── deploy.sh
└── README.md

---

Quick Start

Prerequisites

• Docker Engine 20+
• Docker Compose v2

Local Development

# Clone
git clone git@github.com:SinclairChao/cascade.git
cd cascade

# Start services
docker compose up -d --build

# Access at http://localhost:18880

The frontend Nginx container proxies /api/* requests to the backend FastAPI container automatically.

Local Development (without Docker)

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

---

API Reference

GET /api/health

Health check endpoint.

{ "status": "ok" }

GET /api/refrigerants

Returns the list of supported refrigerants with display names.

{
  "refrigerants": [
    { "value": "R134a", "label": "R134a (1,1,1,2-四氟乙烷)" },
    { "value": "R245fa", "label": "R245fa (1,1,1,3,3-五氟丙烷)" },
    ...
  ]
}

POST /api/calculate

Main calculation endpoint. Accepts all 12 parameters (all optional, defaults applied).

Request body:

{
  "heating_load": 400,
  "high_ref": "R245fa",
  "low_ref": "R134a",
  "t_cond_high": 140,
  "t_evap_low": 40,
  "dt_intermediate": 5,
  "eta_is": 0.8,
  "dt_superheat": 5,
  "dt_subcool": 5,
  "t_mid_min": 70,
  "t_mid_max": 100,
  "t_mid_step": 1
}

Response: CascadeOutput — includes optimal intermediate temperature, total COP, per-stage results with all state points, saturation curve data for P-h plotting, and full optimization curve data.

---

Deployment (Production)

The application is deployed on an Ubuntu 24.04 server behind Caddy + Cloudflare Tunnel.

Architecture

Internet → Cloudflare Tunnel → Caddy (:20615) → Nginx (:18880) → { Vue SPA, FastAPI }

Deploy Steps

# SSH into server
ssh shihan-aqeo

# First-time setup
cd ~ && git clone git@github.com:SinclairChao/cascade.git
cd cascade && bash deploy.sh

# Subsequent deploys
cd ~/cascade && git pull && docker compose up -d --build

Caddy Configuration

The Caddy snippet for cascade.aqeo.dev is provided in caddy/cascade.caddyfile. Append its contents to /etc/caddy/Caddyfile and reload:

sudo systemctl reload caddy

Docker Services

Service	Internal Port	Exposed Port	Image Base
backend	8000	(internal only)	Python 3.12-slim + CoolProp
frontend	80	127.0.0.1:18880	Nginx Alpine

---

Thermodynamic Model

System Description

A cascade heat pump consists of two vapor-compression cycles thermally coupled through an intermediate heat exchanger:

                    ┌─────────────────────┐
                    │   High-Temp Stage    │
   Q_H (heating)   │  (e.g., R245fa)     │
   ←────────────────┤                     │
                    │   Comp → Cond →     │
                    │   Throttle → Evap   │
                    └────────┬────────────┘
                             │ Q_intermediate
                    ┌────────┴────────────┐
                    │   Low-Temp Stage     │
                    │  (e.g., R134a)      │
   Q_L (waste heat) │                     │
   ────────────────→┤   Comp → Cond →     │
                    │   Throttle → Evap   │
                    └─────────────────────┘

Optimization Algorithm

1. Sweep intermediate condensing temperature T_mid from t_mid_min to t_mid_max with t_mid_step increments
2. For each T_mid:
   • High stage condenses at t_cond_high, evaporates at T_mid - dt_intermediate; mass flow sized by heating load Q_H
   • Low stage condenses at T_mid, evaporates at t_evap_low; mass flow sized by energy balance: Q_cond_low = Q_evap_high
3. System COP = Q_H / (W_high + W_low)
4. Return T_mid that maximizes total COP

State Points (per stage)

Point	Location	Process
1	Compressor inlet	Superheated vapor (evap temp + superheat)
2	Compressor outlet	Actual discharge (via isentropic efficiency)
3	Condenser outlet	Subcooled liquid (cond temp - subcooling)
4	Expansion valve outlet	Two-phase mixture (isenthalpic throttling)

---

License

MIT

---

Acknowledgments

• CoolProp — Open-source thermophysical property library
• Plotly.js — Interactive scientific charting
• FastAPI — High-performance Python web framework