Composition

Cycle

Utilizing the incompressible scheme, this module contains functions for constructing coolant cycles and adding Kirchhoff constraints to its flow

class FlowGraph(*edges, funcs=None, reference_node=None, abs_pressure_comps=None, inertial_comps=None, ref_mdots=None, k_constructor=<class 'stream.calculations.kirchhoff.Kirchhoff'>)[source]

Bases: object

A container for the Aggregator and Kirchhoff objects generated from a flow graph.

Parameters:

edges (FlowEdge) – These are (u, v, d) of the graph. Since this is a MultiDiGraph, (u, v) may be repeated, and would mostly be of type Junction (but any hashable is okay). The data d holds a list of components (under the comps key) on each edge, its “significance” (under signify) and any other datum.
funcs (ExternalFunctions or None) – External Aggregator functions
reference_node (tuple[Hashable, Pascal] or None) – A reference (“ground”) node and its absolute pressure
abs_pressure_comps (Sequence[Hashable] or None) – Nodes for which the absolute pressure should be calculated
inertial_comps (Sequence[Calculation] or None) – A subset of calculations in agr which require \(\ddot{m}\) from kirchhoff. This requires k to be KirchhoffWDerivatives.
ref_mdots (Sequence[Calculation] or None) – Calculations for which a reference current is desired. This list must be a subset of a list already known to k from its flow-graph
k_constructor (Type[Kirchhoff]) – A Kirchhoff constructor

check_gravity_mismatch(temperature=10.0, strategy=None, tol=1e-05, head=1.0)[source]

A wrapper for check_gravity_mismatch, see therein for more information

Parameters:

temperature (float | ndarray)
strategy (dict[Calculation, Callable[[float | ndarray, float | ndarray], float | ndarray]] | None)
tol (float)
head (float | ndarray)

Return type:

None

guess_steady_state(mdots, temperature, strategy=None)[source]

A guess for a Kirchhoff derived system, in which the mass flow rates are assumed to be known

Parameters:

mdots (dict[Calculation | str, KgPerS]) – Known mass flow rates \(\dot{m}\) for components in the hydraulic system. Supported Calculations are DPCalculation and Channel.
temperature (Celsius) – Assumed temperature for hydraulic calculations
strategy (HydraulicStrategyMap | None) – For unknown calculations, pressure drop functions \(\Delta p(\dot{m}, T)\) may be provided. These are used when the Calculation isn’t identified as known types or protocols, and failing that, the guess is 0.0.

Returns:

A guess in which pressures are computed from the known flow rates, and the flow rates themselves.

Return type:

State

flow_edge(edge, *components, signify=1.0, **kwargs)[source]

A tool to make input for flow_graph more streamlined.

Warning

Junction weights are edited to reflect signify weighting

Parameters:

edge (tuple[Hashable, Hashable]) – The edge (u, v) to be created.
components (Sequence[Calculation]) – Components on that edge, sequentially from u to v.
signify (float) – The weight this edge carries (or how many equivalent parallel edges it signifies.

Returns:

edge – u, v, edge_data

Return type:

tuple[hashable, hashable, dict[str, Any]]

flow_graph(*edges)[source]

A more declarative way to construct a flow graph, to be used in a Kirchhoff type constructor.

Parameters:: edges (FlowEdge) – These are (u, v, d) of the graph. Since this is a MultiDiGraph, (u, v) may be repeated, and would mostly be of type Junction (but any hashable is okay). The data d holds a list of components (under the comps key) on each edge, its “significance” (under signify) and any other datum.
Returns:: flow_graph
Return type:: MultiDiGraph

flow_graph_to_aggregator(f_graph, funcs=None)[source]

Create a CalculationGraph which stems from a flow_graph. Essentially, this function creates CalculationGraphs by using in_series for each edge (including the nodes), and adding them together.

Parameters:

f_graph (MultiDiGraph) – Flow graph. See Kirchhoff.
funcs (ExternalFunctions or None) – External functions which are inserted into the resultant CalculationGraph

Returns:

agr – An “Hydraulic” Aggregator input.

Return type:

CalculationGraph

flow_graph_to_agr_and_k(f_graph, funcs=None, reference_node=None, abs_pressure_comps=None, inertial_comps=None, ref_mdots=None, k_constructor=<class 'stream.calculations.kirchhoff.Kirchhoff'>)[source]

Create an Aggregator and Kirchhoff objects from a flow graph.

Essentially, it’s just a merger of flow_graph_to_aggregator and kirchhoffify.

Parameters:

f_graph (MultiDiGraph) – Flow graph.
funcs (ExternalFunctions or None) – External Aggregator functions
reference_node (tuple[Hashable, Pascal] or None) – A reference (“ground”) node and its absolute pressure
abs_pressure_comps (Sequence[Hashable] or None) – Calculations for which the absolute pressure should be calculated
inertial_comps (Sequence[Calculation] or None) – A subset of calculations in agr which require \(\ddot{m}\) from kirchhoff. This requires k to be KirchhoffWDerivatives.
ref_mdots (Sequence[Calculation] or None) – Calculations for which a reference current is desired. This list must be a subset of a list already known to k from its flow-graph
k_constructor (Type[Kirchhoff]) – A Kirchhoff constructor

Returns:

agr, k

Return type:

Aggregator, Kirchhoff

in_parallel(start_comp, end_comp, *parallel, funcs=None)[source]

Construct a parallel part of the hydraulic (incompressible) cycle

Parameters:

start_comp (Calculation) – Component from which all parallel components are fed.
end_comp (Calculation) – Component into which all parallel components feed.
parallel (Iterable[Calculation]) – Parallel components
funcs (ExternalFunctions | None) – External functions relating to the components

Returns:

agr – whose graph nodes are linked components in parallel between start_comp and end_comp (included), with edges containing variables = Tin.

Return type:

CalculationGraph

Notes

start_comp is connected through parallel to end_comp. if no parallel components are given, the returned CalculationGraph is simply empty.

in_series(*components, cyclic=False, funcs=None)[source]

Construct a serial part of the hydraulic (incompressible) cycle

Parameters:

components (Iterable[Calculation]) – Components (calculations) to be connected
cyclic (bool) – Should the series be connected in a loop?
funcs (ExternalFunctions | None) – External functions relating to the components

Returns:

agr – Graph whose nodes are serially linked components with edges containing variables = Tin, Tin_minus.

Return type:

CalculationGraph

kirchhoffify(agr, k, hydraulic_comps=None, inertial_comps=None, ref_mdots=None, abs_pressure_comps=None)[source]

Given a subset of the given CalculationGraph calculations which adhere to Kirchhoff’s laws, construct a CalculationGraph which contains Kirchhoff linked properly.

Parameters:

agr (BaseAgr)
k (Kirchhoff) – Calculation which already contains:
hydraulic_comps (Sequence[Calculation]) – a subset of calculations in agr which interact with Kirchhoff. If it empty, the calculations contained in k’s flow graph are used.
inertial_comps (Sequence[Calculation]) – a subset of calculations in agr which require \(\ddot{m}\) from kirchhoff. This requires k to be KirchhoffWDerivatives.
ref_mdots (Sequence[Calculation]) – Calculations for which a reference current is desired. This list must be a subset of a list already known to k from its flow-graph.
abs_pressure_comps (Sequence[Hashable] or None) – Calculations for which the absolute pressure should be calculated.

Returns:

agr

Return type:

CalculationGraph

MTR Geometry

MTR: Material Test Reactors

In this context, MTR refers to a typical type of fuels, which comprise of several rectangular parallel plates in each rod, with coolant flowing between the plates.

The combination of calculations into an MTR-like setup, containing:

Fuel Plates
Coolant (T, incompressible scheme) channels on both sides.

The created objects are CalculationGraph objects which may be combined to eventually create an executable scheme.

chain_fuels_channels(channels, fuels)[source]

Build a setup of interchanging fuel plates and channels by order of appearance. This function is to be used for the following geometry only:

... Channel, Fuel, Channel, Fuel ...

Which is the case for MTR-like reactor rods.

Parameters:

channels (Sequence[ChannelAndContacts]) – Channels
fuels (Sequence[Fuel]) – Fuel Plates

Returns:

agr – whose time-functions are empty

Return type:

CalculationGraph

Raises:

ValueError – if the lengths of sequences does not allow interchanging (if difference is not +-1).

one_sided_connection(channel, fuel, fuel_side, funcs=None)[source]

Connects a single fuel to a single channel on one side

Important

In this connection, the fuel assumes it is connected on both sides to the channel, but the channel is connected only to one chosen fuel_side

Parameters:

channel (ChannelAndContacts) – The channel object to connect.
fuel (Fuel) – The fuel object to connect.

fuel_side ('left' or 'right') –

The side of the channel at which the fuel is placed. The following diagrams might help. Assume there are no previous connections for the fuel or channel. Therefore, a left case looks like this:

||          |            ||
||   Fuel   |   Channel  ||
||          |            ||

and a right case looks like this:

||             |         ||
||   Channel   |   Fuel  ||
||             |         ||

funcs (ExternalFunctions) – Functions of time to connect to fuel or channel.

Return type:

CalculationGraph

plate(channel_l, channel_r, fuel)[source]

Build a fuel “plate” setup and its surroundings using the following components:

Parameters:

channel_l (ChannelAndContacts) – Left coolant channel
channel_r (ChannelAndContacts) – Right coolant channel
fuel (Fuel) – (Central) Fuel region

Returns:

agr – An CalculationGraph whose time-funcs are empty

Return type:

CalculationGraph

rod(channel, channels, fuel, plates)[source]

Create a rod of interleaving channels and fuel plates, in which all channels, fuel plates are the same. This function utilizes chain_fuels_channels.

Parameters:

channel (ChannelAndContacts) – calculation which is to be constructed several times.
channels (int) – # of channels.
fuel (Fuel) – calculation which is to be constructed several times.
plates (int) – # of fuel plates.

Returns:

out – The connected CalculationGraph, created channels, created fuels.

Return type:

tuple[CalculationGraph, Sequence[ChannelAndContacts], Sequence[Fuel]]

Subsystems

Helper functions for creating steady state initial guesses for small and specific subsystems

exception GravityMismatchError[source]: Bases: ValueError

exception MissingFlowError[source]

Bases: Exception

Error to signify missing Kirchhoff flow data.

check_gravity_mismatch(k, temperature=10.0, strategy=None, tol=1e-05, head=1.0)[source]

Report if \(\sum_{loop}\Delta p(\dot{m}=0) \neq 0\) for any loop

Usually, if there are no flows at all and thermally equal, total pressure drops in loops should be trivially zero. If that’s not the case, it is probably due to gravity pressures of differing heights.

This is a tool to allow users to inspect their models for such glaring issues. It relies on guess_steady_state.

Parameters:

k (Kirchhoff) – Kirchhoff Calculation
temperature (Celsius) – Though quite unimportant, some temperature for the hydraulic calculation must be assumed.
strategy (dict[Calculation, Callable[[KgPerS, Celsius], Pascal]] | None) – For unknown calculations, pressure drop functions \(\Delta p(\dot{m}, T)\) may be provided. These are used when the Calculation isn’t identified as known types or protocols, and failing that, the guess is 0.0.
tol (float) – Tolerance for deciding total pressure drops. Default is 1e-5.
head (Pascal) – Convert units to meter head for convenience when checking height differences. Default output is in Pascal.

Raises:

GravityMismatchError –

Return type:

None

guess_hydraulic_steady_state(k, mdots, temperature, strategy=None)[source]

A guess for a Kirchhoff derived system, in which the flows are known

Note

When a component’s pressure difference cannot be physically determined from the flow, the guess is 0.0. Prominent examples are ideal flow sources such as Pump (mdot0=x) or a closed Flapper.

Parameters:

k (Kirchhoff) – Kirchhoff Calculation
mdots (dict[Calculation, KgPerS]) – Known mass flows \(\dot{m}\) for components in the hydraulic system. Supported Calculations are DPCalculation and Channel.
temperature (Celsius) – Assumed temperature for hydraulic calculations
strategy (dict[Calculation, Callable[[KgPerS, Celsius], Pascal]] | None) – For unknown calculations, pressure drop functions \(\Delta p(\dot{m}, T)\) may be provided. These are used when the Calculation isn’t identified as known types or protocols, and failing that, the guess is 0.0.

Returns:

A guess in which pressures are computed from the known flows, and the flows themselves.

Return type:

State

point_kinetics_steady_state(pk, power, power_input=None)[source]

Zero reactivity steady PointKinetics steady state

Parameters:

pk (PointKinetics) – a PK instance
power (Watt) – Desired power at which the reactor operates
power_input (Watt or None) – If another source of power (besides PK, e.g decay heat) contributes to total power (which should be provided at simulation time), the neutronic power generation is power - power_input. Note this only applies to PointKineticsWInput.

Returns:

steady – Assuming zero reactivity (criticality)

Return type:

State

symmetric_plate_steady_state(c, f, mdot, p_abs, power, Tin, initial_guess_iterations=2, **solver_options)[source]

Steady state for a symmetric_plate system

Parameters:

c (ChannelAndContacts) – A channel (and contacts…) instance
f (Fuel) – A fuel instance
mdot (KgPerS) – Desired mass current
p_abs (Pascal) – Desired absolute pressure at the top of the plate
power (Watt) – Desired power
Tin (Celsius) – Desired inlet temperature into the channel. Depending on the sign of mdot (+, -), the inlet temperature is a source term for the (first, last) cell.
initial_guess_iterations (int) – Before employing a solver, an initial educated guess is assumed. This guess should become better educated with each iteration controlled by precondition
solver_options (Dict) – Keyword arguments to control steady state solver behavior

Returns:

steady

Return type:

State

Calculation Constructors

Various alternative constructors for some calculations

Calculation_factory(calculate, mass_vector, variables, unpack=True)[source]

A simple Calculation factory.

This factory does not support non-default methods load, save, should_continue.

Parameters:

calculate (Functional) – See calculate
mass_vector (Sequence[bool]) – See mass_vector
variables (dict[str, Place]) – See variables
unpack (bool or None) – Whether unpacked should be applied to calculate. Default is True.

Returns:

class – A Calculation class

Return type:

Callable

ResistorFromKnownPoint(dp=None, mdot=None, behavior='parabolic', name=None, **kwargs)[source]

Construct a resistor to flow from a known point in the \((\Delta p, \dot{m})\) phase space.

Parameters:

dp (Pascal or None) – Known pressure difference
mdot (KgPerS or None) – Known mass current
behavior (Literal["constant", "linear", "parabolic"]) – Which \(\Delta p (\dot{m})\) dependence should the resistor have.
name (str or None) – Optional name, see Calculation

Returns:

A resistor guaranteed to be working at the desired phase point

Return type:

DPCalculation

Examples

>>> r = ResistorFromKnownPoint(-1.0, 1.0, "linear")
>>> r.dp_out(Tin=25., mdot=3.0)
-3.0
>>> r = ResistorFromKnownPoint(-1.0, behavior="constant")
>>> r.dp_out(Tin=25., mdot=3.0)
0.0

Addenda

Various additional helper functions are available:

maximally_coupled(*calculations, exclude=None)[source]

Connect calculations into an CalculationGraph as fully as possible through inspection. This is an opt-out way of constructing such connections, if you will.

Parameters:

calculations (Calculation) – The calculations to be connected
exclude (Callable[[str], bool], optional) – An exclusion strategy for variable names, that is True values are omitted.

Returns:

agr – Maximally coupled calculations

Return type:

CalculationGraph

Examples

>>> from stream.composition import Calculation_factory as factory
>>> Addition = factory(lambda y, *, x: y + x, [False], dict(y=0))
>>> Multiplication = factory(lambda x, *, y: x * y, [False], dict(x=0))
>>> add, mult = Addition(name="+"), Multiplication("*")
>>> maximally_coupled(add, mult).to_aggregator().external
{*: {'y': {+: 0}}, +: {'x': {*: 1}}}
>>> maximally_coupled(add, mult, exclude=lambda s: s=="x").to_aggregator().external
{*: {'y': {+: 0}}}