General Concepts — Diagnostic Studio

Connection & Purpose

This laboratory does not replace the backend:

It acts as an interactive panel over the SaaS deployed at https://saas-api-hvac.vercel.app. Every action you perform here fires a real request to the backend and shows you, step by step, what is happening inside the thermodynamic engine.

While local presets exist in this UI for testing convenience, all diagnostic results, thermodynamic thresholds, and evaluation rules belong strictly to the backend. The UI only visualizes the API's decisions.

System Capacity

Active faults cataloged

Symptoms

Refrigerants

Pipeline stages

kNN dimensions

Fault breakdown: 12 generic · 11 air-water cooling · 16 air-water heating · 15 air-air cooling · 15 air-air heating
Symptoms breakdown: 20 instantaneous · 14 trend-based

What Problems Does the SaaS Solve?

Detects physically impossible or suspicious readings before trusting them.
Converts temperatures and pressures into useful HVAC indicators: SH, SC, CR, and approaches.
Differentiates symptoms from faults: a high SH is a signal, not a conclusion by itself.
Identifies problems with refrigerant, condenser, evaporator, EEV, compressor, water circuit, sensors, and defrost.
Avoids false alarms from noise through persistence and temporal trends.
Compares the real system with ideal behavior using the digital twin.
Combines physical rules, thermodynamic deviation, and SH/SC signature to rank hypotheses.
Allows reviewing historical batches to find persistently recurring faults.
Uses a kNN classifier as a secondary opinion that can improve with real samples and technician feedback.
Produces a PDF report to communicate system status and recommended actions.

Pipeline & Stages

The diagnostic process follows a strictly ordered pipeline, progressively transforming raw sensor data into actionable fault diagnoses.

Validation

Checks physical ranges and coherence of raw readings

IN: RawReadings

OUT: ValidationIssue[]

Feature extraction

Derives saturation temperatures, SH, SC, CR, approaches and compressor state

IN: RawReadings + DiagnosticContext

OUT: CircuitFeatures + DerivedFeatures

Symptoms

Transforms numeric features into logical signals using mode/equipment thresholds

IN: CircuitFeatures + Thresholds

OUT: Symptom[]

Rules & persistence

Matches symptoms against 73 fault definitions and filters transient detections

IN: Symptom[] + FaultDefinitions

OUT: ActiveFault[] (confirmed + candidates)

Digital twin

Estimates ideal cycle, isentropic efficiency and deviations from ideal values

IN: CircuitFeatures + RefrigerantProperties

OUT: TwinAnalysis (η, deviations, scores)

Signature map

Classifies the SH×SC operating point into a fault region with a confidence score

IN: CircuitFeatures (SH, SC, CR, approach)

OUT: SignatureResult (region + score)

Probability & ML

Combines rule confidence (40%), twin deviation (35%) and signature match (25%). Consults kNN as secondary opinion.

IN: ActiveFault[] + DeviationScores + SignatureResult

OUT: FaultProbability[] (primary + secondary)

Result

Derives system status, includes liquidTemp simulation if missing, and assembles the final response

IN: All previous outputs

OUT: DiagnosticResult (JSON or PDF)

Thermodynamics Core

The engine doesn't decide by looking at a single temperature. It summarizes circuit state using SH, SC, and CR.

SH (Superheat)

Difference between actual suction temperature and saturation temperature at suction pressure. Shows how much the vapor heated after evaporating.

SC (Subcooling)

Difference between condensation saturation temperature and liquid line temperature. Shows how much the liquid cooled after condensing.

CR (Compression Ratio)

Ratio between absolute discharge pressure and absolute suction pressure. Indicates compression effort.

The Math Under the Hood

1. Absolute Pressure Conversion

Gauges measure relative to atmosphere, but thermodynamics require absolute pressure.

P_abs = P_gauge + 1.013 bar

2. Saturation Temperature (Antoine-like Equation)

T_sat = A2 / (ln(P_abs) - A1) - A3

Step-by-step Example

Suction: 8.4 bar gauge → P_abs = 9.413 bar → evapSatTemp via Antoine → SH = suctionTemp - evapSatTemp
Discharge: 22 bar gauge → P_abs = 23.013 bar → condSatTemp via Antoine → SC = condSatTemp - liquidTemp

Other Derived Features & Compressor Evaluation

The engine also calculates discharge superheat, evaporator approach, and condenser approach. The formulas change depending on the operating mode and equipment type.

Isentropic Efficiency (η)

Ideal isentropic discharge temp from suction temp, CR, and κ
Approximate enthalpies with Cp and base values per refrigerant
η_isentropic = (h2s - h1) / (h2 - h1)

Low efficiency + large temp deviation suggests degradation, but show as evidence not replacement for mechanical testing.

Digital Twin & Deviation Engine

The "digital twin" here isn't a 3D model. It's a mathematical model of how the circuit should behave under the same pressures and suction temperature if compression were ideal.

How it works

Receives real sensor readings.
Estimates ideal discharge temperature.
Calculates suction and discharge vapor enthalpy.
Obtains isentropic efficiency.
Ideal values: SH 8 K, SC 5 K, condenser approach 8 K.
Calculates Deviation = real - ideal.

