API Reference

Quantum Model Learning Agent

Manager class

The overall QMLA protocol is managed by this class.

class qmla.QuantumModelLearningAgent(qmla_controls=None, model_priors=None, experimental_measurements=None, **kwargs)

QMLA manager class.

Controls the infrastructure which determines which models are learned and compared. By interpreting user defined ExplorationStrategy, grows ExplorationTree objects which hold numerous models on BranchQMLA objects. All models on branches are learned and then compared. The comparisons on a branch inform the next set of models generated on that tree.

First calls a series of setup functions to implement infrastructure used throughout.

The available algorithms, and their corresponding methods, are:

• Quantum Hamilontian Learning:

  run_quantum_hamiltonian_learning()

• Quantum Hamilontian Learning multiple models:

  run_quantum_hamiltonian_learning_multiple_models()

• Quantum Model Learning Agent:

  run_complete_qmla()

Parameters

• qmla_controls (ControlsQMLA) – Storage for configuration of a QMLA instance.

• model_priors (dict) – values of means/widths to enfore on given models, specifically for further_qhl mode.

• experimental_measurements (dict) – expectation values by time of the underlying true/target model.

_check_model_exists(model_name)

True if model already exists; False if not.

_compile_and_store_qmla_info_summary()

Gather info needed to run QMLA tasks and store remotely.

QMLA issues jobs to run remotely, namely for model (parameter) learning and model comparisons (Bayes factors). These jobs don’t need access to all QMLA data, but do need some common info, e.g. number of particles and epochs. This function gathers all relevant information in a single dict, and stores it on the redis server which all worker nodes have access to. It also stores the probe sets required for the same tasks.

_compute_base_resources()

Compute the set of minimal resources for models to learn on.

In the case self.reallocate_resources==True, models will receive resources (epochs, particles) scaled by how complicated they are. For instance, models with 4 parameters will receive twice as many particles as a model with 2 parameters.

_consider_new_model(model_name)

Check whether a proposed model already exists.

Check whether the new model name, exists in all previously considered models, held in model_lists, organised by dimension of models. If name has not been previously considered, ‘New’ is returned. If name has been previously considered, the corresponding location

in db is returned.

Parameters

• model_lists (dict) – lists of models already considered, organised by the number of qubits of those models

• name (str) – model for consideration

_delete_unpicklable_attributes()

Remove elements of QMLA which cannot be pickled, which cause errors if retained.

_fundamental_settings()

Basic settings, path definitions etc.

_get_model_data_by_field(name, field)

Get any data from the model database corresponding to a given model name.

Parameters

• name (str) – model name to get data of

• field (str) – field name to get data corresponding to model

_inspect_remote_job_crashes()

Check if any job on redis queue has failed.

_plot_bayes_factors()

Plot Bayes factors between pairs of models, both by model IDs and by their F-scores.

_plot_branch_champions_dynamics(all_models=False, model_ids=None)

Plot reproduced dynamics of all branch champions

Parameters

• all_models (bool) – whether to plot all models in the instance

• model_ids (list) – list of model IDs to plot dynamics of

• save_to_file (str) – path at which to save the resultant figure

_plot_branch_champs_quadratic_losses()

Wrapper for plot_quadratic_loss().

_plot_branch_champs_volumes(model_id_list=None, branch_champions=True, branch_id=None, save_to_file=None)

Plot the volume of each branch champion within this instance.

Parameters

• model_id_list (list) – list of model IDs to plot volumes of, if None plot branch champions

• branch_champions (bool) – force plot only branch champions’ volumes

• branch_id (int) – if provided, plot the volumes of all models within that branch

• save_to_file (str) – path at which to store the resultant figure.

_plot_dynamics_all_models_on_branches(branches=None)

Plot the dynamics of all models on given branches.

Parameters

branches (list, optional) – list of branches to draw dynamics for, defaults to None, in which case all branches are drawn.

_plot_evaluation_normalisation_records()

Plot the normalisation record of all models grouped by the branch they are on.

_plot_exploration_tree(modlist=None, only_adjacent_branches=True, save_to_file=None)

Wrapper for plot_qmla_single_instance_tree()

_plot_model_terms(colour_by='binary')

Plot the terms of each model by model ID.

Parameters

colour_by (str, optional) – defaults to ‘binary’ for black/white; alternatively colour by f_score of model

_plot_one_qubit_probes_bloch_sphere(save=False)

Show all one qubit probes on Bloch sphere.

_plot_parameter_learning_champion()

Plot parameter estimates vs experiment number for a single model.

Wrapper for plot_parameter_estimates() :param bool true_model: whether to force only plotting the true

model’s parameter estimeates

_plot_parameter_learning_single_model(model_id=0, true_model=False, save_to_file=None)

Plot parameter estimates vs experiment number for a single model.

Wrapper for plot_parameter_estimates() :param bool true_model: whether to force only plotting the true

model’s parameter estimeates

_plot_parameter_learning_true()

Plot parameter estimates vs experiment number for a single model.

Wrapper for plot_parameter_estimates() :param bool true_model: whether to force only plotting the true

model’s parameter estimeates

_plot_qmla_radar_scores(modlist=None, save_to_file=None)

deprecated Wrapper for plotRadar().

_plot_r_squared_by_epoch_for_model_list(modlist=None, save_to_file=None)

Plot $R^2$ vs experiment number for given model list.

_plot_volume_after_qhl(model_id=None, true_model=True, show_resamplings=True, save_to_file=None)

Plot volume vs experiment number of a single model. Wrapper for plot_volume_after_qhl()

_potentially_redundant_setup()

Graveyard for deprecated ifnrastructure.

Attributes etc stored here which are not functionally used within QMLA, but which are called somewhere, and cause errors when omitted. Should be stored here temporarily during development, and removed entirely when sure they are not needed.

_set_learning_and_comparison_parameters(model_priors, experimental_measurements)

Parameters related to learning/comparing models.

_setup_parallel_requirements()

Infrastructure for use when QMLA run in parallel.

_setup_tree_and_exploration_strategies()

Set up infrastructure.

_true_model_definition()

Information related to true (target) model.

_update_database_model_info()

Calls model_update_learned_values() for all models learned in this instance.

add_model_to_database(model, exploration_tree, branch_id=- 1, force_create_model=False)

Considers adding a model to QMLA’s database of models.

Checks whether the nominated model is already present; if not generates a model instance and stores pertinent details in the model database.

Parameters

• model (str) – name of model to consider

• branch_id (float) – branch id to associate this model with, if the model is new.

• force_create_model (bool) – True: add model even if the name is found already. False: (default) check if the model exists before adding

Return dict add_model_output

is_new_model : bool, whether model is new (True) or has already been added (False) model_id: unique model ID for the model, whether new or existing

analyse_instance()

Basic analysis of this instance

check_champion_reducibility()

Potentially remove negligible terms from the champion model.

Consider whether the champion model has some terms whose parameters were found to be negligible (either within one standard deviation from 0, or very close to zero as determined by the exploration strategy’s learned_param_limit_for_negligibility attribute). Construct a new model which is the same as the champion, less those negligible terms, named the reduced champion. The data of the champion model is inherited by the reduced candidate model, i.e. its parameter estimates, as well as its history of parameter learning for those which are not negligible. A new normalization_record is started, which is used in the comparison between the champion and the reduced champion. Compare the champion with the reduced champion; if the reduced champion is heavily favoured, directly select it as the global champion. This method is triggered if the exploration strategy’s check_champion_reducibility attribute is set to True.

compare_model_pair(model_a_id, model_b_id, return_job=False, branch_id=None, remote=True, wait_on_result=False)

Launch the comparison between two models.

Either locally or by passing to a job queue, run remote_bayes_factor_calculation() for a pair of models specified by their IDs.

Parameters

• model_a_id (int) – unique ID of one model of the pair

