Embedder Classes for Custom Variable Types

When defining your MOOP object as described in the name key section, it is possible to provide a custom variable by using the embedder key.

When used, this key must contain a value with the Embedder type. Embeddings for several common variable types are defined below, and provided behind the scenes by ParMOO whenever a non custom design variable is added to a problem.

They can also be added manually or studied to understand how a custom design variable might be implemented.

from parmoo.embeddings import default_embedders

To implement a custom embedding, import and extend the Embedder ABC.

from parmoo.embeddings.embedder import Embedder

The Embedder class and pre-existing embedders library are documented below.

Embedder

Abstract base class (ABC) for ParMOO embedders.

class embeddings.embedder.Embedder(settings)

ABC describing the embedding of design variables.

This class contains the following methods:

getLatentDesTols()
getFeatureDesTols()
getEmbeddingSize()
getInputType()
getLowerBounds()
getUpperBounds()
embed(x)
embed_grad(dx)
extract(x)

abstract __init__(settings)

Constructor for the Embedder class.

Parameters:: settings (dict) – Contains any variable information that the user might need to provide.
Returns:: A new Embedder object.
Return type:: Embedder

abstract getLatentDesTols()

Get the design tolerances along each dimension of the embedding.

Returns:: array of design space tolerances after embedding.
Return type:: numpy.ndarray

abstract getFeatureDesTols()

Get the design tolerances in the feature space (pre-embedding).

Returns:: the design tolerance in the feature space – a value of 0 indicates that this is a discrete variable.
Return type:: float

abstract getEmbeddingSize()

Get the dimension of the latent (embedded) space.

Returns:: the dimension of the latent space produced.
Return type:: int

abstract getInputType()

Get the input type for this embedder.

Note: Whatever the input type, the output type must always be a ndarray of one or more continuous variables in some range [lb, ub].

Returns:: A numpy string representation of the input type from the feature space. Currently supported values are: [“f8”, “i4”, “a25”, or “u25”].
Return type:: str

abstract getLowerBounds()

Get a vector of lower bounds for the embedded (latent) space.

Returns:

A 1D array of lower bounds in embedded space whose size: matches the output of getEmbeddingSize().

Return type:

ndarray

abstract getUpperBounds()

Get a vector of upper bounds for the embedded (latent) space.

Returns:

A 1D array of upper bounds in embedded space whose size: matches the output of getEmbeddingSize().

Return type:

ndarray

embed(x)

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

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

Parameters:: x (stype) – The value of the design variable to embed, where stype matches the numpy-string type specified by getInputType().
Returns:: A 1D array whose size matches the output of getEmbeddingSize() containing the embedding of x.
Return type:: ndarray

embed_grad(dx)

Embed a partial design gradient as a vector for ParMOO.

Note: If not implemented, ParMOO will still work with gradient-free methods, but will not support autograd features.

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

Parameters:: dx (float) – The partial design gradient to embed.
Returns:: A numpy array of length 1 containing a rescaling of x
Return type:: numpy.ndarray

extract(x)

Extract a design input from an n-dimensional vector for ParMOO.

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

Parameters:: x (ndarray) – A 1D array whose size matches the output of getEmbeddingSize() containing the embedding of x.
Returns:: The value of the design variable to embed, where stype matches the numpy-string type specified by getInputType().
Return type:: stype

Default Embedders

Default embeddings for ParMOO.

This module contains implementations of the Embedder ABC for all of ParMOO’s default embeddings.

This includes the following classes:

ContinuousEmbedder for real/continuous variables,
IntegerEmbedder for integer variables,
CategoricalEmbedder for categorical variables, and
IdentityEmbedder for raw/unscaled variables.

class embeddings.default_embedders.ContinuousEmbedder(settings)

An Embedder class for continuous variables that simply rescales and shifts all inputs to the box [0, 1].

__init__(settings)

Generate the scaling matrices for a continuous variable.

Parameters:

settings (dict) –

Contains the following keys * ‘lb’ (float or int, required): This specifies the lower

bound for the design variable. This value must be strictly less than ‘ub’ (below) up to the tolerance (below).

’ub’ (float or int, required): This specifies the upper bound for the design variable. This value must be strictly greater than ‘lb’ (above) up to the tolerance (below).
’des_tol’ (float, optional): This specifies the design tolerance for this variable, i.e., the minimum spacing before two design values are considered equivalent up to measurement error. If not specified, the default value is eps * max(ub - lb, sqrt(eps)), where eps is the unit roundoff.

getLatentDesTols()

Get the design tolerances along each dimension of the embedding.

Returns:: array of design space tolerances after embedding.
Return type:: numpy.ndarray

getFeatureDesTols()

Get the design tolerances in the feature space (pre-embedding).

Returns:: the design tolerance in the feature space – a value of 0 indicates a discrete variable.
Return type:: float

getEmbeddingSize()

Get dimension of embedded space.

Returns:: the dimension of the embedded space.
Return type:: int

getInputType()

Get the input type for this embedder.

Returns:: A numpy string representation of the input type from the feature space.
Return type:: str

getLowerBounds()

Get a vector of lower bounds for the embedded space.

Returns:: array of lower bounds in embedded space.
Return type:: numpy.ndarray

getUpperBounds()

Get a vector of upper bounds for the embedded space.

Returns:: array of upper bounds in the embedded space.
Return type:: numpy.ndarray

embed(x)

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

Parameters:: x (float) – The value of the design variable to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

embed_grad(dx)

Embed a partial design gradient as a vector for ParMOO.

Parameters:: dx (float) – The partial design gradient to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

extract(x)

Extract a design variable from an n-dimensional vector.

Parameters:: x (numpy.ndarray) – A numpy array of length 1 containing the value to extract.
Returns:: The de-scaled value of x (from the original input space).
Return type:: float

class embeddings.default_embedders.IntegerEmbedder(settings)

An Embedder class for integer variables that simply rescales and shifts all inputs to the box [0, 1], then de-scales and bins to the nearest integer upon extraction.

__init__(settings)

Generate the scaling matrices for an integer variable.

Parameters:

settings (dict) –

Contains the following keys * ‘lb’ (float or int, required): This specifies the lower

bound for the design variable. This value must be strictly less than ‘ub’ (below) up to the tolerance (below).

’ub’ (float or int, required): This specifies the upper bound for the design variable. This value must be strictly greater than ‘lb’ (above) up to the tolerance (below).
’des_tol’ (float, optional): This specifies the design tolerance for this variable, i.e., the minimum spacing before two design values are considered equivalent up to measurement error. If not specified, the default value is eps * max(ub - lb, sqrt(eps)), where eps is the unit roundoff.

getLatentDesTols()

Get the design tolerances along each dimension of the embedding.

Returns:: array of design space tolerances after embedding.
Return type:: numpy.ndarray

getFeatureDesTols()

Get the design tolerances in the feature space (pre-embedding).

Returns:: the design tolerance in the feature space – a value of 0 indicates a discrete variable.
Return type:: float

getEmbeddingSize()

Get dimension of embedded space.

Returns:: the dimension of the embedded space.
Return type:: int

getInputType()

Get the input type for this embedder.

Returns:: A numpy string representation of the input type from the feature space.
Return type:: str

getLowerBounds()

Get a vector of lower bounds for the embedded space.

Returns:: array of lower bounds in embedded space.
Return type:: numpy.ndarray

getUpperBounds()

Get a vector of upper bounds for the embedded space.

Returns:: array of upper bounds in the embedded space.
Return type:: numpy.ndarray

embed(x)

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

Parameters:: x (float or int) – The value of the design variable to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

embed_grad(dx)

Embed a partial design gradient as a vector for ParMOO.

Parameters:: dx (float or int) – The partial design gradient to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

extract(x)

Extract a design variable from an n-dimensional vector.

Parameters:: x (numpy.ndarray) – A numpy array of length 1 containing the value to extract.
Returns:: The de-scaled value of x rounded to the nearest integer.
Return type:: float

class embeddings.default_embedders.CategoricalEmbedder(settings)

