Projects and Solutions

MUM-PCE is logically divided into projects. A project is represented by a Project object which contains the following items:

  • A list of Measurement objects which define the experimental database that will constrain the model parameters
  • A separate list of Measurement objects which define the application space of the model
  • A parametric model which defines the uncertain parameters that will be constrained by the measurements
  • A list of physics models implemented by Model objects which define how to use the parametric model to perform a calculation for each Measurement
  • An initialize_function() that will read outside data
  • A Solution object which contains the constrained parameters and a structure that defines their uncertainty

The intent of this implementation is that the user only ever interacts with the Project object. The user has to create the Model objects and also a suitable initialization function. Once this is done, however, Project has the necessary tools to evaluate the measurements, optimize the model, and perform the outlier and experimental design analyses.

Creating Projects

A blank Project can be instantiated with no arguments:

my_project = mumpce.Project()

This creates a Project with no measurement list, no intialization function, and no physics model of any kind. Such a project would not be very useful, and so normally the user would define a model object and some measurement initialization function:

my_project = mumpce.Project(initialize_function=my_initialize,
                            model=my_model,
                            parameter_uncertainties=my_uncertainty)

Initializing Measurements within the Project

A Project that has been created with an initialization function, as above, allows the initialization function to be accessed directly from the Project:

my_project.measurement_initialize('file_with_my_measurements.ext')

This call has the initialization function read the file ‘file_with_my_measurements.ext’ and then populate the measurement list.

Creating a Project with existing Measurements

Alternatively, the user can initialize the measurement list outside of the Project and then include that list as an argument when creating the Project:

my_measurements = my_initialize('file_with_my_measurements.ext',my_model)
my_applications = my_initialize('file_with_my_applications.ext',my_model)
my_project = mumpce.Project(measurement_list=my_measurements,
                            application_list=my_applications,
                            parameter_uncertainties=my_uncertainty)

Solving Projects to create Solutions

A Project that has a measurement list and parameter uncertainties is ready to be solved. The workflow is:

  • Perform sensitivity analysis on the measurements:

    my_project.find_sensitivity()

  • Find parameters with sensitivity greater than a cutoff value and define those as active:

    my_project.find_active_parameters(sens_cutoff)

  • Pass the active parameters to the measurements in the measurement list:

    my_project.set_active_parameters()

  • Calculate the response function for each measurement in the measurement list, used for the optimization:

    my_project.make_response()

  • Solve for the constrained model based on the response functions:

    my_project.run_optimization()

  • Identify and remove the inconsistent measurements:

    my_project.remove_inconsistent_measurements()

  • Identify and remove the measurements that do not constrain the model:

    my_project.remove_low_information_measurements()

This process will produce a ResponseSurface object within each Measurement and a Solution object associated with the Project as a whole.

Project method summary

Project([name, measurement_list, …]) This is the top level Project class for the MUM-PCE code.
Project.measurement_initialize(filename, …) Calls self.initialize_function() to create the measurement list.
Project.application_initialize(filename) Calls self.app_initialize_function() to create the application list.
Project.find_sensitivity() For each measurement in the measurement and application lists, evaluates and stores the sensitivity
Project.find_active_parameters(…) Determines the active parameters for this project based on the sensitivities of the measurements to the model parameters, weighted by the uncertainty factors
Project.set_active_parameters([…]) For each measurement in the measurement and application lists, sets the active parameter and parameter uncertainty lists to be the same as the Project’s.
Project.make_response() Creates the response surface for each measurement.
Project.run_optimization([initial_guess, …]) Finds the constrained model and its uncertainty and creates the Solution() object.
Project.validate_solution() Calculates predicted measurement values and uncertainties based on the constrained model.
Project.remove_inconsistent_measurements() Finds and removes inconsistent measurements
Project.calculate_entropy() Determines the rate of change of information entropy for each measurement with respect to the uncertainty in each other measurement.
Project.remove_low_information_measurements() Finds and removes low-information measurements
Project.plot_pdfs([factors_list]) Generates a plot of the joint probability density functions for several pairs of parameters.

