# PyTES model contract (Stage B)

Status: **Stage B** (closed 2026-10-16). Changes from here on are logged in `findings.md`;
the contract is frozen at v1.0 (Stage E, DESIGN §5). The executable form is
`src/pytes/conformance.py`, run over every model by `tests/conformance/`. **Where this page
and the tests disagree, the tests win.**

## 1. What a model is

- A `pytes.BaseModel` subclass (itself a `pybamm.BaseModel`). PyBaMM tools apply directly:
  `pybamm.Simulation`, solvers, `QuickPlot`, PyBOP.
- A **fixed composition** of submodels in `model.submodels` (an ordered dict), shown by
  `model.print_submodel_info()`. Users call models; advanced users may build their own from
  submodels with `pytes.ComposedModel` (same wiring checks; not admitted, DESIGN D1).
- It belongs to a family (today: `finned_tube` and `packed_bed`) and passes the conformance
  suite, with every combination of its options (`allowed_options`; today `"storage along
  flow path": "resolved" | "averaged"` in every model; `"heat transfer coefficient":
  "constant" | "Gnielinski"` in the finned tube, `"constant" | "Wakao-Kaguei"` in the
  packed bed, plus any correlation registered for the model's flow with
  `register_correlation`; and in the packed bed `"storage element": "resolved" | "lumped"
  | "lumped with Jeffreson"`). Unknown options or values raise `pytes.OptionError`.

## 2. Submodels

A submodel is a small `pybamm.BaseModel` (`pytes.submodels.BaseSubModel`). PyBaMM's own
`BaseSubModel` is not used: it assumes battery domains and options. In `build()` a submodel
sets its own `variables`, `rhs`, `algebraic`, `boundary_conditions`, `initial_conditions`
and `events`, and reads any variable set by another submodel as a
`pybamm.CoupledVariable` (through `self.coupled(name, domain)`), never by reaching into
that submodel. A storage submodel sets all its own boundary conditions; couplings provide
the value it applies (a heat flux into it, or a temperature).

Metadata, on every submodel, read from the code rather than declared separately:

