ParMOO Core

These classes and helper functions define the core of ParMOO’s solver infrastructure and algorithms.

Serial MOOP Class

This is the main serial implementation for solving MOOPs with ParMOO.

from parmoo import MOOP

Use this class to define and solve a MOOP. Several of the core methods needed during setup and usage may be defined in the base class parmoo.core.moop_base.MOOP_base (defined below). The MOOP.solve(...) method will perform simulations serially for this class.

Contains the MOOP class for defining multiobjective optimization problems.

parmoo.moop.MOOP is the serial implementation of the MOOP_base class for defining and solving multiobjective optimization problems (MOOPs). Each MOOP object may contain several simulations, specified using dictionaries.

class core.moop.MOOP(opt_func, hyperparams=None)

Class for defining a multiobjective optimization problem (MOOP).

Upon initialization, supply a scalar optimization procedure and dictionary of hyperparameters using the default constructor:

MOOP.__init__(ScalarOpt, [hyperparams={}])

New: To fix the random seed, use the hyperparameter key “np_random_gen” and set either an int or numpy.random.Generator instance as the corresponding value.

Class methods are summarized below. Several of these methods may be fully or partially inherited from the parmoo.moop_base.MOOP_base super class.

To define the MOOP, add each design variable, simulation, objective, and constraint by using the following functions:

MOOP.addDesign(*args)

MOOP.addSimulation(*args)

MOOP.addObjective(*args)

MOOP.addConstraint(*args)

Next, define your solver.

Acquisition functions (used for scalarizing problems/setting targets) are added using:

MOOP.addAcquisition(*args)

When you are done defining a MOOP, it can be “compiled” to finalize the definition:

MOOP.compile()

After creating a MOOP, the following methods may be useful for getting the numpy.dtype of the input/output arrays:

MOOP.getDesignType()

MOOP.getSimulationType()

MOOP.getObjectiveType()

MOOP.getConstraintType()

To turn on checkpointing use:

MOOP.setCheckpoint(checkpoint, [filename="parmoo"])

ParMOO also offers logging. To turn on logging, activate INFO-level logging by importing Python’s built-in logging module.

If there is any pre-existing simulation data, it can be added by calling the following method, where (x, sx) are the design, output pair for the simulation “s_name”:

MOOP.updateSimDb(x, sx, s_name)

After defining the MOOP and setting up checkpointing and logging info, use the following method to solve the MOOP (serially):

MOOP.solve(iter_max=None, sim_max=None)

The following methods are used for solving the MOOP and managing the internal simulation/objective databases:

MOOP.checkSimDb(x, s_name)

MOOP.evaluateSimulation(x, s_name)

MOOP.addObjData(x, sx)

MOOP.iterate(k, ib=None)

MOOP.filterBatch(*args)

MOOP.updateAll(k, batch)

Finally, the following methods are used to retrieve data after the problem has been solved:

MOOP.getPF(format='ndarray')

MOOP.getSimulationData(format='ndarray')

MOOP.getObjectiveData(format='ndarray')

The following methods are used to save/load the current checkpoint (state):

MOOP.save([filename="parmoo"])
MOOP.load([filename="parmoo"])

__init__(opt_func, hyperparams=None)

Initializer for the MOOP class.

Parameters:

opt_func (SurrogateOptimizer) – A solver for the surrogate problems.
hyperparams (dict, optional) – A dictionary of hyperparameters for the opt_func, and any other procedures that will be used.

addDesign(*args)

Add a new design variables to the MOOP.

Parameters:

args (dict) –

Each argument is a dictionary representing one design variable. The dictionary contains information about that design variable, including:

’name’ (str, optional): The unique name of this design variable, which ultimately serves as its primary key in all of ParMOO’s databases. This is also how users should index this variable in all user-defined functions passed to ParMOO. If left blank, it defaults to “xi” where i= 1, 2, 3,… corresponds to the order in which the design variables were added.

’des_type’ (str): The type for this design variable. Currently supported options are:

’continuous’ (or ‘cont’ or ‘real’)

’categorical’ (or ‘cat’)

’integer’ (or ‘int’)

’custom’ – an Embedder class must be provided (below)

’raw’ – no re-scaling is performed: NOT RECOMMENDED

’lb’ (float): When des_type is ‘continuous’, ‘integer’, or ‘raw’ this specifies the lower bound for the range of values this design variable could take. This value must be specified, and must be strictly less than ‘ub’ (below) up to the tolerance (below).

’ub’ (float): When des_type is ‘continuous’, ‘integer’, or ‘raw’ this specifies the upper bound for the range of values this design variable could take. This value must be specified, and must be strictly greater than ‘lb’ (above) up to the tolerance (below) or by a whole numer for integer variables.

’des_tol’ (float): When des_type is ‘continuous’, this specifies the tolerance, i.e., the minimum spacing along this dimension, before two design values are considered to have equal values in this dimension. If not specified, the default value is epsilon * max(ub - lb, 1.0e-4).

’levels’ (int or list): When des_type is ‘categorical’, this specifies the number of levels for the variable (when int) or the names of each valid category (when a list). WARNING: If a list is given and the entries in the list do not have numeric types, then ParMOO will not be able to jit the extractor which will lead to seriously degraded performance.

’embedder’ (parmoo.embeddings.embedder.Embedder): When des_type is ‘custom’, this is a custom Embedder class, which maps the input to a point in the unit hypercube and reports the embedded dimension.

addSimulation(*args)

Add new simulations to the MOOP.

Append new simulation functions to the problem.

Parameters:

args (dict) –

Each argument is a dictionary representing one simulation function. The dictionary must contain information about that simulation function, including:

name (str, optional): The name of this simulation (defaults to sim{i}, where i = 1, 2, 3, … for the first, second, third, … simulation added to the MOOP).

m (int): The number of outputs for this simulation.

sim_func (function): An implementation of the simulation function, mapping from X -> R^m (where X is the design space). The interface should match: sim_out = sim_func(x).

search (GlobalSearch): A GlobalSearch object for performing the initial search over this simulation’s design space.

surrogate (SurrogateFunction): A SurrogateFunction object specifying how this simulation’s outputs will be modeled.

hyperparams (dict): A dictionary of hyperparameters, which will be passed to the surrogate and search routines. Most notably, the ‘search_budget’: (int) can be specified here.

addObjective(*args)

Add a new objective to the MOOP.

Append a new objective to the problem. The objective must be an algebraic function of the design variables and simulation outputs. Note that all objectives must be specified before any acquisition functions can be added.

Parameters:

*args (dict) –

Python dictionary containing objective function information, including:

’name’ (str, optional): The name of this objective (defaults to “obj” + str(i), where i = 1, 2, 3, … for the first, second, third, … simulation added to the MOOP).

’obj_func’ (function): An algebraic objective function that maps from X, S –> R, where X is the design space and S is the space of simulation outputs. Interface should match: cost = obj_func(x, sx) where the value sx is given by sx = sim_func(x) at runtime.

’obj_grad’ (function): Evaluates the gradients of obj_func wrt s and sx. Interface should match: dx, ds = obj_grad(x, sx) where the value sx is given by sx = sim_func(x) at runtime. The outputs dx and ds represent the gradients with respect to x and sx, respectively.

addConstraint(*args)

Add a new constraint to the MOOP.

Parameters:

args (dict) –

Python dictionary containing constraint function information, including:

’name’ (str, optional): The name of this constraint (defaults to “const” + str(i), where i = 1, 2, 3, … for the first, second, third, … constraint added to the MOOP).