• model_b_id (int) – unique ID of other model of the pair

• return_job (bool) – True - return the rq job object from this function call. False (default) - return nothing.

• branch_id (int) – unique branch ID, if this model pair are on the same branch

• remote (bool) – whether to run the job remotely or locally True - job is placed on queue for RQ worker False - function is computed locally immediately

• wait_on_result (bool) – whether to wait for the outcome or proceed after sending the job to the queue.

Returns bayes_factor

the Bayes factor calculated between the two models, i.e. BF(m1,m2) where m1 is the lower model id. Only returned when wait_on_result==True.

compare_model_set(model_id_list=None, pair_list=None, remote=True, wait_on_result=False, recompute=False)

Launch pairwise model comparison for a set of models.

If pair_list is specified, those pairs are compared; otherwise all pairs within model_id_list are compared.

Pairs are sent to compare_model_pair() to be computed either locally or on a job queue.

Parameters

• model_id_list (list) – list of model names to compute comparisons between

• pair_list (list) – list of tuples specifying model IDs to compare

• remote (bool) – passed directly to compare_model_pair()

• wait_on_results (bool) – passed directly to compare_model_pair()

• recompute (bool) – whether to force comparison even if a pair has been compared previously

compare_models_within_branch(branch_id, pair_list=None, remote=True, recompute=False)

Launch pairwise model comparison for all models on a branch.

If pair_list is specified, those pairs are compared; otherwise pairs are retrieved from the pairs_to_compare attribute of the branch, which is usually all-to-all.

Pairs are sent to compare_model_pair() to be computed either locally or on a job queue.

Parameters

• branch_id – unique ID of the branch within the QMLA environment

• pair_list (list) – list of tuples specifying model IDs to compare

• remote (bool) – passed directly to compare_model_pair()

• wait_on_results (bool) – passed directly to compare_model_pair()

• recompute (bool) – whether to force comparison even if a pair has been compared previously

compare_nominated_champions()

Compare the champions of all exploration strategy trees.

Get the champions (usually one, but in general can be multiple) from each tree, where each tree is unique to an exploration strategy. Place the champions on a branch together and perform all-versus-all comparisons. The champion of that branch is deemed the global champion.

compute_model_f_score(model_id, model_name=None, model_constructor=None, exploration_class=None, beta=1)

Compte and store f-score of given model.

Parameters

• model_id (int) – model ID to compute f-score of

• beta (float) – for generalised F_beta score. (default) 1 for F1 score.

Return float f_score

F-score of given model.

compute_statistical_metrics_by_generation()

Compute, store and plot various statistical metrics of all studied models.

Parameters

save_to_file (str) – path to save the resultant figure in.

finalise_qmla()

Steps to end QMLA algorithm, such as storing analytics.

get_model_storage_instance_by_id(model_id)

Get the unique ModelInstanceForLearning for the given model_id.

Parameters

model_id (int) – unique ID of desired model

Returns

storage class of the model

Return type

ModelInstanceForLearning

get_results_dict(model_id=None)

Store the useful information of a given model, usually the champion.

Parameters

model_id (int) – unique ID of the model whose information to store

Return dict results_dict

data which will be stored in the results_{ID}.p file following QMLA’s completion.

learn_model(model_name, branch_id, blocking=False)

Learn a given model by calling the standalone model learning functionality.

The model is learned by launching a job either locally or to the job queue. Model learning is implemented by remote_learn_model_parameters(), which takes a unique model name (string) and distills the terms to learn. If running locally, QMLA core info is passed. Else if RQ workers are being used, it retrieves QMLA info from the shared redis database, and the function is launched via rq’s Queue.enqueue function. This puts a task on the redis Queue - the task is the implementation of remote_learn_model_parameters(). The effect is either to learn the model here, or else to have launched a job where it will be learned remotely, so nothing is returned.

Parameters

• model_name (str) – string uniquely representing a model

• branch_id (int) – unique branch ID within QMLA environment

• use_rq (bool) – whether to use RQ workers, or implement locally

• blocking (bool) – whether to wait on model to finish learning before proceeding.

learn_models_on_given_branch(branch_id, blocking=False)

Launches jobs to learn all models on the specified branch.

Models which are on the branch but have already been learned are not re-learned. For each remaining model on the branch, learn_model() is called. The branch is added to the redis database active_branches_learning_models, indicating that branch_id has currently got models in the learning phase. This redis database is monitored by the learn_models_until_trees_complete(). When all models registered on the branch have completed, it is recorded, allowing QMLA to perform the next stage: either spawning a new branch from this branch, or continuing to the final stage of QMLA. This method can block, meaning it waits for a model’s learning to complete before proceeding. If in parallel, do not block as model learning won’t be launched until the previous model has completed.

Parameters

• branch_id (int) – unique QMLA branch ID to learn models of.

• use_rq (bool) – whether to implement learning via RQ workers. Argument only used when passed to QuantumModelLearningAgent.learn_model().

• blocking (bool) – whether to wait on all models’ learning before proceeding.

learn_models_until_trees_complete()

Iteratively learn/compare/generate models on exploration strategy trees.

Each ExplorationStrategy has a unique QMLATree`. Trees hold sets of models on BranchTree objects.

Models on a each branch are learned through learn_models_on_given_branch(). Any model which has previously been considered defaults to the earlier instance of that model, rather than repeating the calculation. When all models on a branch are learned, they are all compared through compare_models_within_branch().

When a branch has completed learning and comparisons of models, the corresponding tree is checked to see if it has finished proposing models, through is_tree_complete(). If the tree is not complete, the next_layer() method is called to generate the next branch on that tree. The next branch can correspond to spawn or prune stages of the tree’s ExplorationStrategy, but QMLA is ambivalent to the inner workings of the tree/exploration strategy: a branch is simply a set of models to learn and compare.

When all trees have completed learning, this method terminates.

log_print(to_print_list)

Wrapper for print_to_log()

new_branch(model_list, pairs_to_compare='all', pairs_to_compare_by_names=None, exploration_strategy=None, spawning_branch=0)

Add a set of models to a new QMLA branch.

Branches have a unique id within QMLA, but belong to a single tree, where each tree corresponds to a single exploration strategy.

Parameters

• model_list (list) – strings corresponding to models to place in the branch

• pairs_to_compare (str or list) – set of model pairs to perform comparisons between. ‘all’ (deafult) means all models in model_list are set to compare. Otherwise a list of tuples of model IDs to compare

• exploration_strategy (str) – exploration strategy identifer; used to get the unique tree object corresponding to an exploration strategy, which is then used to host the branch.

• spawning_branch (int) – branch id which is the parent of the new branch.

Returns

branch id which uniquely identifies the new branch within the QMLA environment.

plot_instance_outcomes()

Generate plots corresponding to this instance.

A number of plotting routines are called, depending on the plot_level set by the user at launch.

process_comparisons_within_branch(branch_id, pair_list=None)

Process comparisons between models on the same branch.

(Similar functionality to process_model_set_comparisons(), but additionally updates some branch infrastructure, such as updating the branch’s champion_id, bayes_points attributes). Pairwise comparisons are retrieved and processed by process_model_pair_comparison(), which informs the superior model. For each pairwise comparison a given model wins, it receives a single point. All comparisons are weighted evenly. Model points are gathered; the model with most points is deemed the champion of the set. If a subset of models have the same (highest) number of points, that subset is compared directly, with the nominated champion deemed the champion of the wider set.

Parameters

branch_id (int) – unique ID of the branch whose models to compare

Returns

• models_points: the points (number of comparisons won) of each model on the branch

• champ_id: unique model ID of the champion model within the set

process_model_pair_comparison(a=None, b=None, pair=None)

Process a comparison between two models.

The comparison (Bayes factor) result is retrieved from the redis database and used to update data on the models.

Parameters

• a (int) – one of the model’s unique ID

• b (int) – one of the model’s unique ID

• pair (tuple) – alternative mechanism to provide the model IDs, effectively (a,b)

Returns

ID of the model which is deemed superior from this pair

process_model_set_comparisons(model_list)

Process comparisons between a set of models.

Pairwise comparisons are retrieved and processed by process_model_pair_comparison(), which informs the superior model.

For each pairwise comparison a given model wins, it receives a single point.

All comparisons are weighted evenly. Model points are gathered; the model with most points is deemed the champion of the set.

If a subset of models have the same (highest) number of points, that subset is compared directly, with the nominated champion deemed the champion of the wider set.

Parameters

model_list (list) – list of model names to compete

Returns

unique model ID of the champion model within the set

run_complete_qmla()

Run complete Quantum Model Learning Agent algorithm.

Each ExplorationStrategy is assigned a QMLATree, which manages the exploration strategy. When new models are spawned by an exploration strategy, they are placed on a BranchQMLA of the corresponding tree. Models are learned/compared/spawned iteratively in learn_models_until_trees_complete(), until all trees declare that their exploration strategy has completed. Exploration Strategies are complete when they have nominated one or more champions, which can follow spawning/pruning stages as required by the exploration strategy. Nominated champions are then compared with compare_nominated_champions(), resulting in a single global champion selected. Some analysis then takes place, including possibly reducing the selected global champion if it is found that some of its terms are not impactful.

run_quantum_hamiltonian_learning()

Run Quantum Hamiltonian Learning algorithm .

The true_model of the ExplorationStrategy is used to generate true data (in simulation) and have its parameters learned.

run_quantum_hamiltonian_learning_multiple_models(model_names=None)

Run Quantum Hamiltonian Learning algorithm with multiple simulated models.

Numerous Hamiltonian models attempt to learn the dynamics of the true model. The underlying model is set in the ExplorationStrategy’s true_model attribute.

Parameters

model_names (list) – list of strings of model names to learn the parameterisations of. None: taken from ExplorationStrategy qhl_models.

spawn_from_branch(branch_id)

Retrieve the next set of models and place on a new branch.

By checking the QMLATree` associated with the branch_id used to call this method, call ExplorationTree.next_layer(), which returns a set of models to place on a new branch, as well as which models therein to compare. These are passed to new_branch(), constructing a new branch in the QMLA environment. The generated new branch then has all its models learned by calling learn_models_on_given_branch(). next_layer() is in control of how to select the next set of models, usually either by calling the ExplorationStrategy’s generate_models() or tree_pruning() methods. This allows the user to define how models are generated, given access to the comparisons of the previous branch, or how the tree is pruned, e.g. by performing preliminary parent/child branch champion comparisons.

