Optimisation Package

This module contains code for automatically optimising parametric models for a given sequence.

Submodules

isambard.optimisation.base_evo_opt module

Base class for bio-inspired optimizers.

class isambard.optimisation.base_evo_opt.BaseOptimizer(specification, sequences, parameters, build_fn=None, eval_fn=None, **kwargs)

Bases: object

Abstract base class for the evolutionary optimizers.

Notes

Not intended to be used directly, see the evolutionary optimizers for full documentation.

assign_fitnesses(targets)

Assigns fitnesses to parameters.

Notes

Uses self.eval_fn to evaluate each member of target.

Parameters:targets – Parameter values for each member of the population.

best_model

Rebuilds the top scoring model from an optimisation.

Returns:model – Returns an AMPAL model of the top scoring parameters. Return type:AMPAL Raises:AttributeError – Raises a name error if the optimiser has not been run.

static funnel_rebuild()

Rebuilds a model and compares it to a reference model.

Parameters:psg_trm ((([float], float, int), AMPAL, specification)) – A tuple containing the parameters, score and generation for a model as well as a model of the best scoring parameters. Returns:energy_rmsd_gen – A triple containing the BUFF score, RMSD to the top model and generation of a model generated during the minimisation. Return type:(float, float, int)

log_results(output_path=None, run_id=None)

Saves files for the minimization.

Notes

Currently saves a logfile with best individual and a pdb of the best model.

make_energy_funnel_data(cores=1)

Compares models created during the minimisation to the best model.

Parameters:cores (int) – Number of CPU cores to rebuild models and measure RMSD. Returns:energy_rmsd_gen – A list of triples containing the BUFF score, RMSD to the top model and generation of a model generated during the minimisation. Return type:[(float, float, int)]

parse_individual(individual)

Converts a deap individual into a full list of parameters.

Parameters:individual (deap individual from optimization) – Details vary according to type of optimization, but parameters within deap individual are always between -1 and 1. This function converts them into the values used to actually build the model Returns:fullpars – Full parameter list for model building. Return type:list

run_opt(pop_size, generations, cores=1, plot=False, log=False, log_path=None, run_id=None, store_params=True, **kwargs)

Runs the optimizer.

Parameters:

• pop_size (int) – Size of the population each generation.
• generation (int) – Number of generations in optimisation.
• cores (int, optional) – Number of CPU cores used to run the optimisation. If the ‘mp_disabled’ keyword is passed to the optimizer, this will be ignored and one core will be used.
• plot (bool, optional) – If true, matplotlib will be used to plot information about the minimisation.
• log (bool, optional) – If true, a log file describing the optimisation will be created. By default it will be written to the current directory and named according to the time the minimisation finished. This can be manually specified by passing the ‘output_path’ and ‘run_id’ keyword arguments.
• log_path (str) – Path to write output file.
• run_id (str) – An identifier used as the name of your log file.
• store_params (bool, optional) – If true, the parameters for each model created during the optimisation will be stored. This can be used to create funnel data later on.

class isambard.optimisation.base_evo_opt.Parameter(label, parameter_type, value)

Bases: object

Defines a parameter used in the evolutionary optimizers.

default_value

classmethod dynamic(label, val_mean, val_range)

Creates a static parameter.

Parameters:

• label (str) – A human-readable label for the parameter.
• val_mean (float) – The mean value of the parameter.
• val_range (float) – The minimum and maximum variance from the mean allowed for parameter.

classmethod static(label, value)

Creates a static parameter.

Parameters:

• label (str) – A human-readable label for the parameter.
• value – The static value to be used.

class isambard.optimisation.base_evo_opt.ParameterType

Bases: enum.IntEnum

Type of parameter used in evolutionary optimizers.

DYNAMIC = 2

STATIC = 1

isambard.optimisation.base_evo_opt.default_build(spec_seq_params)

isambard.optimisation.evo_optimizers module

Bio-inspired optimizers.

class isambard.optimisation.evo_optimizers.CMAES(specification, sequences, parameters, eval_fn, build_fn=<function default_build>, sigma=0.3, weight_type='superlinear', **kwargs)

Bases: isambard.optimisation.base_evo_opt.BaseOptimizer

Covariance matrix adaptation evolutionary strategy optimizer.

Notes

Basically uses a covariance matrix at each step to identify the ‘direction’ of the optimal solution in the search space, and generates new individuals accordingly. Bound handling is achieved by moving any out of bounds parameters to the boundary condition. Other than that the implementation used here is as in the originating code from the deap module.

Parameters:

• specification (ampal.specification.assembly_specification) – An Assembly level specification to be optimised.
• sequences ([str]) – A list of sequences, one for each polymer.
• parameters ([base_ev_opt.Parameter]) – A list of Parameter objects in the same order as the function signature expects.
• build_fn (function((spec, seq, params)) -> ampal) – A function for building a model using parameters supplied by the optimizer.
• eval_fn (function(ampal) -> float) – An evaluation function that assesses an AMPAL object and returns a float. This float will be used to compare models. The optimizer uses the thermodynamic convention that lower numbers are better.
• sigma (float) – Initial standard deviation of the distribution.
• weight_type (str) – Can be ‘linear’, ‘superlinear’ or ‘equal’. Used to decrease speed of particles.

compute_params()

Computes the parameters depending on \(\lambda\).

Notes

It needs to be called again if \(\lambda\) changes during evolution.

initialize_cma_es(lambda_)

A strategy that will keep track of the basic parameters.

Parameters:

• centroid – An iterable object that indicates where to start the evolution.
• parameter – One or more parameter to pass to the strategy as described in the following table, optional.

update(population)

Update the covariance matrix strategy from the population.

Parameters:population – A list of individuals from which to update the parameters.

class isambard.optimisation.evo_optimizers.DE(specification, sequences, parameters, eval_fn, build_fn=<function default_build>, cxpb=0.75, diff_weight=1, neighbours=None, **kwargs)

Bases: isambard.optimisation.base_evo_opt.BaseOptimizer

Differential evolution optimisation algorithm.

Notes

Can use neighbourhood model to reduce chance of getting stuck in local optima. This is a very versatile algorithm, and its use is recommended.

Parameters:

• specification (ampal.specification.assembly_specification) – An Assembly level specification to be optimised.
• sequences ([str]) – A list of sequences, one for each polymer.
• parameters ([base_ev_opt.Parameter]) – A list of Parameter objects in the same order as the function signature expects.
• build_fn (function((spec, seq, params)) -> ampal) – A function for building a model using parameters supplied by the optimizer.
• eval_fn (function(ampal) -> float) – An evaluation function that assesses an AMPAL object and returns a float. This float will be used to compare models. The optimizer uses the thermodynamic convention that lower numbers are better.
• cxpb (float) – The probability of crossing two individuals.
• diff_weight (float) – A scaling factor for crossing.
• neighbours (int or None) – If not None, uses a neighbourhood model to reduce the likelihood of the optimisation getting stuck in a local optima. The number of particles to use as neighbours can be provided as an int.

class isambard.optimisation.evo_optimizers.GA(specification, sequences, parameters, eval_fn, build_fn=<function default_build>, cxpb=0.5, mutpb=0.2, **kwargs)

Bases: isambard.optimisation.base_evo_opt.BaseOptimizer

A classic genetic algorithm optimization algorithm.

Notes

Very good for eliminating unfavourable regions of the search space. Can be heavily customized in terms of mutation and crossover operators etc. Bound handling is achieved simply by amending any out of bounds parameters to the boundary value.

Parameters:

• specification (ampal.specification.assembly_specification) – An Assembly level specification to be optimised.
• sequences ([str]) – A list of sequences, one for each polymer.
• parameters ([base_ev_opt.Parameter]) – A list of Parameter objects in the same order as the function signature expects.
• build_fn (function((spec, seq, params)) -> ampal) – A function for building a model using parameters supplied by the optimizer.
• eval_fn (function(ampal) -> float) – An evaluation function that assesses an AMPAL object and returns a float. This float will be used to compare models. The optimizer uses the thermodynamic convention that lower numbers are better.
• cxpb (float) – The probability of crossing two individuals.
• mutpb (float) – Probability of mutating an individual.

class isambard.optimisation.evo_optimizers.PSO(specification, sequences, parameters, eval_fn, build_fn=<function default_build>, max_speed=0.75, neighbours=None, **kwargs)

Bases: isambard.optimisation.base_evo_opt.BaseOptimizer

A particle swarm optimization algorithm.

Notes

This is good for avoiding bias and premature minimization, though it may struggle to find the ultimate optimum solution. Supports the neighbourhood model. Bound handling is achieved by allowing particles to exceed permitted bounds, but not assigning them a fitness in this case.

Parameters:

• specification (ampal.specification.assembly_specification) – An Assembly level specification to be optimised.
• sequences ([str]) – A list of sequences, one for each polymer.
• parameters ([base_ev_opt.Parameter]) – A list of Parameter objects in the same order as the function signature expects.
• build_fn (function((spec, seq, params)) -> ampal) – A function for building a model using parameters supplied by the optimizer.
• eval_fn (function(ampal) -> float) – An evaluation function that assesses an AMPAL object and returns a float. This float will be used to compare models. The optimizer uses the thermodynamic convention that lower numbers are better.
• max_speed (float) – The maximum speed that a particle can have in the swarm.
• neighbours (int or None) – If not None, uses a neighbourhood model to reduce the likelihood of the optimisation getting stuck in a local optima. The number of particles to use as neighbours can be provided as an int.

update_particle(part, chi=0.729843788, c=2.05)

Constriction factor update particle method.

Notes

Looks for a list of neighbours attached to a particle and uses the particle’s best position and that of the best neighbour.

isambard.optimisation.mmc_optimizer module

Provides optimisation of structure using Metropolis Monte Carlo.

class isambard.optimisation.mmc_optimizer.MMCParameter(label, parameter_type, static_dist_or_list, starting_value=None)

Bases: object

Defines parameters used in the MMC optimizer.

Parameters:

• label (str) – The name of the parameter.
• parameter_type (MMCParameterType) – The type of the parameter.
• static_dist_or_list – The values used to create the parameter. For example, if the parameter types is “STATIC_VALUE” then this can be any object, if it is “LIST” then it should be a list of values and if it is “UNIFORM_DIST” then it should be (mu, sigma) etc.
• optional (starting_value,) – The initial value of the parameter.

label

str – The name of the parameter.

parameter_type

MMCParameterType – The type of the parameter.

static_dist_or_list

The values used to create the parameter. For example, if the parameter types is “STATIC_VALUE” then this can be any object, if it is “LIST” then it should be a list of values and if it is “UNIFORM_DIST” then it should be (mu, sigma) etc.

starting_value

The initial value of the parameter.

current_value

The currently accepted value for the parameter.

proposed_value

A new value proposed for the parameter that has not been accepted.

accept_proposed_value()

Changes the current value to the proposed value.

randomise_proposed_value()

Creates a randomly the proposed value.

Raises:

• TypeError – Raised if this method is called on a static value.
• TypeError – Raised if the parameter type is unknown.

reject_proposed_value()

Removes the proposed value.

class isambard.optimisation.mmc_optimizer.MMCParameterOptimisation(specification, parameters, sequences, eval_function)

Bases: object

Performs Metropolis Monte Carlo opimisation on a specification.

References

[0]	Metropolis N, Rosenbluth AW, Rosenbluth MN, Teller AH and Teller E (1953) Equations of State Calculations by Fast Computing Machines, Journal of Chemical Physics. 21 (6), 1087-1092.

Parameters:

• specification (isambard.Specification) – Any ISAMBARD specification. This will be used to create models during the optimisation.
• parameters ([MMCParameter]) – Parameters to be optimised. The order of the parameters should match the init signiture of the specification.
• sequences ([str]) – The sequences to be used during the optimisation.
• eval_function (f(ampal) -> float) – A function that takes an AMPAL object as an input and returns a float. By default the buff_interaction_energy will be used to evaluate the structure.

specification

isambard.Specification – Any ISAMBARD specification. This will be used to create models during the optimisation.

parameters

[MMCParameter] – Parameters to be optimised. The order of the parameters should match the init signiture of the specification.

sequences

[str] – The sequences to be used during the optimisation.

eval_function

f(ampal) -> float – A function that takes an AMPAL object as an input and returns a float. By default the buff_interaction_energy will be used to evaluate the structure.

current_energy

float – The energy of the current structure.

best_energy

float – The best energy observed for any model.

best_parameters

[MMCParameter] – The parameters associated with the best_energy.

best_model

AMPAL Object – The model associated with the best_energy.

best_energy = None

best_model = None

best_parameters = None

static check_move(old, t)

Determines if a model will be accepted.

Uses Boltzmann distribution scaled by temperature in Kelvin.

current_energy = None

start_optimisation(rounds, temp=298.15)

Begin the optimisation run.

Parameters:

• rounds (int) – The number of rounds of optimisation to perform.
• temp (float, optional) – The temperature (in K) used during the optimisation.

class isambard.optimisation.mmc_optimizer.MMCParameterType

Bases: enum.Enum

Defines the types of parameters that can be used for Monte Carlo.

DISCRETE_RANGE = 2

LIST = 3

NORMAL_DIST = 5

STATIC_VALUE = 1

UNIFORM_DIST = 4

isambard.optimisation.mmc_optimizer.float_f(f)

Formats a float for printing to std out.