A toy example using MUM-PCE¶

This toy model is designed to demonstrate the entire workflow for MUM-PCE. It contains a set of measurements and applications that have hard-wired dependencies on a set of parameters, which guarantees that their response surfaces will take a particular form. This model contains measurements that are known to be outliers and also measurements that poorly constrain the model, thus providing an example of the functionality of MUM-PCE. This document explains how the model is developed, how the initialization function interacts with the model to create measurements, and how these entities interact with a MUM-PCE Project.

In addition, Example usage and output is provided which shows the complete workflow of the toy project:

Defining models¶

The models used in the toy example are defined by the equation,

\[y = A \prod_i k_i p_i\]

This equation is equivalent to \(\ln y = a^\text{T}x + z\) where \(x_i = \ln p_i\), \(a_i = \ln k_i\), and \(z = \ln A\). The parameters \(p_i\) are initially all set to 1, so that the nominal response of the model is equal to \(A\). Consequently, the response surface will be identical to model.

A toy_model object can be created directly:

experiment_number = 0
my_model = toy_model(experiment_number)

Tip

This usage is not the normal way of calling MUM-PCE. One would normally use an initialization function to create a batch of Measurement and Model objects at once.

Calling the my_model.evaluate() method of the toy model returns \(y\). Calling my_model.sensitivity() will return \(y\) and also the sensitivity vector \(S_i = d\ln y/d\ln k_i\), which is equal to \(a_i\) to within numerical error. my_model.sensitivity() has the sensitivity perturbation as a parameter, and the smaller this value is, the closer \(S\) will be to \(a\).

my_model.evaluate()

1.2214027581601699

V,S = my_model.sensitivity(0.0000001)

Value =  1.22140275816
Param  Value+       Value-           Sensitivity
1.22140e+00   1.22140e+00   1.0000e+00
1.22140e+00   1.22140e+00   6.0000e-01
1.22140e+00   1.22140e+00   4.0000e-01
1.22140e+00   1.22140e+00   1.0000e-01
1.22140e+00   1.22140e+00   3.0000e-02
1.22140e+00   1.22140e+00   1.0000e-02
1.22140e+00   1.22140e+00   2.0000e-02

Note

The sensitivity output shown above is printed to the log file and also to the screen.

Calling my_model.get_parameter_info() returns a list of dictionaries that has information about the model parameters. The keys of this dictionary are the number of the parameter and its name; the names are (imaginatively) Parameter 1 through Parameter 7. As an example:

my_model.get_model_parameter_info()

array([{'parameter_number': 0, 'parameter_name': 'Parameter 1'},
       {'parameter_number': 1, 'parameter_name': 'Parameter 2'},
       {'parameter_number': 2, 'parameter_name': 'Parameter 3'},
       {'parameter_number': 3, 'parameter_name': 'Parameter 4'},
       {'parameter_number': 4, 'parameter_name': 'Parameter 5'},
       {'parameter_number': 5, 'parameter_name': 'Parameter 6'},
       {'parameter_number': 6, 'parameter_name': 'Parameter 7'}], dtype=object)

The initialization function¶

The function toy_initialize() gives an example of how to instantiate measurements. This function reads an Excel file to determine the experimental database. The Excel file for the measurement list looks like the following:

Name                 Number  Value   Uncertainty
Experiment 1         0       0.4     0.05
Experiment 2         1       0.25    0.05
Experiment 3         2       0.2     0.05
Experiment 4         3       0.7     0.08
Experiment 5         4       0.4     0.8

The header row gives the names of each column, which will be parsed by toy_initialize(). Each row contains the simulation metadata for one measurement along with the relevant measurement data.

“Name” defines a unique text identifier for each measurement. This identifier is entirely freeform, but because file names will be derived from this name, all characters used in the name must be allowable by the file system. This name also defines whether toy_model or toy_app is used.

“Value” is the experimentally-measured value with which the simulation output is to be compared.

“Uncertainty” is the uncertainty in the experimentally-measured value.

“Number” is the only piece of simulation metadata for the toy model. This number is the experiment_number used when creating the toy_model or toy_app object.

Note

It is allowed to create a Measurement without a value or uncertainty, but it is not possible to optimize a model if any members of the measurement list do not have a value or an uncertainty.

The initialization function is called with the Excel experimental database as its argument:

my_measurements = mumpce.toy.toy_initialize('mumpce_toy_experiments.xlsx',mumpce.toy.toy_model)
my_apps = mumpce.toy.toy_initialize('mumpce_toy_apps.xlsx',mumpce.toy.toy_app)

This creates one list which has the measurements and another with the targeted applications.

Creating a Project¶

In its most simple form, a mumpce Project can be created by defining a measurement initialization function and some parameter uncertainties.

my_project = mumpce.Project(parameter_uncertainties=mumpce.toy.parameter_uncertainties,
                             initialize_function=mumpce.toy.toy_initialize)

This creates an almost-empty Project object that is ready to have its measurements initialized.

Initializing Measurements within the Project¶

If the Project has no measurements to begin with, the measurement and application lists can be created by the measurement_initialize() method

my_project.measurement_initialize('mumpce_toy_experiments.xlsx')
my_project.application_initialize('mumpce_toy_apps.xlsx')

Creating a Project with existing Measurements¶

