ribs.emitters.GaussianEmitter¶

Emits solutions by adding Gaussian noise to existing elites.

If the archive is empty and initial_solutions is set, a call to ask() will return initial_solutions. If initial_solutions is not set, we draw solutions from a Gaussian distribution centered at x0 with standard deviation sigma. Otherwise, each solution is drawn from a distribution centered at a randomly chosen elite with standard deviation sigma.

Parameters:¶

archive: ArchiveBase¶: Archive of solutions, e.g., ribs.archives.GridArchive.
sigma: Float | ArrayLike¶: Standard deviation of the Gaussian distribution. Note we assume the Gaussian is diagonal, so if this argument is an array, it must have the same dimensionality as the solutions.
x0: ArrayLike | None = None¶: Center of the Gaussian distribution from which to sample solutions when the archive is empty. This argument is ignored if initial_solutions is set.
initial_solutions: ArrayLike | None = None¶: An (n, solution_dim) array of solutions to be used when the archive is empty. If this argument is None, then solutions will be sampled from a Gaussian distribution centered at x0 with standard deviation sigma.
bounds: Collection[tuple[None | Float, None | Float]] | None = None¶: Bounds of the solution space. Pass None to indicate there are no bounds. Alternatively, pass an array-like to specify the bounds for each dim. Each element in this array-like can be None to indicate no bound, or a tuple of (lower_bound, upper_bound), where lower_bound or upper_bound may be None to indicate no bound. Unbounded upper bounds are set to +inf, and unbounded lower bounds are set to -inf.
lower_bounds: ArrayLike | None = None¶: Instead of specifying bounds, lower_bounds and upper_bounds may be specified. This is useful if, for instance, solutions are multi-dimensional. Here, pass None to indicate there are no bounds (i.e., bounds are set to -inf), or pass an array specifying the lower bounds of the solution space.
upper_bounds: ArrayLike | None = None¶: Upper bounds of the solution space; see lower_bounds above. Pass None to indicate there are no bounds (i.e., bounds are set to inf).
batch_size: Int = 64¶: Number of solutions to return in ask().
seed: Int | None = None¶: Value to seed the random number generator. Set to None to avoid a fixed seed.

Raises:¶

ValueError – There is an error in x0 or initial_solutions.
ValueError – There is an error in the bounds configuration.

Methods

`ask`()	Creates solutions by adding Gaussian noise to elites in the archive.
`ask_dqd`()	Generates solutions for which gradient information must be computed.
`tell`(solution, objective, measures, ...)	Gives the emitter results from evaluating solutions.
`tell_dqd`(solution, objective, measures, ...)	Gives the emitter results from evaluating the gradient of the solutions.

Attributes

`archive`	Stores solutions generated by this emitter.
`batch_size`	Number of solutions to return in `ask()`.
`initial_solutions`	Returned when the archive is empty (if `x0` is not set).
`lower_bounds`	`(solution_dim,)` array with lower bounds of solution space.
`sigma`	Standard deviation of the (diagonal) Gaussian distribution.
`solution_dim`	Dimensionality of solutions produced by this emitter.
`upper_bounds`	`(solution_dim,)` array with upper bounds of solution space.
`x0`	Initial Gaussian distribution center.

ask() → ndarray[source]¶

Creates solutions by adding Gaussian noise to elites in the archive.

Returns:¶: If the archive is not empty, (batch_size, solution_dim) array – contains batch_size new solutions to evaluate. If the archive is empty, we return initial_solutions, which might not have batch_size solutions.

ask_dqd() → ndarray¶

Generates solutions for which gradient information must be computed.

The solutions should be a (batch_size, solution_dim) array.

This method only needs to be implemented by emitters used in DQD. It returns an empty array by default.

tell(solution: numpy.typing.ArrayLike, objective: numpy.typing.ArrayLike, measures: numpy.typing.ArrayLike, add_info: dict[str, ndarray], **fields: numpy.typing.ArrayLike) → None¶

Gives the emitter results from evaluating solutions.

This base class implementation (in EmitterBase) does nothing by default.

Parameters:¶

solution: numpy.typing.ArrayLike¶: Array of solutions generated by this emitter’s ask() method.
objective: numpy.typing.ArrayLike¶: 1D array containing the objective function value of each solution.
measures: numpy.typing.ArrayLike¶: (n, <measure space dimension>) array with the measure space coordinates of each solution.
add_info: dict[str, ndarray]¶: Data returned from the archive add() method.
**fields: numpy.typing.ArrayLike¶: Additional data for each solution. Each argument should be an array with batch_size as the first dimension.

tell_dqd(solution: numpy.typing.ArrayLike, objective: numpy.typing.ArrayLike, measures: numpy.typing.ArrayLike, jacobian: numpy.typing.ArrayLike, add_info: dict[str, ndarray], **fields: numpy.typing.ArrayLike) → None¶

Gives the emitter results from evaluating the gradient of the solutions.

This method is the counterpart of ask_dqd(). It is only used by DQD emitters.

Parameters:¶

solution: numpy.typing.ArrayLike¶: (batch_size, :attr:`solution_dim`) array of solutions generated by this emitter’s ask() method.
objective: numpy.typing.ArrayLike¶: 1-dimensional array containing the objective function value of each solution.
measures: numpy.typing.ArrayLike¶: (batch_size, measure space dimension) array with the measure space coordinates of each solution.
jacobian: numpy.typing.ArrayLike¶: (batch_size, 1 + measure_dim, solution_dim) array consisting of Jacobian matrices of the solutions obtained from ask_dqd(). Each matrix should consist of the objective gradient of the solution followed by the measure gradients.
add_info: dict[str, ndarray]¶: Data returned from the archive add() method.
**fields: numpy.typing.ArrayLike¶: Additional data for each solution. Each argument should be an array with batch_size as the first dimension.

property archive : ArchiveBase¶: Stores solutions generated by this emitter.

property batch_size : int | integer¶: Number of solutions to return in ask().

property initial_solutions : ndarray | None¶: Returned when the archive is empty (if x0 is not set).

property lower_bounds : ndarray¶

(solution_dim,) array with lower bounds of solution space.

For instance, [-1, -1, -1] indicates that every dimension of the solution space has a lower bound of -1.

property sigma : floating | ndarray¶: Standard deviation of the (diagonal) Gaussian distribution.

property solution_dim : int | integer | tuple[int | integer, ...]¶: Dimensionality of solutions produced by this emitter.

property upper_bounds : ndarray¶

(solution_dim,) array with upper bounds of solution space.

For instance, [1, 1, 1] indicates that every dimension of the solution space has an upper bound of 1.

property x0 : ndarray | None¶

Initial Gaussian distribution center.

Solutions are sampled from this distribution when the archive is empty (if initial_solutions is not set).