Parameters

branch_id (int) – unique ID of the branch which has completed

store_bayes_factors_to_csv(save_to_file, names_ids='latex')

deprecated Store the pairwise comparisons computed during this instance. model_bayes_factorsCSV() removed and is needed TODO if wanted, find in old github commits and reimplement.

Wrapper for model_bayes_factorsCSV().

store_bayes_factors_to_shared_csv(bayes_csv)

Store the pairwise comparisons computed during this instance in a CSV shared by all concurrent instances.

Logistics

Here we list some of the functionality used as the logistics to implement QMLA.

User controls

ControlsQMLA Controls (user and otherwise) to specify QMLA instance.

class qmla.ControlsQMLA(arguments, **kwargs)

Storage for configuration of a QMLA instance.

Command line arguments specify details about the QMLA instance, such as number of experiments/particles etc, required to implement the QMLA instance. The command line arguments are stored together in this class. The class is then given to the qmla.QuantumModelLearningAgent instance, which uses those details into the implementation. Some QMLA parameters are also set by the attributes of the Exploration Strategy. In particular, the ExplorationStrategy of the true model is instantiated by calling get_exploration_class(). model is defined as the true model of that instance. This exploration strategy instance is the master exploration strategy for the QMLA instance: the true Likewise, instances are generated for all of the exploration strategies specified by the user: these instances are associated with the exploration strategy ExplorationTree objects.

Parameters

arguments (dict) – command line arguments, parsed into a dict.

log_print(to_print_list)

Wrapper for print_to_log()

Database framework

Operator Object for mathematical properties of a single model.

Functions

qmla.get_num_qubits(name)

Parse string and determine number of qubits this operator acts on.

Default convention is to use a naming mechanism specified by string_processing_functions(). In all such constructions, the final element of each term is dN, so we can extract the number of qubits N.

If using old convention where terms are tensor-producted by T, TT, TTT… , we find the largest T string instance, from which we deduce the number of qubits. - xTx = pauli_x TENSOR_PRODUCT pauli_x –> 2 qubits - yTyTTy = pauliy_y TENSOR_PRODUCT pauli_y TENSOR_PRODUCT pauli_y –> N=3 i.e. the largest tensor product of of length is N-1.

Parameters

name (str) – name of model

qmla.get_constituent_names_from_name(name)

Separate into separate terms in model name. e.g. ‘pauliSet_1_x_d2+pauliSet_1_y_d2’ -> [‘pauliSet_1_x_d2’, ‘pauliSet_1_y_d2’] :param str name: name of model

qmla.alph(name)

Alphabetise the model name.

If name newer follows convention where terms are separated by +, simply separate them. If name follows older convention, analyse to separate terms and then alphabetise them. Parse string and recursively call alph function to alphabetise substrings.

Parameters

name (str) – name of model to alphabetise

Model Generation

qmla.process_basic_operator(basic_operator)

Transform a string, representing a term in the model, into a matrix.

Physical systems have different corresponding string processing functions. These are provided in the dictionary qmla.process_string_to_matrix.string_processing_functions. There are a number of rules which model strings must obey to be processed properly.

• Terms are separated by +.

• Within terms, components are separated by _.

• Components have different meanings, depending on which string processing function is used.

• The first component is the indicator of which processing function to use; it is matched with a processing function in ~qmla.string_processing_functions.

• The final component in general indicates the dimension N of the system, and is specified by dN.

• No other component should start with d, as it uniquely indicates the dimension.

• Alternatively, core operators can be processed alone, these are given in core_operator_dict.

For example, the string pauliSet_1J2_xJx_d3+pauliSet_1J3_zJz_d3:

• Terms: pauliSet_1J2_xJx_d3, pauliSet_1J3_zJz_d3

• Components (of pauliSet_1J2_xJx_d3): pauliSet, 1J2, xJx, d3

• Indicator pauliSet tells it to process via process_multipauli_term().

• d3 tells it to use a 3 qubit basis

• Other components are interpreted by the string processing function

• In this case, the result is the matrix ( XXI + ZIZ) .

Parameters

basic_operator (str) – term to generate matrix from.

Return np.ndarray mtx

matrix corresponding to the input term.

String to matrix processing

These functions map strings to matrices which can be used in the construction of models.

Initialising Exploration Strategy

qmla.get_exploration_class(exploration_rules, **kwargs)

Get an instance of the class specified by the user which implements an exploration Strategy.

Instance of a ExplorationStrategy (or subclass). This is used to specify how QMLA proceeds, in particular by designing the next batch of models to test. Exploration Strategy is specified by the name passed to implement_qmla in the launch script, through the command line flag exploration_strategy. This string is searched for in the exploration_classes dictionary. New exploration strategies must be added here so that QMLA can find them.

Parameters

exploration_rules (str) – string corresponding to an exploration strategy

Params **kwargs**kwargs

arguments required by the exploration strategy, passed directly to the desired exploration strategy’s constructor.

Return ExplorationStrategy gr

exploration strategy class instance

Trees and branches

class qmla.ExplorationTree(exploration_class)

Tree corresponding to an exploration strategy for management within QMLA.

Each ExplorationStrategy in the QuantumModelLearningAgent instance is associated with one tree (instance of this class). The tree interacts with the QMLA environment, for instance to choose the next set of models to learn through next_layer(). BranchQMLA exist both on the tree and the QMLA environment.

