Correlation Metadata Schema

Each correlation is defined in a YAML file under data/correlations/ and validated against the CorrelationMetadata Pydantic model on registry load.

Required fields

Field	Type	Description
key	str	Dot-namespaced identifier, e.g. internal.gnielinski. Must be unique across all files.
family	str	Domain family: convection_internal, convection_external, or tube_banks.
title	str	Human-readable name including author and year, e.g. "Gnielinski (1976)".
output	str	Physical quantity produced, typically "Nu".
source	dict	Bibliographic reference with keys authors (list), year (int), title, journal, doi.
assumptions	list[str]	Stated assumptions (smooth tube, uniform properties, fully developed flow, etc.).
validity	dict	Bounds used for applicability filtering (see below).

Optional fields

Field	Type	Default	Description
formula_latex	str	""	LaTeX string of the primary correlation formula. Used by the GUI and docs.
flow_regime	str	"all"	Applicable regime: "laminar", "turbulent", "transitional_turbulent", or "all".
boundary_conditions	list[str]	[]	Applicable boundary types: "constant_wall_temperature", "constant_heat_flux", or both. Empty list means no preference.
required_inputs	list[str]	[]	Dimensionless groups or inputs required, e.g. ["Reynolds", "Prandtl"].
literature_uncertainty_pct	float | null	null	Stated accuracy from the source, in percent. Feeds the uncertainty score in ranking.
notes	list[str]	[]	Implementation notes, known limitations, or guidance on when to prefer this correlation.

Validity dict keys

The validity dict is checked by ApplicabilityEngine. All keys are optional.

Key	Type	Description
geometry_type	str	Required geometry: circular_tube, cylinder_crossflow, flat_plate, or tube_bank.
re_min	float	Minimum Reynolds number (exclusive).
re_max	float	Maximum Reynolds number (exclusive).
pr_min	float	Minimum Prandtl number.
pr_max	float	Maximum Prandtl number.
ld_min	float	Minimum $L/D$ (entry length ratio), informational only — not enforced by the engine.

Example

key: internal.gnielinski
family: convection_internal
title: "Gnielinski (1976)"
output: Nu
formula_latex: >
  Nu = \frac{(f/8)(Re - 1000)\,Pr}{1 + 12.7\sqrt{f/8}(Pr^{2/3} - 1)}
flow_regime: transitional_turbulent
boundary_conditions:
  - constant_wall_temperature
  - constant_heat_flux
required_inputs:
  - Reynolds
  - Prandtl
validity:
  geometry_type: circular_tube
  re_min: 3000
  re_max: 5000000
  pr_min: 0.5
  pr_max: 2000
  ld_min: 10
literature_uncertainty_pct: 10
assumptions:
  - Smooth circular tube
  - Fully turbulent or transitional flow (Re > 3000)
  - Constant fluid properties evaluated at bulk temperature
source:
  authors:
    - "Gnielinski, V."
  year: 1976
  title: "New equations for heat and mass transfer in turbulent pipe and channel flow"
  journal: "International Chemical Engineering"
  doi: ""
notes:
  - Preferred over Dittus-Boelter for Re 3000–5e6 due to lower stated uncertainty (~10 %)
  - Uses Petukhov (1970) friction factor f = (0.790 ln Re - 1.64)^{-2}

Engineering trust rules

Every entry must include source, assumptions, validity, and notes. If a ranking or confidence behaviour changes, update both the YAML and any affected tests. Never invent a validity range or uncertainty figure without a literature citation.