# ExpansionValve (legacy, port-based)

Config type: `"ExpansionValve"`  
Source: `crates/components/src/expansion_valve.rs`

> Distinct from `IsenthalpicExpansionValve` / `EXV`. Port-object based, with On/Off/Bypass operational states.  
> Distinct de `IsenthalpicExpansionValve` / `EXV`. Basé sur objets Port, avec états On/Off/Bypass.

---

## EN

### Purpose & physical model

2-port isenthalpic throttling valve for refrigeration systems:

```
h_out = h_in     (isenthalpic)
ṁ_out = ṁ_in     (mass continuity, with z_flow scale)
P_out < P_in     (throttling — pressure not closed by a flow law here)
Q = 0, W = 0     (adiabatic, no work)
```

Operational states:

| State | Behaviour |
|-------|-----------|
| **On** | isenthalpy + mass continuity |
| **Off** | zero mass flow (`opening` < 0.01 also forces off) |
| **Bypass** | adiabatic pipe: `P_out = P_in`, `h_out = h_in` |

`opening` does **not** enter the On residual set as a continuous flow coefficient; it only gates `is_effectively_off` below a 1 % threshold. For a free continuous opening + orifice law, use `IsenthalpicExpansionValve` with `orifice_kv`.

### Residuals & `n_equations()`

```
n_equations = 2 (always)
local state: state[0]=ṁ_in, state[1]=ṁ_out
```

| Row | On | Off | Bypass |
|-----|----|-----|--------|
| r0 | `h_out − h_in` | `ṁ_in = 0` | `P_out − P_in` (with isenthalpy pairing) |
| r1 | `ṁ_out − z_flow·ṁ_in` | 0 | `h_out − h_in` |

### Ports

| Role | Description |
|------|-------------|
| inlet | high pressure, typically subcooled liquid |
| outlet | low pressure, typically two-phase |

Type-state: `ExpansionValve<Disconnected>` → `.connect()` → `ExpansionValve<Connected>`.

### Calibration

| Factor | Effect | Default |
|--------|--------|---------|
| `z_flow` | `ṁ_eff = z_flow · ṁ_in` | **1.0** |

`set_calib_indices` supports a dynamic `z_flow` state index.

### Emergent pressure / orifice

**Not available** on this component. Prefer `"IsenthalpicExpansionValve"` / `"EXV"`.

### energy_transfers

`(Q, W) = (0, 0)` always.

### JSON parameters

| Key | Meaning | Unit | Default |
|-----|---------|------|---------|
| `fluid` | refrigerant | – | **required** |
| `opening` | valve position (off if < 0.01) | – | 1.0 |
| `p_inlet_bar` / `h_inlet_kj_kg` | inlet IC | bar / kJ/kg | 12.0 / 260.0 |
| `p_outlet_bar` / `h_outlet_kj_kg` | outlet IC | bar / kJ/kg | 3.5 / 260.0 |

### Known limitations

- Legacy port-based residual path; less integrated with CM1.4 edge ṁ sharing than EXV.
- No emergent-pressure or orifice actuator.
- Production cycles should use `IsenthalpicExpansionValve`.

---

## FR

### But & modèle physique

Vanne de laminage isenthalpique 2-port :

```
h_out = h_in
ṁ_out = ṁ_in   (avec échelle z_flow)
Q = 0, W = 0
```

États opérationnels :

| État | Comportement |
|------|--------------|
| **On** | isenthalpie + continuité de masse |
| **Off** | débit nul (`opening` < 0.01 force aussi l'arrêt) |
| **Bypass** | tube adiabatique : `P_out = P_in`, `h_out = h_in` |

`opening` ne rentre **pas** dans les résidus On comme coefficient de débit continu ; il ne sert qu'au seuil d'arrêt. Pour une ouverture libre + orifice, utiliser `IsenthalpicExpansionValve` avec `orifice_kv`.

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

```
n_equations = 2 (toujours)
état local : state[0]=ṁ_in, state[1]=ṁ_out
```

| Ligne | On | Off | Bypass |
|-------|----|-----|--------|
| r0 | `h_out − h_in` | `ṁ_in = 0` | `P_out − P_in` |
| r1 | `ṁ_out − z_flow·ṁ_in` | 0 | `h_out − h_in` |

### Ports

| Rôle | Description |
|------|-------------|
| entrée | haute pression, liquide sous-refroidi typique |
| sortie | basse pression, biphasique typique |

Typestate : `Disconnected` → `.connect()` → `Connected`.

### Calibration

| Facteur | Effet | Défaut |
|---------|-------|--------|
| `z_flow` | `ṁ_eff = z_flow · ṁ_in` | **1.0** |

### Pression émergente / orifice

**Non disponibles.** Préférer `"IsenthalpicExpansionValve"` / `"EXV"`.

### energy_transfers

`(Q, W) = (0, 0)` toujours.

### Paramètres JSON

| Clé | Signification | Unité | Défaut |
|-----|---------------|-------|--------|
| `fluid` | frigorigène | – | **requis** |
| `opening` | position (off si < 0.01) | – | 1.0 |
| `p_inlet_bar` / `h_inlet_kj_kg` | CI entrée | bar / kJ/kg | 12.0 / 260.0 |
| `p_outlet_bar` / `h_outlet_kj_kg` | CI sortie | bar / kJ/kg | 3.5 / 260.0 |

### Limites connues

- Chemin legacy port-object, moins intégré au partage ṁ CM1.4 que l'EXV.
- Pas de pression émergente ni d'actionneur orifice.
- Les cycles de production doivent utiliser `IsenthalpicExpansionValve`.