DesignOfExperiments

(class from pyomo.contrib.doe.doe)

class pyomo.contrib.doe.doe.DesignOfExperiments(experiment=None, fd_formula='central', step=0.001, objective_option='determinant', use_grey_box_objective=False, scale_constant_value=1.0, scale_nominal_param_value=False, prior_FIM=None, jac_initial=None, fim_initial=None, L_diagonal_lower_bound=1e-07, solver=None, grey_box_solver=None, tee=False, grey_box_tee=False, get_labeled_model_args=None, logger_level=30, improve_cholesky_roundoff_error=False, _Cholesky_option=True, _only_compute_fim_lower=True)

Bases: object

__init__(experiment=None, fd_formula='central', step=0.001, objective_option='determinant', use_grey_box_objective=False, scale_constant_value=1.0, scale_nominal_param_value=False, prior_FIM=None, jac_initial=None, fim_initial=None, L_diagonal_lower_bound=1e-07, solver=None, grey_box_solver=None, tee=False, grey_box_tee=False, get_labeled_model_args=None, logger_level=30, improve_cholesky_roundoff_error=False, _Cholesky_option=True, _only_compute_fim_lower=True)

This package enables model-based design of experiments analysis with Pyomo. Both direct optimization and enumeration modes are supported.

The package has been refactored from its original form as of August 24. See the documentation for more information.

Parameters:

• experiment –

  Experiment object that holds the model and labels all the components. The object should have a get_labeled_model where a model is returned with the following labeled sets:

  • unknown_parameters,

  • experimental_inputs,

  • experimental_outputs

• fd_formula – Finite difference formula for computing the sensitivity matrix. Must be one of [central, forward, backward], default: central

• step – Relative step size for the finite difference formula. default: 1e-3

• objective_option – String representation of the objective option. Current available options are: - determinant (for determinant, or D-optimality), - trace (for trace of covariance matrix, or A-optimality), - pseudo_trace (for trace of Fisher Information Matrix(FIM), or pseudo A-optimality), - minimum_eigenvalue, (for E-optimality), or condition_number (for ME-optimality) Note: E-optimality and ME-optimality are only supported when using the grey box objective (i.e., grey_box_solver is True) default: determinant

• use_grey_box_objective – Boolean of whether or not to use the grey-box version of the objective function. True to use grey box, False to use standard. Default: False (do not use grey box)

• scale_constant_value – Constant scaling for the sensitivity matrix. Every element will be multiplied by this scaling factor. default: 1

• scale_nominal_param_value – Boolean for whether or not to scale the sensitivity matrix by the nominal parameter values. Every column of the sensitivity matrix will be divided by the respective nominal parameter value. default: False

• prior_FIM – 2D numpy array representing information from prior experiments. If no value is given, the assumed prior will be a matrix of zeros. This matrix will be assumed to be scaled as the user has specified (i.e., if scale_nominal_param_value is true, we will assume the FIM provided here has been scaled by the parameter values)

• jac_initial – 2D numpy array as the initial values for the sensitivity matrix.

• fim_initial – 2D numpy array as the initial values for the FIM.

• L_diagonal_lower_bound – Lower bound for the values of the lower triangular Cholesky factorization matrix. default: 1e-7

• solver – A solver object specified by the user, default=None. If not specified, default solver is set to IPOPT with MA57.

• tee – Solver option to be passed for verbose output.

• get_labeled_model_args – Additional arguments for the get_labeled_model function on the Experiment object.

• improve_cholesky_roundoff_error – Boolean value of whether or not to improve round-off error. If True, it will apply M[i,i] >= L[i,j]^2. Where, M is the FIM and L is the lower triangular matrix from Cholesky factorization. If the round-off error is not significant, this option can be turned off to improve performance by skipping this constraint.

• _Cholesky_option – Boolean value of whether or not to use the cholesky factorization to compute the determinant for the D-optimality criteria. This parameter should not be changed unless the user intends to make performance worse (i.e., compare an existing tool that uses the full FIM to this algorithm)

• _only_compute_fim_lower – If True, only the lower triangle of the FIM is computed. This parameter should not be changed unless the user intends to make performance worse (i.e., compare an existing tool that uses the full FIM to this algorithm)

