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 fixed-size 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 and behavior_dim arguments in __init__ and the solution_dim argument in initialize, 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. in CVTArchive 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 data-type) – 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 column-wise fashion. For instance, _occupied_indices_cols[0] holds index 0 of all the indices in _occupied_indices. This attribute is None until initialize() 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 of pandas.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.

get_random_elite()

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.

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

solution_dim

Dimensionality of the solutions in the archive.

stats

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
    ...
__len__()[source]

Number of elites in the archive.

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 (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)[source]

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

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

  • len(self._storage_dims) columns for the index, named index_0, index_1, ... In GridArchive and SlidingBoundariesArchive, there are behavior_dim columns. In CVTArchive, there is just one column. See get_index() for more info.

  • behavior_dim columns for the behavior characteristics, named behavior_0, behavior_1, ...

  • 1 column for the objective values, named objective

  • solution_dim columns for the solution vectors, named solution_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, 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()[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 (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

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

Elite

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 behavior_dim

Dimensionality of the behavior space.

Type

int

property bins

Total number of bins in the archive.

Type

int

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 solution_dim

Dimensionality of the solutions in the archive.

Type

int

property stats

Statistics about the archive.

See ArchiveStats for more info.

Type

ArchiveStats