Functions
Optional[float]	_num (Any v)
Any	_dig (Any d, str path)
Optional[float]	_pct (Optional[float] err, Optional[float] ref)
Optional[str]	_species (Optional[str] name)
List[float]	_steps (Mapping[str, Any] series)
List[Dict[str, Any]]	feed_lines (Mapping[str, Any] document, str tank_id)
Optional[Mapping[str, Any]]	_document (Mapping[str, Any] result, Any prep, Optional[Mapping[str, Any]] document)
Dict[str, Any]	mass_balance (Mapping[str, Any] result, Any prep=None, Optional[Mapping[str, Any]] document=None)
Tuple[Optional[float], List[str]]	_ullage_masses (Mapping[str, Any] series, Mapping[str, Any] derived, str gas, int i)
Tuple[Optional[float], Optional[float], str]	_vented (Mapping[str, Any] result, Sequence[float] steps)
Dict[str, Any]	pressurant_balance (Mapping[str, Any] result, Any prep=None)
Tuple[Optional[float], str]	_bottle_wall (Mapping[str, Any] result, Any prep, Optional[Mapping[str, Any]] document)
Dict[str, Any]	energy_balance (Mapping[str, Any] result, Any prep=None, Optional[Mapping[str, Any]] document=None)
List[Dict[str, Any]]	convergence (Mapping[str, Any] result)
Dict[str, Any]	check (Mapping[str, Any] result, Any prep=None, *, Optional[Mapping[str, Any]] document=None)

Variables
float	PSI = 6894.757293168361
dict	COOLPROP

Detailed Description

Verification checks on a finished Layer X burn: does it conserve what it must? (DATA-CONTRACT 3, ``vv``)

A burn that converges, plots smoothly and violates no assertion is not evidence (CLAUDE.md). These
checks re-derive three balances from the recorded result, by a path independent of the twin's own
bookkeeping where one exists, and report how far each fails to close:

* **Propellant mass**, per side: what was loaded = what the chamber burned + what is left in the
  tank + what the drawing's feed lines hold. ``burned`` integrates the chamber's flow (or, with the
  full network recorded, the injector branches') step by step; ``loaded`` and ``residual`` are the
  tank's own inventory. The twin's network is algebraic (no liquid inventory in a line), so the
  trapped mass is the same at T-0 and at burnout: it enters both sides, and the error is the tank
  inventory against the integrated flow. It is reported because a stand fills its lines too.
* **Pressurant mass**: gas out of the bottle = gas gained by the ullages + gas vented. The bottle
  figure is the twin's vessel state; each ullage is **re-priced with CoolProp** from the recorded
  pressure, gas temperature and fill (``rho(p, T) * V_tank * (1 - fill)``), so the check does not
  read the twin's ullage mass back. Vented gas needs the full network recorder (``result.network``);
  without it the vents are taken as shut, which the burn plan does.
* **Gas-side energy** (first law over the pressurant: bottle, lines, ullages), reported, never
  graded: see :func:`energy_balance` for what it closes and what it cannot.
* **Convergence** of the outer loops, per pass, from ``result.passes``.

Every relative error is in percent of the quantity that entered the balance (the energy residual: of
the expulsion work, see :func:`energy_balance`). The thresholds that grade them live with every other
limit, in :data:`engine.layerx.diag.limits.THRESHOLDS`.

Sources: mass conservation for a control volume and the first law for an open system,
dU/dt = sum(m_in h_in) - sum(m_out h_out) + Q - p dV/dt (Moran & Shapiro, Fundamentals of Engineering
Thermodynamics, ch. 4, the control-volume energy rate balance). Properties: CoolProp
(Bell et al., Ind. Eng. Chem. Res. 53(6), 2014).

Function Documentation

◆ _bottle_wall()

Tuple[Optional[float], str] engine.layerx.diag.vv._bottle_wall	(	Mapping[str, Any]	result,
		Any	prep,
		Optional[Mapping[str, Any]]	document )

protected

Bottle wall heat capacity m*c [J/K] and where it came from: the drawing's own wall, else
the twin's Setup default (``bottle_wall_kg_per_L`` times the bottle volume, at feedtwin's
``BOTTLE_WALL`` capacity).

