Acquisition Functions

Add one of these to your MOOP object to generate additional scalarizations per iteration. In general, ParMOO typically generates one candidate solution per simulation per acquisition function, so the number of acquisition functions determines the number of candidate simulations evaluated (in parallel) per iteration/batch.

from parmoo import acquisitions

It is also possible to define your own custom acquisition function by importing and extending the ABC

from parmoo.acquisitions.acquisition_function import AcquisitionFunction

The AcquisitionFunction ABC and current options from the existing acquisition function library are defined below.

AcquisitionFunction (ABC)

The ABC for AcquisitionFunction base class can be extended by developers looking to implement custom multiobjective acquisition functions.

The abstract base class (ABC) for AcquisitionFunction objects.

class acquisitions.acquisition_function.AcquisitionFunction(o, lb, ub, hyperparams)

ABC describing acquisition functions.

This class contains the following methods:

setTarget(data, penalty_func)
scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)
useSD()
save(filename)
load(filename)

abstract __init__(o, lb, ub, hyperparams)

Constructor for the AcquisitionFunction class.

Parameters:

o (int) – The number of objectives.
lb (ndarray) – A 1D array of lower bounds for the design space.
ub (ndarray) – A 1D array of upper bounds for the design space.
hyperparams (dict) – A dictionary of hyperparameters that are passed to the acquisition function.

Returns:

A new AcquisitionFunction object.

Return type:

AcquisitionFunction

abstract setTarget(data, penalty_func)

Set a new target value or region for the AcquisitionFunction.

Parameters:

data (dict) –
A dictionary specifying the current function evaluation database. It contains two mandatory fields:
- ’x_vals’ (ndarray): A 2D array of design points.
- ’f_vals’ (ndarray): A 2D array of corresponding objectives.
penalty_func (function) – A function of one (x) or two (x, sx) inputs that evaluates all (penalized) objective scores.

Returns:

A 1D array containing a feasible starting point for the scalarized problem.

Return type:

ndarray

useSD()

Query whether this method uses uncertainties.

When False, allows users to shortcut expensive uncertainty computations.

Default implementation returns True, requiring full uncertainty computation for applicable models.

abstract scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)

Scalarize a vector-valued function using the AcquisitionFunction.

Note: For best performance, make sure that jax can jit this method.

Additionally, for compatibility with gradient-based solvers, this method must be implemented in jax and be differentiable via the jax.jacrev() tool.

Parameters:

f_vals (ndarray) – A 1D array specifying a vector of function values to be scalarized.
x_vals (ndarray) – A 1D array specifying a vector the design point corresponding to f_vals.
s_vals_mean (ndarray) – A 1D array specifying the expected value of the simulation outputs for the x value being scalarized.
s_vals_sd (ndarray) – A 1D array specifying the standard deviation for each of the simulation outputs.

Returns:

The scalarized value.

Return type:

float

save(filename)

Save important data from this class so that it can be reloaded.

Note: If this function is left unimplemented, ParMOO will reinitialize a fresh instance after a save/load. If this is the desired behavior, then this method and the load method need not be implemented.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data should be saved.

load(filename)

Reload important data into this class after a previous save.

Note: If this function is left unimplemented, ParMOO will reinitialize a fresh instance after a save/load. If this is the desired behavior, then this method and the save method need not be implemented.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data has been saved.

Weighted Sum Methods

Implementations of the weighted-sum scalarization technique.

This module contains implementations of the AcquisitionFunction ABC, which use the weighted-sum technique.

The classes include:

UniformWeights (sample convex weights from a uniform distribution)
FixedWeights (uses a fixed scalarization, which can be set upon init)

class acquisitions.weighted_sum.UniformWeights(o, lb, ub, hyperparams)

Randomly generate scalarizing weights.

Generates uniformly distributed scalarization weights, by randomly sampling the probability simplex.

__init__(o, lb, ub, hyperparams)

Constructor for the UniformWeights class.

Parameters:

o (int) – The number of objectives.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) – A dictionary of hyperparameters for tuning the acquisition function.

Returns:

A new UniformWeights generator.

Return type:

UniformWeights

useSD()

Query whether this method uses uncertainties.

When False, allows users to shortcut expensive uncertainty computations.

setTarget(data, penalty_func)

Randomly generate a new vector of scalarizing weights.

Parameters:

data (dict) – A dictionary specifying the current function evaluation database.
penalty_func (function) – A function of one (x) or two (x, sx) inputs that evaluates the (penalized) objectives.

Returns:

A 1d array containing the ‘best’ feasible starting point for the scalarized problem (if any previous evaluations were feasible) or the point in the existing database that is most nearly feasible.

Return type:

numpy.ndarray

scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)

Scalarize a vector of function values using the current weights.

Parameters:

f_vals (numpy.ndarray) – A 1d array specifying the function values to be scalarized.
x_vals (np.ndarray) – A 1D array specifying a vector the design point corresponding to f_vals (unused by this method).
s_vals_mean (np.ndarray) – A 1D array specifying the expected simulation outputs for the x value being scalarized (unused by this method).
s_vals_sd (np.ndarray) – A 1D array specifying the standard deviation for each of the simulation outputs (unused by this method).

Returns:

The scalarized value.

Return type:

float

class acquisitions.weighted_sum.FixedWeights(o, lb, ub, hyperparams)

Use fixed scalarizing weights.

Use a fixed scalarization scheme, based on a fixed weighted sum.

__init__(o, lb, ub, hyperparams)

Constructor for the FixedWeights class.

Parameters:

o (int) – The number of objectives.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) –
A dictionary of hyperparameters for tuning the acquisition function. May contain the following key:
- ’weights’ (numpy.ndarray): A 1d array of length o that, when present, specifies the scalarization weights to use. When absent, the default weights are w = [1/o, …, 1/o].