’con_func’ or ‘constraint’ (function): An algebraic constraint function that maps from X, S –> R where X and S are the design space and space of aggregated simulation outputs, respectively. The constraint function should evaluate to zero or a negative number when feasible and positive otherwise. The interface should match: violation = con_func(x, sx) where the value sx is given by sx = sim_func(x) at runtime. Note that any constraint(x, sim_func(x), der=0) <= 0 indicates that x is feasible, while constraint(x, sim_func(x), der=0) > 0 indicates that x is infeasible, violating the constraint by an amount proportional to the output. It is the user’s responsibility to ensure that after adding all constraints, the feasible region is nonempty and has nonzero measure in the design space.

’con_grad’ (function): Evaluates the gradients of con_func wrt s and sx. Interface should match: dx, ds = con_grad(x, sx) where the value sx is given by sx = sim_func(x) at runtime. The outputs dx and ds represent the gradients with respect to x and sx, respectively.

addAcquisition(*args)

Add an acquisition function to the MOOP.

Parameters:

args (dict) –

Python dictionary of acquisition function info, including:

’acquisition’ (AcquisitionFunction): An acquisition function that maps from R^o –> R for scalarizing outputs.

’hyperparams’ (dict): A dictionary of hyperparameters for the acquisition functions. Can be omitted if no hyperparameters are needed.

iterate(k, ib=None)

Perform an iteration of ParMOO’s solver and generate candidates.

Generates a batch of suggested candidate points (design points) or (candidate point, simulation name) pairs and returns to the user for further processing. Note, this method may produce duplicates.

Parameters:

k (int) – The iteration counter (corresponding to MOOP.iteration).
ib (int, optional) – The index of the acquisition function to optimize and add to the current batch. Defaults to None, which optimizes all acquisition functions and adds all resulting candidates to the batch.

Returns:

A list of tuples (design points, simulation name) specifying the unfiltered list of candidates that ParMOO recommends for true simulation evaluations. Specifically:

The first entry in each tuple is a Python dictionary specifying the design point to evaluate.

The second entry in the tuple is the (str) name of the simulation to evaluate at the design point specified above.

Return type:

(list)

filterBatch(*args)

Filter a batch produced by ParMOO’s MOOP.iterate method.

Accepts one or more batches of candidate design points, produced by the MOOP.iterate() method and checks both the batch and ParMOO’s database for redundancies. Any redundant points (up to the design tolerance) are replaced by model improving points, using each surrogate’s Surrogate.improve() method.

Parameters:

*args (list of tuples) – The list of unfiltered candidates
method. (returned by the MOOP.iterate())

Returns:

A filtered list of tuples, matching the format of the MOOP.iterate() output, but with redundant points removed and suitably replaced.

Return type:

(list)

updateAll(k, batch)

Update all surrogates given a batch of freshly evaluated data.

Parameters:

k (int) – The iteration counter (corresponding to MOOP.iteration).
batch (list) – A list of ordered pairs (tuples), each specifying a design point that was evaluated in this iteration, whose format matches the output of MOOP.iterate().

solve(iter_max=None, sim_max=None)

Solve a MOOP using ParMOO.

If desired, be sure to turn on checkpointing before starting the solve, using:

MOOP.setCheckpoint(checkpoint, [filename="parmoo"])

and turn on INFO-level logging for verbose output, using:

`` import logging logging.basicConfig(level=logging.INFO,

[format=’%(asctime)s %(levelname)-8s %(message)s’,
datefmt=’%Y-%m-%d %H:%M:%S’])

``

Parameters:

iter_max (int) – The max limit for ParMOO’s internal iteration counter. ParMOO keeps track of how many iterations it has completed internally. This value k specifies the stopping criteria for ParMOO.
sim_max (int) – The max limit for ParMOO’s simulation database, i.e., the simulation evaluation budget.

MOOP Base Class

This is the abstract base class for defining MOOPs with ParMOO.

from parmoo.core.moop_base import MOOP_base

Extend this class to define a MOOP.

In order to solve a MOOP, you must provide an implementation including the MOOP.solve(...) and other undefined methods.

Contains the MOOP_base class defining multiobjective optimization problems.

