Measurements and Models

Measurements

A Measurement represents a physical measurement. The Measurement object contains the following items:

  • A Model object that tells the Measurement how to simulate the actual physical measurement. This returns a single number.
  • The parametric model that contains the uncertain parameters.
  • A ResponseSurface object that contains information how the py:class:.Model varies with respect to the parameters in the parametric model.

The logic behind MUM-PCE is that a measurement is a single number. Calling the evaluate() method of the Measurement will call Model one time and return that number. This can be inefficient, especially if the Model objects actually contain many useful pieces of information.

Initializing measurements

The initialization function must be written by the user and will be specific to the user’s application. The toy model example toy_initialize() and the Cantera interface measurement_initialize_pd() provide examples for how a user might do this. Both examples use Pandas to read an Excel spreadsheet containing the experimental database. Each line of the spreadsheet must contain enough information to completely describe each simulation that is being performed. The initialization function reads this spreadsheet, creates a Model object to simulate the measurement, and then a Measurement object containing that Model.

Models and Response Surfaces

Defining models

The Model object is the interface between MUM-PCE and the user’s code The Model class provided with MUM-PCE is a template that the user can follow to interface their own code with MUM-PCE. It is defined as a with a set of abstract methods, and the intent is that the user’s own model class will be a subclass. The abstract methods must be overwritten by a subclass, or else there will be an error.

In order to be a valid model, the user’s model class must provide an evaluate() method that will return the model values \(y_i\) and a sensitivity() method that will return the sensitivity coefficients \(S_ij = d\ln y_i / d\ln x_j\). In addition, the class must provide methods that can retrive or perturb the parameters within the parametric model and also a list of dictionary-like containers that explain what the parameters are. More information is available in the documentation of Model.

Response Surfaces

The ResponseSurface object is the structure that the Project actually interacts with when it is calculating the constrained model. Its interface mimics that of Model, insofar as it has an evaluate() and sensitivity() method, which returns more or less the same information. This object will be created by

Function summary

Measurement method summary

Measurement([name, model, value, …]) A top level class for a measurement object
Measurement.__str__() Returns Name (Status): str(self.model)
Measurement.evaluate() Evaluates the model once and sets self.model_value to the returned value.
Measurement.evaluate_sensitivity([perturbation]) Conducts a sensitivity analysis on the model and storee the nominal value in self.model_value and the sensitivity in self.sensitivity_list
Measurement.make_response() Generates a sensitivity_analysis_based response surface for this measurement
Measurement.evaluate_response(x) Evaluates the response surface for this measurement.
Measurement.sensitivity_response(x) Evaluates the response surface and the response surface gradient for this measurement.
Measurement.evaluate_uncertainty(x, cov) Evaluates the response surface for this measurement and compute its uncertainty
Measurement.save() Saves a pickled representation of the measurement
Measurement.load() Loads the model value, sensitivity list, and response surface from disk.

Model method summary

Model This is the top-level class for a model object.
Model.__str__() Return some interesting information about the model
Model.evaluate() Runs the model once and return a single value
Model.sensitivity(perturbation, …) Evaluates the sensitivity of the model value with respect to the model parameters
Model.get_parameter(parameter_id) Retrieves a model parameter’s value
Model.perturb_parameter(parameter_id, new_value) Replaces a model parameter’s value by a new value.
Model.get_model_parameter_info(number_parameters) Gets information about the parameters, which will go up to the hosting measurement.

ResponseSurface method summary

ResponseSurface([zero_term, a_terms, …]) A top level class describing a polynomial response surface.
ResponseSurface.evaluate(x[, cov_x]) Evaluates the response surface
ResponseSurface.sensitivity(x) Evaluates the response surface and response surface gradient

Measurement class

class measurement.Measurement(name=None, model=None, value=None, uncertainty=None, active_parameters=None, parameter_uncertainties=None, response=None, response_type='linear', response_perturbation=0.3, model_value=None, sensitivity_list=None, comment=None)

A top level class for a measurement object

This class is intended to contain metadata for the measurement it defines as well as a simulation model and a response surface for optimization.

Parameters:
  • name (str) – The name of the measurement
  • comment (str) – An arbitrary text string describing the measurement
  • model (model object) – The simulation model
  • value (float) – The measured value from the experiment
  • uncertainty (float) – The uncertainty in the measured value
  • active_parameters (int list) – The list of active parameters for this simulation. Not normally defined at object creation
  • parameter_uncertainties (float list) – The list of uncertainties in the active parameters. Not normally defined at object creation
  • response (response surface object) – The response surface for this simulation. Not normally defined at object creation
  • response_type (str) – Whether the response is to be linear (‘linear’, \(y = a^{\text{T}}x + z\)) or logarithmic (‘log’, \(\ln y = a^{\text{T}}x + z\))
  • response_perturbation (float) – The perturbation in the parameters for response surface generation
  • model_value (float) – The computed value from the simulation model for this measurement
  • sensitivity_list (float list) – The list of sensitivities of the model value to each parameter
evaluate()

Evaluates the model once and sets self.model_value to the returned value.

Returns:model_value
evaluate_sensitivity(perturbation=0.05)

