bloc.reporting.kpi#

Calculation-Note KPI helpers for design reactor reporting.

These functions operate on physical quantities (mass flows, gas states, STONE config dicts) and produce values suitable for the Calculation Note Excel or for Simulation.scalars. They contain no solver logic and carry no coupling to specific YAML node names.

All functions are pure (no side-effects on Cantera phases) or explicitly document mutation.

Classes#

Constraint

A named pass/fail criterion for a scalar output variable.

ConstraintResult

Evaluation result for one Constraint.

Functions#

actual_flow_m3h(mdot_kg_s, rho_kg_m3)

Return actual volumetric flow [m³/h] at current gas conditions.

normal_flow_m3h(mdot_kg_s, gas)

Return normal volumetric flow [Nm³/h] at 0 °C, 101 325 Pa (DIN 1343).

find_injection_sources(cfg, target_node_ids, ...)

Return STONE node configs for injection reservoirs feeding any of the targets.

find_secondary_source(cfg, target_node_id, ...)

Return the STONE node config for the secondary injection reservoir.

compute_quench_kpis(gas_hot, mdot_hot_kg_s, X_quench, ...)

Compute quench and post-quench volumetric flows from an adiabatic mix.

evaluate_constraints(outputs, constraints)

Evaluate constraints against the scalar outputs dict.

parse_constraints_from_config(export_cfg)

Parse the constraints list from an export configuration dict.

Module Contents#

bloc.reporting.kpi.actual_flow_m3h(mdot_kg_s, rho_kg_m3)#

Return actual volumetric flow [m³/h] at current gas conditions.

Parameters:

  • mdot_kg_s – Mass flow rate [kg/s].

  • rho_kg_m3 – Gas density at actual (T, P) [kg/m³].

bloc.reporting.kpi.normal_flow_m3h(mdot_kg_s, gas)#

Return normal volumetric flow [Nm³/h] at 0 °C, 101 325 Pa (DIN 1343).

Uses bloc.chem.get_DIN1343_properties() to evaluate density at normal conditions without mutating gas.

Parameters:

  • mdot_kg_s – Mass flow rate [kg/s].

  • gas – Cantera Solution carrying the gas composition. Only the species composition is used; (T, P) are overridden internally.

bloc.reporting.kpi.find_injection_sources(cfg, target_node_ids, excluded_source_ids)#

Return STONE node configs for injection reservoirs feeding any of the targets.

Walks STONE connections to find all MassFlowController connections that feed any node in target_node_ids from a source not in excluded_source_ids, then returns the matching node dicts from nodes.

Used for CGR intermediary injections: each InstantaneousMixingReactor receives one upstream tube (inter-stage, excluded by excluded_source_ids) and one injection reservoir. This function returns the injection reservoir nodes only.

Parameters:

  • cfg – Parsed STONE YAML dict.

  • target_node_ids – List of node ids to look for as MFC targets (e.g. ["cgr_mix_1", "cgr_mix_2"]).

  • excluded_source_ids – Set of source node ids to skip (e.g. upstream tube {id}_outlet aliases and tube node ids).

Returns:

STONE node dicts for all matched injection reservoirs.

Return type:

list of dict

bloc.reporting.kpi.find_secondary_source(cfg, target_node_id, excluded_source_ids)#

Return the STONE node config for the secondary injection reservoir.

Walks STONE connections to find any MassFlowController that feeds target_node_id from a source not in excluded_source_ids, then returns the matching node dict from nodes.

Parameters:

  • cfg – Parsed STONE YAML dict (top-level, containing connections and nodes).

  • target_node_id – Node id of the reactor receiving secondary injection (e.g. the PSR).

  • excluded_source_ids – Set of node ids to exclude (e.g. the torch ids).

Returns:

STONE node dict for the first matching secondary source, or None if none is found.

Return type:

dict or None

bloc.reporting.kpi.compute_quench_kpis(gas_hot, mdot_hot_kg_s, X_quench, T_cold_C, T_target_C, mech)#

Compute quench and post-quench volumetric flows from an adiabatic mix.

Calls bloc.reactors.optim.find_quench_flow() to determine the quench mass flow needed to reach T_target_C, then evaluates actual and normal volumetric flows for the quench stream and the mixed post-quench stream.

Parameters:

  • gas_hot – Cantera Solution at the pre-quench state (T_out, P, Y of hot gas). Not mutated.

  • mdot_hot_kg_s – Hot-gas mass flow rate [kg/s].

  • X_quench – Mole-fraction array or dict for the quench gas composition.

  • T_cold_C – Quench gas temperature [°C].

  • T_target_C – Target post-quench temperature [°C].

  • mech – Cantera mechanism file path (used to create temporary gas objects).

Returns:

Keys: "qm_quench_kg_s", "Q_quench_m3h", "Q_quench_N_m3h", "Q_post_quench_m3h", "Q_post_quench_N_m3h". Values are None when the quench calculation cannot be performed.

Return type:

dict

class bloc.reporting.kpi.Constraint#

A named pass/fail criterion for a scalar output variable.

Parameters:

  • key (str) – Key in the outputs dict (e.g. "Fo_D_min").

  • description (str) – Human-readable label shown in the Calculation Note.

  • operator (str) – Comparison operator: one of ">", "<", ">=" or "<=".

  • threshold (float) – Reference value the output must satisfy.

key: str#
description: str#
operator: Literal['>', '<', '>=', '<=']#
threshold: float#
criterion_str()#

Return a compact criterion expression, e.g. 'Fo_D_min > 1.0'.

class bloc.reporting.kpi.ConstraintResult#

Evaluation result for one Constraint.

Parameters:

  • constraint (Constraint) – The constraint that was evaluated.

  • value (float or None) – Actual value extracted from the outputs dict; None if the key was absent.

  • passed (bool or None) – True / False if the value is finite and available; None if the value is missing or NaN.

constraint: Constraint#
value: float | None#
passed: bool | None#
bloc.reporting.kpi.evaluate_constraints(outputs, constraints)#

Evaluate constraints against the scalar outputs dict.

Parameters:

  • outputs (dict) – Flat scalar dict (e.g. from _build_result or _tf_kpi_extractor).

  • constraints (list[Constraint]) – Constraints to evaluate.

Returns:

One result per constraint, in the same order as constraints.

Return type:

list[ConstraintResult]

bloc.reporting.kpi.parse_constraints_from_config(export_cfg)#

Parse the constraints list from an export configuration dict.

Reads export_cfg["constraints"], a list of dicts with keys key, description, operator, threshold.

Parameters:

export_cfg (dict or None) – Export configuration dict (from base_yaml["export"] or similar). If None or missing the "constraints" key, returns [].

Returns:

Parsed constraints; empty list if none defined.

Return type:

list[Constraint]