Analysis

Reporting

A set of utilities for analysing an Aggregator system before solving or as part of a debugging process

report(agr, printer=Printer.JUPYTER)[source]

Print a report with useful information regarding an Aggregator

Parameters:

agr (Aggregator) – to be reported
printer (Printer | Literal["jupyter", "terminal", "raw"]) – Which method to use for printing the report. By default, we try to use IPython to display the report nicely inside a Jupyter notebook. The terminal option uses rich to display the report in simpler REPLs such as the Python REPL.

Return type:

None

Examples

>>> from stream import Aggregator
>>> from stream.composition import Calculation_factory as Factory
>>> A = Factory(lambda v, *, a = None, b: _, [True], dict(v=1))("A")
>>> B = Factory(lambda v, *, c = None, d: _, [True], dict(a=1, b=2))("B")
>>> report(Aggregator.from_decoupled(A, B, funcs={A: dict(b=0)}), "raw")
Contains 2 Equations, 2 Nodes, 0 Edges.

| Calculation | Type | Equation No. | Unset | Set Externally | Missing |
| :---------- | :--- | :----------- | :---- | :------------- | :------ |
| A | Constructed | 0 - 1 | a | b |  |
| B | Constructed | 1 - 2 | c, d |  | d |

Notes

What do Unset, Set Externally, Missing mean?

Unset: Variables which are requested by the calculate method and not present in the graph or external functions
Set Externally: Variables which are not provided by the calculation graph, but by external functions.
Missing: Variables which are requested by the calculate method and not present in the graph or external functions, and do not have a default value. If an Aggregator has a non-empty Missing column, the simulation is expected to crash.

Tools for debugging Aggregators and States.

debug_derivatives(agr, guess)[source]

Return the application of the Aggregator’s functional on a guess, tagged.

For differential equations, this would be the derivative of that variable given this guess. For algebraic equations, this would be the residual of the appropriate equation. Since some variable’s algebraic equations aren’t actually equations on those variables (Mostly because of Kirchhoff’s unknown cycle base this would happen for some of the mass flow rate variables, but other cases may exist as well).

Parameters:

agr (Aggregator) – The Aggregator to test.
guess (State) – The state to use as a guess for steady state.

Return type:

State

debug_guess_flows(agr, guess)[source]

Shows the errors in flows from all Kirchhoffs for a guesstimate.

Parameters:

agr (Aggregator) – The Aggregator to debug.
guess (State) – The State we guesstimate as the solution.

Return type:

dict[str, float | ndarray]

debug_guess_pressures(agr, guess, *, variables={'pressure'})

Show the errors in a variable’s guesstimate across all calculations.

This is a subset of debug_derivatives, since that debug tool shows a lot of data all at once.

Parameters:

agr (Aggregator) – The Aggregator to debug.
guess (State) – The State we guesstimate as the solution.
variables (Container[str]) – The variables we want to debug for.

Return type:

dict[str, float | ndarray]

debug_guess_variables(agr, guess, variables)[source]

Show the errors in a variable’s guesstimate across all calculations.

This is a subset of debug_derivatives, since that debug tool shows a lot of data all at once.

Parameters:

agr (Aggregator) – The Aggregator to debug.
guess (State) – The State we guesstimate as the solution.
variables (Container[str]) – The variables we want to debug for.

Return type:

dict[str, float | ndarray]

Uncertainty Quantification

Uncertainty quantification analysis tools.

class DASKUQModel(parameters, model, *features, feature_length=None, persist=False, step_strategy=<function default_deriv_step>)[source]

A UQ model which is computed asynchronously, using DASK.

The functions given to this object for the model creation and model features should be delayed in advance, and where possible, mark them as pure and with a correct nout. The reason we don’t just do this ourselves is that we want a mapping of DASKUQModels that use the same function but with a different set of parameters to realize that they are actually the same function.

It is also preferred to let people do their own delaying, so we don’t get an accidental double-delay.

Parameters:

parameters (dict[str, Value]) – The nominal model parameters. Must match the parameters of the features and model factory.
model (Model) – The Model of the problem, which takes parameter values and returns a DataFrame.
features (DelayedModel) – Functions that take a model and the set of creation parameters and return DataFrames with the format used by the Aggregator (have calculation, variable, i, j, and so on). Rows from different DataFrames given by features should be distinct, meaning that they should have a different value somewhere that isn’t the “value” column.
persist (bool) – Whether values should persist by default. Defaults to False.
feature_length (int) – The length of a nominal solution for all the features. Used to set the length of the jacobian when the nominal solution does not converge.
step_strategy (Callable[[Value], Array1D]) – A strategy for deciding how big a perturbation step to take. This should be a small positive value, usually.

evaluate(**parameters)[source]

Evaluate the solver with different parameter values.

Return type:: Delayed

subjacobian(param, persist=None)[source]

Derive the Jacobian matrix of derivation by a single input parameter.

See also

UQModel.subjacobian

Parameters:

param (str) – Parameter to perform the derivation by. Must be in parameters.
persist (bool) – Flag for whether to persist the result or not (caching). Defaults to the attribute value of this object.

Returns:

A 2D matrix of the Jacobian submatrix for the output in regard to the given parameter

Return type:

Array2D

uq(persist=None, **uncertainties)[source]

Performs the uncertainty quantification of the model for a given set of uncertainties. Assumes the uncertainties of different parameters are independent.

Parameters:

persist (bool) – Flag for whether to persist the result or not (caching).
uncertainties (Uncertainty) – The uncertainties in each parameter to include in the analysis. Keys must be names of parameters of the model. Any parameter in the model that isn’t listed is considered to have zero uncertainty.

Returns:

The systematic and statistical uncertainty in each output parameter for the given input uncertainties.

Return type:

tuple[Value, Value]

uq_attach(persist=None, **uncertainties)[source]

Performs the uncertainty quantification of the model for a given set of uncertainties, just like uq.

Unlike uq, it returns the nominal model output DataFrame where two columns are added: sys (systematic uncertainty) and stat (statistical uncertainty). Since this is a DaskUQModel, this is a delayed of said operation.

Parameters:

uncertainties (Uncertainty) – The uncertainties in each parameter to include in the analysis. Keys must be names of parameters of the model. Any parameter in the model that isn’t listed is considered to have zero uncertainty.
persist (bool)

Returns:

Nominal DataFrame with added uncertainty columns.

Return type:

Delayed

class UQModel(parameters, model, nominal=None, step_strategy=<function default_deriv_step>)[source]

This object performs the Jacobian analysis for numerical evaluation of the solution values against the model parameters.

Parameters:

parameters (dict[str, Value]) – The nominal model parameters. Must match the parameters of the model.
model (Model) – The Model of the problem, which takes parameter values and returns a DataFrame.
nominal (DataFrame) – The result of running the model on the default parameters. Defaults to running it on instantiation.
step_strategy (Callable[[Value], Array1D]) – A strategy for deciding how big a perturbation step to take. This should be a small positive value, usually.

evaluate(**parameters)[source]

Evaluate the solver with different parameter values.

Return type:: ndarray

subjacobian(param)[source]

Derive the Jacobian matrix of derivation by a single input parameter.

The Jacobian is computed through the simplest finite differences scheme, where schematically:

\[J_{ij}=\frac{df_i}{dx_j}=\frac{f_i(\mathbf{x_0}+h_j) -f_i(\mathbf{x_0})}{h_j}+\mathcal{O}(h_j)\]

Where \(\mathbf{x_0} + h_j\) means only the \(j\)-th index in \(\mathbf{x_0}\) is adjusted by \(h_j\).

Parameters:: param (str) – Parameter to perform the derivation by. Must be in parameters.
Returns:: A 2D matrix of the Jacobian submatrix for the output in regard to the given parameter
Return type:: Array2D

uq(**uncertainties)[source]

Performs the uncertainty quantification of the model for a given set of uncertainties. Assumes the uncertainties of different parameters are independent.