DeviationEngine Scorer

Normalizes deviations:

Score = 1 - exp(-|Δ|/σ)

σ values: discharge 15K, SH 6K, SC 5K, approach 8K
Global weighted score: discharge 35%, SH 30%, SC 20%, approach 15%

Signature Map Regions

SH on X-axis, SC on Y-axis. Evaluation order matters — a higher-priority condition (like floodback or flash gas) can win even when another condition also seems applicable. The score from mapScore is NOT directly the final fault probability.

SH_LOW = 4SH_HIGH = 14SC_LOW = 2SC_HIGH = 10

Code	Label	Condition	Score Formula
NORMAL	Normal	4–14 / 2–10	No abnormal condition detected
LOW_CHARGE	Low charge	> 14 / < 2	High SH with low SC suggests refrigerant undercharge or leak
OVERCHARGE	Overcharge	< 4 / > 10	Low SH with high SC suggests refrigerant overcharge
RESTRICTION	Liquid line restriction	> 14 / > 10	High SH and high SC suggests restriction in liquid line or TXV
DIRTY_CONDENSER	Dirty condenser	< 4 / normal	Low SH without other conditions suggests reduced condenser heat rejection
EVAPORATOR_AIRFLOW	Evaporator airflow	> 14 / 2–10	High SH with normal SC suggests poor evaporator airflow or dirty filters
COMPRESSOR_WEAK	Compressor weak	< 4 / low CR < 1.8	Low SH with low CR suggests valve leak or mechanical wear
FLASH_GAS	Flash gas	> 14 / < 1	Very high SH with very low SC suggests premature evaporation in liquid line
FLOODBACK	Floodback	≤ 1 / discharge SH < 8	Very low SH with low discharge SH suggests liquid reaching compressor
NON_CONDENSABLES	Non-condensables	any / > 10 & approach > 15	High SC with high condenser approach suggests trapped air or nitrogen
UNKNOWN	Unknown	— / —	Compressor inactive; classification not possible

Machine Learning (kNN)

kNN Classifier

6D vector: SH, SC, CR, dischargeSH, evapApproach, condApproach
k=5 neighbors, euclidean distance, inverse-distance weighted voting
Zero distance gets weight 1000
Confidence = winning label weight / total weight

The Data Cycle

Synthetic samples: base profiles with Gaussian noise for initial reference
Upload: POST /train/upload validates, computes vector, stores in training_samples
Retrain: POST /train/retrain replaces classifier with DB samples + optional 30 synthetic
Evaluate: tests a reading without storing
Feedback: technician provides real label and features

WarningsUploading doesn't retrain automatically, deleting samples is irreversible, restarting the process may lose the in-memory model.

Trend Tracking

The TrendTracker identifies slow changes over time rather than instant threshold breaches.

Non-inverter only: no RPS, must have compressorStatus1
With two compressor statuses, all must be running
Minimum 3 readings required
Compares first vs last reading in buffer
Emits RISING or FALLING if difference exceeds threshold
Compressor shutdown clears the buffer

Tracks:

thermalGap
suction/discharge pressures
suction/discharge temps
suction/discharge SH

Differentiate:

"not enough readings yet"
"no trend detected"
"trends detected"

Fault Catalog Overview

FaultDefinition structure: id, label, requiredSymptoms, optionalSymptoms, severity, description, action, applicableModes, applicableEquipment.

View full catalog →

Generic / system faults12

Air-Water cooling11

Air-Water heating16

Air-Air cooling15

Air-Air heating15

Glossary of Fields

Warn that externalTemp, pressures and core temperatures are conceptual minimums even though the HTTP middleware isn't currently validating them.

Field	Meaning	Unit	Req?	Effect if missing
Core Parameters (5 required)
refrigerant	Refrigerant code	Enum	Y	Request rejected
Pressures & Temps
suctionPressure	Low side pressure	bar	N	Cannot compute SH

Supported Refrigerants

Code	Description	Glide	GWP	Safety	Pressure range (gauge)	Applications	Warning
R32	Difluoromethane	No	675	A2L	4.5–40 bar	Residential and commercial split systems, VRF	Mildly flammable (A2L). Requires leak detection and ventilation per local codes.
R410a	R32/R125 blend	0.1K	2088	A1	4.5–40 bar	Residential and commercial AC, heat pumps (legacy)	Non-flammable (A1) but high GWP. Being phased down under F-gas regulations.
R454c	R32/R1234yf blend	7.4K	148	A2L	2.5–32 bar	Next-generation residential AC and heat pumps	Mildly flammable (A2L). Temperature glide of 7.4 K requires careful system design.
R290	Propane	No	3	A3	2.5–32 bar	Small commercial refrigeration, monobloc heat pumps	Highly flammable (A3). Strict charge limits and ignition source control required.
R407c	R32/R125/R134a blend	5.9K	1774	A1	2.5–32 bar	Commercial AC retrofit, chillers	Non-flammable (A1) but high GWP. Zeotropic blend with significant temperature glide.