mimiqcircuits.sweep

Parameter sweeps: ParameterTable, gridtable() and SweepExperiment.

Functions

gridtable(columns)

Build the ParameterTable of every combination of the given values, the Cartesian product of the columns.

Classes

ParameterTable(symbols, values)

Values for the symbolic parameters of a circuit, one row per point of a sweep.

SweepExperiment(circuit, table)

A parameter sweep: a symbolic circuit and the ParameterTable of values to run it with, one execution per point.

class ParameterTable(symbols, values)[source]

Bases: object

Values for the symbolic parameters of a circuit, one row per point of a sweep.

In a sweep every point binds the same symbols, so a table stores them once, in a fixed order, together with a matrix of values: row i holds the values of point i, and column j the values of symbols[j].

ParameterTable(symbols, values) takes the symbols and an (npoints, nsymbols) array. from_columns() builds a table from one column per symbol, from_dicts() from a list of dictionaries (the shape of param_grid), and gridtable() from every combination of the given values.

Every symbol must be a plain variable, such as one created with symengine.symbols, or its name as a string, and appear only once. Values are stored as float.

Tables compose: a * b is the Cartesian product, a.hcat(b) pairs the points of two tables of the same length, and a.vcat(b) appends the points of b after those of a.

len(t) is the number of points, t[i] is point i as a dictionary ready for evaluate(), and t[i:j] or t[[i, j]] is the table of the selected points; listvars() gives the symbols and to_numpy() the values. Iterating over a table gives its points. A table is immutable and hashable.

Parameters:
  • symbols – The symbols, or their names.

  • values – An array-like of shape (npoints, len(symbols)).

Raises:

ValueError – If values has the wrong shape, a symbol appears twice, or a symbol is not a plain variable.

Examples

>>> from mimiqcircuits import *
>>> from symengine import symbols
>>> theta, phi = symbols("theta phi")

Three points, given as one column of values per symbol.

>>> t = ParameterTable.from_columns({theta: [0.0, 0.5, 1.0], phi: [0.0, 0.25, 0.5]})
>>> t
ParameterTable with 3 points over (theta, phi):
├── theta = 0.0, phi = 0.0
├── theta = 0.5, phi = 0.25
└── theta = 1.0, phi = 0.5

A point is a dictionary, ready for evaluate().

>>> t[1][phi]
0.25

Multiplying two tables gives every combination of their points.

>>> ParameterTable.from_columns({theta: [0.0, 1.0]}) * ParameterTable.from_columns({phi: [0.0, 0.5]})
ParameterTable with 4 points over (theta, phi):
├── theta = 0.0, phi = 0.0
├── theta = 0.0, phi = 0.5
├── theta = 1.0, phi = 0.0
└── theta = 1.0, phi = 0.5

hcat() pairs points instead.

>>> ParameterTable.from_columns({theta: [0.0, 1.0]}).hcat(ParameterTable.from_columns({phi: [5.0, 6.0]}))
ParameterTable with 2 points over (theta, phi):
├── theta = 0.0, phi = 5.0
└── theta = 1.0, phi = 6.0
classmethod from_columns(columns)[source]

Build a table from one column of values per symbol.

columns maps each symbol to its values, such as {theta: xs, phi: ys}. All the columns must have the same length, and point i takes the i-th value of each. For every combination of the values instead, use gridtable().

Parameters:

columns – A mapping from symbol (or name) to its values.

Returns:

The new ParameterTable, with the symbols in the order of columns.

Raises:

ValueError – If columns is empty or the columns have different lengths.

classmethod from_dicts(points)[source]

Build a table from a list of dictionaries, one per point.

Every dictionary must bind the same symbols. Symbols are ordered by name, since dictionaries give no order of their own.

Parameters:

points – A list of dictionaries mapping symbols (or names) to values, such as the param_grid of execute().

Returns:

The new ParameterTable.

Raises:

ValueError – If points is empty, a point names a symbol twice, or two points bind different symbols.

Examples

>>> from mimiqcircuits import *
>>> from symengine import symbols
>>> theta, phi = symbols("theta phi")
>>> ParameterTable.from_dicts([{theta: 2.0, phi: 1.0}, {"theta": 3.0, "phi": 4.0}])
ParameterTable with 2 points over (phi, theta):
├── phi = 1.0, theta = 2.0
└── phi = 4.0, theta = 3.0
listvars()[source]

The symbols of the table, in column order.

to_numpy()[source]

A copy of the values, as an (npoints, nsymbols) array.

__mul__(other)[source]

The Cartesian product, with the points of self varying slowest.

hcat(*others)[source]

Pair the points of tables of the same length, side by side.

Parameters:

*others – Tables with as many points as this one and no symbol in common with it or each other.

Returns:

A table whose point i joins point i of every table.

Raises:

ValueError – If the lengths differ or a symbol is repeated.

vcat(*others)[source]

Append the points of other tables after those of this one.

Parameters:

*others – Tables over the same symbols, in any column order.

Returns:

A table with the columns of this one and the points of all.

Raises:

ValueError – If a table has different symbols.

gridtable(columns)[source]

Build the ParameterTable of every combination of the given values, the Cartesian product of the columns.

columns maps each symbol to its values. The first symbol varies slowest and the last one fastest, so gridtable({theta: [0, 1], phi: [0, 2, 4]}) has 6 points: theta = 0 with each phi, then theta = 1 with each phi. It is the same as multiplying the one-column tables with *.

Parameters:

columns – A mapping from symbol (or name) to its values.

Returns:

The ParameterTable with prod(len(v) for v in columns.values()) points.

Raises:

ValueError – If columns is empty.

Examples

>>> from mimiqcircuits import *
>>> from symengine import symbols
>>> theta, phi = symbols("theta phi")
>>> gridtable({theta: [0.0, 1.0], phi: [0.0, 2.0, 4.0]})
ParameterTable with 6 points over (theta, phi):
├── theta = 0.0, phi = 0.0
├── theta = 0.0, phi = 2.0
├── theta = 0.0, phi = 4.0
├── theta = 1.0, phi = 0.0
├── theta = 1.0, phi = 2.0
└── theta = 1.0, phi = 4.0
class SweepExperiment(circuit, table)[source]

Bases: object

A parameter sweep: a symbolic circuit and the ParameterTable of values to run it with, one execution per point.

The table must give values for exactly the free symbols of the circuit, no more and no fewer, so a missing or misspelled symbol is caught when the experiment is built rather than when the sweep runs.

len(ex) is the number of points, ex[i] is the circuit evaluated at point i, ex[i:j] or ex[[i, j]] is the experiment over the selected points, and iterating over the experiment gives the evaluated circuits in order. backend.execute(ex) on a LocalBackend runs every point and returns one QCSResults per point, each with its own seed derived from seed.

Parameters:
  • circuit – The symbolic circuit. It is not copied.

  • table – The ParameterTable of values.

Raises:
  • TypeError – If table is not a ParameterTable.

  • ValueError – If the circuit has no symbols, or the table misses a symbol of the circuit or has one the circuit does not use.

Examples

>>> from mimiqcircuits import *
>>> from symengine import symbols
>>> theta = symbols("theta")
>>> c = Circuit().push(GateRX(theta), 0)

Sweep the angle over three values.

>>> ex = SweepExperiment(c, ParameterTable.from_columns({theta: [0.0, 0.5, 1.0]}))
>>> ex
SweepExperiment:
├── circuit: 1-qubit circuit with 1 instruction
└── table: ParameterTable(3 points over (theta))
>>> len(ex)
3

Each point is the circuit with the angle bound.

>>> ex[1]
1-qubit circuit with 1 instruction:
└── RX(0.5) @ q[0]

Run it with backend.execute(ex, nsamples=1000, seed=1) to get a list of three results.

property circuit

The symbolic circuit.

property table

The ParameterTable of values.

listvars()[source]

The symbols of the sweep, in the table’s column order.

num_qubits()[source]

Return the number of qubits of the circuit.

num_bits()[source]

Return the number of classical bits of the circuit.

num_zvars()[source]

Return the number of z-variables of the circuit.

saveproto(file)[source]

Save the experiment to a Protobuf (.pb) file or file-like object.

Returns the number of bytes written. See saveproto().

static loadproto(file)[source]

Load a SweepExperiment saved with saveproto().