Definition at line 321 of file vv.py.

References _dig(), _document(), and _num().

Referenced by energy_balance().

◆ _dig()

Any engine.layerx.diag.vv._dig	(	Any	d,
		str	path )

protected

Definition at line 54 of file vv.py.

Referenced by _bottle_wall(), _document(), check(), convergence(), energy_balance(), feed_lines(), mass_balance(), and pressurant_balance().

◆ _document()

Optional[Mapping[str, Any]] engine.layerx.diag.vv._document	(	Mapping[str, Any]	result,
		Any	prep,
		Optional[Mapping[str, Any]]	document )

protected

Definition at line 136 of file vv.py.

References _dig().

Referenced by _bottle_wall(), and mass_balance().

◆ _num()

Optional[float] engine.layerx.diag.vv._num ( Any v )

protected

Definition at line 44 of file vv.py.

Referenced by _bottle_wall(), _ullage_masses(), _vented(), convergence(), energy_balance(), feed_lines(), mass_balance(), and pressurant_balance().

◆ _pct()

Optional[float] engine.layerx.diag.vv._pct	(	Optional[float]	err,
		Optional[float]	ref )

protected

Definition at line 62 of file vv.py.

Referenced by energy_balance(), mass_balance(), and pressurant_balance().

◆ _species()

Optional[str] engine.layerx.diag.vv._species ( Optional[str] name )

protected

Definition at line 68 of file vv.py.

Referenced by energy_balance(), mass_balance(), and pressurant_balance().

◆ _steps()

List[float] engine.layerx.diag.vv._steps ( Mapping[str, Any] series )

protected

Definition at line 74 of file vv.py.

Referenced by mass_balance(), and pressurant_balance().

◆ _ullage_masses()

Tuple[Optional[float], List[str]] engine.layerx.diag.vv._ullage_masses	(	Mapping[str, Any]	series,
		Mapping[str, Any]	derived,
		str	gas,
		int	i )

protected

Definition at line 240 of file vv.py.

References _num(), and max.

Referenced by pressurant_balance().

◆ _vented()

Tuple[Optional[float], Optional[float], str] engine.layerx.diag.vv._vented	(	Mapping[str, Any]	result,
		Sequence[float]	steps )

protected

Gas that left the network to the atmosphere [kg] and the enthalpy it carried [J], from the
full network record: every gas branch whose downstream node is ambient (or a vent).

Definition at line 262 of file vv.py.

References _num(), and max.

Referenced by pressurant_balance().

◆ check()

Dict[str, Any] engine.layerx.diag.vv.check	(	Mapping[str, Any]	result,
		Any	prep = None,
		*	,
		Optional[Mapping[str, Any]]	document = None )

The ``diagnostics.vv`` block. Each part that cannot be computed says why; nothing raises.

