Utilities

These modules contain additional utilities, which may be useful for developers.

Such utilities include the MOOP utilities, the error checks, and the MOOP checks.

from parmoo.utilities import moop_utils
from parmoo.utilities import error_checks
from parmoo.core import moop_checks

This module contains several auxiliary functions used throughout ParMOO.

These functions may also be of external interest. They are:

  • lex_leq(a, b)

  • updatePF(data, nondom)

  • to_array(x, dtype)

  • from_array(x, dtype)

  • approx_equal(x1, x2, des_tols)

utilities.moop_utils.lex_leq(a, b)

Lexicographically compare two vectors from back to front.

Check whether the vector a is lexicographically less than or equal to b, starting from the last element and working back to the first element.

Parameters:

  • a (numpy.ndarray) – The first vector to compare.

  • b (numpy.ndarray) – The second vector to compare.

Returns:

Whether a <= b in the lexicographical sense.

Return type:

Boolean

utilities.moop_utils.approx_equal(x1, x2, des_tols)

Check if two dictionaries contain equal values up to the tolerance.

Note: This function allows that a value in x1/x2 could be non numeric, in which case exact equality is checked. This is triggered if the corresponding value in des_tols <= 0.

Parameters:

  • x1 (dict) – A dictionary of design variable names and corresponding values.

  • x2 (dict) – A dictionary of design variable names and corresponding values. Must contain all the keys in x1, but could contain additional keys that are not in x1.

  • des_tols (dict) – A dictionary of design variable names and corresponding tolerances. Keys must match those in x1 and x2. Values must be numerical. Any value less than or equal to zero results in direct comparison for the corresponding

utilities.moop_utils.updatePF(data, nondom)

Update the Pareto front and efficient set by resorting.

Returns:

A dictionary containing a discrete approximation of the Pareto front and efficient set.

  • f_vals (numpy.ndarray): A list of nondominated points discretely approximating the Pareto front.

  • x_vals (numpy.ndarray): A list of corresponding efficient design points.

  • c_vals (numpy.ndarray): A list of corresponding constraint satisfaction scores, all less than or equal to 0.

Return type:

dict

utilities.moop_utils.to_array(x, dtype)

Unroll a ParMOO variable of the given dtype into a flat numpy array.

Parameters:

  • x (dict or numpy structured array) – A ParMOO variable, which needs to be unrolled in a ndarray for convenience.

  • dtype (numpy.dtype) – The numpy.dtype of x.

Returns:

a 1D array containing the values in x unrolled into an ndarray format, ordered by their order in the dtype.names.

Return type:

ndarray

utilities.moop_utils.from_array(x, dtype)

Roll a flat ndarray back up into a ParMOO variable of the given dtype.

Parameters:

  • x (ndarray) – A 1D array whose length matches the sum of the lengths of all fields for the dtype.

  • dtype (numpy.dtype) – The numpy.dtype of the needed output.

Returns:

a ParMOO dictionary representation of x whose keys match the names in dtype and contains the values in x.

Return type:

dict

This module contains several auxiliary functions to aide in error handling.

These functions may also be of external interest. They are:

  • xerror(o, lb, ub, hyperparams)

  • check_names(name, des_schema, sim_schema, obj_schema, con_schema)

  • gradient_error(arg1, arg2)

utilities.error_checks.xerror(o=1, lb=None, ub=None, hyperparams=None)

Typecheck the input arguments for a class interface.

Parameters:

  • o (int) – The number of objectives should be an int greater than or equal to 1.

  • lb (np.ndarray) – The lower bounds should be a 1d array.

  • ub (np.ndarray) – The upper bounds should be a 1d array with the same length as lb, and must satisfy lb[:] < ub[:].

  • hyperparams (dict) – The hyperparameters must be supplied in a dictionary.

utilities.error_checks.check_names(name, *args)

Typecheck the input arguments for a new variable name.

Parameters:

  • name (str) – A str that could be used as the variable name.

  • *args (list of tuples) – 1 or more lists of existing variable names to check against in order to guarantee that name is unique.

utilities.error_checks.gradient_error(arg1, arg2)

Raises an error, warning users that the gradient is undefined.

Parameters:

  • arg1 (un-used) – Here to match the interface of a gradient or bwd pass function.

  • arg2 (un-used) – Here to match the interface of a gradient or bwd pass function.

This module contains several type-checking functions for the MOOP class.

They are:

  • check_sims(n, arg1, arg2, …)

core.moop_checks.check_sims(n, *args)

Check simulation dictionaries for bad input.

Parameters:

  • n (int) – The dimension of the design space. Used for confirming any simulation databases provided in args.

  • *args (dict) –

    An unpacked array of dictionaries, each specifying one of the simulations. The following keys are used:

    • name (String, optional): The name of this simulation (defaults to “sim” + str(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 R^n -> R^m. The interface should match: sim_out = sim_func(x, der=False), where der is an optional argument specifying whether to take the derivative of the simulation. Unless otherwise specified by your solver, der is always omitted by ParMOO’s internal structures, and need not be implemented.

    • 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.

    • des_tol (float): The tolerance for this simulation’s design space; a new design point that is closer than des_tol to a point that is already in this simulation’s database will not be reevaluated.

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

    • sim_db (dict, optional): A dictionary of previous simulation evaluations. When present, contains:

      • x_vals (np.ndarray): A 2d array of pre-evaluated design points.

      • s_vals (np.ndarray): A 2d array of corresponding simulation outputs.

      • g_vals (np.ndarray): A 3d array of corresponding Jacobian values. This value is only needed if the provided SurrogateFunction uses gradients.