# ribs.archives.GridArchive¶

class ribs.archives.GridArchive(dims, ranges, seed=None, dtype=<class 'numpy.float64'>)[source]

An archive that divides each dimension into uniformly-sized bins.

This archive is the container described in Mouret 2015. It can be visualized as an n-dimensional grid in the behavior space that is divided into a certain number of bins in each dimension. Each bin contains an elite, i.e. a solution that maximizes the objective function for the behavior values in that bin.

Parameters
• dims (array-like of int) – Number of bins in each dimension of the behavior space, e.g. [20, 30, 40] indicates there should be 3 dimensions with 20, 30, and 40 bins. (The number of dimensions is implicitly defined in the length of this argument).

• ranges (array-like of (float, float)) – Upper and lower bound of each dimension of the behavior space, e.g. [(-1, 1), (-2, 2)] indicates the first dimension should have bounds $$[-1,1]$$ (inclusive), and the second dimension should have bounds $$[-2,2]$$ (inclusive). ranges should be the same length as dims.

• seed (int) – Value to seed the random number generator. Set to None to avoid a fixed seed.

• dtype (str or data-type) – Data type of the solutions, objective values, and behavior values. We only support "f" / np.float32 and "d" / np.float64.

Raises

ValueErrordims and ranges are not the same length.

Methods

 Creates an iterator over the Elite’s in the archive. Number of elites in the archive. add(solution, objective_value, behavior_values) Attempts to insert a new solution into the archive. as_pandas([include_solutions, include_metadata]) Converts the archive into an ArchiveDataFrame (a child class of pandas.DataFrame). Removes all elites from the archive. elite_with_behavior(behavior_values) Gets the elite with behavior vals in the same bin as those specified. get_index(behavior_values) Returns indices of the behavior values within the archive’s grid. Selects an elite uniformly at random from one of the archive’s bins. initialize(solution_dim) Initializes the archive by allocating storage space.

Attributes

 behavior_dim Dimensionality of the behavior space. bins Total number of bins in the archive. boundaries The boundaries of the bins in each dimension. dims Number of bins in each dimension. dtype The dtype of the solutions, objective values, and behavior values. empty Whether the archive is empty. initialized Whether the archive has been initialized by a call to initialize() interval_size The size of each dim (upper_bounds - lower_bounds). lower_bounds Lower bound of each dimension. solution_dim Dimensionality of the solutions in the archive. stats Statistics about the archive. upper_bounds Upper bound of each dimension.
__iter__()

Creates an iterator over the Elite’s in the archive.

Example

for elite in archive:
elite.sol
elite.obj
...

__len__()

Number of elites in the archive.

add(solution, objective_value, behavior_values, metadata=None)

Attempts to insert a new solution into the archive.

The solution is only inserted if it has a higher objective_value than the elite previously in the corresponding bin.

Parameters
• solution (array-like) – Parameters of the solution.

• objective_value (float) – Objective function evaluation of the solution.

• behavior_values (array-like) – Coordinates in behavior space of the solution.

• metadata (object) – Any Python object representing metadata for the solution. For instance, this could be a dict with several properties.

Returns

2-element tuple describing the result of the add operation. These outputs are particularly useful for algorithms such as CMA-ME.

status (AddStatus): See AddStatus.

value (dtype): The meaning of this value depends on the value of status:

• NOT_ADDED -> the “negative improvement,” i.e. objective value of solution passed in minus objective value of the solution still in the archive (this value is negative because the solution did not have a high enough objective value to be added to the archive)

• IMPROVE_EXISTING -> the “improvement,” i.e. objective value of solution passed in minus objective value of solution previously in the archive

• NEW -> the objective value passed in

Return type

tuple

as_pandas(include_solutions=True, include_metadata=False)

Converts the archive into an ArchiveDataFrame (a child class of pandas.DataFrame).

The implementation of this method in ArchiveBase creates a dataframe consisting of:

In short, the dataframe looks like this:

index_0

behavior_0

objective

solution_0

Compared to pandas.DataFrame, the ArchiveDataFrame adds methods and attributes which make it easier to manipulate archive data. For more information, refer to the ArchiveDataFrame documentation.

