ribs.archives.DiscountArchive¶

class ribs.archives.DiscountArchive(*, solution_dim: int | integer | tuple[int | integer, ...], measure_dim: int | integer, learning_rate: float | floating, threshold_min: float | floating, discount_model_manager: DiscountModelManager, result_archive: GridArchive | CVTArchive, init_train_points: int | integer, empty_points: int | integer, seed: int | integer | None = None, solution_dtype: numpy.typing.DTypeLike = None, objective_dtype: numpy.typing.DTypeLike = None, measures_dtype: numpy.typing.DTypeLike = None, dtype: numpy.typing.DTypeLike = None)[source]¶

Archive that represents the discount function with a model.

This archive originates in the Discount Model Search algorithm in Tjanaka 2026 and is based around a discount model, i.e., a model that maps from measures to discount values. In short, the discount model serves as a smooth representation of the discount function, compared to the histogram representation in CMA-MAE.

To elaborate, CMA-MAE computes improvement values using a “soft archive” that stores a discount value in each cell – the soft archive is essentially a histogram of discount values. In contrast, this archive computes improvement values using a discount model, which provides a smooth representation of the discount function. As Discount Model Search proceeds, the discount model is trained using data from two sources. First is solutions sampled by the emitters, and second is “empty points”, i.e., measure space points sampled at the centers of unoccupied cells in the result_archive. The emitter solutions represent where the search is progressing, while the empty points force the discount model to maintain low values in areas of the archive that have not been explored yet.

From an implementation perspective, this archive focuses on providing the correct training data to the discount model. This data consists of pairs of measure values and discount value targets. Meanwhile, a DiscountModelManager handles the process of training on that data and performing inference. As such, this archive includes configuration parameters like threshold_min and empty_points, while DiscountModelManager takes in the discount model’s neural network itself. Overall, we assume this archive can produce training data, and the discount model manager can successfully regress the discount model to that data.

Note

The usage for this archive is similar to other archives like GridArchive in that it is initialized, passed to the scheduler, and then has solutions added to it. However, it differs in that users must also call the training functions init_discount_model() (before starting the main loop of their algorithm) and train_discount_model() (during the main loop of their algorithm, after calling tell()).

We adopt this API because the training methods can be computationally intensive. Allowing the user to call the methods themselves enables them to control exactly when the training happens; furthermore, they can collect information like training statistics. Otherwise, the discount model training would be placed in __init__() and add(), potentially causing those methods to take a long time.

Parameters:¶

solution_dim: int | integer | tuple[int | integer, ...]¶

Dimensionality of the solution space.

measure_dim: int | integer¶

Dimensionality of the measure space.

learning_rate: float | floating¶

The learning rate for discount updates.

threshold_min: float | floating¶

Minimum discount value. Used when initializing the discount model and when regressing to empty points.

discount_model_manager: DiscountModelManager¶

An object that handles training and inference for the discount model. The archive accesses the discount model through this manager.

result_archive: GridArchive | CVTArchive¶

The archive storing results for the algorithm. This is used for sampling empty points. Currently, only GridArchive and CVTArchive are supported.

init_train_points: int | integer¶

Number of points to use for initializing the discount model.

empty_points: int | integer¶

Number of empty points to sample when training the discount model.

seed: int | integer | None = None¶

Value to seed the random number generator. Set to None to avoid a fixed seed.

solution_dtype: numpy.typing.DTypeLike = None¶

Data type of the solutions. Defaults to float64 (numpy’s default floating point type).

objective_dtype: numpy.typing.DTypeLike = None¶

Data type of the objectives. Defaults to float64 (numpy’s default floating point type).

measures_dtype: numpy.typing.DTypeLike = None¶

Data type of the measures. Defaults to float64 (numpy’s default floating point type).

dtype: numpy.typing.DTypeLike = None¶

Shortcut for providing data type of the solutions, objectives, and measures. Defaults to float64 (numpy’s default floating point type). This parameter sets all the dtypes simultaneously. To set individual dtypes, pass solution_dtype, objective_dtype, and measures_dtype. Note that dtype cannot be used at the same time as those parameters.

Raises:¶

ValueError – Invalid values were provided for arguments.

