ribs.schedulers.Scheduler

class ribs.schedulers.Scheduler(archive: ArchiveBase, emitters: Sequence[EmitterBase], result_archive: ArchiveBase | None = None, *, add_mode: 'batch' | 'single' = 'batch')[source]

A basic class that composes an archive with multiple emitters.

To use this class, first create an archive and list of emitters for the QD algorithm. Then, construct the Scheduler with these arguments. Finally, repeatedly call ask() to collect solutions to analyze, and return the objective and measures of those solutions in the same order using tell().

As all solutions go into the same archive, the emitters passed in must emit solutions with the same dimension (that is, their solution_dim attribute must be the same).

Warning

If constructing many emitters at once, do not pass something like [EmitterClass(...)] * 5, as this creates a list with the same instance of EmitterClass in each position. Instead, use [EmitterClass(...) for _ in range 5], which creates 5 unique instances of EmitterClass.

Parameters:
archive: ArchiveBase

An archive object, e.g., GridArchive.

emitters: Sequence[EmitterBase]

A list of emitter objects, e.g., EvolutionStrategyEmitter.

result_archive: ArchiveBase | None = None

An additional archive where all solutions are added. For example, in CMA-MAE, this archive stores all the best-performing solutions, since the main archive does not store all the best-performing solutions.

add_mode: 'batch' | 'single' = 'batch'

Indicates how solutions should be added to the archive. The default is “batch”, which adds all solutions with one call to add(). Alternatively, use “single” to add the solutions one at a time with add_single(). “single” mode is included since implementing batch addition on an archive is sometimes non-trivial. We highly recommend “batch” mode since it is significantly faster.

Raises:

  • TypeError – The emitters argument was not a list of emitters.

  • ValueError – The emitters passed in do not have the same solution dimensions.

  • ValueError – There is no emitter passed in.

  • ValueError – The same emitter instance was passed in multiple times. Each emitter should be a unique instance (see the warning above).

  • ValueError – Invalid value for add_mode.

  • ValueError – The result_archive and archive are the same object (result_archive should not be passed in this case).

Methods

ask()

Generates a batch of solutions by calling ask on all emitters.

ask_dqd()

Generates a batch of solutions by calling ask_dqd on all DQD emitters.

tell(objective, measures, **fields)

Returns info for solutions from ask().

tell_dqd(objective, measures, jacobian, **fields)

Returns info for solutions from ask_dqd().

Attributes

archive

Archive for storing solutions found in this scheduler.

emitters

Emitters for generating solutions in this scheduler.

result_archive

An additional archive for storing solutions found in this scheduler.
ask() → ndarray[source]

Generates a batch of solutions by calling ask on all emitters.

Note

The order of the solutions returned from this method is important, so do not rearrange them.

Returns:

A (batch_size, dim) array of solutions to evaluate. Each row contains a single solution.

Raises:

RuntimeError – This method was called immediately after calling an ask method.

ask_dqd() → ndarray[source]

Generates a batch of solutions by calling ask_dqd on all DQD emitters.

Note

The order of the solutions returned from this method is important, so do not rearrange them.

Returns:

A (batch_size, dim) array of solutions to evaluate. Each row contains a single solution.

Raises:

RuntimeError – This method was called immediately after calling an ask method.

tell(objective: ArrayLike | None, measures: ArrayLike, **fields: ArrayLike | None) → None[source]

Returns info for solutions from ask().

Note

The objective and measures arrays must be in the same order as the solutions created by ask(); i.e. objective[i] and measures[i] should be the objective and measures for solution[i].

Parameters:
objective: ArrayLike | None

(batch_size,) array where each entry contains the objective function evaluation of a solution. This can also be None to indicate there is no objective, which would be the case in diversity optimization problems.

measures: ArrayLike

(batch_size, measure_dim) array where each row contains a solution’s coordinates in measure space.

**fields: ArrayLike | None

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

Raises:
tell_dqd(objective: ArrayLike | None, measures: ArrayLike, jacobian: ArrayLike, **fields: ArrayLike | None) → None[source]

Returns info for solutions from ask_dqd().

Note

The objective, measures, and jacobian arrays must be in the same order as the solutions created by ask_dqd(); i.e. objective[i], measures[i], and jacobian[i] should be the objective, measures, and jacobian for solution[i].

Parameters:
objective: ArrayLike | None

(batch_size,) array where each entry contains the objective function evaluation of a solution. This can also be None to indicate there is no objective, which would be the case in diversity optimization problems.

measures: ArrayLike

(batch_size, measure_dim) array where each row contains a solution’s coordinates in measure space.

jacobian: ArrayLike

(batch_size, 1 + measure_dim, solution_dim) array consisting of Jacobian matrices of the solutions obtained from ask_dqd(). Each matrix should consist of the objective gradient of the solution followed by the measure gradients.

**fields: ArrayLike | None

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

Raises:
property archive : ArchiveBase

Archive for storing solutions found in this scheduler.

property emitters : Sequence[EmitterBase]

Emitters for generating solutions in this scheduler.

property result_archive : ArchiveBase

An additional archive for storing solutions found in this scheduler.

If result_archive was not passed to the constructor, this property is the same as archive.