emulation module

This module contains a class that implements the main emulation method.

class surmise.emulation.emulator(x=None, theta=None, f=None, method='PCGP', passthroughfunc=None, args={}, options={})

Bases: object

A class used to represent an emulator or surrogate model. Fits an emulator or surrogate model provided in emulationmethods/[method].py where [method] is the user option with default listed above.

Tip

To use a new emulator, just drop a new file to the emulationmethods/ directory with the required formatting.

Example:

emulator(x=x, theta=theta, f=f, method='PCGP', args=args)

Parameters:

• x (numpy.ndarray, optional) – An array of inputs. Each row should correspond to a row in f. The default is None. We will attempt to resolve size differences.

• theta (numpy.ndarray, optional) – An array of parameters. Each row in theta should correspond to a column in f. The default is None. We will attempt to resolve size differences.

• f (numpy.ndarray, optional) – An array of responses with ‘nan’ representing responses not yet available. The default is None. Each column in f should correspond to a row in x. Each row should correspond to a row in f. We will attempt to resolve if these are flipped.

• method (str, optional) – A string that points to the file located in emulationmethods/. The default is PCGP.

• passthroughfunc (function, optional) – DESCRIPTION. The default is None.

• args (dict, optional) – Optional dictionary containing options you would like to pass to [method].fit(x, theta, f, args) or [method].predict(x, theta, args) The default is {}.

• options (dict, optional) – Dictionary containing options you would like emulation to have. This does not get passed to the method. The default is {}.

Return type:

None.

fit(args=None)

Fits an emulator or surrogate and places that in emu._info

Calls emu._info = [method].fit(emu.__theta, emu.__f, emu.__x, args = args)

Parameters:

args (dict) – Optional dictionary containing options you would like to pass to fit function. It will add/modify those in self._args.

predict(x=None, theta=None, args={})

Fits an emulator or surrogate.

Example:

emulator.predict(x=x, theta=theta, args=args)

Parameters:

• x (numpy.ndarray, optional) – An array of inputs. Each row in x should correspond to a row in f. The default is None.

• theta (numpy.ndarray, optional) – An array of parameters. Each row should correspond to a column in f. The default is None.

• args (dict, optional) – A dictionary containing args. The default is {}.

Raises:

ValueError – If the dimensions of inputs do not match with the fitted emulator.

Returns:

An instance of emulation class prediction

Return type:

surmise.emulation.prediction

remove(x=None, theta=None, cal=None, options=None)

Removes either x or theta, and the corresponding f values from the fitted emulator, and refits the emulator.

Example:

emlator.remove(theta=theta)

Parameters:

• x (numpy.ndarray, optional) – x to remove from self.__x. The default is None.

• theta (numpy.ndarray, optional) – theta to remove from self.__theta. The default is None.

• cal (surmise.calibration.calibrator, optional) – A calibrator class instance as defined in surmise.calibration. The default is None.

• options (dict, optional) – A dictionary containing options to build the emulator. The default is None.

Return type:

None.

supplement(size, x=None, xchoices=None, theta=None, thetachoices=None, choicescost=None, cal=None, args=None, overwrite=False, removereps=None)

Chooses new theta or x to be investigated.

Important

A user must provide either x or theta (or cal).

Example:

emulator.supplement(size=size, theta=theta)

Parameters:

• size (int) –

  The number of new supplements to return.

  Note

  • If only theta is supplied, returns at most size of those.

  • If only x is supplied, returns at most size of those.

  • If both x and theta are supplied, then size will be less than the product of the number of returned theta and the number of x.

• x (numpy.ndarray, optional) – An array of parameters where to predict. The default is None.

• xchoices (numpy.ndarray, optional) –

  An array of inputs to select from. If not provided, a subset of x is used. The default is None.

  Warning

  self.__suppx has not developed yet.

• theta (numpy.ndarray, optional) – An array of parameters where to predict. The default is None.

• thetachoices (numpy.ndarray, optional) – An array of parameters to select from. If not provided, a subset of x is used. The default is None.

• choicescost (numpy.ndarray, optional) – An array of positive cost of each element in choice. The default is None.

• cal (surmise.calibration.calibrator, optional) – A calibrator object that contains information about calibration. The default is None.

• args (dict, optional) – A dictionary containing options to pass to the method. The default is None. If not provided, defaults to the one used to build the emulator.

• overwrite (boolean, optional) – True if an existing supplement is replaced. If False, and one exists, returns without doing anything. The default is False.

• removereps (boolean, optional) – True if any replications existing supplement is removed. The default is None. If not provided, defaults to the one used to build the emulator.

Raises:

ValueError – If the dimensions do not match the fitted emulator

Returns:

• numpy.ndarray – self.__thetasupp (or self.__x)

• numpy.ndarray – suppinfo

update(x=None, theta=None, f=None, args=None, options=None)

Updates and refits the emulator.

Example:

emulator.update(x=x)  # Replace self.__x with x

emulator.update(theta=theta)  # Replace self.__theta with theta

emulator.update(f=f)  # Replace self.__f with f if
                      # self.__supptheta is None. Otherwise,
                      # update self.__theta
                      # with (self.__theta, self.__supptheta)
                      # and self.__f with (self.__f, f)

emulator.update(x=x, f=f)  # Update self.__x with (self.__x, x)
                           # and self.__f with (self.__f, f)

emulator.update(theta=theta, f=f)  # Update self.__theta with
                                 # (self.__theta, theta) and
                                 # self.__f with (self.__f, f)

Warning

self.__suppx has not developed yet.

Parameters:

• x (numpy.ndarray, optional) – xs you would like to append. The default is None.

• theta (numpy.ndarray, optional) – thetas you would like to append. Defaults to emu.__supptheta. The default is None.

• f (numpy.ndarray, optional) – An array of responses. The default is None.

• args (dict, optional) – A dictionary containing options you would like to pass to [method].update(f, theta, x, args). Defaults to the one used to build the emulator.

• options (dict, optional) – A dictionary containing options to build the emulator. Modify with update when you want to change it. The default is None.

Raises:

ValueError – If the dimensions of inputs do not match with the existing emulator.

Return type:

None.

class surmise.emulation.prediction(_info, emu)

Bases: object

A class to represent an emulation prediction. predict._info returns the dictionary from the method.

Example:

prediction.mean()

prediction.var()

prediction.covx()

prediction.rnd()

covx(args=None)

Returns the covariance matrix at theta and x when building the prediction.

covxhalf(args=None)

Returns the sqrt of the covariance matrix at theta and x when building the prediction. That is, if this returns A = predict.covhalf(.)[k], then A.T @ A = predict.cov(.)[k]

covxhalf_gradtheta(args=None)

Returns the gradient of the covxhalf matrix at theta and x when building the prediction.

lpdf(f=None, args=None)

Returns a log pdf at theta and x

lpdf_gradtheta(f=None, args=None)

Returns a log pdf at theta and x

mean(args=None)

Returns the mean at theta and x in when building the prediction.

mean_gradtheta(args=None)

Returns the gradient of the mean at theta and x with respect to theta when building the prediction.

rnd(s=100, args=None)

Returns a rnd draws of size s at theta and x

var(args=None)

Returns the pointwise variance at theta and x when building the prediction.