class stk.Selector(key_maker, fitness_modifier, batch_size)[source]

Bases: Generic[T]

An abstract base class for selectors.

Selectors select batches of molecules from a population. Each batch is selected based on its fitness. The fitness of a batch is the sum of all fitness values of the molecules in the batch. Batches may be of size 1.


You might notice that some of the public methods of this abstract base class are implemented. This is purely for convenience when implementing subclasses. The implemented public methods are simply default implementations, which can be safely ignored or overridden, when implementing subclasses. Any private methods are implementation details of these default implementations.

The Default Implementation

This section is only of use to people who want to add a new Selector subclass, and want to make use of the default implementation to make this job easier.

When using the default implementation you do not need to implement select(), which is already provided, but instead _select_from_batches() needs to be implemented. What the default implementation provides, is code, which does the batching of a population for you, which means you only have to worry about implementing the selection algorithm, which works on batches directly.

The default implementation also automatically updates a YieldedBatches object for you, so that you can keep track of which batches have already been yielded, in case you want to prevent duplicate selection of batches or molecule records. Though whether you want to make use of this will depend on the nature of your selection algorithm.

See also

  • Batch: Represents batches of selected molecules.


Subclass Implementation

The source code of the classes listed in selector can serve as good examples.

  • key_maker (MoleculeKeyMaker) – Used to get the keys of molecules, which are used to determine if two molecule records are duplicates of each other.

  • fitness_modifier (Callable[[dict[T, float]], dict[T, float]]) – Takes the population on which select() is called and returns a dict, which maps records in the population to the fitness values the Selector should use.

  • batch_size (int) – The number of molecules yielded at once.



Yield batches of molecule records from population.

select(population, included_batches=None, excluded_batches=None)[source]

Yield batches of molecule records from population.

  • population (dict[T, float]) – A collection of molecules from which batches are selected.

  • included_batches (set[BatchKey] | None) – The identity keys of batches which are allowed to be yielded, if None all batches can be yielded. If not None only batches included_batches will be yielded.

  • excluded_batches (set[BatchKey] | None) – The identity keys of batches which are not allowed to be yielded. If None, no batch is forbidden from being yielded.


A batch of selected molecule records.

Return type: