ribs.archives.GridArchive¶
 class
ribs.archives.
GridArchive
(dims, ranges, seed=None, dtype=<class 'numpy.float64'>)[source]¶ An archive that divides each dimension into uniformlysized bins.
This archive is the container described in Mouret 2015. It can be visualized as an ndimensional 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 (arraylike 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 (arraylike 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 asdims
.seed (int) – Value to seed the random number generator. Set to None to avoid a fixed seed.
dtype (str or datatype) – Data type of the solutions, objective values, and behavior values. We only support
"f"
/np.float32
and"d"
/np.float64
.
 Raises
ValueError –
dims
andranges
are not the same length.
Methods
__iter__
()Creates an iterator over the
Elite
’s in the archive.__len__
()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 ofpandas.DataFrame
).clear
()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
Dimensionality of the behavior space.
Total number of bins in the archive.
The boundaries of the bins in each dimension.
Number of bins in each dimension.
The dtype of the solutions, objective values, and behavior values.
Whether the archive is empty.
Whether the archive has been initialized by a call to
initialize()
The size of each dim (upper_bounds  lower_bounds).
Lower bound of each dimension.
Dimensionality of the solutions in the archive.
Statistics about the archive.
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 (arraylike) – Parameters of the solution.
objective_value (float) – Objective function evaluation of the solution.
behavior_values (arraylike) – 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
2element tuple describing the result of the add operation. These outputs are particularly useful for algorithms such as CMAME.
status (
AddStatus
): SeeAddStatus
.value (
dtype
): The meaning of this value depends on the value ofstatus
: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 archiveNEW
> the objective value passed in
 Return type

as_pandas
(include_solutions=True, include_metadata=False)¶ Converts the archive into an
ArchiveDataFrame
(a child class ofpandas.DataFrame
).The implementation of this method in
ArchiveBase
creates a dataframe consisting of:len(self._storage_dims)
columns for the index, namedindex_0, index_1, ...
InGridArchive
andSlidingBoundariesArchive
, there arebehavior_dim
columns. InCVTArchive
, there is just one column. Seeget_index()
for more info.behavior_dim
columns for the behavior characteristics, namedbehavior_0, behavior_1, ...
1 column for the objective values, named
objective
solution_dim
columns for the solution vectors, namedsolution_0, solution_1, ...
1 column for the metadata objects, named
metadata
In short, the dataframe looks like this:
index_0
…
behavior_0
…
objective
solution_0
…
metadata
…
…
…
Compared to
pandas.DataFrame
, theArchiveDataFrame
adds methods and attributes which make it easier to manipulate archive data. For more information, refer to theArchiveDataFrame
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

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 (arraylike) – 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

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
 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
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 dimensioni
. The array containsself.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]
andboundaries[i][j + 1]
are the lower and upper bounds of binj
in dimensioni
. To access the lower bounds of all the bins in dimensioni
, useboundaries[i][:1]
, and to access all the upper bounds, useboundaries[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
datatype
 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
stats
¶ Statistics about the archive.
See
ArchiveStats
for more info. Type
 property
upper_bounds
¶ Upper bound of each dimension.
 Type
(behavior_dim,) numpy.ndarray