Methods

add(solution, objective, measures, **fields)	Computes the improvement values for the given solutions.
init_discount_model()	Initializes the discount model so that it outputs threshold_min everywhere.
train_discount_model()	Trains the discount model.

Attributes

discount_model_manager	The discount model manager for this archive.
dtypes	Mapping from field name to dtype for all fields in the archive.
empty	Whether the archive is empty; always False.
empty_points	Number of empty points to sample.
init_train_points	Number of points to use for initializing the discount model.
learning_rate	The learning rate for discount updates.
threshold_min	Minimum discount value.

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

Computes the improvement values for the given solutions.

Unlike other archives (see ribs.archives.ArchiveBase.add()), this archive does not store any solutions itself. Rather, calling this function only results in a computation of the improvement value, based on the discount values output by the discount model. Training of the discount model happens separately in train_discount_model().

Parameters:¶

solution: numpy.typing.ArrayLike¶

(batch_size, solution_dim) array of solution parameters.

objective: numpy.typing.ArrayLike¶

(batch_size, objective_dim) array with objective function evaluations of the solutions.

measures: numpy.typing.ArrayLike¶

(batch_size, measure_dim) array with measure space coordinates of all the solutions.

**fields: numpy.typing.ArrayLike¶

Additional data for each solution. Each argument should be an array with batch_size as the first dimension.

Returns:¶

Information describing the result of the add operation. The dict contains the following keys:

• "status" (numpy.ndarray of np.int32): An array of integers that represent the “status” obtained when attempting to insert each solution in the batch. If a solution exceeds the discount value output by the discount model, it is considered to be a “new” solution and thus assigned a status of 2, in accordance with AddStatus. Otherwise, it is considered to be “not added” to the archive and thus assigned a status of 0.

• "value" (numpy.ndarray of the objective dtype): An array of improvement values, computed by subtracting the discount values output by the discount model from the objective values passed in.

• "discount" (numpy.ndarray of the objective dtype): An array with the discount values computed by the discount model for each solution.

Raises:¶

• ValueError – The array arguments do not match their specified shapes.

• ValueError – objective or measures has non-finite values (inf or NaN).

init_discount_model() → dict[source]¶

Initializes the discount model so that it outputs threshold_min everywhere.

To obtain measure values, this method samples init_train_points centers from the result archive. The discount value target for each measure is set to threshold_min. Finally, ribs.discount_models.DiscountModelManager.training_loop() is called to train the discount model with this data.

Returns:¶

Info from training. See train_discount_model() for info on this dict. The format is identical, but note that “solution_measures” and “solution_targets” are arrays of length 0.

train_discount_model() → dict[source]¶

Trains the discount model.

The training process is described in Section 5 of Tjanaka 2026. The first data source for training the discount model comes from solutions sampled by the emitters – this data is cached in the archive during a prior call to add(), which happens inside the scheduler’s tell() method. The second data source, “empty points”, are sampled from the centers of unoccupied cells in the result archive. The number of empty points is controlled by the empty_points property.

Returns:¶

• “solution_measures”: Measures associated with solutions sampled by the emitters, i.e., measures that were previously passed into add().

• ”solution_targets”: Array of target discount values for the aforementioned “solution_measures”. Note that the target for empty points is always threshold_min, so we do not include an “empty_targets” key.

• ”empty_measures”: Array of empty points sampled from the result archive. Note that the number of points may be fewer than empty_points if the result archive did not have enough unoccupied cells.

• ”epochs”: Number of epochs for which the discount model was trained.

• ”losses”: List with loss from each epoch of training the discount model.

Return type:¶

Info from training. The dict contains the following keys

property discount_model_manager : DiscountModelManager¶

The discount model manager for this archive.

property dtypes : dict[str, dtype]¶

Mapping from field name to dtype for all fields in the archive.

property empty : bool¶

Whether the archive is empty; always False.

Since the archive does not store elites, we always mark it as not empty.

property empty_points : int | integer¶

Number of empty points to sample.

property init_train_points : int | integer¶

Number of points to use for initializing the discount model.

property learning_rate : float¶

The learning rate for discount updates.

property threshold_min : float¶

Minimum discount value.