# IsenthalpicExpansionValve (EXV)

Config types: `"IsenthalpicExpansionValve"`, `"EXV"`  
Source: `crates/components/src/isenthalpic_expansion_valve.rs`

---

## EN

### Purpose & physical model

Isenthalpic expansion (throttling) valve for vapor-compression cycles. Three model families:

| Family | Trigger | Physics |
|--------|---------|---------|
| **A — Fixed pressure** | default | Pins `P_out = P_sat(T_evap)` + isenthalpy |
| **B — Emergent pressure** | `emergent_pressure: true` | Isenthalpy only; low-side P from evaporator |
| **C — Orifice** | `orifice_kv` set | Emergent + physical flow law; **opening is a free DoF** |

Orifice law (arch-6 physical actuator):

```
ṁ = Kv · opening · √(2 · ρ_in · max(P_in − P_out, 0)) ,  opening ∈ [0, 1]
```

`with_orifice(kv)` / JSON `orifice_kv` forces `emergent_pressure = true`.

### Residuals & `n_equations()`

| Mode | same-branch | orifice | n_equations | Residuals |
|------|-------------|---------|-------------|-----------|
| Fixed P | no | no | 3 | r0 `P_out − P_sat(T_evap)`; r1 `h_out − h_in`; r2 `ṁ_out − ṁ_in` |
| Fixed P | yes | no | 2 | r0, r1 |
| Emergent | no | no | 2 | r0 `h_out − h_in`; r1 `ṁ_out − ṁ_in` |
| Emergent | yes | no | 1 | r0 `h_out − h_in` |
| Emergent + orifice | either | yes | +1 | + `ṁ − Kv·opening·√(2·ρ_in·ΔP)` |

Orifice adds **1 equation** and the opening adds **1 unknown** → DoF stays balanced. Pair with a `superheat_regulated` evaporator (drops its SH residual) and a controller on `opening` for regulated superheat.

### Ports

| Edge | Role |
|------|------|
| 0 | inlet (cond → EXV) |
| 1 | outlet (EXV → evap) |

### Emergent pressure

Enabled by `emergent_pressure: true` or automatically by orifice mode. Removes the `P_out = P_sat(T_evap)` pin.

### Calibration / actuators

| Item | Notes |
|------|-------|
| Control factor `"opening"` | maps to `actuator` slot; requires `orifice_kv` |
| Free actuator `{name}__opening` | registered when orifice configured without a loop |
| `z_flow` / `z_dp` | **not** used on this component |

### measure_output / energy_transfers

Not specialized (`energy_transfers` none / adiabatic throttling: Q = W = 0).

### JSON parameters

| Key | Meaning | Unit | Default |
|-----|---------|------|---------|
| `t_evap_k` | target evaporating T for P_sat | K | 275.15 |
| `fluid` | refrigerant | – | primary |
| `emergent_pressure` | drop P_evap pin | bool | false |
| `orifice_kv` | orifice coefficient Kv | m² | – (none ⇒ no orifice) |
| `orifice_opening_init` | initial opening | – | 0.5 |
| `orifice_opening_min` | min bound | – | 0.02 |
| `orifice_opening_max` | max bound | – | 1.0 |

### Notes

Preferred EXV for modern cycle configs. For the older port-object valve with On/Off/Bypass see [expansion-valve.md](./expansion-valve.md).

---

## FR

### But & modèle physique

Détendeur isenthalpique (laminage) pour cycles à compression de vapeur. Trois familles :

| Famille | Déclencheur | Physique |
|---------|-------------|----------|
| **A — Pression fixée** | défaut | Impose `P_out = P_sat(T_evap)` + isenthalpie |
| **B — Pression émergente** | `emergent_pressure: true` | Isenthalpie seule ; P BP par l'évaporateur |
| **C — Orifice** | `orifice_kv` | Émergent + loi de débit ; **ouverture = DoF libre** |

Loi d'orifice :

```
ṁ = Kv · opening · √(2 · ρ_in · max(P_in − P_out, 0)) ,  opening ∈ [0, 1]
```

`orifice_kv` force `emergent_pressure = true`.

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

| Mode | même branche | orifice | n_equations | Résidus |
|------|--------------|---------|-------------|---------|
| P fixe | non | non | 3 | r0 `P_out − P_sat(T_evap)` ; r1 `h_out − h_in` ; r2 `ṁ_out − ṁ_in` |
| P fixe | oui | non | 2 | r0, r1 |
| Émergent | non | non | 2 | r0 `h_out − h_in` ; r1 `ṁ_out − ṁ_in` |
| Émergent | oui | non | 1 | r0 `h_out − h_in` |
| Émergent + orifice | – | oui | +1 | + `ṁ − Kv·opening·√(2·ρ_in·ΔP)` |

L'orifice ajoute **1 équation** et l'ouverture **1 inconnu** → DoF équilibré. Couplé à un évaporateur `superheat_regulated` et un contrôleur sur `opening`, la surchauffe devient régulée.

### Ports

| Arête | Rôle |
|-------|------|
| 0 | entrée (cond → EXV) |
| 1 | sortie (EXV → évap) |

### Pression émergente

Via `emergent_pressure: true` ou automatiquement en mode orifice. Supprime le pin `P_out = P_sat(T_evap)`.

### Calibration / actionneurs

| Élément | Notes |
|---------|-------|
| Facteur `"opening"` | mappe le slot `actuator` ; nécessite `orifice_kv` |
| Actionneur libre `{name}__opening` | si orifice sans boucle |
| `z_flow` / `z_dp` | **non** utilisés |

### measure_output / energy_transfers

Non spécialisés ; laminage adiabatique (Q = W = 0).

### Paramètres JSON

| Clé | Signification | Unité | Défaut |
|-----|---------------|-------|--------|
| `t_evap_k` | T évaporation cible pour P_sat | K | 275.15 |
| `fluid` | frigorigène | – | primaire |
| `emergent_pressure` | supprime le pin P_evap | bool | false |
| `orifice_kv` | coefficient d'orifice Kv | m² | – (aucun ⇒ pas d'orifice) |
| `orifice_opening_init` | ouverture initiale | – | 0.5 |
| `orifice_opening_min` | borne min | – | 0.02 |
| `orifice_opening_max` | borne max | – | 1.0 |

### Notes

EXV préféré pour les configs de cycle modernes. Ancienne vanne port-object → [expansion-valve.md](./expansion-valve.md).
