Model#

class Model(system, metrics=None, specification=None, parameters=None, retry_evaluation=True, exception_hook=None)[source]#

Create a Model object that allows for evaluation over a sample space.

Parameters:
  • system (System) – Should reflect the model state.

  • metrics (tuple[Metric]) – Metrics to be evaluated by model.

  • specification=None (Function, optional) – Loads specifications once all parameters are set. Specification should simulate the system as well.

  • params=None (Iterable[Parameter], optional) – Parameters to sample from.

  • exception_hook (callable(exception, sample)) – Function called after a failed evaluation. The exception hook should return either None or metric values given the exception and sample.

copy()[source]#

Return copy.

property exception_hook#

[callable(exception, sample)] Function called after a failed evaluation. The exception hook should return either None or metric values given the exception and sample.

property metrics#

tuple[Metric] Metrics to be evaluated by model.

metric(getter=None, name=None, units=None, element=None)[source]#

Define and register metric.

Parameters:
  • getter (function, optional) – Should return metric.

  • name (str, optional) – Name of metric. If None, defaults to the name of the getter.

  • units (str, optional) – Metric units of measure

  • element (object, optional) – Element being evaluated. Works mainly for bookkeeping. Defaults to ‘Biorefinery’.

Notes

This method works as a decorator.

load_samples(samples=None, optimize=None, file=None, autoload=None, autosave=None, distance=None)[source]#

Load samples for evaluation.

Parameters:
  • samples (numpy.ndarray, dim=2, optional) – All parameter samples to evaluate.

  • optimize (bool, optional) – Whether to internally sort the samples to optimize convergence speed by minimizing perturbations to the system between simulations. The optimization problem is equivalent to the travelling salesman problem; each scenario of (normalized) parameters represent a point in the path. Defaults to False.

  • file (str, optional) – File to load/save samples and simulation order to/from.

  • autosave (bool, optional) – Whether to save samples and simulation order to file (when not loaded from file).

  • autoload (bool, optional) – Whether to load samples and simulation order from file (if possible).

  • distance (str, optional) – Distance metric used for sorting. Defaults to ‘cityblock’. See scipy.spatial.distance.cdist for options.

  • algorithm (str, optional) – Algorithm used for sorting. Defaults to ‘nearest neighbor’. Note that neirest neighbor is a greedy algorithm that is known to result, on average, in paths 25% longer than the shortest path.

evaluate(notify=0, file=None, autosave=0, autoload=False, convergence_model=None, **kwargs)[source]#

Evaluate metrics over the loaded samples and save values to table.

Parameters:
  • notify=0 (int, optional) – If 1 or greater, notify elapsed time after the given number of sample evaluations.

  • file (str, optional) – Name of file to save/load pickled evaluation results.

  • autosave (int, optional) – If 1 or greater, save pickled evaluation results after the given number of sample evaluations.

  • autoload (bool, optional) – Whether to load pickled evaluation results from file.

  • convergence_model (ConvergencePredictionModel, optional) – A prediction model for accelerated system convergence. Defaults to no convergence model and the last solution as the initial guess for the next scenario. If a string is passed, a ConvergenceModel will be created using that model type.

  • kwargs (dict) – Any keyword arguments passed to biosteam.System.simulate().

Warning

Any changes made to either the model or the samples will not be accounted for when autoloading and may lead to misleading results.

metrics_at_baseline()[source]#

Return metric values at baseline sample.

evaluate_across_coordinate(name, f_coordinate, coordinate, *, xlfile=None, notify=0, notify_coordinate=True, multi_coordinate=False, convergence_model=None, f_evaluate=None)[source]#

Evaluate across coordinate and save sample metrics.

Parameters:
  • name (str or tuple[str]) – Name of coordinate

  • f_coordinate (function) – Should change state of system given the coordinate.

  • coordinate (array) – Coordinate values.

  • xlfile (str, optional) – Name of file to save. File must end with “.xlsx”

  • rule (str, optional) – Sampling rule. Defaults to ‘L’.

  • notify (bool, optional) – If True, notify elapsed time after each coordinate evaluation. Defaults to True.

  • f_evaluate (callable, optional) – Function to evaluate model. Defaults to evaluate method.

spearman_r(parameters=None, metrics=None, filter=None, **kwargs)[source]#

Return two DataFrame objects of Spearman’s rho and p-values between metrics and parameters.

Parameters:
  • parameters (Iterable[Parameter], optional) – Parameters to be correlated with metrics. Defaults to all parameters.

  • metrics (Iterable[Metric], optional) – Metrics to be correlated with parameters. Defaults to all metrics.

  • filter (Callable(x, y) -> x, y, or string, optional) –

    Function that accepts 1d arrays of x and y values and returns filtered x and y values to correlate. May also be one of the following strings:

    • ’none’: no filter

    • ’omit nan’: all NaN values are ignored in correlation

    • ’propagate nan’: NaN values return NaN correlation results

    • ’raise nan’: NaN values will raise a ValueError

  • **kwargs – Keyword arguments passed to scipy.stats.spearmanr().

pearson_r(parameters=None, metrics=None, filter=None, **kwargs)[source]#

Return two DataFrame objects of Pearson’s rho and p-values between metrics and parameters.

Parameters:
  • parameters (Iterable[Parameter], optional) – Parameters to be correlated with metrics. Defaults to all parameters.

  • metrics (Iterable[Metric], optional) – Metrics to be correlated with parameters. Defaults to all metrics.

  • filter (Callable(x, y) -> x, y, or string, optional) –

    Function that accepts 1d arrays of x and y values and returns filtered x and y values to correlate. May also be one of the following strings:

    • ’none’: no filter

    • ’omit nan’: all NaN values are ignored in correlation

    • ’propagate nan’: NaN values return NaN correlation results

    • ’raise nan’: NaN values will raise a ValueError

  • **kwargs – Keyword arguments passed to scipy.stats.pearsonr().

kendall_tau(parameters=None, metrics=None, filter=None, **kwargs)[source]#

Return two DataFrame objects of Kendall’s tau and p-values between metrics and parameters.

Parameters:
  • parameters (Iterable[Parameter], optional) – Parameters to be correlated with metrics. Defaults to all parameters.

  • metrics (Iterable[Metric], optional) – Metrics to be correlated with parameters. Defaults to all metrics.

  • filter (Callable(x, y) -> x, y, or string, optional) –

    Function that accepts 1d arrays of x and y values and returns filtered x and y values to correlate. May also be one of the following strings:

    • ’none’: no filter

    • ’omit nan’: all NaN values are ignored in correlation

    • ’propagate nan’: NaN values return NaN correlation results

    • ’raise nan’: NaN values will raise a ValueError

  • **kwargs – Keyword arguments passed to scipy.stats.kendalltau().

kolmogorov_smirnov_d(parameters=None, metrics=None, thresholds=[], filter=None, **kwargs)[source]#

Return two DataFrame objects of Kolmogorov–Smirnov’s D and p-values with the given thresholds for the metrics.

For one particular parameter, all of the sampled values will be divided into two sets, one where the resulting metric value is smaller than or equal to the threshold, and the other where the resulting value is larger than the threshold.

Kolmogorov–Smirnov test will then be performed for these two sets of values for the particular parameter.

Parameters:
  • parameters (Iterable[Parameter], optional) – Parameters to be correlated with metrics. Defaults to all parameters.

  • metrics (Iterable[Metric], optional) – Metrics to be correlated with parameters. Defaults to all metrics.

  • thresholds (Iterable[float]) – The thresholds for separating parameters into sets.

  • filter (Callable(x, y) -> x, y, or string, optional) –

    Function that accepts 1d arrays of x and y values and returns filtered x and y values to correlate. May also be one of the following strings:

    • ’none’: no filter

    • ’omit nan’: all NaN values are ignored in correlation

    • ’propagate nan’: NaN values return NaN correlation results

    • ’raise nan’: NaN values will raise a ValueError

  • **kwargs – Keyword arguments passed to scipy.stats.kstest().

__call__(sample)[source]#

Return pandas Series of metric values at given sample.

show(p=None, m=None)[source]#

Return information on p-parameters and m-metrics.