| Attribute | Meaning |
|---|---|
| `requires` | Names of its coupled variables (PyBaMM's `coupled_variables`) |
| `provides` | Names of its `variables` |
| `parameters` | Names of the parameters in its equations, conditions, variables and state scales |
| `assumptions` | One sentence each, declared, for model cards (rendering deferred) |

On the model: `geometry_parameters`, the parameters of its default geometry (domain
lengths), and `print_submodel_info()`, which shows all of the above. Every parameter of a
model's default set belongs to a submodel or to the geometry, except declared hooks
(tested).

The model merges the submodels with `pybamm.BaseModel.update` and checks the wiring
(`WiringError` otherwise): each required name is provided by exactly one submodel; no
variable depends on itself through coupled variables; after resolution, each provided
variable is on the primary domain its coupled variable declares; no two submodels set
equations or conditions for the same variable. It then resolves every coupled variable
(`pytes.compat.resolve_coupled_variables`), so the finished model contains none and works
with a default `pybamm.Simulation`.

### Domains (DESIGN D12)

- `"flow path"`, coordinate `z`: along the flow, from the inlet; every family.
- `"storage depth"`, coordinate `y`: distance into the storage from the heat-exchange wall,
  **not along the flow** (finned tube; cylindrical around a tube).
- `"fin gap"`, coordinate `x`: across the gap between two resolved fins (mush model).
- `"capsule"`, coordinate `r`: from a capsule's centre (packed bed; spherical).

A storage resolved along the flow path has `"flow path"` as its last secondary domain; an
averaged one (`"storage along flow path": "averaged"`) does not. A lumped storage element
(`"storage element": "lumped"` or `"lumped with Jeffreson"`, packed bed) has no domain of its own: its variables are on
`"flow path"`, or on none when it is also averaged.

### Slots (DESIGN D5)

| Slot | Contract | Current submodels |
|---|---|---|
| Fluid | State: fluid specific enthalpy `"Heat transfer fluid specific enthalpy [J.kg-1]"` on domain `"flow path"`, coordinate `z`; its temperature is `T(h)` from the fluid-property object. Requires `"Heat transfer fluid heat gain per unit length [W.m-1]"` (per flow path) and the initial temperature. Provides the fluid enthalpy and temperature, the inlet/outlet temperatures and specific enthalpies (outlet temperature `T(h_out)`), the mass flow rate and its thermal energy. Its spatial method on `"flow path"` is `compat.fluid_spatial_method()`. | `AdvectedFluid` |
| Storage | Enthalpy method, one submodel for every medium (phase-change or sensible, D5); state list `[H, *material.internal_states]`. Geometry switch = coordinate system of its primary domain. Sets zero flux on its outer side and, on its inner side, applies `"<label> boundary heat flux [W.m-2]"` (into the storage) or `"<label> boundary temperature [K]"`; optionally a volumetric `"<label> heat source [W.m-3]"`. Provides its enthalpy, `dH/dt`, its conduction heating rate `div(k grad T)` (`"<label> conduction heating rate [W.m-3]"`), temperature, surface temperature and thermal energy, its conductivity `"<label> thermal conductivity [W.m-1.K-1]"`; and, for a phase-change material only, the liquid fraction. A lumped storage (issue #5) has one enthalpy per storage element, `dH/dt = (S / V) q` with `q` the boundary heat flux and `S / V` the element's surface over its volume, and provides the same variables, its conduction heating rate being `(S / V) q` and its surface temperature its temperature. | `EnthalpyStorage` (PCM, composite, fin metal, PCM capsule), `LumpedStorage` (lumped PCM capsule) |
| Coupling | Joins fluid to storage or storage to storage. Given the states on both sides: provides the heat gain per unit length (fluid side) and the storage's boundary heat flux or temperature, or a heat source. Every coupling is a ledger (D6): the heat crossing the interface is minus the integral of a storage side's conduction heating rate. The heat flux across a fluid-storage surface comes from a replaceable surface flux law (`SurfaceFluxLaw.heat_flux(fluid, fluid_state, T_s)`, `fluid_state` a `FluidState` with `h`, `T`, `mass_flow_rate` (device), `p` (reserved), positive into the storage); default `NewtonCooling`, `"Heat transfer coefficient [W.m-2.K-1]"` times `fluid_state.T - T_s`; a law's geometry goes to its constructor. Flow-dependent laws are `NusseltCorrelation`s (`Gnielinski`, `WakaoKaguei`, F-049), with no parameters of their own. The coupling also provides the law's own variables, `SurfaceFluxLaw.variables(fluid, fluid_state)` (none by default), and requires those the law reads, `SurfaceFluxLaw.coupled_variables` (none by default; F-051). `Jeffreson` corrects a Newton law for the conduction inside a lumped sphere, reading the storage's conductivity. | `WallCoupling`, `FinRootCoupling` (a `WallCoupling` with flux factor `d_m / d_c`), `FinStorageCoupling` (a storage between fins, phase change or not); formerly `LedgerWallCoupling` and `FinPCMCoupling`, which warn until 0.2.0 (F-054) |
| Device energy | Power, energies, initial state. | `DeviceEnergy` |

## 3. Variables (DESIGN D12)

**Required** (`pytes.variables.REQUIRED_VARIABLES`):

| Name | Notes |
|---|---|
| `Time [s]` | twins `[min]`, `[h]` generated |
| `Mass flow rate [kg.s-1]` | whole device; a control |
| `Inlet temperature [K]`, `Outlet temperature [K]` | outlet = value advected out of the last cell |
| `Inlet specific enthalpy [J.kg-1]`, `Outlet specific enthalpy [J.kg-1]` | zero at the reference temperature |
| `Power [W]` | `mdot (h_out - h_in)`, positive on discharge |
| `Discharged energy [J]` | time integral of power (a solver state) |
| `Charged energy [J]` | `-Discharged energy`, the net energy put in (F-055) |
| `Discharged throughput [J]`, `Charged throughput [J]` | time integrals of `max(P, 0)` and `max(-P, 0)` (solver states); they only grow, and their difference is the discharged energy (F-055) |
| `Storage thermal energy [J]` | storage only (PCM, fins) |
| `Storage average temperature [K]` | over all the storage, volume-weighted (F-055) |
| `Storage cross-section average temperature [K]` | along `z`, over all the storage in each cross-section of the flow path, volume-weighted: across the storage depth (and fin gap) of a finned tube, over a capsule in a packed bed; one value if the storage is averaged along the flow path (F-055) |
| `Heat transfer fluid thermal energy [J]` | fluid inventory |
| `Total thermal energy [J]` | storage + fluid inventory |
| `Heat loss power [W]` | positive for loss; zero today |
| `Heat transfer fluid specific enthalpy [J.kg-1]` | along `z`; the fluid state |
| `Heat transfer fluid temperature [K]` | along `z`; `T(h)` |
| `Heat transfer fluid velocity [m.s-1]` | along `z`; mean velocity in the flow area, `mdot_path / (A_flow rho(h))` (interstitial in a packed bed) (F-055) |
| `Inlet-outlet temperature difference [K]` | `T_in - T_out`; no twin (F-055) |
| `Volume flow rate [m3.s-1]` | whole device, at the inlet density, `mdot / rho(h_in)`; twin `[l.min-1]` (F-055) |
| `Pumped volume [m3]` | time integral of the volume flow rate (a solver state); twin `[l]` (F-055) |

**Optional, standard names:** `Average liquid fraction` (weighted by the PCM volume, fins
and fluid excluded).

**Reserved** (no model computes it yet; the first ones must use this name): `Pressure drop
[Pa]`.

**No state of charge** (DESIGN D13): models provide energies only. The energy between two
uniform states is `pytes.energy_between(model, T_a, T_b)` (§5).

**Also provided by every current model:** `Initial uniform temperature [K]`; `Heat
transfer coefficient [W.m-2.K-1]` (from the coupling's flux law: the parameter, or the
correlation's value), `Surface Reynolds number` and `Surface Prandtl number` (from the
family's flow geometry, with any coefficient; F-055), plus `Surface Nusselt number` with a
correlation (F-049), and `Effective heat transfer coefficient [W.m-2.K-1]` and `Surface
Biot number` with Jeffreson's correction (F-051). Every storage provides its own
volume-weighted averages (F-055), `<label> average temperature [K]` and `<label>
cross-section average temperature [K]` (along `z`): `Phase-change material ...` in every
model and, in the mush model, also `Fin ...`. The `Storage ...` temperatures above combine
them, so that the mush model (fins and PCM apart) compares with the sharp-front model
(homogenised).

**Family-specific:** prefixed (`Fin temperature [K]`). The packed bed adds the device totals
per unit bed cross-section (`Power per unit area [W.m-2]`, `Discharged energy per unit area
[J.m-2]`, `Storage thermal energy per unit area [J.m-2]`, `Total thermal energy per unit
area [J.m-2]`) from the `PerAreaTotals` submodel. `Phase-change material ...` names are
the PCM storage's own (for the sharp-front model, the composite).

**Units** (DESIGN D12): submodels define every variable in SI units. When a model is built,
`pytes.variables.add_unit_twins` adds twins for every variable in `[K]` (`[degC]`), `[W]`
(`[kW]`), `[J]` (`[kWh]`), `[s]` (`[min]`, `[h]`), `[m3.s-1]` (`[l.min-1]`) and `[m3]`
(`[l]`); a twin written by hand is rejected. Temperature differences
(names containing "temperature difference") get no twin. `check_required_variables` checks
that every such variable has its twin and no difference has one; `check_unit_twins`
checks the values, to round-off (relative 1e-10).

**Conservation identity** (`check_energy_conservation`, round-off tolerance):
`Total thermal energy(t) - Total thermal energy(0) = -Discharged energy(t) - int(Heat loss power) dt`.

## 4. Parameters

**Device level** (`pytes.parameters.DeviceParameters`):

| Name | Role |
|---|---|
| `Reference temperature [K]` | every energy is zero at the uniform state at this temperature |
| `Initial temperature [K]` | initial state = uniform at this temperature, solid at `T_m` |
| `Inlet temperature [K]` | function of `Time [s]`; control |
| `Mass flow rate [kg.s-1]` | whole device; control |

**Materials:** `<prefix> ...` names, prefix `PCM` (phase change) or `Metal` (sensible):
`PCM solid phase conductivity [W.m-1.K-1]`, `PCM latent heat [J.kg-1]`, `PCM melting
temperature [K]` (the middle of the melting range), `PCM melting range [K]` (solidus to
liquidus, physical; 0 for a sharp melting point), `PCM smoothing width [K]` (numerical
rounding of the corners; 0 for exact corners), `Metal density [kg.m-3]`, etc.

**Fluid:** `Heat transfer fluid density [kg.m-3]`, `... specific heat capacity
[J.kg-1.K-1]`, `... conductivity [W.m-1.K-1]` and `... viscosity [Pa.s]` (all required in a
fluid layer; the last two are used only by the correlations).

**Surface flux law:** `Heat transfer coefficient [W.m-2.K-1]` (`NewtonCooling`, the
default). The correlations add no parameter (F-049).

**Family geometry** (DESIGN D1): names start with the geometric object, never a material
prefix. Finned tube: `Tube radius [m]`, `Tube length [m]`, `Number of tubes`, `Storage
depth [m]`, `Fin thickness [m]`, `Fin pitch [m]`. Packed bed: `Bed length [m]`, `Bed
cross-sectional area [m2]`, `Bed porosity`, `Capsule radius [m]`.

`pytes.parameters.validate_parameter_values` checks that the reference and initial
temperatures are positive and the parameters it is given (e.g. the melting range and the
smoothing width) are not negative.

## 5. Energy reference and initial state (DESIGN D13, D14)

- Every energy is zero at the uniform equilibrium state at `T_ref`. The fluid's enthalpy is
  zero there; storage energies subtract the material's `T2H(T_ref)`.
- A uniform state is set by its temperature alone: each material is at `T2H(T)` (for a
  sharp melting point, solid at `T_m`; with a melting range, partly liquid inside it). Each
  heat-holding submodel implements `uniform_energy(T)`; `DeviceEnergy.uniform_energy(T)`
  sums them.
- Initial state: uniform at `T_init`, exposed as `Initial uniform temperature [K]`. Other
  starts use `model.set_initial_conditions_from(solution)`.
- `pytes.energy_between(model, T_a, T_b, parameter_values=None, var_pts=None)`: the total
  thermal energy between the uniform states at `T_a` and `T_b`, discretised on the model's
  mesh, so it matches the model's `Total thermal energy [J]` exactly.
- The models have no events; cut-offs are experiment terminations (DESIGN D11).
- Checked (`check_initial_state`): at `T_init` equal to `T_ref`, between `T_ref` and `T_m`,
  at `T_m` and above it, the initial state is uniform at `T_init` and its total thermal
  energy is `energy_between(model, T_ref, T_init)`; run with and without a melting range.

## 6. Materials (DESIGN D7)

A material exposes `internal_states` (empty today), `changes_phase`, `H2T(H, states)`,
`T2H(T)`, `k(H, states)`, `H_scale` and `H_reference`; a phase-change material also
`liquid_fraction(H, states)`, `T_solidus`, `T_liquidus`, `H_solidus` and `H_liquidus`. In
the mushy zone `H` is linear in `T`: the latent heat plus the mean of the solid and liquid
heat capacities. `H2T`, `k` and the liquid fraction are smoothed at the solidus and liquidus
over the smoothing width (floored at 1e-9 K); `T2H` is exact. Sensible materials (`SensibleMaterial`,
the fin metal) go through the same storage submodel. Enthalpy is per unit volume, relative to 0 K internally. The check "T depends
on H alone" (`check_stateless_materials`) applies only when `internal_states` is empty.

## 7. Fluid-property object (DESIGN D8)

Properties at the fluid state `(h, p)`: `T(h, p)`, `c_p(h, p)`, `rho(h, p)`, `k(h, p)`,
`mu(h, p)`; and `h(T, p)` for the inlet and initial conditions. `p` is ignored by liquids.
Only `ConstantPropertyLiquid` exists; its enthalpy reference is `T_ref`. The heat transfer
coefficient is not a fluid property: it belongs to the coupling's surface flux law (§2).

## 8. Controls and experiments (DESIGN D9, D10)

`model.controls` maps control names to parameter symbols: `Inlet temperature [K]`,
`Mass flow rate [kg.s-1]`. Each step declares `controls`; the runner rejects a step that
does not drive exactly the model's controls. Power equations in steps use
`model.power(variables, replaced_controls)`, so they stay `mdot (h_out - h_in)`.
Step types (F-054): `Inlet(inlet_temperature, mass_flow_rate)` holds both controls;
`Power(power, inlet_temperature=... | mass_flow_rate=...)` holds the one given and
adjusts the other (`step.adjusted`), raising unless exactly one is given; `Rest(
inlet_temperature=None)` holds no flow, and the inlet temperature given or, by default, its
value at the end of the previous step (the initial temperature for a first step). The old
names `ConstantInputs` and `ConstantPower` warn until 0.2.0.

## 9. Conformance checks

`check_required_variables`, `check_submodels`, `check_controls`,
`check_stateless_materials`, `check_unit_twins`, `check_energy_conservation`,
`check_power_from_enthalpy`, `check_initial_state`; and the models have no events.
Parametrisation: `tests/conftest.py::MODELS` lists every admitted model.