Breakdown of QPEG’s parameters

This page provides a complete explanation of QPEG’s many parameters.

The explanation of QPEG’s main algorithms is a recommended read beforehand, since concepts such as layers, DMRG blocks, SVD or types of simulations will not be explained here.

For simpler examples of intended QPEG use cases, please check this page on QPEG use cases.

Parameters common to every simulation modes

qudit_grouping:

This parameter indicates how many qubits there are in each qudit, ie: qudit_grouping[i] indicates how many qubits the qudit of index i represents. It follows that the sum of the elements of this parameter should equal the number of qubits of the circuit.

One may provide a tuple or a list, for giving a precise and explicit grouping, like qudit_grouping=(2, 3, 1, 4) for instance. Otherwise, one may provide an integer, such that providing a value a will be translated to a grouping \((a, a, a, ..., a, b)\) with \(b < a\).

Default: 1

do_svd:

Setting this parameter to True will add the SVD step to the simulation.

Default: False

dmrg_sweeps:

Indicates how many iterations of the DMRG algorithm should be performed on any DMRG block of layers. Setting this parameter to 0 disables the DMRG step.

Default: 1

bond_dimension:

Maximum dimension of the inner indices of the grouped MPS.

Default: 1

Strong simulation (default)

gates_per_layer:

Number of gates in each layer, ie: gates_per_layer[i] indicates how many gates the layer of index i contains. It follows that the sum of the elements of this parameter should equal the total number of gates in the circuit. If the SVD step is enabled, one SVD step will be performed for each layer.

One may provide a tuple or a list, for giving a precise and explicite layering, gates_per_layer=(13, 17, 11, 14, 19) for instance. Otherwise, one may provide an integer, such that providing a value a will be translated to a layering \((a, a, a, ..., a, b)\) with \(b < a\).

Default: 30

layers_per_dmrg:

Number of gates in each DMRG block (block of layers onto which a single DMRG algorithm will be run), ie: layers_per_dmrg[i] indicates how many layers the DMRG block of index i contains. It follows that the sum of the elements of this parameter should equal the number of layers (meaning sum(layers_per_dmrg) == len(gates_per_layer)).

One may provide a tuple or a list, for giving a precise and explicite DMRG blocking, layers_per_dmrg=(1, 3, 1, 2) for instance. Otherwise, one may provide an integer, such that providing a value a will be translated to a DMRG grouping \((a, a, a, ..., a, b)\) with \(b < a\).

groupings:

Grouping of the qudits in the grouped MPS for each layer, ie: groupings[i] indicates the grouping of the grouped MPS at the end of the layer of index i. It follows that this parameter should have the same number of elements as the number of layers (meaning len(groupings) == len(gates_per_layer)).

One may provide a tuple or a list, with the elements being the number of qudits in the matrices of the groupedMPS, groupings=(2, 4, 2, 4) for instance. Otherwise, one may provide an integer, such that providing a value a will be translated to a DMRG grouping \((a, a, a, ..., a, b)\) with \(b < a\), and that this DMRG grouping will itself be translated into a groupings parameter in the same way as above.

Default: 10 if qudits_grouping is None, 1 otherwise

Lastly, one may provide a sequence of sequence (with a sequence being a tuple or a list), in order to vary the grouping depending on the layer. For instance, a parameter groupings=((1, 2, 3), (3, 3), (3, 2, 1)), for a circuit of 3 layers, would describe the following grouping evolution:

Single amplitude mode

This simulation mode can be enabled by setting single_amplitude_mode to True. Several parameters change compared to the default strong simulation mode.

The parameters which are altered when using this mode are the three detailed in the above section. Each of these three parameters is doubled, ie: it is now a tuple of two objects, each being similar to the one described in the last part. Moreover, this simulation mode does not allow for “smart” values such as are described in the last part (integer instead of tuple for instance). Rather, each parameter must be described in its most explicit form.

For each parameter, parameter[0] will describe the parameter for the contraction on the left side and parameter[1] will describe the parameter for the contraction on the right side.

Another point to be taken note of is that the sum of the elements of gates_per_layer[0] and gates_per_layer[1] should be inferior to the number of gates in the circuit (the remaining gates “in the middle” will be added in the last phase).

Let us see an example with the most verbose groupings parameter. Here is what a value of groupings=(((2, 1, 2), (1, 1, 1, 1, 1), (2, 1, 2)), ((1, 1, 1, 2), (2, 1, 2), (3, 2))) would look like:

Utility parameters

These parameters will not change the core mechanics of a simulation, but are important in some situations.

optimizer:

Name of an optimizer from the opt_einsum library. It is used for tensor network contractions performed during DMRG steps.

Setting this parameter to None will use a custom contraction, intended only for contracting tensor networks when simulating the Sycamore experiment (this value should perform quite badly in most other use cases).

Default: “random-greedy”

remember_optimization_path:

This parameter should only be set to True for running variational circuits!

After submitting a variational circuit with this parameter enabled, the QPEG object is compromised and a new QPEG should be instanciated before submitting another circuit.

If this parameter is set to True, contraction paths are only computed during the first iteration of a variational optimization. These contraction paths are computed with opt_einsum, depending of the type of optimizer, so setting this parameter to True without specifying an optimizer name will yield an exception.

no_memory_reservation:

Computing the amount of memory needed for a QPEG simulation is a complex problem that is not yet correctly done. As such, a user may want to enable this option for bigger circuits that would otherwise be refused by the Resource Manager. CPUs will still be reserved.

disable_resource_manager:

Completely disables the Resource Manager for simulations done with this QPEG instance. Though available, using this parameter should never be necessary, the above one should suffice.

Checking your simulation parameters

One may not have in mind all the above information when using QPEG, or may not be sure of the way that some parameters interact together, given a certain job.

A helper function is provided, that allow the user to see what the job-dependent parameters’ values would be. These job-dependent parameters are qudit_grouping, groupings, gates_per_layer and layers_per_dmrg. Other parameters are not displayed by this function, since they do not depend on the job provided and their values should be straightforward.

Here is an example:

from qat.qpus import QPEG
from qat.qpeg import show_job_specific_parameters
from qat.lang.AQASM import Program, H

# 28 qubits Hadamard wall
program = Program()
qbits = program.qalloc(28)
for qb in qbits:
   H(qb)
job = program.to_circ().to_job()

# instanciating QPEG with some parameters
# notice that we are using our knowledge of the number of gates and qubits for
# giving more precise values of layers_per_dmrg and groupings
qpeg = QPEG(gates_per_layer=3, layers_per_dmrg=(3, 2, 3, 2), qudit_grouping=2, groupings=(5, 2, 2, 5))

# checking what parameters would be used if submitting this job to this QPEG instance
parameters = show_job_specific_parameters(qpeg, job)
print(parameters)

{'gates_per_layer': (3, 3, 3, 3, 3, 3, 3, 3, 3, 1), 'layers_per_dmrg': (3, 2, 3, 2), 'qudit_grouping': (2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2), 'groupings': ((5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5), (5, 2, 2, 5))}