Parameters

exploration_class (ExplorationStrategy) – instance of the exploration strategy to associate with this tree.

finalise_tree(**kwargs)

After learning/pruning complete, run finalise_model_learning().

get_initial_models()

Models for the first layer of this exploration strategy.

Return list initial_models

list of model names to place on the first layer corresponding to this ES

Return list pairs_to_compare

list of model name pairs to compare

is_tree_complete()

Check if tree has completed and doesn’t need any further branches.

log_print(to_print_list)

Wrapper for print_to_log()

new_branch_on_tree(branch_id, models, pairs_to_compare, model_storage_instances, precomputed_models, spawning_branch, **kwargs)

Add a branch to this tree.

Generate a new BranchQMLA, and places the given models on it, and assign it to this tree. Return the object, so it can also act as a branch/layer in the QuantumModelLearningAgent environment. Note models can reside on multiple branches.

Parameters

• branch_id (int) – branch ID unique to this branch and new in the QMLA environment.

• models (list) – model names to place on this branch.

• pairs_to_compare (list) – list of pairs of models to compare on this branch.

• model_storage_instances (dict) – ModelInstanceForStorage instances of each model id to be placed on this branch.

• precomputed_models (list) – models to place on branch which have already been learned on a previous branch.

• spawning_branch (int) – branch ID spawning this branch, to be recorded as the new branch’s parent.

Return BranchQMLA branch

instance of branch

next_layer(**kwargs)

Determine the next set of models, for the next branch of this exploration strategy tree.

These are generated iteratively in stages, until that stage is marked as complete within the exploration strategy. * Spwaning: using the set of models from the previous branch to construct new models,

via generate_models().

• The spawning stage is terminated when check_tree_completed() returns True. For example, if a predetermined number of spawn steps have passed, or if the model learning has converged.

• After the spawn stage, the tree enters the pruning stage. For example, parental collapse: branch champions of this tree are compared with their parents; if either parent or child is strongly superior, the loser does not progress to the next branch.

