bloc.core.converter#

BlocConverter — DualCanteraConverter subclass pre-loaded with Bloc plugins.

Every BlocConverter instance:

  • Carries all Bloc Design* reactor builders and post-build hooks via _register_bloc_solver_plugins.

  • Resolves mechanism paths through Bloc’s get_mechanism_path search hierarchy (working dir, calling-script dir, Bloc data dir, Cantera data dir). This override is honored at every resolution point: __init__, _get_gas_for_mech, and the staged-solver helpers — thanks to the resolve_mechanism hook introduced in Boulder 0.5.0.

Attributes#

logger

Classes#

BlocConverter

Cantera converter pre-loaded with Bloc Design* reactors and hooks.

Module Contents#

bloc.core.converter.logger#
class bloc.core.converter.BlocConverter(mechanism=None, plugins=None)#

Bases: boulder.cantera_converter.DualCanteraConverter

Cantera converter pre-loaded with Bloc Design* reactors and hooks.

Parameters:

  • mechanism – Raw mechanism name/path (not yet path-resolved). Resolution is performed by resolve_mechanism during construction.

  • plugins – Optional pre-built plugin container. Bloc solver plugins are registered into this container (idempotent) regardless of whether it is provided or freshly created.

SCRIPT_EMITTER_CLASS#
post_build(config)#

Run post-build hooks, but fail-fast on equipment-envelope violations.

Boulder’s default post_build() downgrades every hook exception to a warning (tolerant to optional hooks). Bloc keeps that tolerance but re-raises PBR100EnvelopeError so a supplier model configured outside its nameplate envelope hard-fails the build instead of silently degrading.

resolve_mechanism(name)#

Resolve name using Bloc’s mechanism search hierarchy.

Called from every site that turns a mechanism string into a ct.Solution — both the top-level default mechanism (in __init__) and per-node mechanism overrides (in _get_gas_for_mech). If get_mechanism_path cannot locate the file, returns name unchanged so Cantera can handle bare built-in names (e.g. "gri30.yaml").

script_load_lines(config_path, plan=None)#

Emit a Bloc-aware Cantera-native staged-solve script.

The generated file uses module-level reactors / connections / walls registries, direct Design* construction, and named network_<stage>.advance(...) calls — no BlocConverter shell.

mechanism = 'gri30.yaml'#
plugins#
reactors: Dict[str, cantera.ReactorBase]#
reactor_meta: Dict[str, Dict[str, Any]]#
connections: Dict[str, cantera.FlowDevice]#
walls: Dict[str, Any]#
network: cantera.ReactorNet | None = None#
code_lines: List[str] = []#
last_network: cantera.ReactorNet | None = None#
parse_composition(comp_str)#

Parse a "species:value,species:value,..." composition string.

A handful of real mechanisms (e.g. n-heptane-NUIG-2016.yaml) have species names that themselves contain a literal comma (C6H101-3,3), so naively splitting on every , before every : misparses them. Values are always plain floats, so a fragment is only a complete entry once the text after its last : parses as one; until then the next comma-separated fragment is folded into the same (comma-bearing) name.

set_reactor_volume(reactor, props, reactor_id)#

Set reactor volume if specified in properties.

create_reactor_from_node(node, gas_for_node)#

Instantiate a Cantera reactor from a normalized node dict.

Uses the plugin reactor builder registry when the type matches a registered custom builder; otherwise falls back to the standard Cantera reactor types.

Parameters:

  • node – Normalized node dict with id, type, and properties.

  • gas_for_node – The Solution carrying the initial state.

Returns:

The newly created reactor (not yet added to any network).

Return type:

ct.Reactor

build_connection(conn)#

Create and register one Cantera flow device or wall from a connection dict.

The connection is added to self.connections (for FlowDevice subtypes) or self.walls (for Wall).

Parameters:

conn – Normalized connection dict with id, type, source, target, and properties.

apply_flow_conservation()#

Resolve unset MFC flow rates via mass conservation, then reset tracking state.

