ribs.archives.ArchiveBase¶
 class
ribs.archives.
ArchiveBase
(storage_dims, behavior_dim, seed=None, dtype=<class 'numpy.float64'>)[source]¶ Base class for archives.
This class assumes all archives use a fixedsize container with bins that hold (1) information about whether the bin is occupied (bool), (2) a solution (1D array), (3) objective function evaluation of the solution (float), (4) behavior space coordinates of the solution (1D array), and (5) any additional metadata associated with the solution (object). In this class, the container is implemented with separate numpy arrays that share common dimensions. Using the
storage_dims
andbehavior_dim
arguments in__init__
and thesolution_dim
argument ininitialize
, these arrays are as follows:Name
Shape
_occupied
(*storage_dims)
_solutions
(*storage_dims, solution_dim)
_objective_values
(*storage_dims)
_behavior_values
(*storage_dims, behavior_dim)
_metadata
(*storage_dims)
All of these arrays are accessed via a common index. If we have index
i
, we access its solution at_solutions[i]
, its behavior values at_behavior_values[i]
, etc.Thus, child classes typically override the following methods:
__init__
: Child classes must invoke this class’s__init__
with the appropriate arguments.get_index()
: Returns an index into the arrays above when given the behavior values of a solution. Usually, the index has a meaning, e.g. inCVTArchive
it is the index of a centroid. This method should include an explanation of what the index means.initialize()
: By default, this method sets up the arrays described, so child classes should invoke the parent implementation if they are overriding it.
Note
Attributes beginning with an underscore are only intended to be accessed by child classes (i.e. they are “protected” attributes).
 Parameters
storage_dims (tuple of int) – Primary dimensions of the archive storage. This is used to create the numpy arrays described above.
behavior_dim (int) – The dimension of the behavior space.
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
.
 Variables
_rng (numpy.random.Generator) – Random number generator, used in particular for generating random elites.
_storage_dims (tuple of int) – See
storage_dims
arg._behavior_dim (int) – See
behavior_dim
arg._solution_dim (int) – Dimension of the solution space, passed in with
initialize()
._occupied (numpy.ndarray) – Bool array storing whether each bin in the archive is occupied. This attribute is None until
initialize()
is called._solutions (numpy.ndarray) – Float array storing the solutions themselves. This attribute is None until
initialize()
is called._objective_values (numpy.ndarray) – Float array storing the objective value of each solution. This attribute is None until
initialize()
is called._behavior_values (numpy.ndarray) – Float array storing the behavior space coordinates of each solution. This attribute is None until
initialize()
is called._metadata (numpy.ndarray) – Object array storing the metadata associated with each solution. This attribute is None until
initialize()
is called._occupied_indices (list of (int or tuple of int)) – A list of indices that are occupied in the archive. This attribute is None until
initialize()
is called._occupied_indices_cols (tuple of list of int) – Stores the same data as
_occupied_indices
, but in columnwise fashion. For instance,_occupied_indices_cols[0]
holds index 0 of all the indices in_occupied_indices
. This attribute is None untilinitialize()
is called.
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 archive indices for the given behavior values.
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 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()
Dimensionality of the solutions in the archive.
Statistics about the archive.

__iter__
()[source]¶ Creates an iterator over the
Elite
’s in the archive.Example
for elite in archive: elite.sol elite.obj ...

add
(solution, objective_value, behavior_values, metadata=None)[source]¶ 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)[source]¶ 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
()[source]¶ Removes all elites from the archive.
After this method is called, the archive will be
empty
.

elite_with_behavior
(behavior_values)[source]¶ 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
 abstract
get_index
(behavior_values)[source]¶ Returns archive indices for the given behavior values.
See the
ArchiveBase
class docstring for more info. Parameters
behavior_values (numpy.ndarray) – (
behavior_dim
,) array of coordinates in behavior space. Returns
Indices of the behavior values in the archive’s storage arrays.
 Return type
int or tuple of int

get_random_elite
()[source]¶ 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)[source]¶ 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
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
stats
¶ Statistics about the archive.
See
ArchiveStats
for more info. Type