Above Average

class AboveAverage(num_batches=None, batch_size=1, duplicate_molecules=True, duplicate_batches=True, key_maker=Inchi(), fitness_modifier=None)[source]

Bases: Selector

Yields above average batches of molecules.

Examples

Yielding Single Molecule Batches

Yielding molecules one at a time. For example, if molecules need to be selected for mutation or the next generation

import stk

# Make the selector.
above_avg = stk.AboveAverage()

population = (
    stk.MoleculeRecord(
        topology_graph=stk.polymer.Linear(
            building_blocks=(
                stk.BuildingBlock(
                    smiles='BrCCBr',
                    functional_groups=[stk.BromoFactory()],
                ),
            ),
            repeating_unit='A',
            num_repeating_units=2,
        ),
    ).with_fitness_value(1),
    stk.MoleculeRecord(
        topology_graph=stk.polymer.Linear(
            building_blocks=(
                stk.BuildingBlock(
                    smiles='BrCCBr',
                    functional_groups=[stk.BromoFactory()],
                ),
            ),
            repeating_unit='A',
            num_repeating_units=2,
        ),
    ).with_fitness_value(2)
)

# Select the molecules.
for selected, in above_avg.select(population):
    # Do stuff with each selected molecule.
    pass

Yielding Batches Holding Multiple Molecules

Yielding multiple molecules at once. For example, if molecules need to be selected for crossover.

import stk

# Make the selector.
above_avg = stk.AboveAverage(batch_size=2)

population = (
    stk.MoleculeRecord(
        topology_graph=stk.polymer.Linear(
            building_blocks=(
                stk.BuildingBlock(
                    smiles='BrCCBr',
                    functional_groups=[stk.BromoFactory()],
                ),
            ),
            repeating_unit='A',
            num_repeating_units=2,
        ),
    ).with_fitness_value(1),
    stk.MoleculeRecord(
        topology_graph=stk.polymer.Linear(
            building_blocks=(
                stk.BuildingBlock(
                    smiles='BrCCBr',
                    functional_groups=[stk.BromoFactory()],
                ),
            ),
            repeating_unit='A',
            num_repeating_units=2,
        ),
    ).with_fitness_value(2)
)

# Select the molecules.
for selected1, selected2 in above_avg.select(population):
    # Do stuff with the selected molecules.
    pass

Methods

select(population[, included_batches, ...])

Yield batches of molecule records from population.
__init__(num_batches=None, batch_size=1, duplicate_molecules=True, duplicate_batches=True, key_maker=Inchi(), fitness_modifier=None)[source]

Initialize an AboveAverage instance.

Parameters:

  • num_batches (int, optional) – The number of batches to yield. If None then yielding will continue forever or until the generator is exhausted, whichever comes first.

  • batch_size (int, optional) – The number of molecule records in each yielded Batch.

  • duplicate_molecules (bool, optional) – If True the same molecule can be yielded in more than one batch.

  • duplicate_batches (bool, optional) – If True the same batch can be yielded more than once.

  • key_maker (MoleculeKeyMaker, optional) – Used to get the keys of molecules. If two molecules have the same key, they are considered duplicates.

  • fitness_modifier (callable, optional) – 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. If None, the regular fitness values of the records are used.

select(population, included_batches=None, excluded_batches=None)

Yield batches of molecule records from population.

Parameters:

  • population (tuple of MoleculeRecord) – A collection of molecules from which batches are selected.

  • included_batches (set, optional) – 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 (class:set, optional) – The identity keys of batches which are not allowed to be yielded. If None, no batch is forbidden from being yielded.

Yields:

Batch of MoleculeRecord – A batch of selected molecule records.