Meta

Meta-algorithms that coordinate multiple Ansatz instances.

Swarm

The swarm class enables parallel execution of multiple independent Ansatz instances, useful for parameter sweeps or ensemble methods.

class quop_mpi.meta.swarm(nodes_per_subcomm: int, processes_per_node: int, maxcomm: int, MPI_COMM: COMM_WORLD, alg: type, *args, **kwargs)

Bases: object

Create and operate on a swarm of identical Ansatz instances.

Each Ansatz instance is associated with an MPI subcommunicator such that they can carry out QVA simulation independently.

The Ansatz instance is initialised by the swarm instance as,

Ansatz(*args, MPI_COMM, **kwargs)

Parameters:

nodes_per_subcommint: number of compute nodes associated with each Ansatz subcommunicator, if nodes_per_subcomm == 1 create maxcomm subcommunicators per available compute node.
processes_per_nodeint: number of MPI processes per compute node, must be the same for all nodes
maxcommint: target number of Ansatz subcommunicators
MPI_COMMIntracomm: MPI communicator from which to create the Ansatz subcommunicators
algAnsatz: an Ansatz, quop_mpi.Ansatz or a predefined algorithm (see quop_mpi.algorithm)

benchmark(*args, **kwargs)

Test QVA performance as a function of Ansatz Depth.

Parameters:

args: list[Ans] or list[list[Any]]: positional arguments for quop_mpi.Ansatz.benchmark(), or a list of positional arguments specifying unique input for quop_mpi.Ansatz.benchmark() for each Ansatz instance.
kwargs: dict: keyword arguments for quop_mpi.Ansatz.benchmark(), or keywords pointing to a list of positional arguments specifying unique input for quop_mpi.Ansatz.benchmark() for each Ansatz instance.

See also

benchmark()

benchmark_swarm(ansatz_depths: Iterable[int], repeats: int, basename: str, param_persist: bool = True, verbose: bool = True, save_action: str = 'a', time_limit: float | None = None, logging: bool = True, suspend_path: str | None = None)

Test QVA performance with increasing ansatz depth with repeats at each depth computed in parallel over the swarm.

Parameters:

ansatz_depthsIterable[int]: simulated ansatz depths
repeatsint: number of repeats at each ansatz depth
basenamestr: path to directory in which to write simulation results and logs, by default None
param_persistbool, optional: if True the optimised variational parameter values which achieved the lowest objective function value for all repeats at ansatz_depth will be used as starting parameters for the first ansatz_depth * total_params at ansatz_depth += 1, by default True
verbosebool, optional: if True, print current the ansatz depth, repeat number and optimisation results, by default True
save_action{‘a’, ‘w’}: ‘a’ to append, ‘w’ to (over)write, by default “a”
time_limitfloat, optional: time limit in seconds, program will suspend if the time remaining is less than the time taken by the last simulation, by default None
loggingbool, optional: write simulation results to log files, by default True
suspend_pathstr, optional: path to directory in which to write suspend data, by default None

Returns:

list[dict]: optimisation results ordered by ansatz depth

execute_swarm(param_lists: list[np.ndarray[np.float64]], basename: str, log_path: str = None, h5_path: str = None, labels: str | list[str] = None, save_action: str = 'a', time_limit: float = None, verbose: bool = True, suspend_path: str = None)

Parallel simulation of QVAs over a set of initial variational parameters.

Parameters:

param_listslist[np.ndarray[np.float64]]: list of 1-D real arrays containing initial variational parameters
basenamestr: folder in which to store simulation results and suspend data unless otherwise specified, by default None
log_pathstr, optional: folder in which to write simulation log files, by default None
h5_pathstr, optional: folder in which to write simulation results, by default None
labelsstr or list[str], optional: labels(s) for each simulation, by default None
save_action{“a”, “w”}: “a” to append “w” to (over)write, by default "a"
time_limitfloat, optional: suspend if the time remaining is less than the time taken by the last QVA simulation, by default None
verbosebool, optional: print the simulation results and simulation progress, by default True
suspend_pathstr, optional: folder in which to store suspend data, by default None

Returns:

dict: a dictionary of optimisation results with keys str(params_list[i])

get_optimal_result() → dict

Retrieve the result with the lowest objective function value out of the last set of simulations executed by the swarm.

Returns:

dict: simulation result

save(*args, **kwargs)

Save simulation results.

Parameters:

args:: positional arguments for quop_mpi.Ansatz.save(), or a list of positional arguments specifying unique input for quop_mpi.Ansatz.save() for each Ansatz instance.
kwargs:: keyword arguments for quop_mpi.Ansatz.save(), or keywords pointing to a list of positional arguments specifying unique input for quop_mpi.Ansatz.save() for each Ansatz instance.