# Units and internal conventions

Owner: Rods Project Team  
Status: Active  
Last Updated: 2026-04-16  

## Principle

All values passed from `solver-api` to `solver-c` **JSON** are **SI**:

| Quantity | SI unit |
|----------|---------|
| Length | m |
| Force | N |
| Pressure | Pa |
| Mass density | kg/m³ |
| Time | s |
| Angle | rad (stored in JSON as rad; XML may be degrees) |
| SPM | 1/min (dimensionally s⁻¹ scale; kept as `pumping_speed` scalar per stroke period \(T = 60/\text{SPM}\) s) |

## `UnitsSelection` (XML)

`base-case.xml` uses `<UnitsSelection>2</UnitsSelection>` (example). Parser maps:

| Code | Assumption in parser |
|------|----------------------|
| `0` / missing | Field units match legacy **oilfield mixed** inch–ft–lbf where applicable (see below) |
| `2` | **Imperial oilfield** — lengths in **ft**, diameters in **in**, moduli in **Mpsi** (×10⁶ psi), forces in **lbf**, pressures in **psi** |
| Other | Treated like `2` with warning in `parsed.warnings` (`heuristic`) |

### Conversion factors (exact)

- `1 in = 0.0254 m`  
- `1 ft = 0.3048 m`  
- `1 lbf = 4.4482216152605 N`  
- `1 psi = 6894.757293168 Pa`  
- `1 Mpsi = 6.894757293168e9 Pa`  
- `deg → rad`: multiply by \(\pi/180\)

### Fluid density helper

Mixture density from `WaterCut`, `WaterSpecGravity`, `FluidLevelOilGravity` uses simplified API formula for buoyancy; tagged `heuristic` in `model.fluidDensityHeuristic`.

## JSON to C

`SolverInputs` receives only SI. GUI may show field units; API documentation states SI in solve payload.