bloc.reactors.energy_stream#

Bloc-side energy stream abstraction (power/heat flows, outside Cantera resolution).

An EnergyStream represents a non-mass energy flow into or out of a reactor – e.g. a plasma torch’s electrical power input, or a PFR’s ambient heat loss. Some of these are backed by a real Cantera Wall (heat loss, strongly coupled to the reactor’s own ODE); others are pure Bloc-side bookkeeping around a scalar already used elsewhere (torch power, applied as an instantaneous enthalpy jump, never through a live Cantera integration – see TorchInstantaneousHeatingNet).

Both kinds expose the identical interface here so that Sankey, energy-flow collection, and Cytoscape display treat them the same way – one record type, never re-derived per consumer from wall-name string matching or _meta.

Classes#

`EnergyStream`	A single energy flow attached to a reactor.
`EnergyPortMixin`	Mixin giving a reactor discoverable `energy_inlets`/`energy_outlets`.

Functions#

`is_energy_port_kind`(kind)	Return True when kind is a registered STONE kind using `EnergyPortMixin`.
`wall_sign_for`(wall, reactor)	Return the `EnergyStream.wall_sign` for reactor's side of wall.

Module Contents#

class bloc.reactors.energy_stream.EnergyStream#

A single energy flow attached to a reactor.

Parameters:

name – Identifier for this stream (e.g. the connection id, or a synthetic name for parameter-backed streams).
kind – Open-ended tag describing the physical nature of the flow, e.g. "electric" (torch power) or "heat_loss" (PFR ambient loss).
wall – The real Cantera Wall backing this stream, when one exists (e.g. the PFR’s ambient-loss wall). None for pure-parameter streams (e.g. torch power, which never touches Cantera’s solver).
wall_sign – Only meaningful when wall is set. Cantera defines wall.heat_rate as positive when heat flows left_reactor -> right_reactor, a convention relative to the Wall itself, not to whichever reactor this stream is attached to. Pass +1.0 when the attached reactor is wall.right_reactor (positive heat_rate already means “into this reactor”) or -1.0 when it is wall.left_reactor (heat_rate must be negated). Ignored for parameter-backed streams.

name: str#

kind: str = 'electric'#

wall: cantera.Wall | None = None#

wall_sign: float = 1.0#

property power_w: float#

Signed power in watts, positive = flowing into the attached reactor.

Wall-backed streams read wall.heat_rate live on every access – it is only meaningful post-solve and can change across a staged or iterative solve, so caching a snapshot at construction time would go stale – then apply wall_sign to reorient Cantera’s left-to-right convention relative to the attached reactor. Parameter-backed streams return the stored scalar (it never changes once computed).

bloc.reactors.energy_stream.is_energy_port_kind(kind)#

Return True when kind is a registered STONE kind using EnergyPortMixin.

Resolved the same way as is_torch_reactor_kind() and is_psr_mixing_kind() – via Boulder’s schema registry, so any current or future EnergyPortMixin reactor is recognized automatically. Used by bloc.boulder_plugins.energy_stream_display to find candidate nodes without hardcoding a torch-specific check; wall-backed streams (e.g. the PFR’s ambient loss) are still excluded from synthesis there because they already have a real STONE Wall connection to draw.

bloc.reactors.energy_stream.wall_sign_for(wall, reactor)#

Return the EnergyStream.wall_sign for reactor’s side of wall.

Computed from which side reactor is actually on, rather than assumed at each call site – correct regardless of which endpoint a given unfolder happened to declare as the STONE connection’s source/target.

class bloc.reactors.energy_stream.EnergyPortMixin#

Mixin giving a reactor discoverable energy_inlets/energy_outlets.

Attach records via add_energy_stream(); energy_inlets and energy_outlets are read-only views over the same list, filtered by the live sign of EnergyStream.power_w. The backing list is created lazily on first use so no reactor __init__ needs editing to pick this up – classes just add EnergyPortMixin to their bases.

Most Bloc reactors do not use this mixin; consumers must access it duck-typed, e.g. getattr(obj, "energy_inlets", []).

Example

Declare it as one of the reactor’s bases – no constructor changes needed:

class PFR(EnergyPortMixin, ct.ExtensibleIdealGasConstPressureMoleReactor):
    ...

Once built, whoever owns the reactor attaches its energy stream(s) (typically in a Boulder post-build hook, e.g. bloc.reactors.builders._post_build_design_volumes()):

pfr.add_energy_stream(
    EnergyStream("loss_wall", kind="heat_loss", wall=loss_wall,
                 wall_sign=wall_sign_for(loss_wall, pfr))
)

From then on, pfr exposes:

energy_inlets / energy_outlets – the live, signed streams currently flowing in/out ([] if none were attached).
Discoverability for generic consumers that don’t know about torches or PFRs specifically: bloc.plotting.sankey and bloc.boulder_plugins.energy_stream_display both walk energy_inlets/energy_outlets on every reactor to draw the “Electricity”/”Heat_loss”-style flows, without any per-reactor-kind branching in that display code (see is_energy_port_kind()).

add_energy_stream(stream)#: Attach an EnergyStream record to this reactor.

property energy_inlets: list[EnergyStream]#: Energy streams currently flowing into this reactor (power_w > 0).

property energy_outlets: list[EnergyStream]#: Energy streams currently flowing out of this reactor (power_w < 0).