Parameters
• include_solutions (bool) – Whether to include solution columns.

• include_metadata (bool) – Whether to include the metadata column. Note that methods like to_csv() may not properly save the dataframe since the metadata objects may not be representable in a CSV.

Returns

See above.

Return type

ArchiveDataFrame

clear()

Removes all elites from the archive.

After this method is called, the archive will be empty.

elite_with_behavior(behavior_values)

Gets the elite with behavior vals in the same bin as those specified.

Since Elite is a namedtuple, the result can be unpacked (here we show how to ignore some of the fields):

sol, obj, beh, *_ = archive.elite_with_behavior(...)


Or the fields may be accessed by name:

elite = archive.elite_with_behavior(...)
elite.sol
elite.obj
...

Parameters

behavior_values (array-like) – Coordinates in behavior space.

Returns

• If there is an elite with behavior values in the same bin as those specified, this Elite holds the info for that elite. In that case, beh (the behavior values) may not be exactly the same as the behavior values specified since the elite is only guaranteed to be in the same archive bin.

• If no such elite exists, then all fields of the Elite are set to None. This way, tuple unpacking (e.g. sol, obj, beh, idx, meta = archive.elite_with_behavior(...)) still works.

Return type

Elite

get_index(behavior_values)[source]

Returns indices of the behavior values within the archive’s grid.

First, values are clipped to the bounds of the behavior space. Then, the values are mapped to bins; e.g. bin 5 along dimension 0 and bin 3 along dimension 1.

The indices can be used to access boundaries of a behavior value’s bin. For example, the following retrieves the lower and upper bounds of the bin along dimension 0:

idx = archive.get_index(...)  # Other methods also return indices.
lower = archive.boundaries[0][idx[0]]
upper = archive.boundaries[0][idx[0] + 1]


See boundaries for more info.

Parameters

behavior_values (numpy.ndarray) – (behavior_dim,) array of coordinates in behavior space.

Returns

The grid indices.

Return type

tuple of int

get_random_elite()

Selects an elite uniformly at random from one of the archive’s bins.

Since Elite is a namedtuple, the result can be unpacked (here we show how to ignore some of the fields):

sol, obj, beh, *_ = archive.get_random_elite()


Or the fields may be accessed by name:

elite = archive.get_random_elite()
elite.sol
elite.obj
...

Returns

A randomly selected elite from the archive.

Return type

Elite

Raises

IndexError – The archive is empty.

initialize(solution_dim)

Initializes the archive by allocating storage space.

Child classes should call this method in their implementation if they are overriding it.

Parameters

solution_dim (int) – The dimension of the solution space.

Raises

RuntimeError – The archive is already initialized.

property behavior_dim

Dimensionality of the behavior space.

Type

int

property bins

Total number of bins in the archive.

Type

int

property boundaries

The boundaries of the bins in each dimension.

Entry i in this list is an array that contains the boundaries of the bins in dimension i. The array contains self.dims[i] + 1 entries laid out like this:

Archive bins:   | 0 | 1 |   ...   |    self.dims[i]    |
boundaries[i]:  0   1   2   self.dims[i] - 1     self.dims[i]


Thus, boundaries[i][j] and boundaries[i][j + 1] are the lower and upper bounds of bin j in dimension i. To access the lower bounds of all the bins in dimension i, use boundaries[i][:-1], and to access all the upper bounds, use boundaries[i][1:].

Type

list of numpy.ndarray

property dims

Number of bins in each dimension.

Type

(behavior_dim,) numpy.ndarray

property dtype

The dtype of the solutions, objective values, and behavior values.

Type

data-type

property empty

Whether the archive is empty.

Type

bool

property initialized

Whether the archive has been initialized by a call to initialize()

property interval_size

The size of each dim (upper_bounds - lower_bounds).

Type

(behavior_dim,) numpy.ndarray

property lower_bounds

Lower bound of each dimension.

Type

(behavior_dim,) numpy.ndarray

property solution_dim

Dimensionality of the solutions in the archive.

Type

int

property stats

See ArchiveStats for more info.

Type

ArchiveStats

property upper_bounds

Upper bound of each dimension.

Type

(behavior_dim,) numpy.ndarray