• logger_level – Specify the level of the logger. Change to logging.DEBUG for all messages.

Methods

__init__([experiment, fd_formula, step, ...])	This package enables model-based design of experiments analysis with Pyomo.
check_model_FIM([model, FIM])	Checks if the specified matrix, FIM, matches the shape expected from the model.
check_model_jac([jac])
check_model_labels([model])	Checks if the model contains the necessary suffixes for the DoE model to be constructed automatically.
compute_FIM([model, method])	Computes the FIM for the experimental design that is initialized from the experiment`s get_labeled_model() function.
compute_FIM_full_factorial([model, ...])	Will run a simulation-based full factorial exploration of the experimental input space (i.e., a grid search or parameter sweep) to understand how the FIM metrics change as a function of the experimental design space.
create_doe_model([model])	Add equations to compute sensitivities, FIM, and objective.
create_grey_box_objective_function([model])
create_objective_function([model])	Generates the objective function as an expression and as a Pyomo Objective object
draw_factorial_figure([results, ...])	Extract results needed for drawing figures from the results dictionary provided by the compute_FIM_full_factorial function.
get_FIM([model])	Gets the FIM values from the model specified
get_experiment_input_values([model])	Gets the experiment input values (experimental design) from the model specified.
get_experiment_output_values([model])	Gets the experiment output values (y hat) from the model specified.
get_measurement_error_values([model])	Gets the experiment output values (sigma) from the model specified.
get_sensitivity_matrix([model])	Gets the sensitivity matrix (Q) values from the model specified.
get_unknown_parameter_values([model])	Gets the unknown parameter values (theta) from the model specified.
run_doe([model, results_file])	Runs DoE for a single experiment estimation.
run_multi_doe_sequential([N_exp])
run_multi_doe_simultaneous([N_exp])
update_FIM_prior([model, FIM])	Updates the prior FIM on the model object.
update_unknown_parameter_values([model, ...])

Member Documentation

check_model_FIM(model=None, FIM=None)

Checks if the specified matrix, FIM, matches the shape expected from the model. This method should only be called after the model has been probed for the length of the unknown parameter, experiment input, experiment output, and measurement error has been stored to the object.

Parameters:

• model (model for suffix checking, Default: None, (self.model))

• FIM (FIM value to check on the model)

check_model_labels(model=None)

Checks if the model contains the necessary suffixes for the DoE model to be constructed automatically.

Parameters:

model (model for suffix checking)

compute_FIM(model=None, method='sequential')

Computes the FIM for the experimental design that is initialized from the experiment`s get_labeled_model() function.

Parameters:

• model (model to compute FIM, default: None, (self.compute_FIM_model))

• method (string to specify which method should be used) – options are kaug and sequential

Returns:

computed FIM

Return type:

2D numpy array of the FIM

compute_FIM_full_factorial(model=None, design_ranges=None, method='sequential')

Will run a simulation-based full factorial exploration of the experimental input space (i.e., a grid search or parameter sweep) to understand how the FIM metrics change as a function of the experimental design space.

Parameters:

• model (DoE model, optional) – model to perform the full factorial exploration on

• design_ranges (dict) – dictionary of lists, of the form {<var_name>: [start, stop, numsteps]}

• method (str, optional) – to specify which method should be used. Options are kaug and sequential

Returns:

fim_factorial_results – A dictionary of the results with the following keys and their corresponding values as a list:

• keys of model’s experiment_inputs

• ”log10 D-opt”: list of log10(D-optimality)

• ”log10 A-opt”: list of log10(A-optimality)

• ”log10 pseudo A-opt”: list of log10(trace(FIM))

• ”log10 E-opt”: list of log10(E-optimality)

• ”log10 ME-opt”: list of log10(ME-optimality)

• ”eigval_min”: list of minimum eigenvalues

• ”eigval_max”: list of maximum eigenvalues

• ”det_FIM”: list of determinants

• ”trace_cov”: list of traces of covariance matrix

• ”trace_FIM”: list of traces of FIM

• ”solve_time”: list of solve times

Return type:

dict

Raises:

ValueError – If the design_ranges’ keys do not match the model’s experiment_inputs’ keys.

create_doe_model(model=None)

Add equations to compute sensitivities, FIM, and objective. Builds the DoE model. Adds the scenarios, the sensitivity matrix Q, the FIM, as well as the objective function to the model.

The function alters the model input.

In the single experiment case, model will be self.model. In the multi-experiment case, model will be one experiment to be enumerated.

Parameters:

model (model to add finite difference scenarios)

create_objective_function(model=None)

Generates the objective function as an expression and as a Pyomo Objective object

The function alters the model input.

In the single experiment case, model will be self.model. In the multi-experiment case, model will be one experiment to be enumerated.

Parameters:

model (model to add finite difference scenarios)

draw_factorial_figure(results=None, sensitivity_design_variables=None, fixed_design_variables=None, full_design_variable_names=None, title_text='', xlabel_text='', ylabel_text='', figure_file_name=None, font_axes=16, font_tick=14, log_scale=True)

Extract results needed for drawing figures from the results dictionary provided by the compute_FIM_full_factorial function.

Draw either the 1D sensitivity curve or 2D heatmap.

Parameters:

• results (dictionary, results dictionary from compute_FIM_full_factorial) – default: None (self.fim_factorial_results)

• sensitivity_design_variables (a list, design variable names to draw sensitivity)

• fixed_design_variables (a dictionary, keys are the design variable names to be) – fixed, values are the value of it to be fixed.

• full_design_variable_names (a list, all the design variables in the problem.)

• title_text (a string, name for the figure)

• xlabel_text (a string, label for the x-axis of the figure) – default: last design variable name In a 1D sensitivity curve, it should be design variable by which the curve is drawn In a 2D heatmap, it should be the second design variable in the design_ranges

• ylabel_text (a string, label for the y-axis of the figure) – default: None (1D); first design variable name (2D) A 1D sensitivity curve does not need it. In a 2D heatmap, it should be the first design variable in the dv_ranges

• figure_file_name (string or Path, path to save the figure as)

• font_axes (axes label font size)

• font_tick (tick label font size)

• log_scale (if True, the result matrix will be scaled by log10)

get_FIM(model=None)

Gets the FIM values from the model specified

Parameters:

model (model to grab FIM from, Default: None, (self.model))

Returns:

FIM

Return type:

2D list representation of the FIM (can be cast to numpy)

get_experiment_input_values(model=None)

Gets the experiment input values (experimental design) from the model specified.

Parameters:

model (model to grab the experimental design from,) – default: None, (self.model)

Returns:

d

Return type:

1D list of experiment input values (optimal or specified design)

get_experiment_output_values(model=None)

Gets the experiment output values (y hat) from the model specified.

Parameters:

model (model to grab y hat from,) – default: None, (self.model)

Returns:

y_hat

Return type:

1D list of experiment output values from the design experiment

get_measurement_error_values(model=None)

Gets the experiment output values (sigma) from the model specified.

Parameters:

model (model to grab sigma values from,) – default: None, (self.model)

Returns:

sigma_diag

Return type:

1D list of measurement errors used to design the experiment

get_sensitivity_matrix(model=None)

Gets the sensitivity matrix (Q) values from the model specified.

Parameters:

model (model to grab Q from, Default: None, (self.model))

Returns:

Q

Return type:

2D list representation of the sensitivity matrix (can be cast to numpy)

get_unknown_parameter_values(model=None)

Gets the unknown parameter values (theta) from the model specified.

Parameters:

model (model to grab theta from,) – default: None, (self.model)

Returns:

theta – this experiment was designed

Return type:

1D list of unknown parameter values at which

run_doe(model=None, results_file=None)

Runs DoE for a single experiment estimation. Can save results in a file based on the flag.

Parameters:

• model (model to run the DoE, default: None (self.model))

• results_file (string name of the file path to save the results) – to in the form of a .json file default: None –> don’t save

update_FIM_prior(model=None, FIM=None)

Updates the prior FIM on the model object. This may be useful when running a loop and the user doesn’t want to rebuild the model because it is expensive to build/initialize.

Parameters:

• model (model where FIM prior is to be updated, Default: None, (self.model))

• FIM (2D np array to be the new FIM prior, Default: None)