#
# Copyright © 2023-2025 QPerfect. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""Parameter sweeps: :class:`ParameterTable`, :func:`gridtable` and
:class:`SweepExperiment`."""
from functools import reduce
import numpy as np
import symengine as se
def _as_symbol(s):
if isinstance(s, str):
return se.Symbol(s)
s = se.sympify(s)
if not isinstance(s, se.Symbol):
raise ValueError(f"`{s}` is not a plain symbolic variable")
return s
[docs]
class ParameterTable:
r"""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. :meth:`from_columns` builds a table from one
column per symbol, :meth:`from_dicts` from a list of dictionaries (the
shape of ``param_grid``), and :func:`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 :meth:`~mimiqcircuits.Circuit.evaluate`, and
``t[i:j]`` or ``t[[i, j]]`` is the table of the selected points;
:meth:`listvars` gives the symbols and :meth:`to_numpy` the values.
Iterating over a table gives its points. A table is immutable and
hashable.
Args:
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
:meth:`~mimiqcircuits.Circuit.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
:meth:`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
"""
__slots__ = ("_symbols", "_values")
def __init__(self, symbols, values):
syms = tuple(_as_symbol(s) for s in symbols)
vals = np.array(values, dtype=float)
if vals.ndim != 2 or vals.shape[1] != len(syms):
raise ValueError(
f"the table has {len(syms)} symbols, so values must have shape "
f"(npoints, {len(syms)}), not {vals.shape}"
)
if len(set(syms)) != len(syms):
raise ValueError("every symbol must appear only once in a table")
vals.flags.writeable = False
self._symbols = syms
self._values = vals
[docs]
@classmethod
def from_columns(cls, columns):
"""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 :func:`gridtable`.
Args:
columns: A mapping from symbol (or name) to its values.
Returns:
The new :class:`ParameterTable`, with the symbols in the order of
``columns``.
Raises:
ValueError: If ``columns`` is empty or the columns have
different lengths.
"""
columns = list(dict(columns).items())
if not columns:
raise ValueError("a table needs at least one column")
n = len(columns[0][1])
if any(len(v) != n for _, v in columns):
raise ValueError(
"all columns must have the same length; use `gridtable` for "
"every combination of values"
)
values = np.column_stack([np.asarray(v, dtype=float) for _, v in columns])
return cls([s for s, _ in columns], values)
[docs]
@classmethod
def from_dicts(cls, points):
"""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.
Args:
points: A list of dictionaries mapping symbols (or names) to
values, such as the ``param_grid`` of
:meth:`~mimiqcircuits.backends.Backend.execute`.
Returns:
The new :class:`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
"""
converted = []
for i, p in enumerate(points):
q = {_as_symbol(k): v for k, v in p.items()}
# `{theta: 1, "theta": 2}` names one symbol twice.
if len(q) != len(p):
raise ValueError(f"point {i} gives a symbol twice")
converted.append(q)
points = converted
if not points:
raise ValueError("a table needs at least one point")
syms = sorted(points[0], key=str)
for i, p in enumerate(points):
if set(p) != set(syms):
raise ValueError(f"point {i} binds different symbols than point 0")
return cls(syms, [[float(p[s]) for s in syms] for p in points])
def __len__(self):
return self._values.shape[0]
def __getitem__(self, i):
if isinstance(i, (int, np.integer)):
return dict(zip(self._symbols, self._values[i].tolist()))
return ParameterTable(self._symbols, self._values[i])
def __eq__(self, other):
if not isinstance(other, ParameterTable):
return NotImplemented
return self._symbols == other._symbols and np.array_equal(
self._values, other._values
)
def __hash__(self):
return hash((self._symbols, tuple(self._values.ravel().tolist())))
def __iter__(self):
return (self[i] for i in range(len(self)))
[docs]
def listvars(self):
"""The symbols of the table, in column order."""
return list(self._symbols)
[docs]
def to_numpy(self):
"""A copy of the values, as an ``(npoints, nsymbols)`` array."""
return self._values.copy()
def _check_disjoint(self, other):
shared = [s for s in self._symbols if s in other._symbols]
if shared:
raise ValueError(
f"both tables give values for {', '.join(map(str, shared))}"
)
[docs]
def __mul__(self, other):
"""The Cartesian product, with the points of ``self`` varying slowest."""
if not isinstance(other, ParameterTable):
return NotImplemented
self._check_disjoint(other)
na, nb = len(self), len(other)
values = np.hstack(
[np.repeat(self._values, nb, axis=0), np.tile(other._values, (na, 1))]
)
return ParameterTable(self._symbols + other._symbols, values)
[docs]
def hcat(self, *others):
"""Pair the points of tables of the same length, side by side.
Args:
*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.
"""
out = self
for other in others:
out._check_disjoint(other)
if len(out) != len(other):
raise ValueError(
f"cannot pair the points of tables with {len(out)} and "
f"{len(other)} points"
)
out = ParameterTable(
out._symbols + other._symbols, np.hstack([out._values, other._values])
)
return out
[docs]
def vcat(self, *others):
"""Append the points of other tables after those of this one.
Args:
*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.
"""
out = self
for other in others:
if set(out._symbols) != set(other._symbols):
raise ValueError(
"only tables over the same symbols can be concatenated"
)
# Lay `other` out like `out`.
perm = [other._symbols.index(s) for s in out._symbols]
out = ParameterTable(
out._symbols, np.vstack([out._values, other._values[:, perm]])
)
return out
def _format_point(self, i):
return ", ".join(
f"{s} = {v}" for s, v in zip(self._symbols, self._values[i].tolist())
)
def _short(self):
return f"ParameterTable({len(self)} points over ({', '.join(map(str, self._symbols))}))"
def __repr__(self):
n = len(self)
head = (
f"ParameterTable with {n} point{'' if n == 1 else 's'} over "
f"({', '.join(map(str, self._symbols))}):"
)
# Long tables show their first and last points only.
shown = list(range(n)) if n <= 10 else list(range(5)) + list(range(n - 5, n))
lines = [head]
for k, i in enumerate(shown):
if n > 10 and k == 5:
lines.append("├── ⋮")
prefix = "└── " if k == len(shown) - 1 else "├── "
lines.append(prefix + self._format_point(i))
return "\n".join(lines)
__str__ = __repr__
[docs]
def gridtable(columns):
"""Build the :class:`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 ``*``.
Args:
columns: A mapping from symbol (or name) to its values.
Returns:
The :class:`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
"""
columns = dict(columns)
if not columns:
raise ValueError("a table needs at least one column")
return reduce(
lambda a, b: a * b,
(ParameterTable.from_columns({s: v}) for s, v in columns.items()),
)
[docs]
class SweepExperiment:
r"""A parameter sweep: a symbolic ``circuit`` and the
:class:`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
:class:`~mimiqcircuits.backends.LocalBackend` runs every point and
returns one :class:`~mimiqcircuits.QCSResults` per point, each with its
own seed derived from ``seed``.
Args:
circuit: The symbolic circuit. It is not copied.
table: The :class:`ParameterTable` of values.
Raises:
TypeError: If ``table`` is not a :class:`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]
<BLANKLINE>
Run it with ``backend.execute(ex, nsamples=1000, seed=1)`` to get a
list of three results.
"""
__slots__ = ("_circuit", "_table")
def __init__(self, circuit, table):
if not isinstance(table, ParameterTable):
raise TypeError(
f"table must be a ParameterTable, not {type(table).__name__}"
)
if not circuit.is_symbolic():
raise ValueError("the circuit of a sweep must be symbolic")
cvars = {str(s) for s in circuit.listvars()}
tvars = {str(s) for s in table.listvars()}
missing = sorted(cvars - tvars)
if missing:
raise ValueError(f"the table gives no values for {', '.join(missing)}")
extra = sorted(tvars - cvars)
if extra:
raise ValueError(
f"the table gives values for {', '.join(extra)}, which the "
"circuit does not use"
)
self._circuit = circuit
self._table = table
@property
def circuit(self):
"""The symbolic circuit."""
return self._circuit
@property
def table(self):
"""The :class:`ParameterTable` of values."""
return self._table
def __len__(self):
return len(self._table)
def __getitem__(self, i):
point = self._table[i]
if isinstance(point, ParameterTable):
return SweepExperiment(self._circuit, point)
return self._circuit.evaluate(point)
# The circuit is mutable, so an experiment is left unhashable.
def __eq__(self, other):
if not isinstance(other, SweepExperiment):
return NotImplemented
return self._circuit == other._circuit and self._table == other._table
def __iter__(self):
return (self[i] for i in range(len(self)))
[docs]
def listvars(self):
"""The symbols of the sweep, in the table's column order."""
return self._table.listvars()
[docs]
def num_qubits(self):
"""Return the number of qubits of the circuit."""
return self._circuit.num_qubits()
[docs]
def num_bits(self):
"""Return the number of classical bits of the circuit."""
return self._circuit.num_bits()
[docs]
def num_zvars(self):
"""Return the number of z-variables of the circuit."""
return self._circuit.num_zvars()
def __repr__(self):
header = str(self._circuit).split("\n", 1)[0].rstrip(":")
return "\n".join(
[
"SweepExperiment:",
f"├── circuit: {header}",
f"└── table: {self._table._short()}",
]
)
__str__ = __repr__
[docs]
def saveproto(self, file):
"""Save the experiment to a Protobuf (.pb) file or file-like object.
Returns the number of bytes written. See
:func:`~mimiqcircuits.proto.protoio.saveproto`.
"""
from mimiqcircuits.proto.protoio import saveproto
return saveproto(self, file)
[docs]
@staticmethod
def loadproto(file):
"""Load a :class:`SweepExperiment` saved with :meth:`saveproto`."""
from mimiqcircuits.proto.protoio import loadproto
return loadproto(file, SweepExperiment)
__all__ = ["ParameterTable", "gridtable", "SweepExperiment"]