Applications

NV centre characterisation

The model searches presented in [GFK20] have exploration strategies as presented here.

Greedy search

class qmla.exploration_strategies.nv_centre_spin_characterisation.NVCentreExperimentalData(exploration_rules, **kwargs)

Study experimental data.

Uses the same model generation/comparison strategies as SimulatedExperimentNVCentre, but targets data measured from a real system. This is done by using an alternative qinfer_model_subroutine, which searches in the dataset for the system’s likelihood, rather than computing it.

get_measurements_by_time()

Uses the experimental data as target system data.

class qmla.exploration_strategies.nv_centre_spin_characterisation.FullAccessNVCentre(exploration_rules, **kwargs)

Exploration strategy for NV system described in experimental paper, assuming full access to the state so the likelihood is based on :math`langle++ | e^{ -ihat{H(vec{x})} t } | ++ rangle`.

This is the base class for results presented in the experimental paper, namely Fig 2. The same model generation strategy is used in each case (i), (ii), (iii): this ES is for (i) pure simulation.

generate_models(model_list, spawn_step, model_dict, **kwargs)

Determine the next set of models for this exploration strategy.

This method is the main driver of QMLA. This method is called iteratively during the spawn stage of QMLA, until check_tree_completed() returns True, for instance after a fixed depth of spawning. In particular it is called by next_layer(), which either spawns on the ES tree, or prunes it.

Custom ESs must use this method to determine a set of models for QMLA to consider on the next layer (or BranchQMLA) of QMLA. Such a set of models can be constructed based on the results of the previous layers, or according to any logic required by the ES.

Custom methods to replace this have access to the following parameters, and must return the same format of outputs. # TODO remove old/unused data passed to this method

Parameters

• model_list (list) – list of models on the previous QMLA layer, ordered by their ranking on that layer.

• model_names_ids (dict) – map ID : model_name for all models in the QuantumModelLearningAgent instance.

• called_by_branch (int) – the branch ID from which QMLA is spawning. This does not always need to be set; it is mostly used by the ExplorationTree to track which models/branches are parents/children of each other.

• branch_model_points (dict) – `` ID : number_wins `` number of wins of each model in the previous branch.

• evaluation_log_likelihoods (dict) – `` ID : eval_log_likel `` foe each model in the previous branch, where eval_log_likel is the log likelihood computed against a set of validation data (i.e. not the data on which the model was trained.)

• model_dict (dict) – lists of models in the QMLA instance, organised by corresponding number of qubits.

Return list model_names

names of models as unique strings where terms in each model are separated by +, and each term in each model is interpretable by process_basic_operator().

class qmla.exploration_strategies.nv_centre_spin_characterisation.SimulatedExperimentNVCentre(exploration_rules, **kwargs)

Uses all the same functionality, growth etc as TieredGreedySearchNVCentre, but uses an expectation value which traces out the environment, mimicing the Hahn echo measurement.

This is used to generate (ii) simulated data in the Nature Physics 2021 paper.

class qmla.exploration_strategies.nv_centre_spin_characterisation.TieredGreedySearchNVCentre(exploration_rules, **kwargs)

Exploration strategy for NV system described in Nature Physics 2021 paper, assuming full access to the state so the likelihood is based on \(\langle++| e^{ -i\hat{H(\vec{x})} t } |++\rangle\).

This is the base class for results presented in the experimental paper, namely Fig 2. The same model generation strategy is used in each case (i), (ii), (iii):

this ES is for (i) pure simulation.

check_tree_completed(spawn_step, **kwargs)

QMLA asks the exploration tree whether it has finished growing; the exploration tree queries the exploration strategy through this method

generate_models(model_list, **kwargs)

Overwrites qmla.QuantumModelLearningAgent.generate_models().

Constructs models in tiers, where each tier is explored greedily, and only the strongest model from the tier is progressed as the seed model for the subsequent tier.

Genetic algorithm for spin bath

class qmla.exploration_strategies.nv_centre_spin_characterisation.nature_physics_2021.NVCentreGenticAlgorithmPrelearnedParameters(exploration_rules, true_model=None, **kwargs)

Exploration strategy for studying large model space of NV centre through a genetic algorithm.

Model generation is through the genetic algorithm exploration strategy, Genetic. This Exploration Strategy sets up the true model as an NV centre spin interacting with a number of nuclei, and makes a wider number of nuceli searchable by the genetic algorithm. The NV centre is approximated by the Gali approximation [SCG13]. Candidate models are assumed to have been learned extremely well by a parameter esimation algorithm, which may be unrealistic in some cases. In the genetic algorithm, to assess candidate models, we use an objective function which computes the average residual between the candidate and the system’s dynamics, against a representative dataset.

_get_secular_approx_true_params(num_qubits=2, total_num_qubits=5)

Using the secular approximation, define true parameters for all present terms.

Parameters

• num_qubits (int) – number of qubits in the target model

• total_num_qubits (int) – number of qubits of the search space, i.e. terms will be defined in this dimension, even if the system is not expected to be this large.

Returns dict true_params

frequencies of each term to include in the true model

_set_true_params()

Set up the target model: call a series of subroutines to define the true model, as well as setting the parameters to represent the physics appropriately.

_setup_available_terms_gali_model(n_qubits=2, available_axes=['z'])

Generates the set of terms to include in the genetic algorithm.

Terms are stored as an attribute of the class.

Parameters

• n_qubits (int) – number of qubits to construct terms up to

• available_axes (lsit) – axes about which to generate terms, under the Gali approximation

_setup_prior_by_parameters()

Constructs the prior distribution to assign true parameters in the model.

These are set in the gaussian_prior_means_and_widths attribute of this exploration strategy class.

generate_evaluation_data(num_times=100, **kwargs)

Generates sequential, equally spaced times for evaluating the candidate models against.

Parameters

num_times (int) – number of datapoints to generate

Returns dict eval_data

set of experiments for model evaluation

get_evaluation_prior(model_name, estimated_params, cov_mt, **kwargs)

Generate a QInfer distribution representing the trained model’s paramterisation, in order to evaluate that model.

Parameters

• model_name (str) – string representing the candidate model

• estimated_params (dict) – average values of the posterior distribution after training, representing the parameter estimates for the model

• cov_mt (np.array) – covariance matrix, i.e. the relationship between parameters after training

get_prior(model_name, **kwargs)

Given a candidate model, constructs a very thin prior.

This is done to skip the model training stage, and assumes the training has performed extremely well. This method is called by QMLA in constructing candidate models.

Parameters

model_name (str) – string representing the model which is being tested.

Returns prior

QInfer object, used for sampling parameter values when considering the given model

Genetic Algorithms

Genetic algorithms can be used within the Exploration Strategy of QMLA; here we provide a genetic algorithm framework which can be plugged in.

class qmla.shared_functionality.genetic_algorithm.GeneticAlgorithmQMLA(genes, num_sites, true_model=None, base_terms=['x', 'y', 'z'], selection_method='roulette', crossover_method='one_point', mutation_method='element_wise', mutation_probability=0.1, selection_truncation_rate=0.5, num_protected_elite_models=2, unchanged_elite_num_generations_cutoff=5, log_file=None, **kwargs)

Standalone genetic algorithm implementation for integration with qmla.QuantumModelLearningAgent.

This class works with the ExplorationStrategy to construct models according to the genetic strategy.

Parameters

• genes (list) – individual terms which can be combined to form chromosomes

• num_sites (int) – maximum dimension permitted in model search

• true_model (str) – target model. if None, set at random from space of valid models.

• base_terms (list) – deprecated TODO remove

• selection_method (str) – mechanism through which to select chromosomes as parents. Currently only ‘roulette’ available, but the framework should facilitate alternatives.

• crossover_method (str) – mechanism through which parent chromosomes are combined to form offspring. Currently only ‘one_point’ available, but the framework should facilitate alternatives.

• mutation_method (str) – mechanism through which to perform chromosome mutation Currently only ‘element_wise’ available, but the framework should facilitate alternatives.

• mutation_probability (float) – rate with which the mutation mechanism incurs mutation.

• selection_truncation_rate (float) – fraction of models to retain as viable parents to the subsequent generation; the lower-rated other models are discarded.

• num_protected_elite_models (int) – number of models to automatically admit to the subsequent generation.

• unchanged_elite_num_generations_cutoff (int) – after this number of generations, if the top model has not changed, the model search is terminated.

• log_file (str) – path of QMLA instance’s log file.

basic_pair_selection(chromosome_selection_probabilities, **kwargs)

Mechanism for selecting two models from the database of potential parents.

Parameters

chromosome_selection_probabilities (pd.DataFrame) – database indicating the probability that every valid pair of parents should be selected.

Return tuple selected_chromosomes

two models

chromosome_f_score(chromosome)

Get the F score of a candidate model from its chromosome representation.

Parameters

chromosome (np.array) – representation of candidate model

Returns float f_score

F score, between 0 and 1, indicating how many terms overlap between the candidate and target models.

chromosome_string(c)

Map a chromosome array to a string.

consolidate_generation(model_fitnesses, **kwargs)

Following the training of all models on a generation, consolidate that generation.

This involves determining the strongest models from the generation, and constructing the database of parent-pairs and their associated selection probabilities.

Parameters

model_fitnesses (dict) – the fitness of each model in this generation according to the chosen objective function.

crossover(**kwargs)

Wrapper for crossover mechanism.

This method assumes only 2 chromosomes to crossover and passes them to the method set as self.crossover_method, which can be easily replaced to facilitate alternative crossover schemes.

element_wise_mutation(**kwargs)

Probabilistically mutate each gene independently.

elite_ranking_top_n_models(model_fitnesses, **kwargs)

Get the top N models, and store info on the elite models to date.

Parameters

model_fitnesses (dict) – the fitness of each model in this generation according to the chosen objective function.

genetic_algorithm_step(model_fitnesses, **kwargs)

Perform a complete step of the genetic algorithm, assuming all of the required steps have been performed. That is, the database for parent selection must already be available.

Parameters

model_fitnesses (dict) – the fitness of each model in this generation according to the chosen objective function.

Returns list new_models

set of models to place on the next generation.

get_base_chromosome()

Creates basic chromosome, i.e. with all genes set to 0.

get_elite_models(**kwargs)

Wrapper for elite model selection method,

here set to self.elite_ranking_top_n_models.

get_pair_selection_order()

Use the probabilities of parental selection to define the order in which to generate offspring. It is cheaper to perform this once than call the database repeatedly.

Return list pair_selection_order

list of tuples of the order in which to pass the model pairs to the crossover mechanism to generate offspring

get_selection_probabilities(**kwargs)

Wrapper for parent selection function, here set to self.truncate_to_top_half.

log_print(to_print_list)

Wrapper for print_to_log()

map_chromosome_to_model(chromosome)

Given a chromosome, get the corresponding model.

Parameters

chromosome (np.array) – chromosome representing a candidate model

Returns str model_string

name of the corresponding model

map_model_to_chromosome(model)

Given a model, get the corresponding chromosome.

Parameters

model (str) – name of candidate model

Returns np.array chromosome

array of ones and zeros indicating which genes are active in the model

model_f_score(model_name)

Get the F score of a candidate model.

Parameters

model_name (str) – name of candidate model

Returns float f_score

F score, between 0 and 1, indicating how many terms overlap between the candidate and target models.

mutation(**kwargs)

Wrapper for mutation mechanism. All input arguments to the mutation method are passed directly to the nominated mutation function, set as self.mutation_method.

one_point_crossover(**kwargs)

Crossover two chromosomes about a single gene.

Input two chromosomes, and selection (a dict) in kwargs. selection contains chromosome_1 and chromosome_2, as well as a dict called other_data containing cut, which is the position about which to crossover the two chromosomes.

prepare_chromosome_pair_dataframe(chromosome_probabilities, force_mutation=False)

Given a set of individual chromosome fitnesses, generate database of pairs of parent chromosomes, with probability proportional to the fitness of both parents.

rand_model_f()

Generate a random model chromosome and evaluate its F score.

random_initial_models(num_models=5)

Generate random models from the space of valid candidates.

Parameters

num_models (int) – number of candidates to generate

Returns list new_models

the randomly generated model names

random_models_sorted_by_f_score(num_models=14)

Generate a set of random models and sort them by F score.

selection(**kwargs)

Wrapper for user’s selected selection method.

Whatever method is called must return

• prescribed_chromosomes

• chromosomes_for_crossover - pairs

truncate_to_top_half(model_fitnesses, **kwargs)

Retain only the top-performing half of models considered at this generation, for consideration as parents to offspring on the subsequent generation.

Parameters

model_fitnesses (dict) – the fitness of each model in this generation according to the chosen objective function.

Genetic Exploration Strategy

A base class for genetic algorithm incorporated into the Exploration Strategy.

class qmla.exploration_strategies.genetic_algorithms.genetic_exploration_strategy.Genetic(exploration_rules, genes, true_model, **kwargs)

Exploration Strategy where the model search is mediated through a genetic algorithm. Genetic algorithm is implemented through qmla.GeneticAlgorithmQMLA. This forms the base class for genetic algorithm applications within QMLA.

Parameters

• exploration_rules (str) – name of exploration strategy used

• genes (list) – terms which are permitted in the model search, which become genes in the chromomsomes of the genetic algorithm

• true_model (str) – name of the target model.

__plot_gene_pool_progression()

Succinct representation of the progression of gene pool with respect to F score.

_plot_correlation_fitness_with_f_score(save_to_file=None)

Show how the fitness of models at each generation progress in terms of F score.

_plot_fitness_v_fscore()

Plot fitness against f score

_plot_fitness_v_fscore_by_generation()

Plot fitness vs f score throughout generations of the genetic algorithm.

_plot_fitness_v_generation(save_to_file=None)

Plot progression of fitness against generations of the genetic algorithm.

_plot_gene_pool()

Show the F scores of all models in all generations

_plot_model_ratings()

Plot ratings of models on all generations, as determined by the RatingSystem

_plot_selection_probabilities()

Plot pie charts of the selection probabilities of prospective parents at each generation. Models are signified by their F score.

analyse_generation(model_points, model_names_ids, **kwargs)

Following a complete generation of the genetic algorithm, perform all necessary processing to enable construction of next set of models.

Parameters

• model_points (dict) – the number of Bayes factor comparisons for which each candidate within the generation was deemed superior against a contemporary model

• model_names_ids (dict) – mapping between models’ names and their IDs from the QMLA environment; this enables analaysing further data passed from QMLA within kwargs.

check_tree_completed(spawn_step, **kwargs)

Genetic algorithm specific version of qmla.ExplorationStrategy.check_tree_completed().

check_tree_pruned(**kwargs)

Genetic algorithm specific version of qmla.ExplorationStrategy.check_tree_pruned().

exploration_strategy_finalise()

Genetic algorithm specific version of qmla.ExplorationStrategy.exploration_strategy_finalise().

f_score_from_chromosome_string(chromosome)

F1 score between chromosome and true model

f_score_model_comparison(test_model, target_model=None, beta=1)

Get F score of candidate model, measure of overlap between the terms of the candidate and target model

Parameters

• test_model (str) – name of candidate model

• target_model (str) – name of target model, if None, assumed that target is self.true_model

• beta (float) – relative importance of precision to sensitivity. in general this is F-beta score, usually beta = 1

static gene_pool_progression(gene_pool, ax, f_score_cmap=None, draw_cbar=True, cbar_ax=None)

Method for plotting succinct summary of progression of gene pool with respect to F score.

generate_models(model_list, **kwargs)

Model generation using genetic algorithm.

Follows rules of generate_models().

hamming_distance_model_comparison(test_model, target_model=None)

Compare test_model with target_model by Hamming distance

nominate_champions()

Choose model with highest fitness on final generation

plot_generational_metrics()

Show various metrics across all generations

set_specific_plots(**kwargs)

Genetic algorithm specific version of qmla.ExplorationStrategy.set_specific_plots().