parmoo.moop.MOOP_base is the base class for defining and solving multiobjective optimization problems (MOOPs). Each MOOP object may contain several simulations, specified using dictionaries. This class defines all private utilities and several setter/getter methods. The methods used for actually solving the MOOP must be defined in another instantiation of this class.

class core.moop_base.MOOP_base(opt_func, hyperparams=None)

ABC for defining a multiobjective optimization problem (MOOP).

The following public methods are defined herein, but may need to be extended by an implementation class:

Setters and problem definition:

MOOP.addDesign(*args)

MOOP.addSimulation(*args)

MOOP.addObjective(*args)

MOOP.addConstraint(*args)

MOOP.addAcquisition(*args)

MOOP.compile()

Getters:

MOOP.getDesignType()

MOOP.getSimulationType()

MOOP.getObjectiveType()

MOOP.getConstraintType()

Database lookups and evaluator utilities:

MOOP.updateSimDb(x, sx, s_name)

MOOP.checkSimDb(x, s_name)

MOOP.getPF(format='ndarray')

MOOP.getSimulationData(format='ndarray')

MOOP.getObjectiveData(format='ndarray')

MOOP.evaluateSimulation(x, s_name)

MOOP.addObjData(x, sx)

Checkpointing methods:

MOOP.setCheckpoint(checkpoint, [filename="parmoo"])

MOOP.save([filename="parmoo"])

MOOP.load([filename="parmoo"])

The following solver steps must be defined in another implementation class (subclass) of this:

MOOP.iterate(k, ib=None)

MOOP.filterBatch(*args)

MOOP.updateAll(k, batch)

MOOP.solve(iter_max=None, sim_max=None)

The following private methods are also implemented herein:

MOOP._embed(x)

MOOP._extract(x)

MOOP._embed_grads(x)

MOOP._pack_sim(sx)

MOOP._unpack_sim(sx)

MOOP._vobj_funcs(x, sx)

MOOP._vcon_funcs(x, sx)

MOOP._vpen_funcs(x, sx, cx)

MOOP._fit_surrogates()

MOOP._update_surrogates()

MOOP._set_surrogate_tr(center, radius)

MOOP._evaluate_surrogates(x)

MOOP._surrogate_uncertainty(x)

MOOP._evaluate_objectives(x, sx)

MOOP._obj_fwd(x, sx)

MOOP._obj_bwd(res, w)

MOOP._evaluate_constraints(x, sx)

MOOP._con_fwd(x, sx)

MOOP._con_bwd(res, w)

MOOP._evaluate_penalty(x, sx)

MOOP._pen_fwd(x, sx)

MOOP._pen_bwd(res, w)

__init__(opt_func, hyperparams=None)

Initializer for the MOOP class.

Parameters:

opt_func (SurrogateOptimizer) – A solver for the surrogate problems.
hyperparams (dict, optional) – A dictionary of hyperparameters for the opt_func, and any other procedures that will be used.

_extract(x)

Extract a design variable from an n-dimensional vector.

Parameters:: x (ndarray) – A 1D array of length n_latent containing the embedded design vector.
Returns:: A Python dictionary whose keys match the design variable names, and whose values contain design variable values.
Return type:: dict

_embed(x)

Embed a design input as a n-dimensional vector for ParMOO.

Parameters:: x (dict) – A Python dictionary whose keys match the design variable names, and whose values contain design variable values.
Returns:: A 1D array of length n_latent containing the embedded design vector.
Return type:: ndarray

_embed_grads(dx)

Embed a design input as a n-dimensional vector for ParMOO.

Parameters:: dx (dict) – A Python dictionary whose keys match the design variable names, and whose values contain the partials with respect to each of the design variables.
Returns:: A 1D array of length n_latent containing the embedded design vector.
Return type:: ndarray

_unpack_sim(sx)

Extract a simulation output from a m-dimensional vector.

Parameters:: sx (ndarray) – A 1D array of length m containing the vectorized simulation outputs.
Returns:: A dictionary with keys corresponding to simulation names and values corresponding to simulation outputs.
Return type:: dict

_pack_sim(sx)

Pack a simulation output into a m-dimensional vector.

Parameters:: sx (dict) – A dictionary with keys corresponding to simulation names and values corresponding to simulation outputs.
Returns:: A 1D ndarray of length m containing the vectorized simulation outputs.
Return type:: ndarray

_vobj_funcs(x, sx)

Jittable evaluation of all objectives from the feature space.

Parameters:

x (dict) – A Python dictionary containing the design point to evaluate.
sx (dict) – A Python dictionary containing the simulation outputs at x.

Returns:

A 1D array containing the result of the evaluation.

Return type:

ndarray

_vcon_funcs(x, sx)

Jittable evaluation of all constraints from the feature space.

Parameters:

x (dict) – A Python dictionary containing the design point to evaluate.
sx (dict) – A Python dictionary containing the simulation outputs at x.

Returns:

A 1D array containing the list of constraint violations at x, where a negative or zero score implies feasibility.

Return type:

ndarray

_vpen_funcs(x, sx, cx, lamx)

Jittable evaluation of all penalties from the feature space.

Parameters:

x (dict) – A Python dictionary containing the design point to evaluate.
sx (dict) – A Python dictionary containing the simulation outputs at x.
cx (float) – The aggregated constraint violations at x.
lamx (float) – The penalty parameter to apply.

Returns:

A 1D array containing the result of the evaluation.

Return type:

ndarray

_fit_surrogates(): Fit the surrogate models using the current sim databases.

_update_surrogates(): Update the surrogate models using the current sim databases.

_set_surrogate_tr(center, radius)

Alert the surrogate functions of a new trust region.

Parameters:

center (ndarray) – A 1D array containing the (embedded) coordinates of the new trust region center.
radius (ndarray or float) – The trust region radius.

_evaluate_surrogates(x)

Evaluate all simulation surrogates.

Parameters:: x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
Returns:: A 1D array containing the (packed) result of the surrogate model evaluations.
Return type:: ndarray

_surrogate_uncertainty(x)

Evaluate the standard deviation of the possible surrogate outputs.

Parameters:: x (ndarray) – A 1D array containing the (embedded) design point to evaluate the surrogate uncertainties at.
Returns:: A 1D array containing the standard deviation of the surrogate prediction at x.
Return type:: ndarray

_evaluate_objectives(x, sx)

Evaluate all objectives from the latent space.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

A 1D array containing the result of the evaluation.

Return type:

ndarray

_obj_fwd(x, sx)

Evaluate a forward pass over the objective functions.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

The first entry is a 1D array containing the result of the evaluation, and the second entry contains the extracted pair (xx, ssx).

Return type:

(ndarray, (ndarray, ndarray))

_obj_bwd(res, w)

Evaluate a backward pass over the objective functions.

Parameters:

res (tuple of ndarrays) – Contains extracted value of x and the unpacked value of sx computed during the forward pass.
w (ndarray) – Contains the adjoint vector for the computation succeeding the objective evaluation in the compute graph.

Returns:

A pair of 1D arrays containing the products w * jac(f wrt x) and w * jac(f wrt s), respectively.

Return type:

(ndarray, ndarray)

_evaluate_constraints(x, sx)

Evaluate the constraints from the latent space.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

A 1D array containing the list of constraint violations at x, where a negative or zero score implies feasibility.

Return type:

ndarray

_con_fwd(x, sx)

Evaluate a forward pass over the constraint functions.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

The first entry is a 1D array containing the constraint violations at x, and the second entry contains the extracted pair (xx, ssx).

Return type:

(ndarray, (ndarray, ndarray))

_con_bwd(res, w)

Evaluate a backward pass over the constraint functions.

Parameters:

res (tuple of ndarrays) – Contains extracted value of x and the unpacked value of sx computed during the forward pass.
w (ndarray) – Contains the adjoint vector for the computation succeeding the constraint evaluation in the compute graph.

Returns:

A pair of 1D arrays containing the products w * jac(c wrt x) and w * jac(c wrt s), respectively.

Return type:

(ndarray, ndarray)

_evaluate_penalty(x, sx)

Evaluate the penalized objective from the latent space.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

A 1D array containing the result of the objective evaluation with a penalty added for violated constraints.

Return type:

ndarray

_pen_fwd(x, sx)

Evaluate a forward pass over the penalized objective functions.

Parameters:

x (ndarray) – A 1D array containing the (embedded) design point to evaluate.
sx (ndarray) – A 1D array containing the (packed) simulation vector at x.

Returns:

The first entry is a 1D array containing the result of the evaluation, and the second entry contains the tuple (xx, ssx, activities) where xx and ssx are the extracted values of x and sx, and “activities” gives the active constraint penalties.

Return type:

(ndarray, tuple)

_pen_bwd(res, w)

Evaluate a backward pass over the penalized objective functions.

Parameters:

res (tuple of ndarrays) – Contains extracted value of x and the unpacked value of sx computed during the forward pass followed by a vector encoding the indices/penalties for the active constraints.
w (ndarray) – Contains the adjoint vector for the computation succeeding the penalty evaluation in the compute graph.

Returns:

A pair of 1D arrays containing the products w * jac(c wrt x) and w * jac(c wrt s), respectively.

Return type:

(ndarray, ndarray)

addDesign(*args)

Add a new design variables to the MOOP.

Parameters:

args (dict) –

Each argument is a dictionary representing one design variable. The dictionary contains information about that design variable, including:

’name’ (str, optional): The unique name of this design variable, which ultimately serves as its primary key in all of ParMOO’s databases. This is also how users should index this variable in all user-defined functions passed to ParMOO. If left blank, it defaults to “xi” where i= 1, 2, 3,… corresponds to the order in which the design variables were added.

’des_type’ (str): The type for this design variable. Currently supported options are:

’continuous’ (or ‘cont’ or ‘real’)

’categorical’ (or ‘cat’)

’integer’ (or ‘int’)

’custom’ – an Embedder class must be provided (below)

’raw’ – no re-scaling is performed: NOT RECOMMENDED

’lb’ (float): When des_type is ‘continuous’, ‘integer’, or ‘raw’ this specifies the lower bound for the range of values this design variable could take. This value must be specified, and must be strictly less than ‘ub’ (below) up to the tolerance (below).

’ub’ (float): When des_type is ‘continuous’, ‘integer’, or ‘raw’ this specifies the upper bound for the range of values this design variable could take. This value must be specified, and must be strictly greater than ‘lb’ (above) up to the tolerance (below) or by a whole numer for integer variables.

’des_tol’ (float): When des_type is ‘continuous’, this specifies the tolerance, i.e., the minimum spacing along this dimension, before two design values are considered to have equal values in this dimension. If not specified, the default value is epsilon * max(ub - lb, 1.0e-4).

’levels’ (int or list): When des_type is ‘categorical’, this specifies the number of levels for the variable (when int) or the names of each valid category (when a list). WARNING: If a list is given and the entries in the list do not have numeric types, then ParMOO will not be able to jit the extractor which will lead to seriously degraded performance.

’embedder’ (parmoo.embeddings.embedder.Embedder): When des_type is ‘custom’, this is a custom Embedder class, which maps the input to a point in the unit hypercube and reports the embedded dimension.

addSimulation(*args)

Add new simulations to the MOOP.

Append new simulation functions to the problem.

Parameters:

args (dict) –

Each argument is a dictionary representing one simulation function. The dictionary must contain information about that simulation function, including:

name (str, optional): The name of this simulation (defaults to sim{i}, where i = 1, 2, 3, … for the first, second, third, … simulation added to the MOOP).

m (int): The number of outputs for this simulation.

sim_func (function): An implementation of the simulation function, mapping from X -> R^m (where X is the design space). The interface should match: sim_out = sim_func(x).

search (GlobalSearch): A GlobalSearch object for performing the initial search over this simulation’s design space.