An Embedder class for categorical variables that uses matrix operations to embed a one-hot-encoding into a lower-dimensional space then round the result back to the nearest category.

__init__(settings)

Generate the encoding matrices for a categorical variable.

Parameters:

settings (dict) –

Contains the following keys * ‘levels’ (int or list, required): The number of levels

for the variable (when int) or the names of each valid category (when a list).

getLatentDesTols()

Get the design tolerances along each dimension of the embedding.

Returns:: array of design space tolerances after embedding.
Return type:: numpy.ndarray

getFeatureDesTols()

Get the design tolerances in the feature space (pre-embedding).

Returns:: the design tolerance in the feature space – a value of 0 indicates a discrete variable.
Return type:: float

getEmbeddingSize()

Get dimension of embedded space.

Returns:: the dimension of the embedded space.
Return type:: int

getInputType()

Get the input type for this embedder.

Returns:: A numpy string representation of the input type from the feature space.
Return type:: str

getLowerBounds()

Get a vector of lower bounds for the embedded space.

Returns:: array of lower bounds in embedded space.
Return type:: numpy.ndarray

getUpperBounds()

Get a vector of upper bounds for the embedded space.

Returns:: array of upper bounds in the embedded space.
Return type:: numpy.ndarray

embed(x)

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

Parameters:: x (int or str) – a category from the list of categories or an int less than the number of categories.
Returns:: a 1d array containing the embedded category.
Return type:: numpy.ndarray

embed_grad(dx)

Embed a partial design gradient as a vector for ParMOO.

Parameters:: dx (int or str) – The partial design gradient to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

extract(x)

Extract a design variable from an n-dimensional vector.

Parameters:: x (numpy.ndarray) – a 1d array containing the embedded category in vector form.
Returns:: the extracted category.
Return type:: int or str

class embeddings.default_embedders.IdentityEmbedder(settings)

An Embedder class for continuous variables that leaves them raw and un-scaled.

__init__(settings)

Generate identity embedding for an unscaled design variable.

Parameters:

settings (dict) –

Contains the following keys * ‘lb’ (float or int, required): This specifies the lower

bound for the design variable. This value must be strictly less than ‘ub’ (below) up to the tolerance (below).

’ub’ (float or int, required): This specifies the upper bound for the design variable. This value must be strictly greater than ‘lb’ (above) up to the tolerance (below).
’des_tol’ (float, optional): This specifies the design tolerance for this variable, i.e., the minimum spacing before two design values are considered equivalent up to measurement error. If not specified, the default value is eps * max(ub - lb, sqrt(eps)), where eps is the unit roundoff.

getLatentDesTols()

Get the design tolerances along each dimension of the embedding.

Returns:: array of design space tolerances after embedding.
Return type:: numpy.ndarray

getFeatureDesTols()

Get the design tolerances in the feature space (pre-embedding).

Returns:: the design tolerance in the feature space – a value of 0 indicates a discrete variable.
Return type:: float

getEmbeddingSize()

Get dimension of embedded space.

Returns:: the dimension of the embedded space.
Return type:: int

getInputType()

Get the input type for this embedder.

Returns:: A numpy string representation of the input type from the feature space.
Return type:: str

getLowerBounds()

Get a vector of lower bounds for the embedded space.

Returns:: array of lower bounds in embedded space.
Return type:: numpy.ndarray

getUpperBounds()

Get a vector of upper bounds for the embedded space.

Returns:: array of upper bounds in the embedded space.
Return type:: numpy.ndarray

embed(x)

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

Parameters:: x (float or int) – The value of the design variable to embed.
Returns:: A numpy array of length 1 containing x.
Return type:: numpy.ndarray

embed_grad(dx)

Embed a partial design gradient as a vector for ParMOO.

Parameters:: dx (float or int) – The partial design gradient to embed.
Returns:: A numpy array of length 1 containing a rescaling of x.
Return type:: numpy.ndarray

extract(x)

Extract a design variable from an n-dimensional vector.

Parameters:: x (numpy.ndarray) – A numpy array of length 1 containing the value to extract.
Returns:: The value of x (but as a scalar, not a singleton array).
Return type:: float