Fitness Calculators¶

Fitness calculators are classes which inherit FitnessCalculator and define a get_fitness() method. This method is used to calculate the fitness of molecules. A FitnessCalculator will hold calculated fitness values in a cache. The values calculated by get_fitness() can be any Python object, as long as the value after FitnessNormalizer.normalize is applied is set to a positive, non-zero float. The FitnessCalculator can be pickled if the calculated values are to be saved.

For examples of how a FitnessCalculator may be used, look at the documentation of classes which inherit it, for example PropertyVector.

During the EA, fitness values are initially calculated by a fitness calculator, which is an instance of a FitnessCalculator. After this, fitness normalization takes place through an instance of a FitnessNormalizer. The difference between fitness calculation and normalization is that a fitness calculation always returns the same fitness value for a given molecule and conformer, while fitness normalization updates existing fitness values based on all the fitness values in a population, for example by dividing the fitness value of all molecules by the mean fitness across the population.

Making New Fitness Calculators¶

A new class inheriting FitnessCalculator must be created. FitnessCalculator is an abstract base class and its virtual methods must be implemented.

class FitnessCalculator¶

Bases: stk.calculators.base_calculators.MoleculeCalculator

Calculates fitness values of molecules.

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, /, *args, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

Raises

NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

set_cache_use(self, use_cache)¶

Set cache use on or off.

Parameters: use_cache (bool) – True if the cache is to be used.
Returns: The calculator.
Return type: MoleculeCalculator
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

class FitnessFunction(fitness_fn, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator

Takes a function and uses it as a calculator.

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, fitness_fn, use_cache=False)¶

Initialize a FitnessFunction instance.

Parameters

fitness_fn (callable) – Take a single parameter, the Molecule whose fitness needs to be calculated, and returns its fitness value.
use_cache (bool, optional) – If True a fitness calculation will not be performed on the same molecule twice, instead the previously returned value will be returned.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

set_cache_use(self, use_cache)¶

Set cache use on or off.

Parameters: use_cache (bool) – True if the cache is to be used.
Returns: The calculator.
Return type: MoleculeCalculator

class PropertyVector(*property_fns, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator

Calculates a set of properties of a molecule.

This FitnessCalculator applies a series of function to a Molecule and appends each result to a list. The list forms the property vector of the molecule and it is returned as the fitness value of the molecule.

Examples

Use on BuildingBlock objects.

import stk

# Create the molecules which are to have fitness values
# evaluated.
mol1 = stk.BuildingBlock('NCCN', ['amine'])
mol2 = stk.BuildingBlock('NC[Si]CCCN', ['amine'])
mol3 = stk.BuildingBlock('O=CCC(C=O)CCC=O', ['aldehyde'])

# Create the functions which calculate the molecule properties.
def atom_number(mol):
    return len(mol.atoms)

def diameter(mol):
    return mol.maximum_diamater()

def energy(mol):
    energy_calculator = stk.MMFFEnergy()
    return energy_calculator.get_energy(mol)

# Create the fitness calculator.
fitness_calculator = PropertyVector(
    atom_number,
    diameter,
    energy
)

# Calculate the fitness vector of mol1. It will be a list
# holding the number of atoms, diameter and energy of mol1,
# respectively.
mol1_fitness = fitness_calculator.get_fitness(mol1)

# Calculate the fitness vector of mol2. It will be a list
# holding the number of atoms, diameter and energy of mol2,
# respectively.
mol2_fitness = fitness_calculator.get_fitness(mol2)

# Calculate the fitness vector of mol3. It will be a list
# holding the number of atoms, diameter and energy of mol3,
# respectively.
mol3_fitness = fitness_calculator.get_fitness(mol3)

Use on ConstructedMolecule objects

# First create molecules whose fitness value we wish to
# calculate.
bb1 = stk.BuildingBlock('[Br]CC[Br]', ['bromine'])
polymer1 = stk.ConstructedMolecule(
    building_blocks=[bb1],
    topology_graph=stk.polymer.Linear('A', [0], n=5)
)

bb2 = stk.BuildingBlock('[Br]CCNNCC[Br]', ['bromine'])
polymer2 = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graph=stk.polymer.Linear('AB', [0, 0], n=2)
)

# Create the functions which calculate the molecule properties.
def atom_number(mol):
    return len(mol.atoms)

def diameter(mol):
    return mol.maximum_diameter()

def monomer_number(mol):
    return sum(mol.building_block_counter.values())

# Create the fitness calculator.
fitness_calculator = PropertyVector(
    atom_number,
    diameter,
    monomer_number
)

# Calculate the fitness vector of polymer1. It will be a list
# holding the number of atoms, diameter and the number of
# monomers in polymer1, respectively.
polymer1_fitness = fitness_calculator.get_fitness(polymer1)

# Calculate the fitness vector of polymer2. It will be a list
# holding the number of atoms, diameter and the number of
# monomers in polymer2, respectively.
polymer2_fitness = fitness_calculator.get_fitness(polymer2)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, *property_fns, use_cache=False)¶

Initialize a CageFitness instance.

Parameters

*property_fns (tuple of function) – A group of function, each of which is used to calculate a single property of the molecule. Each function must take one parameter, mol, which accepts a Molecule object. This is the molecule used to calculate the property.
use_cache (bool, optional) – If True then fitness values for molecules already held in the cache are not re-calculated but the value already stored is used.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

set_cache_use(self, use_cache)¶

Set cache use on or off.

Parameters: use_cache (bool) – True if the cache is to be used.
Returns: The calculator.
Return type: MoleculeCalculator