Returns:

A new FixedWeights generator.

Return type:

FixedWeights

useSD()

Query whether this method uses uncertainties.

When False, allows users to shortcut expensive uncertainty computations.

setTarget(data, penalty_func)

Randomly generate a feasible starting point.

Parameters:

data (dict) – A dictionary specifying the current function evaluation database.
penalty_func (function) – A function of one (x) or two (x, sx) inputs that evaluates the (penalized) objectives.

Returns:

A 1d array containing the ‘best’ feasible starting point for the scalarized problem (if any previous evaluations were feasible) or the point in the existing database that is most nearly feasible.

Return type:

numpy.ndarray

scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)

Scalarize a vector of function values using the current weights.

Parameters:

f_vals (numpy.ndarray) – A 1d array specifying the function values to be scalarized.
x_vals (np.ndarray) – A 1D array specifying a vector the design point corresponding to f_vals (unused by this method).
s_vals_mean (np.ndarray) – A 1D array specifying the expected simulation outputs for the x value being scalarized (unused by this method).
s_vals_sd (np.ndarray) – A 1D array specifying the standard deviation for each of the simulation outputs (unused by this method).

Returns:

The scalarized value.

Return type:

float

Epsilon Constraint Methods

Implementations of the epsilon-constraint-style scalarizations.

This module contains implementations of the AcquisitionFunction ABC, which use the epsilon constraint method.

The classes include:

RandomConstraint (randomly set a ub for all but 1 objective)

class acquisitions.epsilon_constraint.RandomConstraint(o, lb, ub, hyperparams)

Improve upon a randomly set target point.

Randomly sets a target point inside the current Pareto front. Attempts to improve one of the objective values by reformulating all other objectives as constraints, upper bounded by their target value.

__init__(o, lb, ub, hyperparams)

Constructor for the RandomConstraint class.

Parameters:

o (int) – The number of objectives.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) – A dictionary of hyperparameters for tuning the acquisition function.

Returns:

A new RandomConstraint scalarizer.

Return type:

RandomConstraint

useSD()

Query whether this method uses uncertainties.

When False, allows users to shortcut expensive uncertainty computations.

setTarget(data, penalty_func)

Randomly generate a target based on current nondominated points.

Parameters:

data (dict) –
A dictionary specifying the current function evaluation database. It contains two mandatory fields:
- ’x_vals’ (numpy.ndarray): A 2d array containing the list of design points.
- ’f_vals’ (numpy.ndarray): A 2d array containing the corresponding list of objective values.
penalty_func (function) – A function of one (x) or two (x, sx) inputs that evaluates the (penalized) objectives.

Returns:

A 1d array containing the ‘best’ feasible starting point for the scalarized problem (if any previous evaluations were feasible) or the point in the existing database that is most nearly feasible.

Return type:

numpy.ndarray

scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)

Scalarize a vector of function values using the current bounds.

Parameters:

f_vals (numpy.ndarray) – A 1d array specifying the function values to be scalarized.
x_vals (np.ndarray) – A 1D array specifying a vector the design point corresponding to f_vals (unused by this method).
s_vals_mean (np.ndarray) – A 1D array specifying the expected simulation outputs for the x value being scalarized (unused by this method).
s_vals_sd (np.ndarray) – A 1D array specifying the standard deviation for each of the simulation outputs (unused by this method).

Returns:

The scalarized value.

Return type:

float

class acquisitions.epsilon_constraint.EI_RandomConstraint(o, lb, ub, hyperparams)

Expected improvement of a randomly set target point.

Randomly sets a target point inside the current Pareto front. Attempts to improve one of the objective values by reformulating all other objectives as constraints, upper bounded by their target value. Uses surrogate uncertainties to maximize expected improvement in the target objective subject to constraints.

__init__(o, lb, ub, hyperparams)

Constructor for the RandomConstraint class.

Parameters:

o (int) – The number of objectives.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) –
A dictionary of hyperparameters for tuning the acquisition function. Including
- mc_sample_size (int): The number of samples to use for Monte Carlo integration (defaults to 10 * m ** 2).

Returns:

A new RandomConstraint scalarizer.

Return type:

RandomConstraint

useSD()

Query whether this method uses uncertainties.

When False, allows users to shortcut expensive uncertainty computations.

setTarget(data, penalty_func)

Randomly generate a target based on current nondominated points.

Parameters:

data (dict) –
A dictionary specifying the current function evaluation database. It contains two mandatory fields:
- ’x_vals’ (numpy.ndarray): A 2d array containing the list of design points.
- ’f_vals’ (numpy.ndarray): A 2d array containing the corresponding list of objective values.
penalty_func (function) – A function of one (x) or two (x, sx) inputs that evaluates the (penalized) objectives.

Returns:

A 1d array containing the ‘best’ feasible starting point for the scalarized problem (if any previous evaluations were feasible) or the point in the existing database that is most nearly feasible.

Return type:

numpy.ndarray

scalarize(f_vals, x_vals, s_vals_mean, s_vals_sd)

Scalarize a vector of function values using the current bounds.

Parameters:

f_vals (numpy.ndarray) – A 1d array specifying the function values to be scalarized.
x_vals (np.ndarray) – A 1D array specifying a vector the design point corresponding to f_vals (unused by this method).
s_vals_mean (np.ndarray) – A 1D array specifying the expected simulation outputs for the x value being scalarized (unused by this method).
s_vals_sd (np.ndarray) – A 1D array specifying the standard deviation for each of the simulation outputs (unused by this method).

Returns:

The scalarized value.

Return type:

float