Called after all connections for a network (or sub-network stage) have been built. MFCs without an explicit mass_flow_rate in the YAML config are resolved by enforcing steady-state mass conservation at each non-Reservoir reactor node. Resolved values are also appended to code_lines so the --download script reflects the actual flow rates.

Raises:

ValueError – Propagated from resolve_unset_flow_rates() if any flow rate cannot be uniquely determined.

build_isolated_reactor(node)#

Build a single reactor from one node, with no surrounding network.

Resolves the node’s mechanism, sets the gas state from its initial properties (temperature / pressure / composition / mass_composition, either top-level or under initial:), and delegates to create_reactor_from_node() so that energy, clone, volume and any other recognised properties are honoured exactly as in a full network build. This is the single source of truth for reactor construction for callers (e.g. parametric τ-sweeps) that drive their own ReactorNet instead of the staged solver.

Property values may be unit strings ("1273.15 K", "1 bar") or plain numbers; temperature/pressure are coerced to SI.

Parameters:

node – A node dict with id, type, and properties (the normalised form; STONE Kind: {...} blocks must be converted to type / properties by the caller first).

Returns:

The constructed reactor and the Solution carrying its initial state.

Return type:

(reactor, gas)

build_sub_network(stage_nodes, stage_connections, stage_mechanism, inlet_states, stage_id='', stage=None, pre_solve_hook=None)#

Build (and solve) a ReactorNet for one stage.

Reactors whose IDs appear in inlet_states are initialised from the provided Solution (upstream outlet, already mechanism-switched) instead of from the YAML properties.

Parameters:

  • stage_nodes – Normalized node dicts for this stage only.

  • stage_connections – Intra-stage normalized connection dicts.

  • stage_mechanism – Default kinetic mechanism for the stage.

  • inlet_states – {node_id: ct.Solution} mapping inlet conditions for reactors that receive inter-stage flow.

  • stage_id – For logging/error messages.

  • stage – Stage dataclass; used to set the solve directive (advance_to_steady_state vs advance).

  • pre_solve_hook – Optional callback invoked with self after self.reactors/ self.connections are populated for this stage but before the solve dispatch runs. This is the only correct place to wire causal-layer bindings (e.g. apply_bindings_block) — calling them after this method returns means the solve already ran to completion with no schedule callbacks registered.

Returns:

network is the solved ReactorNet. stage_reactors is a {node_id: ct.ReactorBase} dict for this stage (a subset of self.reactors).

Return type:

(network, stage_reactors)

build_viz_network(all_connections, built_conn_ids=None)#

Build a visualization-only ReactorNet.

Uses all reactor objects already in self.reactors (which carry converged states after a staged solve) and adds any inter-stage connections that were not built during the per-stage solve.

The returned network is initialized with advance(0.0) so flow-device properties (mass_flow_rate) are ready for downstream reporting.

Parameters:

  • all_connections – The full list of normalized connection dicts (including inter-stage ones).

  • built_conn_ids – Set of connection IDs already built (intra-stage). Inter-stage connections not in this set will be created now.

Return type:

ct.ReactorNet

build_network(config, progress_callback=None)#

Build and solve the Cantera network through the staged solver.

normalize_config guarantees that the config has a top-level groups section (synthesising a single default group when the YAML does not declare one), so this method always delegates to solve_staged(). It builds one sub- ReactorNet per stage, solves each according to its solve_directive and returns a visualization ReactorNet with all reactors in their converged state. The Lagrangian trajectory is stored on self._staged_trajectory.

Parameters:

  • config – Normalised and validated configuration dict.

  • progress_callback – Optional (stage_id: str, n_done: int, n_total: int) -> None called after each stage completes. Forwarded to solve_staged().

run_streaming_simulation(simulation_time=10.0, time_step=1.0, progress_callback=None, config=None)#

Run simulation with streaming progress updates.

finalize_results(times, reactors_series)#

Finalize simulation results with post-processing.

build_network_and_code(config)#

Build+solve the network and return (network, results, code_str).

build_network now solves the whole network through the staged solver, so results only reports what the staged path already produced: the converged per-reactor states (as a single-time-point SolutionArray) and any scalars stored by post-build hooks.