``prep`` (a Prepared) and ``document`` (the drawing's ``{nodes, edges}``) are optional: the
result's own provenance names the drawing, and a shipped one is found by id.

Definition at line 470 of file vv.py.

References _dig(), convergence(), energy_balance(), mass_balance(), and pressurant_balance().

◆ convergence()

List[Dict[str, Any]] engine.layerx.diag.vv.convergence ( Mapping[str, Any] result )

Per outer pass: the throat schedule's and the flight acceleration's change against their
tolerances (``replay.THROAT_TOLERANCE``, ``flight.ACCEL_TOLERANCE``).

Definition at line 441 of file vv.py.

References _dig(), _num(), and max.

Referenced by check().

◆ energy_balance()

Dict[str, Any] engine.layerx.diag.vv.energy_balance	(	Mapping[str, Any]	result,
		Any	prep = None,
		Optional[Mapping[str, Any]]	document = None )

The first law over the pressurant, over the recorded window.

For the bottle, ``-dU_bottle + Q_bottle_wall`` is the enthalpy that left it. For the ullages,
``dU_ullage + W`` (``W = integral p dV`` on the liquid) is what arrived, less the heat the tank
walls and the liquid surface gave the gas. Lines and regulators hold no gas and do no work
(isenthalpic throttling). So the unclosed part,

    R = (-dU_bottle + Q_bottle_wall) - dU_ullage - W - H_vented,

is minus the heat the tank walls, the liquid surface and (with ``line_walls``) the line walls put
into the gas, plus integration error. **It closes** the bottle (its wall from the drawing or the
Setup default, its gas priced with CoolProp at the recorded pressure and m/V), the ullages
(CoolProp at the recorded p, T) and the boundary work (trapezoidal p dV). **It cannot** separate
the tank-wall and interface heat from numerical error, because the series records neither the tank
wall temperatures nor the interface: ``error_pct`` is therefore not a defect measure and the
limits report it as information only. Vent enthalpy is not in the network record, so a run that
vents carries that term in R too.

Definition at line 353 of file vv.py.

References _bottle_wall(), _dig(), _num(), _pct(), _species(), and max.

Referenced by check().

◆ feed_lines()

List[Dict[str, Any]] engine.layerx.diag.vv.feed_lines	(	Mapping[str, Any]	document,
		str	tank_id )

The drawing's lines from ``tank_id`` to the engine: the walk the propellant takes, edge by
edge, while the next symbol carries the tank's fluid (a fill or vent line, which turns to the
pressurant, is not followed). Each line as ``{id, length_m, bore_m, volume_m3, provenance}``;
a line missing a length or bore is returned with ``volume_m3`` None.

Definition at line 87 of file vv.py.

References _dig(), and _num().

Referenced by mass_balance().

◆ mass_balance()

Dict[str, Any] engine.layerx.diag.vv.mass_balance	(	Mapping[str, Any]	result,
		Any	prep = None,
		Optional[Mapping[str, Any]]	document = None )

Per side: ``{loaded_kg, burned_kg, residual_kg, trapped_kg, error_pct, basis, lines}``.

``loaded_kg`` is the tank at T-0 plus the feed lines' liquid; ``error_pct`` is
``(loaded - burned - residual - trapped) / loaded``.

Definition at line 157 of file vv.py.

References _dig(), _document(), _num(), _pct(), _species(), _steps(), and feed_lines().

Referenced by check().

◆ pressurant_balance()

Dict[str, Any] engine.layerx.diag.vv.pressurant_balance	(	Mapping[str, Any]	result,
		Any	prep = None )

``{bottle_out_kg, ullage_in_kg, vented_kg, error_pct, basis}`` over the recorded window.

Definition at line 282 of file vv.py.

References _dig(), _num(), _pct(), _species(), _steps(), _ullage_masses(), and _vented().

Referenced by check().

Variable Documentation

◆ COOLPROP

dict engine.layerx.diag.vv.COOLPROP

Initial value:

1= {"oxygen": "Oxygen", "ethanol": "Ethanol", "nitrogen": "Nitrogen", "helium": "Helium",

2 "water": "Water", "lox": "Oxygen", "ln2": "Nitrogen", "gn2": "Nitrogen", "he": "Helium"}

Definition at line 40 of file vv.py.

◆ PSI

float engine.layerx.diag.vv.PSI = 6894.757293168361

Definition at line 37 of file vv.py.

Functions

Variables

Detailed Description

Function Documentation

◆ _bottle_wall()

◆ _dig()

◆ _document()

◆ _num()

◆ _pct()

◆ _species()

◆ _steps()

◆ _ullage_masses()

◆ _vented()

◆ check()

◆ convergence()

◆ energy_balance()

◆ feed_lines()

◆ mass_balance()

◆ pressurant_balance()

Variable Documentation

◆ COOLPROP

◆ PSI