Conformance and validation

Conformance checks

Conformance checks: the executable contract (see docs/design/contract.md).

Every admitted model passes these checks (tests/conformance/ runs them over every model). They are importable so that anyone building a model with PyBaMM directly can check it against the same contract. Each check raises AssertionError with a message when it fails.

pytes.conformance.check_required_variables(model)

Every required variable is defined, and every variable in [K], [W] or [J] has its unit twin, except temperature differences, which have none (DESIGN D12)

pytes.conformance.check_submodels(model)

The model lists its submodels, and their declarations fit together

pytes.conformance.check_controls(model)

The model declares its controls, each with a variable of the same name

pytes.conformance.check_stateless_materials(model)

For storage whose material declares no internal states, the temperature is a function of the enthalpy alone (DESIGN D7)

pytes.conformance.check_unit_twins(solution)

Every unit twin equals its SI variable converted (DESIGN D12), to round-off: the solver may evaluate a twin’s expression in another order than the conversion here

pytes.conformance.check_energy_conservation(solution, rtol=1e-09)

The conservation identity (DESIGN D12), exactly up to round-off: change in total energy = -int(power) dt - int(heat loss) dt.

The heat loss is zero for every current model, so this checks that it is zero and that the change in total thermal energy is minus the discharged energy.

pytes.conformance.check_power_from_enthalpy(solution)

The power is mdot (h_out - h_in) (DESIGN D8)

pytes.conformance.check_initial_state(model, parameter_values=None, var_pts=None)

The initial state is uniform at “Initial temperature [K]”, and every energy is zero at the uniform state at “Reference temperature [K]” (DESIGN D14): the initial total thermal energy equals pytes.energy_between() from the reference temperature to the initial one, at the reference itself, below, at and above the melting temperature (inside the mushy zone if the material has a melting range)

pytes.conformance.check_model(model, parameter_values=None, var_pts=None, t_end=600)

Run every check on a model: its structure, then a solve of t_end seconds from its initial state for the conservation, power and unit-twin checks, then its initial state. For a model built from submodels or options of your own, e.g. with a correlation added by pytes.submodels.register_correlation().

Parameters:

• model (pytes.BaseModel) – The model.

• parameter_values (pybamm.ParameterValues, optional) – The parameter values (default: the model’s).

• var_pts (dict, optional) – The mesh (default: the model’s).

• t_end (float, optional) – The duration of the solve [s] (default 600).

Returns:

pybamm.Solution – The solution of the solve, to inspect further.

Raises:

AssertionError – If a check fails.

Analytical solutions

Analytical solutions the models are validated against (DESIGN D1, §6). Importable, like the conformance checks, so that anyone can compare a model with them.

• schumann(): a packed bed of a sensible material with lumped particles (Schumann, 1929).

• sphere_melting_time(): the quasi-steady melting of a sphere from its surface, the limit of the spherical Stefan problem at small Stefan number.

pytes.validation.schumann(xi, eta)

Schumann’s solution for a packed bed of a sensible material with lumped particles, no axial conduction or dispersion, initially uniform, with a step in the inlet temperature.

With theta = (T - T_0) / (T_in - T_0) for the fluid and the solid, the equations are d theta_f / d xi = theta_s - theta_f and d theta_s / d eta = theta_f - theta_s, with theta_f = 1 at the inlet and theta_s = 0 initially, in the variables

• xi = h a z / (eps rho_f c_f u): the number of transfer units from the inlet,

• eta = h a (t - z / u) / ((1 - eps) rho_s c_s): the time since the fluid that entered at t = 0 reached z, in units of the particles’ time constant,

with a the particle surface per unit bed volume and u the interstitial velocity. Before that fluid arrives (eta <= 0) both are 0.

Parameters:

• xi (float) – The transfer units and the transfer time.

• eta (float) – The transfer units and the transfer time.

Returns:

theta_f, theta_s (float) – The fluid and solid temperatures, scaled.

pytes.validation.sphere_melting_time(liquid_fraction)

Time for a sphere at its melting temperature to melt a volume fraction liquid_fraction when its surface is held above the melting temperature, in the quasi-steady limit (small Stefan number, conduction through the liquid shell only):

t / tau = 1 - 3 (s / R)**2 + 2 (s / R)**3, with s / R = (1 - liquid_fraction)**(1/3)

the radius of the solid core, and tau = rho L R**2 / (6 k_l (T_surface - T_m)) the time to melt it completely.

Parameters:

liquid_fraction (float or numpy.ndarray) – The melted volume fraction, between 0 and 1.

Returns:

float or numpy.ndarray – The time, in units of tau.