Parameters:: uncertainties (Uncertainty) – The uncertainties in each parameter to include in the analysis. Keys must be names of parameters of the model. Any parameter in the model that isn’t listed is considered to have zero uncertainty.
Returns:: The systematic and statistical uncertainty in each output parameter for the given input uncertainties.
Return type:: tuple[Value, Value]

uq_attach(**uncertainties)[source]

Performs the uncertainty quantification of the model for a given set of uncertainties, just like uq.

Unlike uq, it returns the nominal model output DataFrame where two columns are added: sys (systematic uncertainty) and stat (statistical uncertainty).

Parameters:: uncertainties (Uncertainty) – The uncertainties in each parameter to include in the analysis. Keys must be names of parameters of the model. Any parameter in the model that isn’t listed is considered to have zero uncertainty.
Returns:: Nominal DataFrame with added uncertainty columns.
Return type:: DataFrame

class Uncertainty(systematic_relative=0.0, statistical_relative=0.0, systematic_absolute=0.0, statistical_absolute=0.0)[source]

Describes perturbations, both statistical and systematic. In relation to a given variable \(x\) which, unperturbed, is denoted \(x_0\). The perturbed value is assumed to have the following distribution \(X\):

\[X \sim x_0 (1 + \mu_\text{sys, rel.}) \mathcal{N}(1, \sigma^2_\text{stat, rel.}) + \mathcal{N}(\mu_\text{sys, abs.}, \sigma^2_\text{stat, abs.})\]

Where \(\mu_\text{sys, rel.}\) defines a systematic relative uncertainty, \(\sigma_\text{stat, rel.}\) defines a statistical relative uncertainty, \(\mu_\text{sys, abs.}\) defines a systematic absolute uncertainty and \(\sigma_\text{stat, abs.}\) defines statistical absolute uncertainty

Parameters:

systematic_relative (float | ndarray)
statistical_relative (float | ndarray)
systematic_absolute (float | ndarray)
statistical_absolute (float | ndarray)

as_absolute(nominal)[source]

Returns an absolute representation of the systematic and statistical uncertainties.

Parameters:: nominal (Value) – The nominal value to use for the relative-to-absolute conversion.
Return type:: tuple[float | ndarray, float | ndarray]

Threshold Post-Processing

Tools for post-processing analysis of the thresholds for different phenomena in channels.

These tools are used to analyse the results in post-processing and add these thresholds to the analysed state. The pattern to use this is as follows:

>>> from functools import partial
>>> onb_left: ThresholdFunction = partial(Bergles_Rohsenow_T_ONB, direction=Direction.left)
>>> onb_right: ThresholdFunction = partial(Bergles_Rohsenow_T_ONB, direction=Direction.right)
>>> osv: ThresholdFunction = partial(Saha_Zuber_OSV, direction=Direction.left)
>>> post_analysis = threshold_analysis(CHF=Sudo_Kaminaga_CHF, OSV=osv, ONB_left=onb_left, ONB_right=onb_right)
>>> # agr = Aggregator(...)
>>> # state = agr.solve_steady(...)
>>> # state = post_analysis(state, agr, "channel")  # Given that "channel" is how the Channel is
>>> #                                               # called in agr

class ThresholdFunction(*args, **kwargs)[source]: A Protocol for how we expect our input functions to look like for the threshold_analysis_factory.

Bergles_Rohsenow_T_ONB(*, state, direction, onb_factor=1.0, inhomogeneity_factor=1.0, **_)[source]

A wrapper for Bergles_Rohsenow_T_ONB

The wall temperature at which ONB would occur according to Bergles and Rohsenow.

The fluid is set to light water because that’s what Bergles & Rohsenow is good for.

See also

Bergles_Rohsenow_T_ONB

Parameters:

state (CalcState) – The state of the channel
direction (Direction) – The direction in the channel we want to analyze.
onb_factor (float) – Relative uncertainty factor increase for the correlation to account for its uncertainty.
inhomogeneity_factor (float) – Relative factor by which the local flux must be factored to take fuel inhomogeneity into account.

Returns:

ONB_margin – T_wall - T_ONB

Return type:

Celsius

