Entropyk/apps/web/public/docs/components/isentropic-compressor.md

# IsentropicCompressor

Config type: `"IsentropicCompressor"`  
Source: `crates/components/src/isentropic_compressor.rs`

---

## EN

### Purpose & physical model

Vapor-compression compressor for cycle simulation. Two operating families:

| Mode | When | Mass / pressure behaviour |
|------|------|---------------------------|
| **Fixed-pressure** (default) | `emergent_pressure: false` | Pins `P_dis = P_sat(T_cond)`; mass continuity across suction/discharge |
| **Emergent-pressure** | `emergent_pressure: true` | Closes ṁ with a **volumetric displacement law**; `P_dis` floats from the condenser ↔ secondary balance |

True isentropic path via CoolProp: `(P,h)→s` then `(P,s)→h_is`, corrected by isentropic efficiency:

```
h_dis = h_suc + (h_is − h_suc) / η_is,eff
```

Swept mass flow (emergent only):

```
ṁ_calc = ρ_suc · V_s · N · η_vol(P_dis/P_suc) · f_VSD,vol
ṁ      = σ · z_flow · ṁ_calc
```

Volumetric efficiency models:

| Model | Formula |
|-------|---------|
| Constant | `η_vol = const` (default 1.0) |
| Clearance | `η_vol = 1 + C − C · (P_dis/P_suc)^(1/n)` |

Optional **VSD speed map** (quadratic, identity default `[1,0,0]`):

```
f(r) = c0 + c1·r + c2·r² ,  r = N / N_ref ,  clamped ∈ [0.1, 1.2]
η_vol,eff = η_vol · f_vol(r) ;  η_is,eff = η_is · f_is(r)
```

Optional **liquid injection** desuperheat (no extra equation; φ from controls):

```
h_dis,eff = h_dis − φ_inj · (h_dis − h_f(P_dis)) ,  φ_inj ∈ [0, φ_max]
```

Design anchors `t_cond_k`, `t_evap_k`, `superheat_k` are used for fixed-pressure pins and as initial-condition helpers; in emergent mode the live suction `(P,h)` drives the isentropic path.

### Residuals & `n_equations()`

```
n_equations = (2 if same_branch else 3) + (1 if slide_valve active else 0)
```

| Row | Fixed-pressure | Emergent-pressure |
|-----|----------------|-------------------|
| r0 | `P_dis − P_sat(T_cond)` | `ṁ − σ·z_flow·ṁ_calc` |
| r1 | `H_dis − h_dis` | `H_dis − h_dis,eff` |
| r2 | `ṁ_dis − ṁ_suc` (dropped if same-branch) | same |
| r3 | — | (slide) `T_sat(P_suc) − SST_target` |

### Ports

| Index | Role |
|-------|------|
| 0 | suction (inlet) |
| 1 | discharge (outlet) |

Edge-wired via `set_system_context` (CM1.3 ṁ/P/h triples). `get_ports()` may be empty.

### Emergent pressure & actuators

- Requires `displacement_m3` and `speed_hz` when `emergent_pressure: true`.
- **Slide valve** (`slide_valve_sst_target_k` / `_c`): free actuator σ ∈ [σ_min, 1] scales swept volume and holds SST.
- **Liquid injection** (`liquid_injection: true`): φ_inj on the `actuator` / control factor `"injection"`; closing equation from a user `controls[]` loop (e.g. max DGT), not hard-coded.

### Calibration

| Factor | Effect | Default |
|--------|--------|---------|
| `z_flow` | scales swept ṁ (emergent r0) | **1.0** |
| `actuator` | slide σ **or** injection φ | – |

### measure_output / energy_transfers

- `measure_output(Temperature)` → discharge gas temperature (DGT) for injection control.
- `energy_transfers`: `(Q, W) = (0, −ṁ·(h_dis,work − h_suc))` — adiabatic; shaft work negative. With liquid injection, work uses un-desuperheated compression enthalpy.

### JSON parameters

| Key | Meaning | Unit | Default |
|-----|---------|------|---------|
| `isentropic_efficiency` | η_is | – | 0.75 |
| `t_cond_k` | condensing sat. T (fixed pin / design) | K | 323.15 |
| `t_evap_k` | evaporating sat. T (design) | K | 275.15 |
| `superheat_k` | suction superheat design | K | 5.0 |
| `fluid` | refrigerant | – | primary |
| `emergent_pressure` | enable displacement closure | bool | false |
| `displacement_m3` | swept volume V_s | m³/rev | 0.0 |
| `speed_hz` | rotational speed N | rev/s | 0.0 |
| `volumetric_efficiency` | constant η_vol | – | 1.0 |
| `clearance` | clearance ratio C (enables clearance model) | – | – |
| `polytropic_n` | re-expansion exponent | – | 1.1 |
| `vsd_reference_speed_hz` | VSD N_ref (enables map) | rev/s | – |
| `vsd_volumetric_coeffs` | `[c0,c1,c2]` η_vol map | – | [1,0,0] |
| `vsd_isentropic_coeffs` | `[c0,c1,c2]` η_is map | – | [1,0,0] |
| `slide_valve_sst_target_k` / `_c` | slide SST setpoint | K / °C | – |
| `liquid_injection` | enable injection desuperheat | bool | false |
| `slide_position_init` / `min` / `max` | free-actuator bounds | – | 1.0 / 0.1 / 1.0 |

### Notes

Preferred cycle compressor for physics-based machines. For manufacturer AHRI maps use `"Compressor"`; for economized screws use `"ScrewEconomizerCompressor"`.

---

## FR

### But & modèle physique

Compresseur à compression de vapeur. Deux familles de fonctionnement :

| Mode | Quand | Comportement |
|------|-------|--------------|
| **Pression fixée** (défaut) | `emergent_pressure: false` | Impose `P_dis = P_sat(T_cond)` ; continuité de masse |
| **Pression émergente** | `emergent_pressure: true` | Ferme ṁ par une **loi volumétrique** ; `P_dis` flotte via le condenseur |

Chemin isentropique CoolProp + rendement :

```
h_dis = h_suc + (h_is − h_suc) / η_is,eff
```

Débit balayé (émergent) :

```
ṁ_calc = ρ_suc · V_s · N · η_vol(P_dis/P_suc) · f_VSD,vol
ṁ      = σ · z_flow · ṁ_calc
```

Modèles de rendement volumétrique : constant, ou volume mort `η_vol = 1 + C − C·Pr^(1/n)`.  
Carte VSD optionnelle (quadratique, identité `[1,0,0]`).  
Injection liquide optionnelle : `h_dis,eff = h_dis − φ_inj·(h_dis − h_f(P_dis))` (pas d'équation interne).

### Résiduels & `n_equations()`

```
n_equations = (2 si même branche sinon 3) + (1 si tiroir actif)
```

| Ligne | Pression fixée | Pression émergente |
|-------|----------------|--------------------|
| r0 | `P_dis − P_sat(T_cond)` | `ṁ − σ·z_flow·ṁ_calc` |
| r1 | `H_dis − h_dis` | `H_dis − h_dis,eff` |
| r2 | `ṁ_dis − ṁ_suc` (supprimée si même branche) | idem |
| r3 | — | (tiroir) `T_sat(P_suc) − SST_cible` |

### Ports

| Index | Rôle |
|-------|------|
| 0 | aspiration (entrée) |
| 1 | refoulement (sortie) |

Câblage par arêtes (`set_system_context`, triples ṁ/P/h CM1.3).

### Pression émergente & actionneurs

- `displacement_m3` et `speed_hz` obligatoires en mode émergent.
- **Tiroir** (`slide_valve_sst_target_k` / `_c`) : actionneur libre σ pour tenir la SST.
- **Injection liquide** : φ_inj via boucle `controls[]` (ex. DGT max), facteur `"injection"`.

### Calibration

| Facteur | Effet | Défaut |
|---------|-------|--------|
| `z_flow` | échelle le débit balayé | **1.0** |
| `actuator` | position tiroir σ **ou** ratio d'injection φ | – |

### measure_output / energy_transfers

- `Temperature` → température des gaz de refoulement (DGT).
- `(Q, W) = (0, −ṁ·(h_dis,work − h_suc))` — adiabatique ; travail sur le compresseur négatif.

### Paramètres JSON

| Clé | Signification | Unité | Défaut |
|-----|---------------|-------|--------|
| `isentropic_efficiency` | η_is | – | 0.75 |
| `t_cond_k` | T sat. condensation (pin / design) | K | 323.15 |
| `t_evap_k` | T sat. évaporation (design) | K | 275.15 |
| `superheat_k` | surchauffe aspiration design | K | 5.0 |
| `fluid` | fluide frigorigène | – | primaire |
| `emergent_pressure` | active la fermeture volumétrique | bool | false |
| `displacement_m3` | cylindrée V_s | m³/tr | 0.0 |
| `speed_hz` | vitesse N | tr/s | 0.0 |
| `volumetric_efficiency` | η_vol constant | – | 1.0 |
| `clearance` | rapport volume mort C | – | – |
| `polytropic_n` | exposant de détente | – | 1.1 |
| `vsd_reference_speed_hz` | N_ref carte VSD | tr/s | – |
| `vsd_volumetric_coeffs` | `[c0,c1,c2]` carte η_vol | – | [1,0,0] |
| `vsd_isentropic_coeffs` | `[c0,c1,c2]` carte η_is | – | [1,0,0] |
| `slide_valve_sst_target_k` / `_c` | consigne SST tiroir | K / °C | – |
| `liquid_injection` | active la désurchauffe par injection | bool | false |
| `slide_position_init` / `min` / `max` | bornes actionneur libre | – | 1.0 / 0.1 / 1.0 |

### Notes

Compresseur de cycle préféré pour les machines physiques. Cartes fabricant AHRI → `"Compressor"` ; vis économisée → `"ScrewEconomizerCompressor"`.