Project class

class Project.Project(name=None, measurement_list=None, application_list=None, model=None, active_parameters=None, active_parameter_uncertainties=None, parameter_uncertainties=None, initialize_function=None, app_initialize_function=None, solution=None)

This is the top level Project class for the MUM-PCE code.

Parameters:
  • measurement_list (list of measurement objects) – The list of measurements that will constrain the model
  • application_list – The list of applications that will be targeted for experimental design
  • initialize_function (function) – A user-specified function that will read a database of experiments and create the measurement list. Stored in self.initialize_function()
  • app_initialize_function (function) – A user-specified function that will read a database of experiments and create the application list. Stored in self.app_initialize_function(). By default, it is the same as initialize_function
  • model (str) – The model that will be passed to the initialization function when creating the measurement list
  • active_parameters (int list) – The list of parameters in the model that will be optimized. Normally not defined at project creation.
  • active_parameter_uncertainties (float list) – The uncertainty factors of the active parameters. Normally not defined at project creation.
  • parameter_uncertainties (float list) – The uncertainty factors of all parameters in the model. Normally this is not provided as part of the model and must be specified separately.
  • solution (solution object) – The solution object generated by optimization and uncertainty constraint. Normally not defined at project creation.

A Project object is intended to contain a model, a set of measurements, and a version of that model that has been constrained against those experiments. Note that it is allowed to create a project object without specifying any parameter, instead defining them later.

The Project object acts as a container for the measurment and application lists. Measurements in either list can be accessed by number or by name, that is by calling:

Project[0]
Project["First experiment's name"]
measurement_list = None

The list of measurements that are part of this project

initialize_function = None

A user-specified function that will read a database of experiments and create the measurement list.

measurement_initialize(filename, **kwargs)

Calls self.initialize_function() to create the measurement list.

Parameters:filename (str) – The file containing the experimental database
application_list = None

The list of applications that will be used for experimental design

app_initialize_function = None

A user-specified function that will read a database of experiments and create the application list. Stored in self.app_initialize_function(). By default, it is the same as initialize_function

application_initialize(filename)

Calls self.app_initialize_function() to create the application list.

Parameters:filename (str) – The file containing the application database
find_active_parameters(sensitivity_cutoff)

Determines the active parameters for this project based on the sensitivities of the measurements to the model parameters, weighted by the uncertainty factors

Parameters:sensitivity_cutoff (float) – The sensitivity cutoff \(S_c\)


For each parameter \(i\) and measurement \(r\), an impact factor \(I_{i,r}\) is calculated as \(I_{i,r} = S_{i,r} \ln(f_i)\) where \(S_{i,r}\) is the sensitivity of the rth measurement to the ith parameter and \(f_i\) is the uncertainty factor of the ith parameter.

Active parameters are those such that \(I_{i,r} > \max_i(I_{i,r}) S_c\), where \(S_c\) is the sensitivity cutoff.

run_optimization(initial_guess=None, initial_covariance=None)

Finds the constrained model and its uncertainty and creates the Solution() object.

Parameters:
  • initial_guess – The prior parameter values. If not specified, the default is the zero vector
  • initial_covariance (numpy.ndarray, len(self.active_parameters) x len(self.active_parameters)) – The prior parameter covariance. If not specified, the default is \(I/4\), where I is the identity matrix

This function finds the optimal set of model parameters based on the experimental measurements and uncertainties provided in the measurement list. It uses the Levenberg-Marquardt algorithm to solve the optimization problem:

\[x_{\text{opt}} = \text{argmin}_x [\sum_i \frac{(y_i(x) - y_{i,\text{exp}})}{\sigma_{i,\text{exp}}} + (x - x_{\text{init}})^T\Sigma_{\text{init}}^{-1}(x - x_{in\text{init}it})]^2\]

and it estimates the uncertainty in the optimized parameters by linearizing the objective function and calculating the covariance matrix as:

\[\Sigma = [ \Sigma_{\text{init}}^{-1} + \sum_i \frac{J_j J_j^T}{\sigma_{i,\text{exp}}} ]^{-1}\]

where

  • \(x\) is the vector of model parameters
  • \(x_{\text{init}}\) is the vector of prior parameter values
  • \(y_{i,\text{exp}}\) is the measured value of the ith measurement
  • \(\sigma_{i,\text{exp}}\) is the uncertainty in the measured value of the ith measurement
  • \(y_i(x) = x^Tb_ix + a_i^Tx + z_i\) is the response-surface-predicted value of the ith measurement
  • \(J_i(x) = b_ix + a_i\) is the gradient of the ith response surface
  • \(\Sigma_{\text{init}}\) is the prior parameter covariance matrix
validate_solution()

Calculates predicted measurement values and uncertainties based on the constrained model.

Once the constrained model and associated uncertainty has been calculated, this method will evaluate the response surfaces for each measurement and calculate the corresponding uncertainty in the response-surface value based on the uncertainty in the constrained model. The response value is found by calculating \(y_i(x_{opt}\) and the uncertainty by calculating \(\sigma_{i,opt} = J_i^T\Sigma J_i\)

where \(J_i = 2b_ix_{\text{opt}} + a_i\) is the gradient of the ith response surface

In addition, the method will compare the measured values and uncertainties to the response-surface values and use this information to calculate the consistency scores, which are used in remove_inconsistent_measurements. The consistency score \(Z\) and weighted consistency score \(W\) are calculated as follows:

  • \(Z_i = \frac{(y_i(x_{\text{opt}}) - y_{i,\text{exp}})}{2 \sigma_{i,\text{exp}}}\)
  • \(W_i = \|Z_i\| (\frac{\sigma_{i,\text{exp}}}{\sigma_{i,\text{opt}}})^2\)

The method will then store these values as attributes of each measurement object.

calculate_entropy()

Determines the rate of change of information entropy for each measurement with respect to the uncertainty in each other measurement.

This function calculates the derivative \(\frac{d \ln \sigma_{i,opt}}{d \ln \sigma_{j,exp}}\) for each measurement pair. The derivative is calculated using

\[\frac{d \ln \sigma_{i,\text{opt}}}{d \ln \sigma_{j,\text{exp}}} = \frac{J_i^T\Sigma J_j J_j^T\Sigma J_i + 2 \text{tr}[2b_i \Sigma b_i \Sigma J_j J_j^T \Sigma] }{\sigma_{j,\text{exp}}^2\sigma_{i,\text{opt}}^2}\]

where \(J_i = 2b_ix_{\text{opt}} + a_i\) is the gradient of the ith response surface.

The entropy flux term is defined as

\[\Phi_i = \sum_j [\frac{d \ln \sigma_{j,\text{opt}}}{d \ln \sigma_{i,\text{exp}}} - \frac{d \ln \sigma_{i,\text{opt}}}{d \ln \sigma_{j,\text{exp}}}]\]
plot_pdfs(factors_list=[[0, 1]])

Generates a plot of the joint probability density functions for several pairs of parameters.

Parameters:factors_list (list of length-2 lists.) – A list of pairs of parameters. For each pair [x, y] the parameter x will appear on the x axis and the parameter y will appear on the y axis. If this parameter is not supplied, it defaults to [0,1].

Solution class

class solution.Solution(solution_x, covariance_x=None, second_order_x=None, initial_x=None, initial_covariance=None)

A top level class for a constrained model with uncertainty

Parameters:
  • solution_x (ndarray,float) – The solution vector
  • covariance_x (ndarray,float) – The covariance matrix among the elements of the solution vector
  • second_order_x – A structure describing the second order variation in the elements of the solution vector
x = None

The solution vector, \(x_{opt}\)

cov = None

The covariance matrix, \(\Sigma\)

alpha = None

The lower triangular decomposition \(\alpha\) where \(\Sigma = \alpha \alpha^{\text{T}}\)