Conducts a sensitivity analysis on the model and storee the nominal value in self.model_value and the sensitivity in self.sensitivity_list

Parameters:perturbation (float) – The amount to perturb each parameter when conducting the sensitivity analysis
make_response()

Generates a sensitivity_analysis_based response surface for this measurement

evaluate_response(x)

Evaluates the response surface for this measurement.

Parameters:x (1d array) – The set of parameter values at which the surface must be evaluated
Returns:response
Return type:float
sensitivity_response(x)

Evaluates the response surface and the response surface gradient for this measurement.

Parameters:x (1d array) – The set of parameter values at which the surface must be evaluated
Returns:response,response_gradient
Return type:tuple
evaluate_uncertainty(x, cov)

Evaluates the response surface for this measurement and compute its uncertainty

Parameters:
  • x (1d array) – The set of parameter values at which the surface must be evaluated
  • cov (2d array) – The covariance matrix among the model parameters
Returns:

response,response_uncertainty
Return type:

tuple
save()

Saves a pickled representation of the measurement

load()

Loads the model value, sensitivity list, and response surface from disk. By default, they are loaded from the file ‘self.name’.npz

Generic model class

class model.Model

This is the top-level class for a model object. Methods are defined as abstract methods, which must be implemented as a subclass of model.

The following methods are abstract methods within this class and must all be defined in order

  • evaluate(): Returns the model value \(y\)
  • sensitivity(): Returns the sensitivity coefficients \(S_{ij} = \frac{d\ln y_i}{d\ln x_j}\)
  • get_parameter(): Takes a parameter ID and returns the value of the corresponding model parameter
  • perturb_parameter(): Takes a parameter ID and replaces the corrsponding value with a new value
  • reset model(): Resets all model parameter values to their default values.
  • get_model_parameter_info(): Returns a list of dicts containing, at least, the parameter’s name and possibly additional information
evaluate()

Runs the model once and return a single value

Returns:model_value
Return type:float
sensitivity(perturbation, parameter_list, logfile)

Evaluates 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 (array_like) – 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
Return type:

tuple of float and 1d array
get_parameter(parameter_id)

Retrieves a model parameter’s value

Parameters:parameter_id – The parameter identifier. This might be an int or a str or possibly another type, which will depend on the model.
Returns:parameter_value
Return type:float
perturb_parameter(parameter_id, new_value)

Replaces a model parameter’s value by a new value.

Parameters:
  • parameter_id – The parameter identifier. This might be an int or a str or possibly another type, which will depend on the model.
  • new_value (float) – The amount to change the parameters value.
get_model_parameter_info(number_parameters)

Gets 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

Response surface class

class response_surface.ResponseSurface(zero_term=None, a_terms=None, b_terms=None, c_terms=None, d_terms=None, active_parameters=None)

A top level class describing a polynomial response surface.

This class contains the methods for a response surface object. It largely parallels model() in that it has an evaluate() method which will return a value and a sensitivity() method which will return a value and a vector of sensitivities.

The response surface is assumed here to be a second order polynomial \(y = z + a^{\text{T}}x + x^{\text{T}}bx\)

Parameters:
  • zero_term (float) – The zero-order term of the response surface, \(z\)
  • a_terms (ndarray(float), len(active_parameters)) – The first order terms of the response surface, \(a\)
  • b_terms (ndarray(float), len(active_parameters)xlen(active_parameters)) – The second order terms of the response surface, \(b\)
  • c_terms (ndarray(float)) – The third order terms of the response surface (not implemented)
  • d_terms (ndarray(float), len(active_parameters)xlen(active_parameters)) – The estimated error in the second order terms of the response surface
  • active_parameters (ndarray(int)) – If the list of active paremeters differs from measurement to measurement, it would be specified here.
Todo:

implement active_parameters, implement c_terms
z = None

\(z\)

a = None

\(a\)

b = None

\(b\)

evaluate(x, cov_x=None)

Evaluates the response surface

Computes the response value \(y = z + a^{\text{T}}x + x^{\text{T}}bx\) If cov_x is supplied, returns the uncertainty \(\sigma^2 = a^{\text{T}}\Sigma a + 2\text{tr}((b\Sigma)^2)\)

Parameters:
  • x (ndarray(float), len(active_parameters)) – The parameter vector at which the response value is to be calculated
  • cov_x (ndarray(float), len(active_parameters)xlen(active_parameters)) – The covariance matrix among the parameters
Returns:

response_value: \(y = z + a^{\text{T}}x + x^{\text{T}}bx\) and computed_unc: \(\sigma^2 = a^{\text{T}}\Sigma a + 2\text{tr}((b\Sigma)^2)\) if cov_x is supplied
Return type:

tuple
sensitivity(x)

Evaluates the response surface and response surface gradient

Computes the response value \(y = z + a^{\text{T}}x + x^{\text{T}}bx\) and the response surface gradient \(\frac{dy}{dx} = a + 2bx\)

Parameters:x (ndarray(float), len(active_parameters)) – The parameter vector at which the response value is to be calculated
Returns:response_value: \(y = z + a^{\text{T}}x + x^{\text{T}}bx\) and response_gradient: \(\frac{dy}{dx} = a + 2bx\)
Return type:tuple