surrogate (SurrogateFunction): A SurrogateFunction object specifying how this simulation’s outputs will be modeled.

hyperparams (dict): A dictionary of hyperparameters, which will be passed to the surrogate and search routines. Most notably, the ‘search_budget’: (int) can be specified here.

addObjective(*args)

Add a new objective to the MOOP.

Append a new objective to the problem. The objective must be an algebraic function of the design variables and simulation outputs. Note that all objectives must be specified before any acquisition functions can be added.

Parameters:

*args (dict) –

Python dictionary containing objective function information, including:

’name’ (str, optional): The name of this objective (defaults to “obj” + str(i), where i = 1, 2, 3, … for the first, second, third, … simulation added to the MOOP).

’obj_func’ (function): An algebraic objective function that maps from X, S –> R, where X is the design space and S is the space of simulation outputs. Interface should match: cost = obj_func(x, sx) where the value sx is given by sx = sim_func(x) at runtime.

’obj_grad’ (function): Evaluates the gradients of obj_func wrt s and sx. Interface should match: dx, ds = obj_grad(x, sx) where the value sx is given by sx = sim_func(x) at runtime. The outputs dx and ds represent the gradients with respect to x and sx, respectively.

addConstraint(*args)

Add a new constraint to the MOOP.

Parameters:

args (dict) –

Python dictionary containing constraint function information, including:

’name’ (str, optional): The name of this constraint (defaults to “const” + str(i), where i = 1, 2, 3, … for the first, second, third, … constraint added to the MOOP).

’con_func’ or ‘constraint’ (function): An algebraic constraint function that maps from X, S –> R where X and S are the design space and space of aggregated simulation outputs, respectively. The constraint function should evaluate to zero or a negative number when feasible and positive otherwise. The interface should match: violation = con_func(x, sx) where the value sx is given by sx = sim_func(x) at runtime. Note that any constraint(x, sim_func(x), der=0) <= 0 indicates that x is feasible, while constraint(x, sim_func(x), der=0) > 0 indicates that x is infeasible, violating the constraint by an amount proportional to the output. It is the user’s responsibility to ensure that after adding all constraints, the feasible region is nonempty and has nonzero measure in the design space.

’con_grad’ (function): Evaluates the gradients of con_func wrt s and sx. Interface should match: dx, ds = con_grad(x, sx) where the value sx is given by sx = sim_func(x) at runtime. The outputs dx and ds represent the gradients with respect to x and sx, respectively.

addAcquisition(*args)

Add an acquisition function to the MOOP.

Parameters:

args (dict) –

Python dictionary of acquisition function info, including:

’acquisition’ (AcquisitionFunction): An acquisition function that maps from R^o –> R for scalarizing outputs.

’hyperparams’ (dict): A dictionary of hyperparameters for the acquisition functions. Can be omitted if no hyperparameters are needed.

compile()

Compile the MOOP object and initialize its components.

This locks the MOOP definition and jits all jit-able methods.

This must be done before adding any simulation or objective data to the internal database.

This cannot be done after simulation or objective data has been added to the internal database.

getDesignType()

Get the numpy dtype of all design points for this MOOP.

Returns:: The numpy dtype of this MOOP’s design points. If no design variables have yet been added, returns None.
Return type:: dtype

getSimulationType()

Get the numpy dtypes of the simulation outputs for this MOOP.

Returns:: The numpy dtype of this MOOP’s simulation outputs. If no simulations have been given, returns None.
Return type:: dtype

getObjectiveType()

Get the numpy dtype of an objective point for this MOOP.

Returns:: The numpy dtype of this MOOP’s objective points. If no objectives have yet been added, returns None.
Return type:: dtype

getConstraintType()

Get the numpy dtype of the constraint violations for this MOOP.

Returns:: The numpy dtype of this MOOP’s constraint violation outputs. If no constraint functions have been given, returns None.
Return type:: dtype

checkSimDb(x, s_name)

Check self.sim_db[s_name] to see if the design x was evaluated.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to search for.
s_name (str) – The name of the simulation whose database will be searched.

Returns:

returns None if x is not in self.sim_db[s_name] (up to the design tolerance). Otherwise, returns the corresponding value of sx.

Return type:

None or numpy.ndarray

updateSimDb(x, sx, s_name)

Update sim_db[s_name] by adding a design/simulation output pair.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to add.
sx (ndarray) – A 1D array containing the corresponding simulation output(s).
s_name (str) – The name of the simulation to whose database the pair (x, sx) will be added into.

evaluateSimulation(x, s_name)

Evaluate sim_func[s_name] and store the result in the database.

Parameters:

x (dict) – A Python dictionary with keys/names corresponding to the design variable names given and values containing the corresponding values of the design point to evaluate.
s_name (str) – The name of the simulation to evaluate.

Returns:

A 1D array containing the output from the evaluation sx = simulation[s_name](x).

Return type:

ndarray

addObjData(x, sx)

Update the internal objective database by truly evaluating x.

Parameters:

x (dict) – A Python dictionary containing the value of the design variable to add to ParMOO’s database.
sx (dict) – A Python dictionary containing the values of the corresponding simulation outputs for ALL simulations involved in this MOOP – sx[‘s_name’][:] contains the output(s) for sim_func[‘s_name’].

getPF(format='ndarray')

Extract nondominated and efficient sets from internal databases.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains a discrete approximation of the Pareto front and efficient set.
Return type:: numpy structured array or pandas DataFrame

getSimulationData(format='ndarray')

Extract all computed simulation outputs from the MOOP’s database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: A Python dictionary whose keys match the names of the simulations. Each value is either a numpy structured array or pandas dataframe (depending on the option selected above) whose column/key names match the names of the design variables plus either and ‘out’ field for single-output simulations, or ‘out_1’, ‘out_2’, … for multi-output simulations.
Return type:: dict

getObjectiveData(format='ndarray')

Extract all computed objective scores from this MOOP’s database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains the results for every fully evaluated design point.
Return type:: numpy structured array or pandas DataFrame

abstract iterate(k, ib=None): Perform an iteration of ParMOO’s solver to generate candidates.

abstract filterBatch(*args): Filter a batch produced by ParMOO’s MOOP.iterate method.

abstract updateAll(k, batch): Update all surrogates given a batch of freshly evaluated data.

abstract solve(iter_max=None, sim_max=None): Solve a MOOP using ParMOO.

setCheckpoint(checkpoint=True, filename='parmoo')

Activate ParMOO’s checkpointing feature.

Note that for checkpointing to work, all simulation, objective, and constraint functions must be defined in the global scope. ParMOO also cannot save lambda functions.

Parameters:

checkpoint (bool) – Turn checkpointing on (True) or off (False).
filename (str, optional) – Set the base checkpoint filename/path. The checkpoint file will have the JSON format and the extension “.moop” appended to the end of filename. Additional checkpoint files may be created with the same filename but different extensions, depending on the choice of AcquisitionFunction, SurrogateFunction, and GlobalSearch. When omitted, this parameter defaults to “parmoo” and is saved inside current working directory.

save(filename='parmoo')

Serialize and save the MOOP object and all of its dependencies.

Parameters:: filename (str, optional) – The filepath to serialized checkpointing file(s). Do not include file extensions, they will be appended automatically. This method may create several additional save files with this same name, but different file extensions, in order to recursively save dependency objects (such as surrogate models). Defaults to the value “parmoo” (filename will be “parmoo.moop”).

load(filename='parmoo')

Load a serialized MOOP object and all of its dependencies.

Parameters:: filename (str, optional) – The filepath to the serialized checkpointing file(s). Do not include file extensions, they will be appended automatically. This method may also load from other save files with the same name, but different file extensions, in order to recursively load dependency objects (such as surrogate models) as needed. Defaults to the value “parmoo” (filename will be “parmoo.moop”).