• Pruning is carried out by tree_pruning(), until :meth:`~qmla.exploration_strategies.ExplorationStrategy.check_tree_pruned returns True.

• After the pruning stage, it must be possible for this tree to nominate a list of models to be considered for global champion, by nominate_champion().

The set of models decided by this method are placed on the next QMLA branch. pairs_to_compare here specifies which pairs of models on that next branch should be compared. Typically, model learning corresponds to spawning; during this stage all models on branches should be compared. Pruning then corresponds to comparing models which have already been leared (though new unlearned models will be learned). During pruning, it may not be necessary to compare all pairs, for instance if it is desired only to compare parent/child pairs at a given branch.

Parameters

kwargs (dict) – key word args passed directly to spawning/pruning functions.

Return list model_list

list of model names to place on the next QMLA branch

Return str or list pairs_to_compare

which model IDs within the model_list to perform comparisons between.

nominate_champions()

After tree has completed, nominate champion(s) to contest for global champion.

Exploration Strategies can nominate one or more models as global champion. The nominated champions of all ESs enter an all-vs-all contest in compare_nominated_champions(), with the winner deemed the global champion. This tree object interfaces with the ES, so here it is just a wrapper for nominate_champions().

class qmla.BranchQMLA(branch_id, models, model_storage_instances, pairs_to_compare, tree, precomputed_models, spawning_branch)

update_branch(pair_list, models_points=None)

Process results for this branch.

Parameters

• pair_list (list) – pairs of models which were compared on this branch

• models_points (dict) – results of comparisons

Parameter definition

qmla.set_shared_parameters(exploration_class, run_info_file=None, all_exploration_strategies=[], run_directory='', num_particles=100, probe_max_num_qubits_all_exploration_strategies=12, generate_evaluation_experiments=True)

Set up parameters for this run of QMLA. A run consists of any number of independent QMLA instances; for consistency they must share the same information. Parameters, such as true model (system) parameters and probes to use for plotting purposes, are shared by all QMLA instances within a given run.

This function does not return anything, but stores data required for the run to the run_info_file path. The data pickled as run_info are:

True_model

name of true model, i.e. the model we call the system, against which candidate models are tested

Params_list

list of parameters of the true model

Params_dict

dict of parameters of the true model

Exploration_rule

exploration strategy (name) of true model

All_exploration_strategies

list of all exploration strategies (names) which are to be performed by each instance

Evaluation_probes

proebs to use during evaluation experiments

Evaluation_times

times to use during evaluation experiments

Parameters

• exploration_class (ExplorationStrategy) – exploration strategy of true model, from which to extract key info, e.g. true parameter ranges and prior.

• run_info_file (str) – path to which to store system information

• all_exploration_strategies (list) – list of instances of ExplorationStrategy which are the alternative exploration strategies, i.e. which are performed during each instance, but which do not specify the true model (system).

• run_directory (str) – path to which all results/information pertaining to this unique QMLA run are stored

• num_paritlces (int) – number of particles used during model learning

• probe_max_num_qubits_all_exploration_strategies (int) – largest system size for which to generate plot probes

• generate_evaluation_experiments (bool) – whether to construct an evaluation dataset which can be used to objectively evaluate models. Evaluation data consists of experiments (i.e. probes and evolution times) which were not typically used in model learning, therefore each model can be compared fairly on this data set.

Redis

qmla.get_redis_databases_by_qmla_id(host_name, port_number, qmla_id, tree_identifiers=None)

Gets the set of redis databases unique to this QMLA instance.

Each QuantumModelLearningAgent instance is associated with a unique redis database. Redis databases are specified by their hostname and port number. All workers for the QMLA instance can read the redis databsae of that instance. Data required by various workers is stored here, through _compile_and_store_qmla_info_summary().

A set of databases are stored at the redis database host_name:port_number; these are listed in qmla.redis_settings.databases_required.

Parameters

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – this QMLA instance’s unique port number (6300 + qmla_id).

• qmla_id (int) – QMLA id, unique to a single instance within a run.

Return dict database_dict

set of database addresses unique to the qmla_id, host_name and port_number.

qmla.get_seed(host_name, port_number, qmla_id)

Unique seed for this QMLA id.

Numerous databases can belong to a given host:port address, and these are identified by their db attribute (a number to keep databases separate). Databases are seeded using the qmla_id, as well as the host:port, to avoid multiple QMLA instances, which can exist on the same host and port, clashing and interfering with each others’ data.

E.g. * A host:port is already in use for qmla_id=1, which uses a set of 5 databases. * qmla_id=2 requests a set of databases on the same host:port * The first available db is 6, such that qmla_id=2 will not interfere with

the databases of qmla_id=1.

Parameters

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – this QMLA instance’s unique port number (6300 + qmla_id).

• qmla_id (int) – QMLA id, unique to a single instance within a run.

Return int seed

unique number to use as the starting db for a given QMLA instances set of databases.

Logging

qmla.print_to_log(to_print_list, log_file, log_identifier='')

Writes to the log file, registering the time and identifier.

Adds the content of to_print_list to the log_file, using the log_identifier to indicate where a given log entry originated.

Parameters

• to_print_list (str() or list()) – string you want to print

• log_file (str()) – path of the log file you want to update

• log_identifier (str()) – identifier for the log

Models

Model for training

Model to perform parameter learning upon, usually QHL.

This is a disposable class which instatiates indepdendently from QuantumModelLearningAgent, trains the model via qmla.remote_learn_model_parameters(), performs analysis on the trained model, summarises the outcome of the training and sends a concise data packet to the database, before being deleted. The model training refers to QHL, performed in conjunction with [QInfer], via update_model().

class qmla.ModelInstanceForLearning(model_id, model_name, qid, exploration_rule, log_file, qmla_core_info_database=None, host_name='localhost', port_number=6379, **kwargs)

Model used for parameter learning.

Models are specified by their name; they can be separated into separate terms by splitting the name string by ‘+’. Individual terms correspond to base matrices and are assigned parameters. Each term is assigned a parameter probability distribution, or a prior distribution: this will be iteratively changed according to evidence from experiments, and its mean gives the estimate for that parameter. Prior distributions are used by the QInfer updater, and can be specified by the get_prior() method. The individual terms are parsed into matrices for calculations. This is achieved by process_basic_operator(): different string syntax enable different core oeprators.

Parameter estimation is done by update_model(). The final parameter estimates are set as the mean of the posterior distribution after n_experiments wherein n_particles are sampled per experiment (these user definted parameters are retrieved from qmla_core_info_dict). learned_info_dict() returns the pertinent learned information.

Parameters

• model_id (int) – ID of the model to study

• model_name (str) – name of the model to be learned

• qid – ID of the QMLA instance

• exploration_rule (str) – name of exploration_strategy

• qmla_core_info_database (dict) – essential details about the QMLA instance needed to learn/compare models. If None, this is retrieved instead from the redis database.

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – port number unique to this QMLA instance on redis database

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

_consider_reallocate_resources()

Model might get less resources if it is deemed less complex than others

_finalise_learning()

Record and log final result.

_initialise_model_for_learning(model_name, qmla_core_info_database, **kwargs)

Preliminary set up necessary before parameter learning.

Start instances of classes used throughout, generally by calling the exploration strategy’s method,

• qinfer inferface: qinfer_model().

• updater is default QInfer.SMCUpdater.

• parameter distribution prior: get_prior().

Parameters

• model_name (str) – name of the model to be learned

• exploration_rule (str) – name of exploration_strategy

• qmla_core_info_database (dict) – essential details about the QMLA instance needed to learn/compare models. If None, this is retrieved instead from the redis database.

_initialise_tracking_infrastructure()

Arrays, dictionaries etc for tracking learning across experiments

_model_plots_old()

Generate plots specific to this model. Which plots are drawn depends on the plot_level set in the launch script.

_plot_distributions()

For each parameter, plot: * prior distribution * posterior distributino * prior distribution for comparison, i.e. posterior from learning recast as a unimodal normal * true parameters (if applicable) * learned parameter estimates * covariance matrix between parameters (separate plot)

# TODO add plotting levels: run, instance, model

_plot_dynamics()

Plots the dynamics reproduced by this model against system data.

_plot_learning_summary()

Plot summary of this model’s learning:

• parameter estimates and uncertainties

• volume of parameter distribution

• experimental times used

• (resample points superposed on the above)

• likelihoods of system/particles

• difference between system/particles’ likelihoods

_plot_posterior_mesh_pairwise()

Plots the posterior mesh as contours for each pair of parameters.

Mesh from qinfer.SMCUpdater.posterior_mesh

_plot_preliminary_preparation()

Prepare model for plots; make directory.

_record_experiment_updates(update_step, new_experiment=None, datum=None, update_time=0)

Update tracking infrastructure.

_setup_qinfer_infrastructure()

Set up prior, model and updater (via QInfer) which are used to run Bayesian inference.

_store_prior()

Save the prior raw and as plot.

compute_likelihood_after_parameter_learning()

” Evaluate the model after parameter learning on independent evaluation data.

learned_info_dict()

Place essential information after learning has occured into a dict.

This is used to recreate the model for

• comparisons: ModelInstanceForComparison

• storage within the main QMLA environment ModelInstanceForStorage>.

log_print(to_print_list, log_identifier=None)

Wrapper for print_to_log()

log_print_debug(to_print_list)

Log print if global debug_log_print set to True.

update_model()

Run updates on model, corresponding to quantum Hamiltonian learning procedure.

This function is called on an instance of this model to run the entire QHL algorithm.

Get datum corresponding to true system, where true system is either experimental or simulated, by calling simulate_experiment on the QInfer.SMCUpdater. This datum is taken as the true expected value for the system, which is used in the likelihood calucation in the Bayesian inference step. This is done by calling the update method on the qinfer_updater. Effects of the update are then recorded by _record_experiment_updates(), and terminate either upon convergence or after a fixed num_experiments. Final details are recorded by _finalise_learning().

Model for comparisons

Model to use during Bayes factor comparisons.

This is a disposable class which reads the redis database to retrieve information about the trainng of the given model ID. It then reconstructs the model, e.g. based on the final estimated mean of the parameter distribution. Then, it is interfaced with a competing instance of the class within remote_bayes_factor_calculation(): the opponent’s experiments are used for further updates to the present model, such that the two models under consideration have identical experiment records (at least partially whereupon the BF is based), allowing for meaningful comparison among the two.

class qmla.ModelInstanceForComparison(model_id, qid, opponent, qmla_core_info_database=None, learned_model_info=None, host_name='localhost', port_number=6379, log_file='QMD_log.log')

Model instances used for Bayes factor comparisons.

When Bayes factors are calculated remotely (ie on RQ workers), they require infrastructure to do calculations, e.g. QInfer SMCUpdater instances. This class captures the minimum required to enable these calculations. After learning, important data from ModelInstanceForLearning is stored on the redis database. This class unpickles the useful information and generates new instances of the updater etc. to use in the comparison calculations.

If run locally, qmla_core_info_database and learned_model_info can be passed directly to this class, to save unpickling data from the redis database.

Parameters

• model_id (int) – ID of the model to study

• qid – ID of the QMLA instance

• qmla_core_info_database (dict) – essential details about the QMLA instance needed to learn/compare models. If None, this is retrieved instead from the redis database.

• learned_model_info (dict) – result of learning, generated by learned_info_dict().

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – port number unique to this QMLA instance on redis database

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

log_print(to_print_list, log_identifier=None)

Wrapper for print_to_log()

log_print_debug(to_print_list)

Log print if global debug_log_print set to True.

plot_dynamics(ax, times)

Plot dynamics of this model after its parameter learning stage.

Parameters

• ax – matplotlib axis to plot on

• times (list) – times against which to plot

update_log_likelihood(new_times, new_experimental_params)

Model for storage

This object is much smaller than the other forms of the model, i.e. those used for training (ModelInstanceForLearning) and comparisons (ModelInstanceForComparison), which retains only the useful information for storage/analysis within the bigger picture in QuantumModelLearningAgent. It retrieves the succinct summaries of the training/comparisons pertainng to a single model which are stored on the redis database, allowing for later anlaysis as required by QMLA.

class qmla.ModelInstanceForStorage(model_name, model_id, qid, plot_probes=None, qmla_core_info_database=None, host_name='localhost', port_number=6379, log_file='QMD_log.log', **kwargs)

Model stored in QMLA environment.

Retrieves data after model is trained remotely, so that qmla.QuantumModelLearningAgent can access that data.

Parameters

• model_name (str) – name of model under study

• model_id (int) – ID of model which is unique to QMLA instance

• model_terms_matrices (np.array()) – list of matrices corresponding to the operators which compose the model

• plot_probes (dict) – probes used in all plots for consistency

• qmla_core_info_database (dict) – essential details about the QMLA instance needed to learn/compare models. If None, this is retrieved instead from the redis database.

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – port number unique to this QMLA instance on redis database

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

compute_expectation_values(times=[])

Get the expectation values using the learned Hamiltonian.

Construct Hamiltonian from estimated learned parameters, and compute the expectation values, using the same input state as used for plotting. Stores a dictionary of { t : expectation value }.

Parameters

times (list) – times to use

log_print(to_print_list)

Wrapper for print_to_log()

model_update_learned_values(learned_info=None, **kwargs)

Get result of model learning and store within this object.

Every element stored by learned_info_dict() is stored as an attribute here.

Parameters

learned_info (dict) – results of remote model learning if None, retrieved from the redis database if not None, computed locally and passed

r_squared(times=None, min_time=0, max_time=None)

Compute and store r squared for given times.

Parameters

• times (list) – times to use for calculation

• min_time (float) – minimum time to use for calculation

• min_time – maximum time to use for calculation

Return float final_r_squared

r squared of the learned model against the times given

r_squared_by_epoch(times=None, min_time=0, max_time=None, num_points=10)

Compute and store r squared up to all times.

TODO incorporate as flag in r_squared() to store by epoch instead of separate fnc.

Implementation

Model learning

qmla.remote_learn_model_parameters(name, model_id, branch_id, exploration_rule, qmla_core_info_dict=None, remote=False, host_name='localhost', port_number=6379, qid=0, log_file='rq_output.log')

Standalone function to perform Quantum Hamiltonian Learning on individual models.

Used in conjunction with redis databases so this calculation can be performed without any knowledge of the QMLA instance.

Given model ids and names are used to instantiate the ModelInstanceForLearning class, which is then used for learning the models parameters.

QMLA info is unpickled from a redis databse, containing true operator, params etc.

Once parameters are learned, we pickle the results to dictionaries held on a redis database which can be accessed by other actors.

Parameters

• name (str) – model name string

• model_id (int) – unique model id

• branch_id (int) – QMLA branch where the model was generated

• exploration_rule (str) – string corresponding to a unique exploration strategy, used by get_exploration_class to generate a ExplorationStrategy (or subclass) instance.

• qmla_core_info_dict (dict) – crucial data for QMLA, such as number of experiments/particles etc. Default None: core info is stored on the redis database so can be retrieved there on a server; if running locally, can be passed to save pickling.

• remote (bool) – whether QMLA is running remotely via RQ workers.

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – this QMLA instance’s unique port number, on which redis database exists.

• qid (int) – QMLA id, unique to a single instance within a run. Used to identify the redis database corresponding to this instance.

• log_file (str) – Path of the log file.

Model comparison

qmla.remote_bayes_factor_calculation(model_a_id, model_b_id, branch_id=None, bf_data_folder=None, times_record='BayesFactorsTimes.txt', check_db=False, bayes_threshold=1, host_name='localhost', port_number=6379, qid=0, log_file='rq_output.log')

Standalone function to compute Bayes factors.

Used in conjunction with redis databases so this calculation can be performed without any knowledge other than model IDs. Data is unpickled from a redis databse, containing learned_model information, i.e. final parameters etc. Given `model_id`s correspond to model names in the database, which are combined with the final learned parameters to reconstruct model classes of complete learned models. Each model had been trained on a given set of experimental parmaeters (times). The reconstructed model classes are updated according to the experimental parameters of the opponent model, such that both models have underwent the same experiments. From these we extract log likelihoods to compute the Bayes factor, BF(A,B). Models have a unique pair_id, simply (min(A,B), max(A,B)). For BF(A,B) >> 1, A is deemed the winner; BF(A,B)<<1 deems B the winner. The result is then stored redis databases:

• bayes_factors_db: BF(A,B)

• bayes_factors_winners_db: id of winning model

• active_branches_bayes: when complete, increase the count of complete pairs’ BF on the given branch.

Parameters

• model_a_id (int) – unique id for model A

• model_b_id (int) – unique id for model B

• branch_id (int) – unique id of branch the pair (A,B) are on

• or int num_times_to_use (str) – how many times, used during the training of models A,B, to use during the BF calculation. Default ‘all’; if otherwise, Nt, keeps the most recent Nt experiment times of A,B.

• bf_data_folder (str) – folder path to store information such as times used during calculation, and plots of posterior marginals.

• times_record (str) – filename to store times used during calculation.

• check_db (bool) – look in redis databases to check if this pair’s BF has already been computed; return pre-computed BF if so.

• bayes_threshold (float) – value to determine whether either model is superior enough to “win” the comparison. If 1 < BF < threshold, neither win.

• host_name (str) – name of host server on which redis database exists.

• port_number (int) – this QMLA instance’s unique port number, on which redis database exists.

• qid (int) – QMLA id, unique to a single instance within a run. Used to identify the redis database corresponding to this instance.

• log_file (str) – Path of the log file.

qmla.remote_bayes_factor.plot_dynamics_from_models(models, exp_msmts, bf_times, bayes_factor, save_directory, figure_format='png')

Plot the dynamics of the pair of models considered in a Bayes factor comparison.

Parameters

• models (ModelInstanceForLearning) – list of 2 models which were compared during this calculation, [model_a, model_b].

• exp_msmts (dict) – times and expectation values for the system.

• bf_times (list) – Times used for the BF calculation

• bayes_factor (float) – Bayes factor between the two input models, to be read as BF(model_a, model_b)

• save_directory (path) – path where the generated figure is to be saved

Exploration Strategies

ExplorationStrategy Exploration Strategies drive the progression of the QMLA algorithm, as described in Exploration Strategy.

class qmla.exploration_strategies.ExplorationStrategy(exploration_rules, true_model=None, **kwargs)

User defined mechanism to control which models are considered by QMLA.

By changing the attributes, various aspects of QMLA are altered. A number of exploration strategy attributes point to standalone methods available within QMLA, e.g. to generate probes according to a desired mechanism. This allows the user to easily change functionality in a modular fashion. To develop a new exploration strategy, users should read the definitions of all exploration strategy attributes listed in the various setup methods, and ensure that the default are suitable for their system, or that they have replaced them in their custom exploration strategy. The setup methods are:

• _setup_modular_subroutines()

• _setup_true_model()

• _setup_model_learning()

• _setup_tree_infrastructure()

• _setup_logistics()

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

exploration_strategy_finalise()

Steps needed to finalise the exploration strategy.

gaussian_prior(model_name, default_sigma=None, **kwargs)

Genearates a QInfer Gaussian distribution .

Given a model_name, deteremines the number of terms in the model, N. Generates a multivariate distribution with N dimensions. This is then used as the initial prior, which QHL uses to learn the model parameters. By default, each parameter’s mean is the average of param_min and param_max, with sigma = mean/4. This can be changed by specifying prior_specific_terms:

individual parameter’s means/sigmas can be given.

Parameters

• model_name (str) – Unique string representing a model.

• param_minimum (float) – Lower bound for distribution.

• param_maximum (float) – Upper bound for distribution.

• default_sigma (float) – Width of distribution desired. If None, defaults to 0.25 * (param_max - param_min).

• prior_specific_terms (dict) – Individual parameter mean and sigma to enforce in the distribution.

• log_file (str) – Path of the log file for logging errors.

• log_identifier (str) – Unique identifying sting for logging.

Return QInfer.Distribution dist

distribution to be used as prior for parameter learning of the named model.

generate_models(model_list, **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().

generate_plot_probes(probe_maximum_number_qubits=None, **kwargs)

Call the ES’s plot_probes_generation_subroutine.

Generates a set of probes against which to compute measurements for plotting purposes. The same probe dict is used by all QMLA instances within a run for consistency.

Plot probe generation methods must adhere to the same rules as in generate_probes().

Parameters

probe_maximum_number_qubits (int) – how many qubits to compose probes up to. Can be left None, in which case assigned based on ES’s max_num_qubits, or forced to a different value by passing to function call.

Return dict plot_probe_dict

set of states against which all models are plotted over time in dynamics plots.

generate_probes(probe_maximum_number_qubits=None, store_probes=True, **kwargs)

Call the ES’s probe generation methods to set the system and simulator probes.

In general it is possible for the system and simulator to have different probe states (e.g. due to noise). These can be generated from the same or different methods. if shared_probes is True, then probe_generation_function is called once and the same probes are used for the system as simulator. else simulator_probes_generation_subroutine is called for the simulator probes.

Probe generation methods must take parameters

max_num_qubits

number of qubits to go up to when generating probes

num_probes

number of probces to produce

Probe generation methods must return

probe_dict

A set of probes with num_probes states for each of 1, …, N qubits up to max_num_qubits. Probe dictionaries should have keys which are tuples of the number of qubits and a probe ID, i.e. (probe_id, num_qubits).

Parameters

• probe_maximum_number_qubits (int) – how many qubits to compose probes up to. Can be left None, in which case assigned based on ES’s max_num_qubits, or forced to a different value by passing to function call.

• store_probes (bool) – whether to assign the generated probes to the ES instance. If False, probe dict is just returned .

Returns dict new_probes

(if not storing) dictionary of probes returned from probe generation function, fulfilling the requirements outlined above.

get_expectation_value(**kwargs)

Call the ES’s measurement_probability_function to compute quantum likelihood.

Compute the probability of measuring in some basis, to be used as likelihood. The default probability is that of the expectation value. Given an input state \(\| \psi \rangle\), \(P(\hat{H}, t, \| \psi \rangle) = \| \langle \| e^{-i \hat{H} t} \| \psi \rangle \|^2\). However it is possible to use alternative measurements, for instance corresponding to a physical measurement scheme such as Hahn echo or Ramsey sequences.

Modular functions here must take as parameters

ham

Hamiltonian to compute probability of

t

time to evolve ham for

state

proobe state to compute probability with

**kwargs

any further inputs required can be passed as kwargs

Modular functions must return

\(P\) : the probability of measurement according to custom requirements, to be used as likelihood in (interactive) quantum likelihood estimation.

get_heuristic(**kwargs)

Call the ES’s model_heuristic_function to build an experiment design heuristic class.

The heuristic class is called upon to design experiments to perform on the system during model learning.

Heuristics should inherit from BaseHeuristic. Details of requirements for custom heuristics can be found in the defintion of BaseHeuristic. # TODO clear up - the heuristic is a class, not a function

get_measurements_by_time()

Measure the true model for a series of times.

In some experiment design heuristics, those prescribed times are the only ones available to the learning procedure. Other heuristics allow the choice of any experimental time in principle. In either case, the measurements generated here are computed using the plot_probes, which are shared by all QMLA instances within the run. They are used for all dynamics plots.

get_prior(model_name, **kwargs)

Call the ES’s prior_distribution_subroutine function.

Parameters

model_name (str) – model for which to construct a prior distribution

Return qinfer.Distribution prior

N-dimensional distribution used by QInfer as the starting distribution for learning model parameters.

get_qinfer_model(**kwargs)

Call the ES’s qinfer_model_class to build the interface with QInfer used for model learning.

The default QInfer model class, and details of what to include in custom classes, can be found in QInferModelQMLA.

get_true_parameters()

Retrieve parameters of the true model and use them to construct the true Hamiltonian.

True parameters are set once per run and shared by all instances within that run. Therefore the true parameters are generated only once by set_shared_parameters(), and stored to a file which is accessible by all instances within the run.

This method retrieves those shared true parameters and stores them for use by the QuantumModelLearningAgent instance and its subsidiary models and methods. It then uses the true parameters to construct true_hamiltonian for the ES.

latex_name(name, **kwargs)

Call the ES’s latex_string_map_subroutine.

Map a model name (string) to its LaTeX representation.

Parameters

name (str) – name of model to map.

Return str latex_name

representation of input model as LaTeX string.

name_branch_map(latex_mapping_file, **kwargs)

Assign branch to model for visual representation of ES as tree.

Only used for attempt to plot the QMLA instance as a single tree, which is often not suitable, so this is not essential.

plot_dynamics_of_true_model(probe_dict, times)

Given a set of probes and times, plot their dynamics.

set_specific_plots()

Over-writeable method to set the target plotting methods. Also place any manual plotting methods in here, i.e. which require arguments.

tree_pruning(previous_prune_branch)

Get next model set through pruning.

true_model_latex()

Latex representation of true model.

property true_model_terms

Terms (as latex strings) which make up the true model

In order to initialise an ES, QMLA calls this function, which searches within the namespace of qmla/exploration_strategies.

qmla.get_exploration_class(exploration_rules, **kwargs)

Get an instance of the class specified by the user which implements an exploration Strategy.

Instance of a ExplorationStrategy (or subclass). This is used to specify how QMLA proceeds, in particular by designing the next batch of models to test. Exploration Strategy is specified by the name passed to implement_qmla in the launch script, through the command line flag exploration_strategy. This string is searched for in the exploration_classes dictionary. New exploration strategies must be added here so that QMLA can find them.

Parameters

exploration_rules (str) – string corresponding to an exploration strategy

Params **kwargs**kwargs

arguments required by the exploration strategy, passed directly to the desired exploration strategy’s constructor.

Return ExplorationStrategy gr

exploration strategy class instance

Modular functionality

As outlined in Modular functionality, some subroutines are modular; here we list some of the availbale implementations.

Experiment Design Hueristics

class qmla.shared_functionality.experiment_design_heuristics.ExperimentDesignHueristic(*args: Any, **kwargs: Any)

Experiment Design Heuristic base class, to be inherited by specific implementations. This object has access to the QInfer Updater and Model objects, so it can, e.g., sample from the particle distribution, to use these values in the design of a new experiment.

Parameters

• updater (QInfer Updater object) – QInfer updater for SMC

• model_id (int) – ID of model under study, defaults to 1

• oplist (list, optional) – list of matrices representing the operators constituting this model, defaults to None

• norm (str, optional) – type of norm to use, defaults to ‘Frobenius’

• inv_field (str, optional) – inversion field to use (legacy - should not matter) defaults to ‘x_’

• t_field (str, optional) – name of field corresponding to $t$, defaults to ‘t’

• maxiters (int, optional) – manimum number of iterations to attempt to find distinct particles from the distribution, defaults to 10

• other_fields (list, optional) – optional further fields, defaults to None

• inv_func (function, optional) – inverse function, used by QInfer, (legacy - should not matter) defaults to identity

• t_func (function, optional) – function for computing $t$, defaults to identity

• log_file (str, optional) – path to log file, defaults to ‘qmla_log.log’

design_experiment(**kwargs)

Design an experiment. Children classes can overwrite this function to implement custom logic

for the deisggn of experiments.

finalise_heuristic(**kwargs)

Any functionality the user wishes to happen at the final call to the heuristic.

log_print(to_print_list)

Wrapper for print_to_log()

plot_heuristic_attributes(save_to_file, **kwargs)

Summarise the heuristic used for the model training through several plots.

volume of distribution at each experiment

time designed by heuristic for each experiment

effecitve sample size at each experiment, used to determine when to resample

Parameters

save_to_file (path) – path to which the summary figure is stored

Expectation Values

qmla.shared_functionality.expectation_value_functions.default_expectation_value(ham, t, state, log_file='qmla_log.log', log_identifier='Expecation Value')

Default probability calculation: | <state.transpose | e^{-iHt} | state> |**2

Returns the expectation value computed by evolving the input state with

the provided Hamiltonian operator.

Parameters

• ham (np.array) – Hamiltonian needed for the time-evolution

• t (float) – Evolution time

• state (np.array) – Initial state to evolve and measure on

• log_file (str) – (optional) path of the log file

• log_identifier (str) – (optional) identifier for the log

Returns

probability of measuring the input state after Hamiltonian evolution

Prior probability distributions

qmla.shared_functionality.prior_distributions.gaussian_prior(model_name, param_minimum=0, param_maximum=1, default_sigma=None, random_mean=False, prior_specific_terms={}, log_file='qmd.log', log_identifier=None, **kwargs)

Genearates a QInfer Gaussian distribution .

Given a model_name, deteremines the number of terms in the model, N. Generates a multivariate distribution with N dimensions. This is then used as the initial prior, which QHL uses to learn the model parameters. By default, each parameter’s mean is the average of param_min and param_max, with sigma = mean/4. This can be changed by specifying prior_specific_terms:

individual parameter’s means/sigmas can be given.

Parameters

• model_name (str) – Unique string representing a model.

• param_minimum (float) – Lower bound for distribution.

• param_maximum (float) – Upper bound for distribution.

• default_sigma (float) – Width of distribution desired. If None, defaults to 0.25 * (param_max - param_min).

• prior_specific_terms (dict) – Individual parameter mean and sigma to enforce in the distribution.

• log_file (str) – Path of the log file for logging errors.

• log_identifier (str) – Unique identifying sting for logging.

Return QInfer.Distribution dist

distribution to be used as prior for parameter learning of the named model.

QInfer Interface

class qmla.shared_functionality.qinfer_model_interface.QInferModelQMLA(*args: Any, **kwargs: Any)

Interface between QMLA and QInfer.

QInfer is a library for performing Bayesian inference on quantum data for parameter estimation. It underlies the Quantum Hamiltonian Learning subroutine employed within QMLA. Bayesian inference relies on comparisons likelihoods of the target and candidate system. This class, specified by an exploration strategy, defines how to compute the likelihood for the user’s system. Most functionality is inherited from QInfer, but methods listed here are edited for QMLA’s needs. The likelihood function given here should suffice for most QMLA implementations, though users may want to overwrite get_system_pr0_array and get_simulator_pr0_array, for instance to specify which experimental data points to use.

Parameters

• model_name (str) – Unique string representing a model.

• modelparams (np.ndarray) – list of parameters to multiply by operators, unused for QMLA reasons but required by QInfer.

• oplist (np.ndarray) – Set of operators whose sum defines the evolution Hamiltonian (where each operator is associated with a distinct parameter).

• true_oplist (np.ndarray) – list of operators of the target system, used to construct true hamiltonian.

• trueparams (np.ndarray) – list of parameters of the target system, used to construct true hamiltonian.

• num_probes (int) – number of probes available in the probe sets, used to loop through probe set

• probes_system (dict) – set of probe states to be used during training for the system, indexed by (probe_id, num_qubits).

• probes_simulator (dict) – set of probe states to be used during training for the simulator, indexed by (probe_id, num_qubits). Usually the same as the system probes, but not always.

• exploration_rule (str) – string corresponding to a unique exploration strategy, used to generate an explorationStrategy_ instance.

• experimental_measurements (dict) – fixed measurements of the target system, indexed by time.

• experimental_measurement_times (list) – times indexed in experimental_measurements.

• log_file (str) – Path of log file.

are_models_valid(modelparams)

Checks that the proposed models are valid.

Before setting new distribution after resampling, checks that all parameters have same sign as the initial given parameter for that term. Otherwise, redraws the distribution. Modified from qinfer.

property expparams_dtype

Returns the dtype of an experiment parameter array.

For a model with single-parameter control, this will likely be a scalar dtype, such as "float64". More generally, this can be an example of a record type, such as [('time', py.'float64'), ('axis', 'uint8')]. This property is assumed by inference engines to be constant for the lifetime of a Model instance. In the context of QMLA the expparams_dtype are assumed to be a list of tuple where the first element of the tuple identifies the parameters (including type) while the second element is the actual type of of the parameter, typicaly a float. (Modified from Qinfer).

get_simulator_pr0_array(particles, times, probe)

Compute pr0 array for the simulator.

For user specific data, or method to compute simulator data,

replace this function in exploration_strategy.qinfer_model_subroutine.

Here we pass the candidate model’s operators and particles

to default_pr0_from_modelparams_times_.

Parameters

• times (list) – times to compute pr0 for; usually single element.

• particles (np.ndarry) – list of particles (parameter-lists), used to construct Hamiltonians.

Returns np.ndarray pr0

probabilities of measuring specified outcome

get_system_pr0_array(times, probe)

Compute pr0 array for the system. # TODO compute e^(-iH) once for true Hamiltonian and use that rather than computing every step.

For user specific data, or method to compute system data, replace this function

in exploration_strategy.qinfer_model_subroutine.

Parameters

times (list) – times to compute pr0 for; usually single element.

Returns np.ndarray pr0

probabilities of measuring specified outcome on system

likelihood(outcomes, modelparams, expparams)

Function to calculate likelihoods for all the particles

Inherited from Qinfer: Calculates the probability of each given outcome, conditioned on each given model parameter vector and each given experimental control setting.

QMLA modifications: Given a list of experiments to perform, expparams, extract the time list. Typically we use a single experiment (therefore single time) per update. QInfer passes particles as modelparams. QMLA updates its knowledge in two steps:

• “simulate” an experiment (which can include outsourcing from here to perform a real experiment),

• update parameter distribution by comparing Np particles to the experimental result

It is important that the comparison is fair, meaning:

• The evolution time must be the same

• The probe state to evolve must be the same.

To simulate the experiment, we call QInfer’s simulate_experiment, which calls likelihood(), passing a single particle. The update function calls simulate_experiment with Np particles. Therefore we know, when a single particle is passed to likelihood, that we want to call the true system (we know the true parameters and operators by the constructor of this class). So, when a single particle is detected, we circumvent QInfer by triggering get_system_pr0_array. Users can overwrite this function as desired; by default it computes true_hamiltonian, and computes the likelhood for the given time. When >1 particles are detected, pr0 is computed by constructing Np candidate Hamiltonians, each corresponding to a single particle, where particles are chosen by Qinfer and given as modelparams. This is done through get_simulator_pr0_array. We know calls to likelihood are coupled: one call for the system, and one for the update, which must use the same probes. Therefore probes are indexed by a probe_id as well as their dimension. We track calls to likelihood() in _a and increment the probe_id to pull every second call, to ensure the same probe_id is used for system and simulator.

Parameters

• outcomes (np.ndarray) – outcomes of the experiments

• modelparams (np.ndarray) – values of the model parameters particles A shape (n_particles, n_modelparams) array of model parameter vectors describing the hypotheses for which the likelihood function is to be calculated.

• expparams (np.ndarray) – experimental parameters, A shape (n_experiments, ) array of experimental control settings, with dtype given by expparams_dtype, describing the experiments from which the given outcomes were drawn.

Return type

np.ndarray

Returns

A three-index tensor L[i, j, k], where i is the outcome being considered, j indexes which vector of model parameters was used, and where k indexes which experimental parameters where used. Each element L[i, j, k] then corresponds to the likelihood \(\Pr(d_i | \vec{x}_j; e_k)\).

log_print(to_print_list, log_identifier=None)

Writng to unique QMLA instance log.

log_print_debug(to_print_list)

Log print if global debug_mode set to True.

property modelparam_names

Returns the names of the various model parameters admitted by this model, formatted as LaTeX strings. (Inherited from Qinfer)

property n_modelparams

Number of parameters in the specific model typically, in QMLA, we have one parameter per model.

n_outcomes(expparams)

Returns an array of dtype uint describing the number of outcomes for each experiment specified by expparams.

Parameters

expparams (numpy.ndarray) – Array of experimental parameters. This array must be of dtype agreeing with the expparams_dtype property.

Latex name mapping

Some examples of working latex name maps are provided.

qmla.shared_functionality.latex_model_names.pauli_set_latex_name(name, **kwargs)

Get latex string for model of Hubbard type.

Individual terms must be of the form, to implement operator t on qubit i of an N-qubit system:

pauliSet_i_t_dN

>>> model_name = 'pauliSet_1_x_d2+pauliSet_2_y_d2'
>>> pauli_set_latex_name(model_name)

Parameters

name (str) – name of model or term to map

qmla.shared_functionality.latex_model_names.grouped_pauli_terms(name, **kwargs)

qmla.shared_functionality.latex_model_names.fermi_hubbard_latex(name, **kwargs)

Get latex string for model of Hubbard type.

Parameters

name (str) – name of model or term to map