Fabrega_CHF(*, state, fluid, pipe, **_)[source]

A wrapper for the Fabrega_CHF function.

See also

Fabrega_CHF

Parameters:

state (State) – The channel state to analyze.
pipe (EffectivePipe) – The geometry of the flow channel.
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.

Returns:

The flux necessary at each point to have achieved CHF conditions given the rest of the channel stays as is.

Return type:

WPerM2

Mirshak_CHF(*, state, fluid, pipe, **_)[source]

A wrapper for the Mirshak_CHF function.

See also

Mirshak_CHF

Parameters:

state (State) – The channel state to analyze.
pipe (EffectivePipe) – The geometry of the flow channel.
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.

Returns:

The flux necessary at each point to have achieved CHF conditions given the rest of the channel stays as is.

Return type:

WPerM2

Saha_Zuber_OSV(*, state, fluid, pipe, dz, direction, inhomogeneity_factor=1.0, **_)[source]

A wrapper for Saha & Zuber based OSV.

For details, see the underlying Saha_Zuber_OSV.

See also

Saha_Zuber_OSV

Parameters:

state (State) – The channel state to analyze.
pipe (EffectivePipe) – The geometry of the flow channel.
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.
dz (Meter) – Cell length for each cell in the channel.
direction (Direction) – Which wall direction to take the power shape from.
inhomogeneity_factor (float) – Factor to make flux worse by locally (fuel inhomogeneity, usually).

Returns:

The flux which for the given local physical state would have caused OSV to occur there.

Return type:

WPerM2

Sudo_Kaminaga_CHF(*, state, fluid, pipe, gravity=9.80665, **_)[source]

A wrapper for the Sudo_Kaminaga_CHF function.

See also

Sudo_Kaminaga_CHF

Parameters:

state (State) – The channel state to analyze.
pipe (EffectivePipe) – The geometry of the flow channel.
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.
gravity (MPerS2) – Gravitational acceleration constant in the channel.

Returns:

The flux necessary at each point to have achieved CHF conditions given the rest of the channel stays as is.

Return type:

WPerM2

Whittle_Forgan_OFI(*, state, fluid, pipe, **_)[source]

A wrapper for the Whittle_Forgan_OFI function.

See also

Whittle_Forgan_OFI

Parameters:

state (State) – The channel state to analyze.
pipe (EffectivePipe) – The geometry of the flow channel.
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.

Returns:

The power necessary to achieve OFI conditions according to Whittle & Forgan with Fabrega.

Return type:

Watt

boiling_power(*, state, fluid, **__)[source]

A wrapper for the boiling_power function.

See also

boiling_power

Parameters:

state (CalcState) – The state of the channel
fluid (LiquidFuncs) – The functional properties of the fluid in the channel.

Returns:

The power required to reach the saturation temperature.

Return type:

Watt

threshold_analysis(**funcs)[source]

A factory to create a function that can analyze an aggregator’s State to yield a new State with threshold values.

Parameters:: funcs (ThresholdFunction) – Threshold value functions, named for their threshold.
Returns:: A function that adds threshold values to a state.
Return type:: Callable[[State, Aggregator, str], State]

transient_threshold_analysis(**funcs)[source]

A factory to create a function that can analyze an aggregator’s StateTimeseries to yield a new StateTimeseries with threshold values.

Parameters:: funcs (Callable[[State, EffectivePipe], Value]) – Threshold value functions, named for their threshold.
Returns:: A function that adds threshold values to a state.
Return type:: Callable[[StateTimeseries, Aggregator, str], StateTimeseries]

See also

threshold_analysis

twall_limit(*, state, inhomogeneity_factor=1.0, **_)[source]

A function that finds the limiting wall temperature.

We can’t just take the physical twall from the calculation because of fuel inhomogeneity, which isn’t taken into account in the physical solution.

Parameters:

state (CalcState) – The channel state to analyze.
inhomogeneity_factor (float) – Factor to make flux worse by locally (fuel inhomogeneity, usually).

Returns:

The maximal wall temperature for the wall temperature limit check

Return type:

Celsius