If the measurement and application lists have already been created, the Project can then be created with the measurement and application lists as arguments

my_project = mumpce.Project(measurement_list=toy_measurements,
                          application_list=toy_apps,
                          model=mumpce.toy.toy_model,
                          parameter_uncertainties=mumpce.toy.parameter_uncertainties,
                          initialize_function=mumpce.toy.toy_initialize)

Solving the Project¶

The Project is now ready to be solved. The workflow described in Projects and Solutions can be followed from this point:

my_project.find_sensitivity()
my_project.find_active_parameters(sens_cutoff)
my_project.set_active_parameters()
my_project.run_optimization()
my_project.remove_inconsistent_measurements()
my_project.remove_low_information_measurements()

Function summary¶

Toy model class summary¶

`toy_initialize`(filename, model)	The initialization function for the toy model.
`toy_model`(experiment_number[, loglevel])	An example of a generic model for use with the MUMPCE program.
`toy_app`(experiment_number[, loglevel])	An example of a generic model for use with the MUMPCE program.

Initialization function¶

toy.toy_initialize(filename, model)¶

The initialization function for the toy model. This function shows how to instantiate a MUMPCE model object and then associate it with a MUMPCE measurement object. It will read an experimental database from an Excel file and use this information to build the measurement lists.

Parameters:	filename (str) – The file that contains the experimental database.
Returns:	measurement_list, a list of MUMPCE measurement objects
Return type:	list

Toy Model¶

`toy_model()` method summary¶

`toy_model`(experiment_number[, loglevel])	An example of a generic model for use with the MUMPCE program.
`toy_model.__str__`()	Returns the experiment number, which is the only thing interesting about this model
`toy_model.evaluate`()	Run the model once and return a single value
`toy_model.sensitivity`([perturbation, …])	Evaluate the sensitivity of the model value with respect to the model parameters
`toy_model.get_parameter`(parameter_id)	Retrieve a model parameter’s value
`toy_model.perturb_parameter`(parameter_id, factor)	Perturb a model parameter’s value by a specified amount.
`toy_model.reset_model`()	Reset all model parameters to their original values
`toy_model.get_model_parameter_info`()	Get information about the parameters, which will go up to the hosting measurement.

class toy.toy_model(experiment_number, loglevel=True)¶

An example of a generic model for use with the MUMPCE program.

This is a toy model where the response is given by \(\ln y = ax + z\), where \(x\) is the vector of parameters that can be perturbed, \(a\) is some sensitivity vector and \(z\) is some zero-order term. All of the parameters are nominally set to zero, with +/- 1 representing the upper and lower bounds of the prior uncertainty for these parameters.

The model has a matrix of five possible hard-wired \(z\) and \(a\) values. The experiment number corresponds to which pair is being used when the model is being instantiated.

Parameters:	experiment_number (int) – Which experiment (of five possible) this model represents
Returns:	A MUM-PCE model object representing this measurement

evaluate()¶

Run the model once and return a single value

Returns:	model_value

sensitivity(perturbation=0.001, parameter_list=None, logfile='file', **kwargs)¶

Evaluate the sensitivity of the model value with respect to the model parameters

Parameters:	perturbation (float) – The amount to perturb each parameter during the sensitivity analysis parameter_list (iterable) – The list of parameters to perturb. Usually this will be a list of parameter identifiers, which are usually ints or strs. logfile (str) – The logging file that will contain the sensitivity calculation output.
Returns:	model_value,sensitivity_vector

get_parameter(parameter_id)¶

Retrieve a model parameter’s value

Parameters:	parameter_id (int) – The parameter number whose value to retrieve
Returns:	parameter_value
Return type:	float

perturb_parameter(parameter_id, factor)¶

Perturb a model parameter’s value by a specified amount.

Parameters:	parameter_id – The parameter identifier whose value to modify factor (float) – The amount to change the parameter’s value.

reset_model()¶: Reset all model parameters to their original values

get_model_parameter_info()¶

Get information about the parameters, which will go up to the hosting measurement. This is called during instantiation of the model and normally would not be called at any other time.

Returns:	model_parameter_info
Return type:	list of dicts

class toy.toy_app(experiment_number, loglevel=True)¶

An example of a generic model for use with the MUMPCE program.

This is identical to toy.toy_model(), except that it is intended as an targeted application to highlight the experimental design functions. There are three possible hard-wired \(z\) and \(a\) values, which are different from those available in toy.toy_model()

Parameters:	experiment_number (int) – Which targeted application (of three possible) this model represents
Returns:	A MUM-PCE model object representing this experiment

evaluate()¶

Run the model once and return a single value

Returns:	model_value

A toy example using MUM-PCE¶

Defining models¶

The initialization function¶

Creating a Project¶

Initializing Measurements within the Project¶

Creating a Project with existing Measurements¶

Solving the Project¶

Function summary¶

Toy model class summary¶

Initialization function¶

Toy Model¶

`toy_model()` method summary¶

Table of Contents

Search

A toy example using MUM-PCE¶

Defining models¶

The initialization function¶

Creating a Project¶

Initializing Measurements within the Project¶

Creating a Project with existing Measurements¶

Solving the Project¶

Function summary¶

Toy model class summary¶

Initialization function¶

Toy Model¶

toy_model() method summary¶

Table of Contents

Search

`toy_model()` method summary¶