Models #

Phase Encoder#

Encodes data of length \(n\) into the phases of \(n\) qubits.

For instance, the following two circuit generations are equivalent:

nqubits = 3
phases = np.random.rand(nqubits)

circuit_1 = phase_encoder(phases, rotation="RX")

circuit_2 = Circuit(3)
circuit_2.add(gates.RX(qubit, phases[qubit]) for qubit in range(nqubits))

qibo.models.encodings.phase_encoder(data, rotation: str = 'RY', backend=None, **kwargs)[source]#

Create circuit that performs the phase encoding of data.

Parameters:

data (ndarray or list) – \(1\)-dimensional array of phases to be loaded.
rotation (str, optional) – If "RX", uses qibo.gates.gates.RX as rotation. If "RY", uses qibo.gates.gates.RY as rotation. If "RZ", uses qibo.gates.gates.RZ as rotation. Defaults to "RY".
kwargs (dict, optional) – Additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit that loads data in phase encoding.

Return type:

Sparse encoder#

qibo.models.encodings.sparse_encoder(data, nqubits: int = None, backend=None, **kwargs)[source]#

Create circuit that encodes \(1\)-dimensional data in a subset of amplitudes of the computational basis.

Consider a sparse-access model, where for a data vector \(\mathbf{x} \in \mathbb{C}^{d}\), with \(d = 2^{n}\) and \(s\) non-zero amplitudes, one has access to the data vector \(\mathbf{y}\) of the form

\[\mathbf{y} = \left\{ (b_{1}, x_{1}), \, \dots, \, (b_{s}, x_{s}) \right\} \, ,\]

where \(\{x_{j}\}_{j\in[s]}\) is the non-zero components of \(\mathbf{x}\) and \(\{b_{j}\}_{j\in[s]}\) is the set of addresses associated with these values. Then, this function generates a quantum circuit \(s\text{-}\mathrm{Load}\) that encodes \(\mathbf{x}\) in the amplitudes of an \(n\)-qubit quantum state as

\[s\text{-}\mathrm{Load}(\mathbf{y}) \, \ket{0}^{\otimes \, n} = \sum_{j\in[s]} \, \frac{x_{j}}{\|\mathbf{x}\|_{F}} \, \ket{b_{j}} \, ,\]

where \(\|\cdot\|_{F}\) is the Frobenius norm.

Resulting circuit parametrizes data in hyperspherical coordinates in the \((2^{n} - 1)\)-unit sphere.

Parameters:

data (ndarray or list or zip) – sequence of tuples of the form \((b_{j}, x_{j})\). The addresses \(b_{j}\) can be either integers or in bitstring format of size \(n\).
nqubits (int, optional) – total number of qubits in the system. To be used when \(b_j\) are integers. If \(b_j\) are strings and nqubits is None, defaults to the length of the strings \(b_{j}\). Defaults to None.

Returns:

Circuit that loads sparse \(\mathbf{x}\).

Return type:

References

1. R. M. S. Farias, T. O. Maciel, G. Camilo, R. Lin, S. Ramos-Calderer, and L. Aolita, Quantum encoder for fixed-Hamming-weight subspaces, Phys. Rev. Applied 23, 044014 (2025).

Hyperpherical coordinates.

Binary encoder#

qibo.models.encodings.binary_encoder(data, parametrization: str = 'hyperspherical', backend=None, **kwargs)[source]#

Create circuit that encodes \(1\)-dimensional data in all amplitudes of the computational basis.

Given data vector \(\mathbf{x} \in \mathbb{C}^{d}\), with \(d = 2^{n}\), this function generates a quantum circuit \(\mathrm{Load}\) that encodes \(\mathbf{x}\) in the amplitudes of an \(n\)-qubit quantum state as

\[\mathrm{Load}(\mathbf{x}) \, \ket{0}^{\otimes \, n} = \sum_{j=0}^{d-1} \, \frac{x_{j}}{\|\mathbf{x}\|_{F}} \, \ket{b_{j}} \, ,\]

where \(b_{j} \in \{0, \, 1\}^{\otimes \, n}\) is the \(n\)-bit representation of the integer \(j\), \(\|\cdot\|_{F}\) is the Frobenius norm.

Resulting circuit parametrizes data in either hyperspherical or Hopf coordinates in the \((2^{n} - 1)\)-unit sphere.

Parameters:: data (ndarray) – \(1\)-dimensional array or length \(d = 2^{n}\) to be loaded in the amplitudes of a \(n\)-qubit quantum state.
Returns:: Circuit that loads data in binary encoding.
Return type:: qibo.models.circuit.Circuit

References

1. R. M. S. Farias, T. O. Maciel, G. Camilo, R. Lin, S. Ramos-Calderer, and L. Aolita, Quantum encoder for fixed-Hamming-weight subspaces Phys. Rev. Applied 23, 044014 (2025).

Hyperpherical coordinates.

3. H. S. Cohl, Fourier, Gegenbauer and Jacobi expansions for a power-law fundamental solution of the polyharmonic equation and polyspherical addition theorems, Symmetry, Integrability and Geometry: Methods and Applications 10.3842/sigma.2013.042 (2013).

Unary Encoder#

Given a classical data array \(\mathbf{x} \in \mathbb{R}^{d}\) such that

\[\mathbf{x} = (x_{1}, x_{2}, \dots, x_{d}) \, ,\]

this function generate the circuit that prepares the following quantum state \(\ket{\psi} \in \mathcal{H}\):

\[\ket{\psi} = \frac{1}{\|\mathbf{x}\|_{\textup{HS}}} \, \sum_{k=1}^{d} \, x_{k} \, \ket{k} \, ,\]

with \(\mathcal{H} \cong \mathbb{C}^{d}\) being a \(d\)-qubit Hilbert space, and \(\|\cdot\|_{\textup{HS}}\) being the Hilbert-Schmidt norm.

Here, \(\ket{k}\) is a unary representation of the number \(k\). For instance, for \(d = 3\), the final state would be

\[\ket{\psi} = \frac{1}{\|\mathbf{x}\|_{\textup{HS}}} \, \left( x_{1} \ket{001} + x_{2} \ket{010} + x_{3} \ket{100} \right) \, .\]

There are multiple circuit architechtures that lead to unary encoding of classical data. For example, to encode a \(8\)-dimensional data, one could use the so-called tree architechture below:

where the first gate is the qibo.gates.X and the parametrized gates are the qibo.gates.RBS. To know how the angles \(\{\theta_{k}\}_{[k]}\) are calculated for this architecture, please refer to S. Johri et al., Nearest Centroid Classiﬁcation on a Trapped Ion Quantum Computer, arXiv:2012.04145v2 [quant-ph].

On the other hand, the same encoding could be performed using the so-called diagonal (also known as ladder) architecture below:

This architecture leads to a choice of angles based on spherical coordinates in a d-dimensional hypersphere.

qibo.models.encodings.unary_encoder(data, architecture: str = 'tree', backend=None, **kwargs)[source]#

Create circuit that performs the (deterministic) unary encoding of data.

Parameters:

data (ndarray) – \(1\)-dimensional array of data to be loaded.
architecture (str, optional) – circuit architecture used for the unary loader. If diagonal, uses a ladder-like structure. If tree, uses a binary-tree-based structure. Defaults to tree.
kwargs (dict, optional) – Additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit that loads data in unary representation.

Return type:

Unary Encoder for Random Gaussian States#

Performs the same unary encoder as qibo.models.encodings.unary_encoder using the tree architecture , with the difference being that now each entry of the \(d\)-dimensional array is sampled from a Gaussian distribution \(\mathcal{N}(0, 1)\).

qibo.models.encodings.unary_encoder_random_gaussian(nqubits: int, architecture: str = 'tree', seed=None, backend=None, **kwargs)[source]#

Create a circuit that performs the unary encoding of a random Gaussian state.

At depth \(h\) of the tree architecture, the angles \(\theta_{k} \in [0, 2\pi]\) of the the gates \(RBS(\theta_{k})\) are sampled from the following probability density function:

\[p_{h}(\theta) = \frac{1}{2} \, \frac{\Gamma(2^{h-1})}{\Gamma^{2}(2^{h-2})} \, \left|\sin(\theta) \, \cos(\theta)\right|^{2^{h-1} - 1} \, ,\]

where \(\Gamma(\cdot)\) is the Gamma function.

Parameters:

nqubits (int) – number of qubits.
architecture (str, optional) – circuit architecture used for the unary loader. If tree, uses a binary-tree-based structure. Defaults to tree.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
kwargs (dict, optional) – Additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit that loads a random Gaussian array in unary representation.

Return type:

References

1. A. Bouland, A. Dandapani, and A. Prakash, A quantum spectral method for simulating stochastic processes, with applications to Monte Carlo. arXiv:2303.06719v1 [quant-ph]

Fixed Hamming-weight Encoder#

qibo.models.encodings.hamming_weight_encoder(data, nqubits: int, weight: int, full_hwp: bool = False, optimize_controls: bool = True, phase_correction: bool = True, initial_string=None, backend=None, **kwargs)[source]#

Create circuit that encodes data in the Hamming-weight-\(k\) basis of nqubits.

Let \(\mathbf{x}\) be a \(1\)-dimensional array of size \(d = \binom{n}{k}\) and \(B_{k} \equiv \{ \ket{b_{j}} : b_{j} \in \{0, 1\}^{\otimes n} \,\, \text{and} \,\, |b_{j}| = k \}\) be a set of \(d\) computational basis states of \(n\) qubits that are represented by bitstrings of Hamming weight \(k\). Then, an amplitude encoder in the basis \(B_{k}\) is an \(n\)-qubit parameterized quantum circuit \(\operatorname{Load}_{B_{k}}\) such that

\[\operatorname{Load}(\mathbf{x}) \, \ket{0}^{\otimes n} = \frac{1}{\|\mathbf{x}\|} \, \sum_{j = 1}^{d} \, x_{j} \, \ket{b_{j}}\]

Parameters:

data (ndarray) – \(1\)-dimensional array of data to be loaded.
nqubits (int) – number of qubits.
weight (int) – Hamming weight that defines the subspace in which data will be encoded.
full_hwp (bool, optional) – if False, includes Pauli-\(X\) gates that prepare the first bitstring of Hamming weight k = weight. If True, circuit is full Hamming weight preserving. Defaults to `False.
optimize_controls (bool, optional) – if True, removes unnecessary controlled operations. Defaults to True.
kwargs (dict, optional) – Additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit that loads ``data``in Hamming-weight-\(k\) representation.

Return type:

References

1. R. M. S. Farias, T. O. Maciel, G. Camilo, R. Lin, S. Ramos-Calderer, and L. Aolita, Quantum encoder for fixed-Hamming-weight subspaces Phys. Rev. Applied 23, 044014 (2025).

Entangling layer#

Generates a layer of nearest-neighbour two-qubit gates, assuming 1-dimensional connectivity. With the exception of qibo.gates.gates.GeneralizedfSim, any of the two-qubit gates implemented in qibo can be selected to customize the entangling layer. If the chosen gate is parametrized, all phases are set to \(0.0\). Note that these phases can be updated a posterior by using qibo.models.Circuit.set_parameters(). The possible choices of layer architecture are the following, in alphabetical order: diagonal, even_layer, next_nearest, pyramid, odd_layer, shifted, v, and x. For instance, we show below an example of four of those architectures for nqubits = 6 and entangling_gate = "CNOT".

If closed_boundary is set to True, then an extra gate is added connecting the last and the first qubit, with the last qubit as the control qubit and the first qubit as a target qubit.

qibo.models.encodings.entangling_layer(nqubits: int, architecture: str = 'diagonal', entangling_gate: str | Gate = 'CNOT', closed_boundary: bool = False, **kwargs)[source]#

Create a layer of two-qubit entangling gates.

If the chosen gate is a parametrized gate, all phases are set to \(0.0\).

Parameters:

nqubits (int) – Total number of qubits in the circuit.
architecture (str, optional) – Architecture of the entangling layer. In alphabetical order, options are "diagonal", "even_layer", "next_nearest", "odd_layer", "pyramid", "shifted", "v", and "x". The "x" architecture is only defined for an even number of qubits. Defaults to "diagonal".
entangling_gate (str or qibo.gates.Gate, optional) – Two-qubit gate to be used in the entangling layer. If entangling_gate is a parametrized gate, all phases are initialized as \(0.0\). Defaults to "CNOT".
closed_boundary (bool, optional) – If True and architecture not in ["pyramid", "v", "x"], adds a closed-boundary condition to the entangling layer. Defaults to False.
kwargs (dict, optional) – Additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit containing layer of two-qubit gates.

Return type:

Greenberger-Horne-Zeilinger (GHZ) state#

qibo.models.encodings.ghz_state(nqubits: int, **kwargs)[source]#

Generate an \(n\)-qubit Greenberger-Horne-Zeilinger (GHZ) state that takes the form

\[\ket{\text{GHZ}} = \frac{\ket{0}^{\otimes n} + \ket{1}^{\otimes n}}{\sqrt{2}}\]

where \(n\) is the number of qubits.

Parameters:

nqubits (int) – number of qubits \(n >= 2\).
kwargs (dict, optional) – additional arguments used to initialize a Circuit object. For details, see the documentation of qibo.models.circuit.Circuit.

Returns:

Circuit that prepares the GHZ state.

Return type:

Error Mitigation#

Qibo allows for mitigating noise in circuits via error mitigation methods. Unlike error correction, error mitigation does not aim to correct qubit errors, but rather it provides the means to estimate the noise-free expected value of an observable measured at the end of a noisy circuit.

Readout Mitigation#

A common kind of error happening in quantum circuits is readout error, i.e. the error in the measurement of the qubits at the end of the computation. In Qibo there are currently two methods implemented for mitigating readout errors, and both can be used as standalone functions or in combination with the other general mitigation methods by setting the paramter readout.

Response Matrix#

Given \(n\) qubits, all the possible \(2^n\) states are constructed via the application of the corresponding sequence of \(X\) gates \(X_0\otimes I_1\otimes\cdot\cdot\cdot\otimes X_{n-1}\). In the presence of readout errors, we will measure for each state \(i\) some noisy frequencies \(F_i^{noisy}\) different from the ideal ones \(F_i^{ideal}=\delta_{i,j}\).

The effect of the error is modeled by the response matrix composed of the noisy frequencies as columns \(M=\big(F_0^{noisy},...,F_{n-1}^{noisy}\big)\). We have indeed that:

\[F_i^{noisy} = M \cdot F_i^{ideal}\]

and, therefore, the calibration matrix obtained as \(M_{\text{cal}}=M^{-1}\) can be used to recover the noise-free frequencies.

The calibration matrix \(M_{\text{cal}}\) lacks stochasticity, resulting in a ‘negative probability’ issue. The distributions that arise after applying \(M_{\text{cal}}\) are quasiprobabilities; the individual elements can be negative surpass 1, provided they sum to 1. It is posible to use Iterative Bayesian Unfolding (IBU) to preserve non-negativity. See Nachman et al for more details.

qibo.models.error_mitigation.get_response_matrix(nqubits, qubit_map=None, noise_model=None, nshots: int = 10000, backend=None)[source]#

Computes the response matrix for readout mitigation.

Parameters:

nqubits (int) – Total number of qubits.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
noise_model (qibo.noise.NoiseModel, optional) – noise model used for simulating noisy computation. This matrix can be used to mitigate the effect of qibo.noise.ReadoutError.
nshots (int, optional) – number of shots. Defaults to \(10000\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

the computed (nqubits, nqubits) response matrix for: readout mitigation.

Return type:

numpy.ndarray

qibo.models.error_mitigation.iterative_bayesian_unfolding(probabilities, response_matrix, iterations=10)[source]#

Iterative Bayesian Unfolding (IBU) method for readout mitigation.

Parameters:

probabilities (numpy.ndarray) – the input probabilities to be unfolded.
response_matrix (numpy.ndarray) – the response matrix.
iterations (int, optional) – the number of iterations to perform. Defaults to 10.

Returns:

the unfolded probabilities.

Return type:

numpy.ndarray

Reference:

B. Nachman, M. Urbanek et al, Unfolding Quantum Computer Readout Noise. arXiv:1910.01969 [quant-ph].
S. Srinivasan, B. Pokharel et al, Scalable Measurement Error Mitigation via Iterative Bayesian Unfolding. arXiv:2210.12284 [quant-ph].

qibo.models.error_mitigation.apply_resp_mat_readout_mitigation(state, response_matrix, iterations=None)[source]#

Applies readout error mitigation to the given state using the provided response matrix.

Parameters:

state (qibo.measurements.CircuitResult) – the input state to be updated. This state should contain the frequencies that need to be mitigated.
response_matrix (numpy.ndarray) – the response matrix for readout mitigation.
iterations (int, optional) – the number of iterations to use for the Iterative Bayesian Unfolding method. If None the ‘inverse’ method is used. Defaults to None.

Returns:

the input state with the updated (mitigated) frequencies.

Return type:

qibo.measurements.CircuitResult

qibo.models.error_mitigation.apply_randomized_readout_mitigation(circuit, noise_model=None, nshots: int = 10000, ncircuits: int = 10, qubit_map=None, seed=None, backend=None)[source]#

Readout mitigation method that transforms the bias in an expectation value into a measurable multiplicative factor.

This factor can be eliminated at the expense of increased sampling complexity for the observable.

Parameters:

circuit (qibo.models.Circuit) – input circuit.
noise_model (qibo.noise.NoiseModel, optional) – noise model used for simulating noisy computation. Defaults to None.
nshots (int, optional) – number of shots. Defaults to \(10000\).
ncircuits (int, optional) – number of randomized circuits. Each of them uses int(nshots / ncircuits) shots. Defaults to 10.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

the state of the input circuit with: mitigated frequencies.

Return type:

qibo.measurements.CircuitResult

References

1. Ewout van den Berg, Zlatko K. Minev et al, Model-free readout-error mitigation for quantum expectation values. arXiv:2012.09738 [quant-ph].

qibo.models.error_mitigation.get_expectation_val_with_readout_mitigation(circuit, observable, noise_model=None, nshots: int = 10000, readout=None, qubit_map=None, seed=None, backend=None)[source]#

Applies readout error mitigation to the given circuit and observable.

Parameters:

circuit (qibo.models.Circuit) – input circuit.
observable (qibo.hamiltonians.Hamiltonian/:class:`qibo.hamiltonians.SymbolicHamiltonian) – The observable to be measured.
noise_model (qibo.models.noise.Noise, optional) – the noise model to be applied. Defaults to None.
nshots (int, optional) – the number of shots for the circuit execution. Defaults to \(10000\).
readout (dict, optional) –
a dictionary that may contain the following keys:
- ncircuits: int, specifies the number of random circuits to use for the randomized method of readout error mitigation.
- response_matrix: numpy.ndarray, used for applying a pre-computed response matrix for readout error mitigation.
- ibu_iters: int, specifies the number of iterations for the iterative Bayesian unfolding method of readout error mitigation. If provided, the corresponding readout error mitigation method is used. Defaults to {}.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – the backend to be used in the execution. If None, it uses the global backend. Defaults to None.

Returns:

the mitigated expectation value of the observable.

Return type:

Randomized readout mitigation#

This approach converts the effect of any noise map \(A\) into a single multiplication factor for each Pauli observable, that is, diagonalizes the measurement channel. The multiplication factor \(\lambda\) can be directly measured even without the quantum circuit. Dividing the measured value \(\langle O\rangle_{noisy}\) by these factor results in the mitigated Pauli expectation value \(\langle O\rangle_{ideal}\),

\[\langle O\rangle_{ideal} = \frac{\langle O\rangle_{noisy}}{\lambda}\]

This process can be implemented with the aforementioned qibo.models.error_mitigation.apply_randomized_readout_mitigation().

Zero Noise Extrapolation (ZNE)#

Given a noisy circuit \(C\) and an observable \(A\), Zero Noise Extrapolation (ZNE) consists in running \(n+1\) versions of the circuit with different noise levels \(\{c_j\}_{j=0..n}\) and, for each of them, measuring the expected value of the observable \(E_j=\langle A\rangle_j\).

Then, an estimate for the expected value of the observable in the noise-free condition is obtained as:

\[\hat{E} = \sum_{j=0}^n \gamma_jE_j\]

with \(\gamma_j\) satisfying:

\[\sum_{j=0}^n \gamma_j = 1 \qquad \sum_{j=0}^n \gamma_j c_j^k = 0 \quad \text{for}\,\, k=1,..,n\]

This implementation of ZNE relies on the insertion of gate pairs (that resolve to the identity in the noise-free case) to realize the different noise levels \(\{c_j\}\), see He et al for more details. Hence, the canonical levels are mapped to the number of inserted pairs as \(c_j\rightarrow 2 c_j + 1\).

qibo.models.error_mitigation.ZNE(circuit, observable, noise_levels, noise_model=None, nshots=10000, solve_for_gammas=False, global_unitary_folding=True, insertion_gate='CNOT', readout=None, qubit_map=None, seed=None, backend=None)[source]#

Runs the Zero Noise Extrapolation method for error mitigation.

The different noise levels are realized by the insertion of pairs of either CNOT or RX(pi/2) gates that resolve to the identiy in the noise-free case.

Parameters:

circuit (qibo.models.Circuit) – input circuit.
observable (qibo.hamiltonians.Hamiltonian/:class:`qibo.hamiltonians.SymbolicHamiltonian) – Observable to measure.
noise_levels (numpy.ndarray) – Sequence of noise levels.
noise_model (qibo.noise.NoiseModel, optional) – Noise model applied to simulate noisy computation.
nshots (int, optional) – Number of shots. Defaults to \(10000\).
solve_for_gammas (bool, optional) – If True, explicitly solve the equations to obtain the gamma coefficients. Default is False.
global_unitary_folding (bool, optional) – If True, noise is increased by global unitary folding. If False, local unitary folding is used. Defaults to True.
insertion_gate (str, optional) – gate to be folded in the local unitary folding. If RX, the gate used is :math:RX(\pi / 2). Otherwise, it is the CNOT gate.
readout (dict, optional) –
a dictionary that may contain the following keys:
- ncircuits: int, specifies the number of random circuits to use for the randomized method of readout error mitigation.
- response_matrix: numpy.ndarray, used for applying a pre-computed response matrix for readout error mitigation.
- ibu_iters: int, specifies the number of iterations for the iterative Bayesian unfolding method of readout error mitigation. If provided, the corresponding readout error mitigation method is used. Defaults to {}.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Estimate of the expected value of observable in the noise free condition.

Return type:

numpy.ndarray

Reference:

K. Temme, S. Bravyi et al, Error mitigation for short-depth quantum circuits. arXiv:1612.02058 [quant-ph].

qibo.models.error_mitigation.get_gammas(noise_levels, analytical: bool = True)[source]#

Standalone function to compute the ZNE coefficients given the noise levels.

Parameters:

noise_levels (numpy.ndarray) – array containing the different noise levels. Note that in the CNOT insertion paradigm this corresponds to the number of CNOT pairs to be inserted. The canonical ZNE noise levels are obtained as 2 * c + 1.
analytical (bool, optional) – if True, computes the coeffients by solving the linear system. If False, use the analytical solution valid for the CNOT insertion method. Default is True.

Returns:

the computed coefficients.

Return type:

numpy.ndarray

qibo.models.error_mitigation.get_noisy_circuit(circuit, num_insertions: int, global_unitary_folding=True, insertion_gate=None)[source]#

Standalone function to generate the noisy circuit with the inverse gate pairs insertions.

Parameters:

circuit (qibo.models.circuit.Circuit) – circuit to modify.
num_insertions (int) – number of insertion gate pairs / global unitary folds to add.
global_unitary_folding (bool) – If True, noise is increased by global unitary folding. If False, local unitary folding is used. Defaults to True.
insertion_gate (str, optional) – gate to be folded in the local unitary folding. If RX, the gate used is :math:RX(\pi / 2). Otherwise, it is the CNOT gate.

Returns:

circuit with the inserted gate pairs or with global folding.

Return type:

qibo.models.Circuit

Clifford Data Regression (CDR)#

In the Clifford Data Regression (CDR) method, a set of \(n\) circuits \(S_n=\{C_i\}_{i=1,..,n}\) is generated starting from the original circuit \(C_0\) by replacing some of the non-Clifford gates with Clifford ones. Given an observable \(A\), all the circuits of \(S_n\) are both simulated to obtain the correspondent expected values of \(A\) in noise-free condition \(\{a_i^{exact}\}_{i=1,..,n}\), and run in noisy conditions to obtain the noisy expected values \(\{a_i^{noisy}\}_{i=1,..,n}\).

Finally a model \(f\) is trained to minimize the mean squared error:

\[E = \sum_{i=1}^n \bigg(a_i^{exact}-f(a_i^{noisy})\bigg)^2\]

and learn the mapping \(a^{noisy}\rightarrow a^{exact}\). The mitigated expected value of \(A\) at the end of \(C_0\) is then obtained simply with \(f(a_0^{noisy})\).

In this implementation the initial circuit is expected to be decomposed in the three Clifford gates \(RX(\frac{\pi}{2})\), \(CNOT\), \(X\) and in \(RZ(\theta)\) (which is Clifford only for \(\theta=\frac{n\pi}{2}\)). By default the set of Clifford gates used for substitution is \(\{RZ(0),RZ(\frac{\pi}{2}),RZ(\pi),RZ(\frac{3}{2}\pi)\}\). See Sopena et al for more details.

qibo.models.error_mitigation.CDR(circuit, observable, noise_model, nshots: int = 10000, model=<function <lambda>>, n_training_samples: int = 100, full_output: bool = False, readout=None, qubit_map=None, seed=None, backend=None)[source]#

Runs the Clifford Data Regression error mitigation method.

Parameters:

circuit (qibo.models.Circuit) – input circuit decomposed in the primitive gates X, CNOT, RX(pi/2), RZ(theta).
observable (qibo.hamiltonians.Hamiltonian/:class:`qibo.hamiltonians.SymbolicHamiltonian) – observable to be measured.
noise_model (qibo.noise.NoiseModel) – noise model used for simulating noisy computation.
nshots (int, optional) – number of shots. Defaults \(10000\).
model (callable, optional) – model used for fitting. This should be a callable function object f(x, *params), taking as input the predictor variable and the parameters. Default is a simple linear model f(x,a,b) := a*x + b.
n_training_samples (int, optional) – number of training circuits to sample. Defaults to 100.
full_output (bool, optional) – if True, this function returns additional information: val, optimal_params, train_val. Defaults to False.
readout (dict, optional) –
a dictionary that may contain the following keys:
- ncircuits: int, specifies the number of random circuits to use for the randomized method of readout error mitigation.
- response_matrix: numpy.ndarray, used for applying a pre-computed response matrix for readout error mitigation.
- ibu_iters: int, specifies the number of iterations for the iterative Bayesian unfolding method of readout error mitigation. If provided, the corresponding readout error mitigation method is used. Defaults to {}.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Mitigated expectation value of observable. val (float): Noisy expectation value of observable. optimal_params (list): Optimal values for params. train_val (dict): Contains the noise-free and noisy expectation values obtained with the training circuits.

Return type:

mit_val (float)

Reference:

P. Czarnik, A. Arrasmith et al, Error mitigation with Clifford quantum-circuit data. arXiv:2005.10189 [quant-ph].

qibo.models.error_mitigation.sample_training_circuit_cdr(circuit, replacement_gates: list = None, sigma: float = 0.5, seed=None, backend=None)[source]#

Samples a training circuit for CDR by susbtituting some of the non-Clifford gates.

Parameters:

circuit (qibo.models.Circuit) – circuit to sample from, decomposed in RX(pi/2), X, CNOT and RZ gates.
replacement_gates (list, optional) – candidates for the substitution of the non-Clifford gates. The list should be composed by tuples of the form (gates.XYZ, kwargs). For example, phase gates are used by default: list((RZ, {'theta':0}), (RZ, {'theta':pi/2}), (RZ, {'theta':pi}), (RZ, {'theta':3*pi/2})).
sigma (float, optional) – standard devation of the Gaussian distribution used for sampling.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

The sampled circuit.

Return type:

qibo.models.Circuit

Variable Noise CDR (vnCDR)#

Variable Noise CDR (vnCDR) is an extension of the CDR method described above that factors in different noise levels as in ZNE. In detail, the set of circuits \(S_n=\{\mathbf{C}_i\}_{i=1,..,n}\) is still generated as in CDR, but for each \(\mathbf{C}_i\) we have \(k\) different versions of it with increased noise \(\mathbf{C}_i=C_i^0,C_i^1,...,C_i^{k-1}\).

Therefore, in this case we have a \(k\)-dimensional predictor variable \(\mathbf{a}_i^{noisy}=\big(a_i^0, a_i^1,..,a_i^{k-1}\big)^{noisy}\) for the same noise-free targets \(a_i^{exact}\), and we want to learn the mapping:

\[f:\mathbf{a}_i^{noisy}\rightarrow a_i^{exact}\]

via minimizing the same mean squared error:

\[E = \sum_{i=1}^n \bigg(a_i^{exact}-f(\mathbf{a}_i^{noisy})\bigg)^2\]

In particular, the default choice is to take \(f(\mathbf{x}):=\Gamma\cdot \mathbf{x}\;\), with \(\Gamma=\text{diag}(\gamma_0,\gamma_1,...,\gamma_{k-1})\;\), that corresponds to the ZNE calculation for the estimate of the expected value.

Here, as in the implementation of the CDR above, the circuit is supposed to be decomposed in the set of primitive gates \({RX(\frac{\pi}{2}),CNOT,X,RZ(\theta)}\). See Sopena et al for all the details.

qibo.models.error_mitigation.vnCDR(circuit, observable, noise_levels, noise_model, nshots: int = 10000, model=None, n_training_samples: int = 100, insertion_gate: str = 'CNOT', full_output: bool = False, readout=None, qubit_map=None, seed=None, backend=None)[source]#

Runs the variable-noise Clifford Data Regression error mitigation method.

Parameters:

circuit (qibo.models.Circuit) – input circuit decomposed in the primitive gates X, CNOT, RX(pi/2), RZ(theta).
observable (qibo.hamiltonians.Hamiltonian/:class:`qibo.hamiltonians.SymbolicHamiltonian) – observable to be measured.
noise_levels (numpy.ndarray) – sequence of noise levels.
noise_model (qibo.noise.NoiseModel) – noise model used for simulating noisy computation.
nshots (int, optional) – number of shots. Defaults to \(10000\).
model (callable, optional) – model used for fitting. This should be a callable function object f(x, *params), taking as input the predictor variable and the parameters. Default is a simple linear model f(x,a,b) := a*x + b.
n_training_samples (int, optional) – number of training circuits to sample.
insertion_gate (str, optional) – gate to be used in the insertion. If "RX", the gate used is :math:RX(\pi / 2). Default is "CNOT".
full_output (bool, optional) – if True, this function returns additional information: val, optimal_params, train_val. Defaults to False.
readout (dict, optional) –
a dictionary that may contain the following keys:
- ncircuits: int, specifies the number of random circuits to use for the randomized method of readout error mitigation.
- response_matrix: numpy.ndarray, used for applying a pre-computed response matrix for readout error mitigation.
- ibu_iters: int, specifies the number of iterations for the iterative Bayesian unfolding method of readout error mitigation. If provided, the corresponding readout error mitigation method is used. Defaults to {}.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Mitigated expectation value of observable. val (list): Expectation value of observable with increased noise levels. optimal_params (list): Optimal values for params. train_val (dict): Contains the noise-free and noisy expectation values obtained with the training circuits.

Return type:

mit_val (float)

Reference:

A. Lowe, MH. Gordon et al, Unified approach to data-driven quantum error mitigation. arXiv:2011.01157 [quant-ph].

Importance Clifford Sampling (ICS)#

In the Importance Clifford Sampling (ICS) method, a set of \(n\) circuits \(S_n=\{C_i\}_{i=1,..,n}\) that stabilizes a given Pauli observable is generated starting from the original circuit \(C_0\) by replacing all the non-Clifford gates with Clifford ones. Given an observable \(A\), all the circuits of \(S_n\) are both simulated to obtain the correspondent expected values of \(A\) in noise-free condition \(\{a_i^{exact}\}_{i=1,..,n}\), and run in noisy conditions to obtain the noisy expected values \(\{a_i^{noisy}\}_{i=1,..,n}\).

Finally, a theoretically inspired model \(f\) is learned using the training data.

The mitigated expected value of \(A\) at the end of \(C_0\) is then obtained simply with \(f(a_0^{noisy})\).

qibo.models.error_mitigation.ICS(circuit, observable, readout=None, qubit_map=None, noise_model=None, nshots=10000, n_training_samples=10, full_output=False, seed=None, backend=None)[source]#

Computes the Important Clifford Sampling method.

Parameters:

circuit (qibo.models.Circuit) – input circuit.
observable (qibo.hamiltonians.Hamiltonian/:class:`qibo.hamiltonians.SymbolicHamiltonian) – the observable to be measured.
readout (dict, optional) –
a dictionary that may contain the following keys:
- ncircuits: int, specifies the number of random circuits to use for the randomized method of readout error mitigation.
- response_matrix: numpy.ndarray, used for applying a pre-computed response matrix for readout error mitigation.
- ibu_iters: int, specifies the number of iterations for the iterative Bayesian unfolding method of readout error mitigation. If provided, the corresponding readout error mitigation method is used. Defaults to {}.
qubit_map (list, optional) – the qubit map. If None, a list of range of circuit’s qubits is used. Defaults to None.
noise_model (qibo.models.noise.Noise, optional) – the noise model to be applied. Defaults to None.
nshots (int, optional) – the number of shots for the circuit execution. Defaults to \(10000\).
n_training_samples (int, optional) – the number of training samples. Defaults to 10.
full_output (bool, optional) – if True, this function returns additional information: val, optimal_params, train_val. Defaults to False.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – the backend to be used in the execution. If None, it uses the global backend. Defaults to None.

Returns:

the mitigated expectated value. mitigated_expectation_std (float): the standard deviation of the mitigated expectated value. dep_param (float): the depolarizing parameter. dep_param_std (float): the standard deviation of the depolarizing parameter. lambda_list (list): the list of the depolarizing parameters. data (dict): the data dictionary containing the noise-free and noisy expectation values obtained with the training circuits.

Return type:

mitigated_expectation (float)

Reference:

Dayue Qin, Yanzhu Chen et al, Error statistics and scalability of quantum error mitigation formulas. arXiv:2112.06255 [quant-ph].

qibo.models.error_mitigation.sample_clifford_training_circuit(circuit, seed=None, backend=None)[source]#

Samples a training circuit for CDR by susbtituting all the non-Clifford gates.

Parameters:

circuit (qibo.models.Circuit) – circuit to sample from.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

the sampled circuit.

Return type:

qibo.models.Circuit

Gates#

All supported gates can be accessed from the qibo.gates module. Read below for a complete list of supported gates.

All gates support the controlled_by method that allows to control the gate on an arbitrary number of qubits. For example

gates.X(0).controlled_by(1, 2) is equivalent to gates.TOFFOLI(1, 2, 0),
gates.RY(0, np.pi).controlled_by(1, 2, 3) applies the Y-rotation to qubit 0 when qubits 1, 2 and 3 are in the |111> state.
gates.SWAP(0, 1).controlled_by(3, 4) swaps qubits 0 and 1 when qubits 3 and 4 are in the |11> state.

Abstract gate#

class qibo.gates.abstract.Gate[source]#

The base class for gate implementation.

All base gates should inherit this class.

name#

Name of the gate.

Type:: str

draw_label#

Optional label for drawing the gate in a circuit with qibo.models.Circuit.draw().

Type:: str

is_controlled_by#

True if the gate was created using the qibo.gates.abstract.Gate.controlled_by() method, otherwise False.

Type:: bool

init_args#

Arguments used to initialize the gate.

Type:: list

init_kwargs#

Arguments used to initialize the gate.

Type:: dict

target_qubits#

Tuple with ids of target qubits.

Type:: tuple

control_qubits#

Tuple with ids of control qubits sorted in increasing order.

Type:: tuple

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property raw: dict#

Serialize to dictionary.

The values used in the serialization should be compatible with a JSON dump (or any other one supporting a minimal set of scalar types). Though the specific implementation is up to the specific gate.

static from_dict(raw: dict)[source]#

Load from serialization.

Essentially the counter-part of raw().

to_json()[source]#: Dump gate to JSON.

Note

Consider using raw() directly.

property qubits: Tuple[int, ...]#: Tuple with ids of all qubits (control and target) that the gate acts.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

property target_qubits: Tuple[int, ...]#: Tuple with ids of target qubits.

property control_qubits: Tuple[int, ...]#: Tuple with ids of control qubits sorted in increasing order.

property parameters#: Returns a tuple containing the current value of gate’s parameters.

commutes(gate: Gate) → bool[source]#

Checks if two gates commute.

Parameters:: gate – Gate to check if it commutes with the current gate.
Returns:: True if the gates commute, False otherwise.
Return type:: bool

on_qubits(qubit_map) → Gate[source]#

Creates the same gate targeting different qubits.

Parameters:: qubit_map (int) – Dictionary mapping original qubit indices to new ones.
Returns:: A qibo.gates.Gate object of the original gate type targeting the given qubits.

Example

from qibo import Circuit, gates
circuit = Circuit(4)
# Add some CNOT gates
circuit.add(gates.CNOT(2, 3).on_qubits({2: 2, 3: 3})) # equivalent to gates.CNOT(2, 3)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 3, 3: 0})) # equivalent to gates.CNOT(3, 0)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 1, 3: 3})) # equivalent to gates.CNOT(1, 3)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 2, 3: 1})) # equivalent to gates.CNOT(2, 1)
circuit.draw()

───X─────
───|─o─X─
─o─|─|─o─
─X─o─X───

dagger() → Gate[source]#

Returns the dagger (conjugate transpose) of the gate.

Note that dagger is not persistent for parametrized gates. For example, applying a dagger to an qibo.gates.gates.RX gate will change the sign of its parameter at the time of application. However, if the parameter is updated after that, for example using qibo.models.circuit.Circuit.set_parameters(), then the action of dagger will be lost.

Returns:: object representing the dagger of the original gate.
Return type:: qibo.gates.Gate

decompose(*free) → List[Gate][source]#

Decomposes multi-control gates to gates supported by OpenQASM.

Decompositions are based on arXiv:9503016.

Parameters:: free – Ids of free qubits to use for the gate decomposition.
Returns:: gates that have the same effect as applying the original gate.
Return type:: list

matrix(backend=None)[source]#

Returns the matrix representation of the gate.

If gate has controlled qubits inserted by qibo.gates.Gate.controlled_by(), then qibo.gates.Gate.matrix() returns the matrix of the original gate.

from qibo import gates

gate = gates.SWAP(3, 4).controlled_by(0, 1, 2)
print(gate.matrix())

To return the full matrix that takes the control qubits into account, one should use qibo.models.Circuit.unitary(), e.g.

from qibo import Circuit, gates

nqubits = 5
circuit = Circuit(nqubits)
circuit.add(gates.SWAP(3, 4).controlled_by(0, 1, 2))
print(circuit.unitary())

Parameters:: backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.
Returns:: Matrix representation of gate.
Return type:: ndarray

Note

Gate.matrix was defined as an atribute in qibo versions prior to 0.2.0. From 0.2.0 on, it has been converted into a method and has replaced the asmatrix method.

generator_eigenvalue()[source]#

This function returns the eigenvalues of the gate’s generator.

Returns:: eigenvalue of the generator.
Return type:: float

basis_rotation()[source]#: Transformation required to rotate the basis for measuring the gate.

Single qubit gates#

Hadamard (H)#

class qibo.gates.H(q)[source]#

The Hadamard gate.

Corresponds to the following unitary matrix

\[\begin{split}\frac{1}{\sqrt{2}} \, \begin{pmatrix} 1 & 1 \\ 1 & -1 \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Pauli X (X)#

class qibo.gates.X(q)[source]#

The Pauli-\(X\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 0 & 1 \\ 1 & 0 \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose(*free, use_toffolis=True)[source]#

Decomposes multi-control X gate to one-qubit, CNOT and TOFFOLI gates.

Parameters:

free – Ids of free qubits to use for the gate decomposition.
use_toffolis – If True the decomposition contains only TOFFOLI gates. If False a congruent representation is used for TOFFOLI gates. See qibo.gates.TOFFOLI for more details on this representation.

Returns:

List with one-qubit, CNOT and TOFFOLI gates that have the same effect as applying the original multi-control gate.

basis_rotation()[source]#: Transformation required to rotate the basis for measuring the gate.

Pauli Y (Y)#

class qibo.gates.Y(q)[source]#

The Pauli-\(Y\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 0 & -i \\ i & 0 \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

basis_rotation()[source]#: Transformation required to rotate the basis for measuring the gate.

Pauli Z (Z)#

class qibo.gates.Z(q)[source]#

The Pauli-\(Z\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 \\ 0 & -1 \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

basis_rotation()[source]#: Transformation required to rotate the basis for measuring the gate.

Square-root of Pauli X (SX)#

class qibo.gates.SX(q)[source]#

The \(\sqrt{X}\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\frac{1}{2} \, \begin{pmatrix} 1 + i & 1 - i \\ 1 - i & 1 + i \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose()[source]#

Decomposition of \(\sqrt{X}\) up to global phase.

A global phase difference exists between the definitions of \(\sqrt{X}\) and \(\text{RX}(\pi / 2)\), with \(\text{RX}\) being the qibo.gates.RX gate. More precisely, \(\sqrt{X} = e^{i \pi / 4} \, \text{RX}(\pi / 2)\).

S gate (S)#

class qibo.gates.S(q)[source]#

The \(S\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 \\ 0 & i \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

T gate (T)#

class qibo.gates.T(q)[source]#

The T gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 \\ 0 & e^{i \pi / 4} \\ \end{pmatrix}\end{split}\]

Parameters:: q (int) – the qubit id number.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Identity (I)#

class qibo.gates.I(*q)[source]#

The identity gate.

Parameters:: *q (int) – the qubit id numbers.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Align (A)#

class qibo.gates.Align(q, delay=0, trainable=False)[source]#

Aligns proceeding qubit operations and (optionally) waits delay amount of time.

Note

For this gate, the trainable parameter is by default set to False.

Parameters:

q (int) – The qubit ID.
delay (int, optional) – The time (in ns) for which to delay circuit execution on the specified qubits. Defaults to 0 (zero).

Measurement (M)#

class qibo.gates.M(*q, register_name: str | None = None, collapse: bool = False, basis: ~qibo.gates.abstract.Gate | str = <class 'qibo.gates.gates.Z'>, p0: ProbsType | None = None, p1: ProbsType | None = None)[source]#

The measure gate.

Parameters:

*q (int) – id numbers of the qubits to measure. It is possible to measure multiple qubits using gates.M(0, 1, 2, ...). If the qubits to measure are held in an iterable (eg. list) the * operator can be used, for example gates.M(*[0, 1, 4]) or gates.M(*range(5)).
register_name (str, optional) – Optional name of the register to distinguish it from other registers when used in circuits.
collapse (bool) – Collapse the state vector after the measurement is performed. Can be used only for single shot measurements. If True the collapsed state vector is returned. If False the measurement result is returned.
basis (qibo.gates.Gate or str or list, optional) – Basis to measure. Can be either: - a qibo gate - the string representing the gate - a callable that accepts a qubit, for example: lambda q: gates.RX(q, 0.2) - a list of the above, if a different basis will be used for each measurement qubit. Defaults is to qibo.gates.Z.
p0 (dict, optional) – bitflip probability map. Can be: A dictionary that maps each measured qubit to the probability that it is flipped, a list or tuple that has the same length as the tuple of measured qubits or a single float number. If a single float is given the same probability will be used for all qubits.
p1 (dict, optional) – bitflip probability map for asymmetric bitflips. Same as p0 but controls the 1->0 bitflip probability. If p1 is None then p0 will be used both for 0->1 and 1->0 bitflips.

property raw: dict#

Serialize to dictionary.

The values used in the serialization should be compatible with a JSON dump (or any other one supporting a minimal set of scalar types). Though the specific implementation is up to the specific gate.

add(gate)[source]#

Adds target qubits to a measurement gate.

This method is only used for creating the global measurement gate used by the qibo.models.Circuit. The user is not supposed to use this method and a ValueError is raised if he does so.

Parameters:: gate – Measurement gate to add its qubits in the current gate.

classmethod load(payload)[source]#: Constructs a measurement gate starting from a json serialized one.

on_qubits(qubit_map) → Gate[source]#

Creates the same measurement gate targeting different qubits and preserving the measurement result register.

Parameters:: qubit_map (dict) – dictionary mapping original qubit indices to new ones.
Returns:: object of the original gate type targeting the given qubits.
Return type:: qibo.gates.Gate.M

Example

from qibo import Circuit, gates

measurement = gates.M(0, 1)

circuit = Circuit(3)
circuit.add(measurement.on_qubits({0: 0, 1: 2}))
assert circuit.queue[0].result is measurement.result
circuit.draw()

─M─
─|─
─M─

Rotation X-axis (RX)#

class qibo.gates.RX(q, theta, trainable=True)[source]#

Rotation around the X-axis of the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos \frac{\theta }{2} & -i\sin \frac{\theta }{2} \\ -i\sin \frac{\theta }{2} & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

generator_eigenvalue()[source]#

This function returns the eigenvalues of the gate’s generator.

Returns:: eigenvalue of the generator.
Return type:: float

Rotation Y-axis (RY)#

class qibo.gates.RY(q, theta, trainable=True)[source]#

Rotation around the Y-axis of the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos \frac{\theta }{2} & -\sin \frac{\theta }{2} \\ \sin \frac{\theta }{2} & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

generator_eigenvalue()[source]#

This function returns the eigenvalues of the gate’s generator.

Returns:: eigenvalue of the generator.
Return type:: float

Rotation Z-axis (RZ)#

class qibo.gates.RZ(q, theta, trainable=True)[source]#

Rotation around the Z-axis of the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} e^{-i \theta / 2} & 0 \\ 0 & e^{i \theta / 2} \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

generator_eigenvalue()[source]#

This function returns the eigenvalues of the gate’s generator.

Returns:: eigenvalue of the generator.
Return type:: float

First general unitary (U1)#

class qibo.gates.U1(q, theta, trainable=True)[source]#

First general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 \\ 0 & e^{i \theta} \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Second general unitary (U2)#

class qibo.gates.U2(q, phi, lam, trainable=True)[source]#

Second general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\frac{1}{\sqrt{2}} \begin{pmatrix} e^{-i(\phi + \lambda )/2} & -e^{-i(\phi - \lambda )/2} \\ e^{i(\phi - \lambda )/2} & e^{i (\phi + \lambda )/2} \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
phi (float) – first rotation angle.
lamb (float) – second rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Third general unitary (U3)#

class qibo.gates.U3(q, theta, phi, lam, trainable=True)[source]#

Third general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} e^{-i(\phi + \lambda )/2}\cos\left (\frac{\theta }{2}\right ) & -e^{-i(\phi - \lambda )/2}\sin\left (\frac{\theta }{2}\right ) \\ e^{i(\phi - \lambda )/2}\sin\left (\frac{\theta }{2}\right ) & e^{i (\phi + \lambda )/2}\cos\left (\frac{\theta }{2}\right ) \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – first rotation angle.
phi (float) – second rotation angle.
lamb (float) – third rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose() → List[Gate][source]#

Decomposition of \(U_{3}\) up to global phase.

A global phase difference exists between the definitions of \(U3\) and this decomposition. More precisely,

\[U_{3}(\theta, \phi, \lambda) = e^{i \, \frac{3 \pi}{2}} \, \text{RZ}(\phi + \pi) \, \sqrt{X} \, \text{RZ}(\theta + \pi) \, \sqrt{X} \, \text{RZ}(\lambda) \, ,\]

where \(\text{RZ}\) and \(\sqrt{X}\) are, respectively, qibo.gates.RZ and :class`qibo.gates.SX`.

Two qubit gates#

Controlled-NOT (CNOT)#

class qibo.gates.CNOT(q0, q1)[source]#

The Controlled-NOT gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#

Decomposes multi-control gates to gates supported by OpenQASM.

Decompositions are based on arXiv:9503016.

Parameters:: free – Ids of free qubits to use for the gate decomposition.
Returns:: gates that have the same effect as applying the original gate.
Return type:: list

Controlled-Y (CY)#

class qibo.gates.CY(q0, q1)[source]#

The Controlled-\(Y\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & -i \\ 0 & 0 & i & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose() → List[Gate][source]#

Decomposition of \(\text{CY}\) gate.

Decompose \(\text{CY}\) gate into qibo.gates.SDG in the target qubit, followed by qibo.gates.CNOT, followed by a qibo.gates.S in the target qubit.

Controlled-phase (CZ)#

class qibo.gates.CZ(q0, q1)[source]#

The Controlled-Phase gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & -1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose() → List[Gate][source]#

Decomposition of \(\text{CZ}\) gate.

Decompose \(\text{CZ}\) gate into qibo.gates.H in the target qubit, followed by qibo.gates.CNOT, followed by another qibo.gates.H in the target qubit

Controlled-Square Root of X (CSX)#

class qibo.gates.CSX(q0, q1)[source]#

The Controlled-\(\sqrt{X}\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{i\pi/4} & e^{-i\pi/4} \\ 0 & 0 & e^{-i\pi/4} & e^{i\pi/4} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Controlled-rotation X-axis (CRX)#

class qibo.gates.CRX(q0, q1, theta, trainable=True)[source]#

Controlled rotation around the X-axis for the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & \cos \frac{\theta }{2} & -i\sin \frac{\theta }{2} \\ 0 & 0 & -i\sin \frac{\theta }{2} & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Controlled-rotation Y-axis (CRY)#

class qibo.gates.CRY(q0, q1, theta, trainable=True)[source]#

Controlled rotation around the Y-axis for the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & \cos \frac{\theta }{2} & -\sin \frac{\theta }{2} \\ 0 & 0 & \sin \frac{\theta }{2} & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Note that this differs from the qibo.gates.RZ gate.

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose() → List[Gate][source]#: Decomposition of \(\text{CRY}\) gate.

Controlled-rotation Z-axis (CRZ)#

class qibo.gates.CRZ(q0, q1, theta, trainable=True)[source]#

Controlled rotation around the Z-axis for the Bloch sphere.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{-i \theta / 2} & 0 \\ 0 & 0 & 0 & e^{i \theta / 2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Controlled first general unitary (CU1)#

class qibo.gates.CU1(q0, q1, theta, trainable=True)[source]#

Controlled first general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & e^{i \theta } \\ \end{pmatrix}\end{split}\]

Note that this differs from the qibo.gates.CRZ gate.

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Controlled second general unitary (CU2)#

class qibo.gates.CU2(q0, q1, phi, lam, trainable=True)[source]#

Controlled second general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\frac{1}{\sqrt{2}} \begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{-i(\phi + \lambda )/2} & -e^{-i(\phi - \lambda )/2} \\ 0 & 0 & e^{i(\phi - \lambda )/2} & e^{i (\phi + \lambda )/2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
phi (float) – first rotation angle.
lamb (float) – second rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

Controlled third general unitary (CU3)#

class qibo.gates.CU3(q0, q1, theta, phi, lam, trainable=True)[source]#

Controlled third general unitary gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{-i(\phi + \lambda )/2}\cos\left (\frac{\theta }{2}\right ) & -e^{-i(\phi - \lambda )/2}\sin\left (\frac{\theta }{2}\right ) \\ 0 & 0 & e^{i(\phi - \lambda )/2}\sin\left (\frac{\theta }{2}\right ) & e^{i (\phi + \lambda )/2}\cos\left (\frac{\theta }{2}\right ) \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the control qubit id number.
q1 (int) – the target qubit id number.
theta (float) – first rotation angle.
phi (float) – second rotation angle.
lamb (float) – third rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Swap (SWAP)#

class qibo.gates.SWAP(q0, q1)[source]#

The swap gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

iSwap (iSWAP)#

class qibo.gates.iSWAP(q0, q1)[source]#

The iSWAP gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & i & 0 \\ 0 & i & 0 & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Square root of iSwap (SiSWAP)#

class qibo.gates.SiSWAP(q0, q1)[source]#

The \(\sqrt{\text{iSWAP}}\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1/\sqrt{2} & i/\sqrt{2} & 0 \\ 0 & i/\sqrt{2} & 1/\sqrt{2} & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.

f-Swap (FSWAP)#

class qibo.gates.FSWAP(q0, q1)[source]#

The fermionic swap gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & -1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be f-swapped id number.
q1 (int) – the second qubit to be f-swapped id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

fSim#

class qibo.gates.fSim(q0, q1, theta, phi, trainable=True)[source]#

The fSim gate defined in arXiv:2001.08343.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos \theta & -i\sin \theta & 0 \\ 0 & -i\sin \theta & \cos \theta & 0 \\ 0 & 0 & 0 & e^{-i \phi } \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.
theta (float) – Angle for the one-qubit rotation.
phi (float) – Angle for the |11> phase.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

Sycamore gate#

class qibo.gates.SYC(q0, q1)[source]#

The Sycamore gate, defined in the Supplementary Information of Quantum supremacy using a programmable superconducting processor.

Corresponding to the following unitary matrix

\[\begin{split}\text{fSim}(\pi / 2, \, \pi / 6) = \begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & -i & 0 \\ 0 & -i & 0 & 0 \\ 0 & 0 & 0 & e^{-i \pi / 6} \\ \end{pmatrix} \, ,\end{split}\]

where \(\text{fSim}\) is the qibo.gates.fSim gate.

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.

fSim with general rotation#

class qibo.gates.GeneralizedfSim(q0, q1, unitary, phi, trainable=True)[source]#

The fSim gate with a general rotation.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & R_{00} & R_{01} & 0 \\ 0 & R_{10} & R_{11} & 0 \\ 0 & 0 & 0 & e^{-i \phi } \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.
unitary (np.ndarray) – Unitary that corresponds to the one-qubit rotation.
phi (float) – Angle for the |11> phase.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property parameters#: Returns a tuple containing the current value of gate’s parameters.

Parametric XX interaction (RXX)#

class qibo.gates.RXX(q0, q1, theta, trainable=True)[source]#

Parametric 2-qubit XX interaction, or rotation about XX-axis.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos \frac{\theta }{2} & 0 & 0 & -i\sin \frac{\theta }{2} \\ 0 & \cos \frac{\theta }{2} & -i\sin \frac{\theta }{2} & 0 \\ 0 & -i\sin \frac{\theta }{2} & \cos \frac{\theta }{2} & 0 \\ -i\sin \frac{\theta }{2} & 0 & 0 & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first entangled qubit id number.
q1 (int) – the second entangled qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Parametric YY interaction (RYY)#

class qibo.gates.RYY(q0, q1, theta, trainable=True)[source]#

Parametric 2-qubit YY interaction, or rotation about YY-axis.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos \frac{\theta }{2} & 0 & 0 & i\sin \frac{\theta }{2} \\ 0 & \cos \frac{\theta }{2} & -i\sin \frac{\theta }{2} & 0 \\ 0 & -i\sin \frac{\theta }{2} & \cos \frac{\theta }{2} & 0 \\ i\sin \frac{\theta }{2} & 0 & 0 & \cos \frac{\theta }{2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first entangled qubit id number.
q1 (int) – the second entangled qubit id number.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Parametric ZZ interaction (RZZ)#

class qibo.gates.RZZ(q0, q1, theta, trainable=True)[source]#

Parametric 2-qubit ZZ interaction, or rotation about ZZ-axis.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} e^{-i \theta / 2} & 0 & 0 & 0 \\ 0 & e^{i \theta / 2} & 0 & 0 \\ 0 & 0 & e^{i \theta / 2} & 0 \\ 0 & 0 & 0 & e^{-i \theta / 2} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first entangled qubit id number.
q1 (int) – the second entangled qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Parametric ZX interaction (RZX)#

class qibo.gates.RZX(q0, q1, theta, trainable=True)[source]#

Parametric 2-qubit ZX interaction, or rotation about ZX-axis.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \text{RX}(\theta) & 0 \\ 0 & \text{RX}(-\theta) \\ \end{pmatrix} = \begin{pmatrix} \cos{\frac{\theta}{2}} & -i \sin{\frac{\theta}{2}} & 0 & 0 \\ -i \sin{\frac{\theta}{2}} & \cos{\frac{\theta}{2}} & 0 & 0 \\ 0 & 0 & \cos{\frac{\theta}{2}} & i \sin{\frac{\theta}{2}} \\ 0 & 0 & i \sin{\frac{\theta}{2}} & \cos{\frac{\theta}{2}} \\ \end{pmatrix} \, ,\end{split}\]

where \(\text{RX}\) is the qibo.gates.RX gate.

Parameters:

q0 (int) – the first entangled qubit id number.
q1 (int) – the second entangled qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

Parametric XX-YY interaction (RXXYY)#

class qibo.gates.RXXYY(q0, q1, theta, trainable=True)[source]#

Parametric 2-qubit \(XX + YY\) interaction, or rotation about \(XX + YY\)-axis.

Corresponds to the following unitary matrix

\[\begin{split}\exp\left(-i \frac{\theta}{4}(XX + YY)\right) = \begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos{\frac{\theta}{2}} & -i \sin{\frac{\theta}{2}} & 0 \\ 0 & -i \sin{\frac{\theta}{2}} & \cos{\frac{\theta}{2}} & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix} \, ,\end{split}\]

Parameters:

q0 (int) – the first entangled qubit id number.
q1 (int) – the second entangled qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#

Decomposition of \(\text{R_{XX-YY}}\) up to global phase.

This decomposition has a global phase difference with respect to the original gate due to a phase difference in \(\left(\sqrt{X}\right)^{\dagger}\).

Givens gate#

class qibo.gates.GIVENS(q0, q1, theta, trainable=True)[source]#

The Givens gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos(\theta) & -\sin(\theta) & 0 \\ 0 & \sin(\theta) & \cos(\theta) & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit id number.
q1 (int) – the second qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#: Decomposition of RBS gate according to ArXiv:2109.09685.

Reconfigurable Beam Splitter gate (RBS)#

class qibo.gates.RBS(q0, q1, theta, trainable=True)[source]#

The Reconfigurable Beam Splitter gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos(\theta) & \sin(\theta) & 0 \\ 0 & -\sin(\theta) & \cos(\theta) & 0 \\ 0 & 0 & 0 & 1 \\ \end{pmatrix}\end{split}\]

Note that, in our implementation, \(\text{RBS}(\theta) = \text{Givens}(-\theta)\), where \(\text{Givens}\) is the qibo.gates.GIVENS gate. However, we point out that this definition is not unique.

Parameters:

q0 (int) – the first qubit id number.
q1 (int) – the second qubit id number.
theta (float) – the rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#: Decomposition of RBS gate according to ArXiv:2109.09685.

Echo Cross-Resonance gate (ECR)#

class qibo.gates.ECR(q0, q1)[source]#

THe Echo Cross-Resonance gate.

Corresponds ot the following matrix

\[\begin{split}\frac{1}{\sqrt{2}} \left( X \, I - Y \, X \right) = \frac{1}{\sqrt{2}} \, \begin{pmatrix} 0 & 0 & 1 & i \\ 0 & 0 & i & 1 \\ 1 & -i & 0 & 0 \\ -i & 1 & 0 & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit id number.
q1 (int) – the second qubit id number.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#

Decomposition of \(\textup{ECR}\) gate up to global phase.

A global phase difference exists between the definitions of \(\textup{ECR}\) and this decomposition. More precisely,

\[\textup{ECR} = e^{i 7 \pi / 4} \, S(q_{0}) \, \sqrt{X}(q_{1}) \, \textup{CNOT}(q_{0}, q_{1}) \, X(q_{0})\]

Special gates#

Toffoli#

class qibo.gates.TOFFOLI(q0, q1, q2)[source]#

The Toffoli gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first control qubit id number.
q1 (int) – the second control qubit id number.
q2 (int) – the target qubit id number.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose(*free, use_toffolis: bool = True) → List[Gate][source]#

Decomposes multi-control gates to gates supported by OpenQASM.

Decompositions are based on arXiv:9503016.

Parameters:: free – Ids of free qubits to use for the gate decomposition.
Returns:: gates that have the same effect as applying the original gate.
Return type:: list

congruent(use_toffolis: bool = True) → List[Gate][source]#

Congruent representation of TOFFOLI gate.

This is a helper method for the decomposition of multi-control X gates. The congruent representation is based on Sec. 6.2 of arXiv:9503016. The sequence of the gates produced here has the same effect as TOFFOLI with the phase of the |101> state reversed.

Parameters:: use_toffolis – If True a single TOFFOLI gate is returned. If False the congruent representation is returned.
Returns:: List with RY and CNOT gates that have the same effect as applying the original TOFFOLI gate.

CCZ#

class qibo.gates.CCZ(q0, q1, q2)[source]#

The controlled-CZ gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & -1 \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first control qubit id number.
q1 (int) – the second control qubit id number.
q2 (int) – the target qubit id number.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose() → List[Gate][source]#

Decomposition of \(\text{CCZ}\) gate.

Decompose \(\text{CCZ}\) gate into qibo.gates.H in the target qubit, followed by qibo.gates.TOFFOLI, followed by a qibo.gates.H in the target qubit.

Deutsch#

class qibo.gates.DEUTSCH(q0, q1, q2, theta, trainable=True)[source]#

The Deutsch gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & i \cos{\theta} & \sin{\theta} \\ 0 & 0 & 0 & 0 & 0 & 0 & \sin{\theta} & i \cos{\theta} \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first control qubit id number.
q1 (int) – the second control qubit id number.
q2 (int) – the target qubit id number.

Generalized Reconfigurable Beam Splitter (RBS)#

class qibo.gates.GeneralizedRBS(qubits_in: Tuple[int] | List[int], qubits_out: Tuple[int] | List[int], theta: float, phi: float = 0.0, trainable: bool = True)[source]#

The generalized (complex) Reconfigurable Beam Splitter gate (\(\text{gRBS}\)).

Given a register called qubits_in containing \(m\) qubits and a register named qubits_out containing \(m'\) qubits, the \(\text{gRBS}\) is a \((m + m')\)-qubit gate that has the following matrix representation:

\[\begin{split}\begin{pmatrix} I & & & & \\ & e^{-i\phi}\cos\theta & & e^{-i\phi}\sin\theta & \\ & & I' & & \\ & -e^{i\phi}\sin\theta & & e^{i\phi}\cos\theta & \\ & & & & I\\ \end{pmatrix} \,\, ,\end{split}\]

where \(I\) and \(I'\) are, respectively, identity matrices of size \(2^{m} - 1\) and \(2^{m}(2^{m'} - 2)\).

This unitary matrix is also known as a Givens rotation.

References

1. R. M. S. Farias, T. O. Maciel, G. Camilo, R. Lin, S. Ramos-Calderer, and L. Aolita, Quantum encoder for fixed-Hamming-weight subspaces, Phys. Rev. Applied 23, 044014 (2025)

Parameters:

qubits_in (tuple or list) – ids of “input” qubits.
qubits_out (tuple or list) – ids of “output” qubits.
theta (float) – the rotation angle.
phi (float) – the phase angle. Defaults to \(0.0\).
trainable (bool) – whether gate parameter can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

decompose() → List[Gate][source]#

Decomposition of \(\text{gRBS}\) gate.

Decompose \(\text{gRBS}\) gate into qibo.gates.X, qibo.gates.CNOT, qibo.gates.RY, and qibo.gates.RZ.

Arbitrary unitary#

class qibo.gates.Unitary(unitary, *q, trainable=True, name: str = None, check_unitary: bool = True)[source]#

Arbitrary unitary gate.

Parameters:

unitary – Unitary matrix as a tensor supported by the backend.
*q (int) – Qubit id numbers that the gate acts on.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.
name (str) – Optional name for the gate.
check_unitary (bool) – if True, checks if unitary is an unitary operator. If False, check is not performed and unitary attribute defaults to False. Note that, even when the check is performed, there is no enforcement. This allows the user to create non-unitary gates. Default is True.

property parameters#: Returns a tuple containing the current value of gate’s parameters.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

on_qubits(qubit_map)[source]#

Creates the same gate targeting different qubits.

Parameters:: qubit_map (int) – Dictionary mapping original qubit indices to new ones.
Returns:: A qibo.gates.Gate object of the original gate type targeting the given qubits.

Example

from qibo import Circuit, gates
circuit = Circuit(4)
# Add some CNOT gates
circuit.add(gates.CNOT(2, 3).on_qubits({2: 2, 3: 3})) # equivalent to gates.CNOT(2, 3)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 3, 3: 0})) # equivalent to gates.CNOT(3, 0)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 1, 3: 3})) # equivalent to gates.CNOT(1, 3)
circuit.add(gates.CNOT(2, 3).on_qubits({2: 2, 3: 1})) # equivalent to gates.CNOT(2, 1)
circuit.draw()

───X─────
───|─o─X─
─o─|─|─o─
─X─o─X───

Callback gate#

class qibo.gates.CallbackGate(callback: Callback)[source]#

Calculates a qibo.callbacks.Callback at a specific point in the circuit.

This gate performs the callback calulation without affecting the state vector.

Parameters:: callback (qibo.callbacks.Callback) – Callback object to calculate.

Fusion gate#

class qibo.gates.FusedGate(*q)[source]#

Collection of gates that will be fused and applied as single gate during simulation. This gate is constructed automatically by qibo.models.circuit.Circuit.fuse() and should not be used by user.

can_fuse(gate, max_qubits)[source]#: Check if two gates can be fused.

matrix(backend=None)[source]#

Returns matrix representation of special gate.

Parameters:: backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.
Returns:: Matrix representation of special gate.
Return type:: ndarray

fuse(gate)[source]#: Fuses two gates.

IONQ Native gates#

GPI#

class qibo.gates.GPI(q, phi, trainable=True)[source]#

The GPI gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} 0 & e^{- i \phi} \\ e^{i \phi} & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
phi (float) – phase.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

GPI2#

class qibo.gates.GPI2(q, phi, trainable=True)[source]#

The GPI2 gate.

Corresponds to the following unitary matrix

\[\begin{split}\frac{1}{\sqrt{2}} \, \begin{pmatrix} 1 & -i e^{- i \phi} \\ -i e^{i \phi} & 1 \\ \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
phi (float) – phase.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.AbstractCircuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

property clifford#: Return boolean value representing if a Gate is Clifford or not.

Mølmer–Sørensen (MS)#

class qibo.gates.MS(q0, q1, phi0, phi1, theta: float = 1.5707963267948966, trainable=True)[source]#

The Mølmer–Sørensen (MS) gate is a two-qubit gate native to trapped ions.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos(\theta / 2) & 0 & 0 & -i e^{-i( \phi_0 + \phi_1)} \sin(\theta / 2) \\ 0 & \cos(\theta / 2) & -i e^{-i( \phi_0 - \phi_1)} \sin(\theta / 2) & 0 \\ 0 & -i e^{i( \phi_0 - \phi_1)} \sin(\theta / 2) & \cos(\theta / 2) & 0 \\ -i e^{i( \phi_0 + \phi_1)} \sin(\theta / 2) & 0 & 0 & \cos(\theta / 2) \\ \end{pmatrix}\end{split}\]

Parameters:

q0 (int) – the first qubit to be swapped id number.
q1 (int) – the second qubit to be swapped id number.
phi0 (float) – first qubit’s phase.
phi1 (float) – second qubit’s phase
theta (float, optional) – arbitrary angle in the interval \(0 \leq \theta \leq \pi /2\). If \(\theta \rightarrow \pi / 2\), the fully-entangling MS gate is defined. Defaults to \(\pi / 2\).
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

Quantinuum native gates#

U1q#

class qibo.gates.U1q(q, theta, phi, trainable=True)[source]#

Native single-qubit gate in the Quantinuum platform.

Corresponds to the following unitary matrix:

\[\begin{split}\begin{pmatrix} \cos\left(\frac{\theta}{2}\right) & -i \, e^{-i \, \phi} \, \sin\left(\frac{\theta}{2}\right) \\ -i \, e^{i \, \phi} \, \sin\left(\frac{\theta}{2}\right) & \cos\left(\frac{\theta}{2}\right) \\ \end{pmatrix}\end{split}\]

Note that \(U_{1q}(\theta, \phi) = U_{3}(\theta, \phi - \frac{\pi}{2}, \frac{\pi}{2} - \phi)\), where \(U_{3}\) is qibo.gates.U3.

Parameters:

q (int) – the qubit id number.
theta (float) – first rotation angle.
phi (float) – second rotation angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

Note

The other Quantinuum single-qubit and two-qubit native gates are implemented in Qibo as:

Pauli-\(Z\) rotation: qibo.gates.RZ
Arbitrary \(ZZ\) rotation: qibo.gates.RZZ
Fully-entangling \(ZZ\)-interaction: \(R_{ZZ}(\pi/2)\)

IQM native gates#

Phase-\(RX\)#

class qibo.gates.PRX(q, theta, phi, trainable=True)[source]#

Phase \(RX\) gate.

Corresponds to the following unitary matrix

\[\begin{split}\begin{pmatrix} \cos{(\theta / 2)} & -i e^{-i \phi} \sin{(\theta / 2)} \\ -i e^{i \phi} \sin{(\theta / 2)} & \cos{(\theta / 2)} \end{pmatrix}\end{split}\]

Parameters:

q (int) – the qubit id number.
theta (float) – the first angle corresponding to a rotation angle.
phi (float) – the second angle correspoding to a phase angle.
trainable (bool) – whether gate parameters can be updated using qibo.models.circuit.Circuit.set_parameters(). Defaults to True.

property qasm_label#: String corresponding to OpenQASM operation of the gate.

decompose()[source]#: Decomposition of Phase-\(RX\) gate.

Note

The other IQM two-qubit native gate is implemented in Qibo as:

Controlled-\(Z\) rotation: qibo.gates.CZ

Channels#

Channels are implemented in Qibo as additional gates and can be accessed from the qibo.gates module. Channels can be used on density matrices to perform noisy simulations. Channels that inherit qibo.gates.UnitaryChannel can also be applied to state vectors using sampling and repeated execution. For more information on the use of channels to simulate noise we refer to How to perform noisy simulation? The following channels are currently implemented:

Kraus channel#

class qibo.gates.KrausChannel(qubits, operators)[source]#

General channel defined by arbitrary Kraus operators.

Implements the following transformation:

\[\mathcal{E}(\rho ) = \sum _k A_k \rho A_k^\dagger\]

where A are arbitrary Kraus operators given by the user. Note that Kraus operators set should be trace preserving, however this is not checked. Simulation of this gate requires the use of density matrices. For more information on channels and Kraus operators please check J. Preskill’s notes.

Parameters:

qubits (int or list or tuple) – Qubits that the Kraus operators act on. Type int and tuple will be considered as the same qubit ids for all operators. A list should contain tuples of qubits corresponding to each operator. Can be [] if operators are of type qibo.gates.Gate, otherwise adds given gates on specified qubits.
operators (list) – List of Kraus operators Ak as matrices of type ndarray | tf.Tensor or gates qibo.gates.Gate.

Example

import numpy as np

from qibo import Circuit, gates

# initialize circuit with 3 qubits
circuit = Circuit(3, density_matrix=True)
# define a sqrt(0.4) * X gate
a_1 = np.sqrt(0.4) * np.array([[0, 1], [1, 0]])
# define a sqrt(0.6) * CNOT gate
a_2 = np.sqrt(0.6) * np.array([[1, 0, 0, 0], [0, 1, 0, 0],
                              [0, 0, 0, 1], [0, 0, 1, 0]])
# define the channel rho -> 0.4 X{1} rho X{1} + 0.6 CNOT{0, 2} rho CNOT{0, 2}
channel_1 = gates.KrausChannel([(1,), (0, 2)], [a_1, a_2])
# add channel to the circuit
circuit.add(channel_1)

# define the same channel using qibo.gates.Unitary
a_1 = gates.Unitary(a_1, 1)
a_2 = gates.Unitary(a_2, 0, 2)
channel_2 = gates.KrausChannel([], [a_1, a_2])
# add channel to the circuit
circuit.add(channel_2)

# define the channel rho -> 0.4 X{0} rho X{0} + 0.6 CNOT{1, 2} rho CNOT{1, 2}
channel_3 = gates.KrausChannel([(0,), (1, 2)], [a_1, a_2])
# add channel to the circuit
circuit.add(channel_3)

Unitary channel#

class qibo.gates.UnitaryChannel(qubits, operators)[source]#

Channel that is a probabilistic sum of unitary operations.

Implements the following transformation:

\[\mathcal{E}(\rho ) = \left (1 - \sum _k p_k \right )\rho + \sum _k p_k U_k \rho U_k^\dagger\]

where U are arbitrary unitary operators and p are floats between 0 and 1. Note that unlike qibo.gates.KrausChannel which requires density matrices, it is possible to simulate the unitary channel using state vectors and probabilistic sampling. For more information on this approach we refer to Using repeated execution.

Parameters:

qubits (int or list or tuple) – Qubits that the unitary operators act on. Types int and tuple will be considered as the same qubit(s) for all unitaries. A list should contain tuples of qubits corresponding to each operator. Can be [] if operators are of type qibo.gates.Gate, otherwise adds given gates on specified qubits.
operators (list) – List of operators as pairs (pk, Uk) where pk is float probability corresponding to a unitary Uk of type ndarray/tf.Tensor or gates qibo.gates.Gate.

Pauli noise channel#

class qibo.gates.PauliNoiseChannel(qubits: Tuple[int, list, tuple], operators: list)[source]#

Multi-qubit noise channel that applies Pauli operators with given probabilities.

Implements the following transformation:

\[\mathcal{E}(\rho ) = \left (1 - \sum _{k} p_{k} \right ) \, \rho + \sum_{k} \, p_{k} \, P_{k} \, \rho \, P_{k}\]

where \(P_{k}\) is the \(k\)-th Pauli string and \(p_{k}\) is the probability associated to \(P_{k}\).

Example

from itertools import product

import numpy as np

from qibo.gates.channels import PauliNoiseChannel

qubits = (0, 2)
nqubits = len(qubits)

# excluding the Identity operator
paulis = list(product(["I", "X"], repeat=nqubits))[1:]
# this next line is optional
paulis = [''.join(pauli) for pauli in paulis]

probabilities = np.random.rand(len(paulis) + 1)
probabilities /= np.sum(probabilities)
#Excluding probability of Identity operator
probabilities = probabilities[1:]

channel = PauliNoiseChannel(
    qubits, list(zip(paulis, probabilities))
)

This channel can be simulated using either density matrices or state vectors and sampling with repeated execution. See How to perform noisy simulation? for more information.

Parameters:

qubits (int or list or tuple) – Qubits that the noise acts on.
operators (list) – list of operators as pairs \((P_{k}, p_{k})\).

Depolarizing channel#

class qibo.gates.DepolarizingChannel(qubits, lam: float)[source]#

\(n\)-qubit Depolarizing quantum error channel,

\[\mathcal{E}(\rho ) = (1 - \lambda) \rho + \lambda \text{Tr}_q[\rho]\otimes \frac{I}{2^n}\]

where \(\lambda\) is the depolarizing error parameter and \(0 \le \lambda \le 4^n / (4^n - 1)\).

If \(\lambda = 1\) this is a completely depolarizing channel \(E(\rho) = I / 2^n\)
If \(\lambda = 4^n / (4^n - 1)\) this is a uniform Pauli error channel: \(E(\rho) = \sum_j P_j \rho P_j / (4^n - 1)\) for all \(P_j \neq I\).

Parameters:

qubits (int or list or tuple) – Qubit ids that the noise acts on.
lam (float) – Depolarizing error parameter.

Thermal relaxation channel#

class qibo.gates.ThermalRelaxationChannel(qubit: int, parameters: list)[source]#

Single-qubit thermal relaxation error channel.

Implements the following transformation:

If \(T_1 \geq T_2\):

\[\mathcal{E} (\rho ) = (1 - p_z - p_0 - p_1) \rho + p_z \, Z\rho Z + \mathrm{Tr}_{q}[\rho] \otimes (p_0 | 0\rangle \langle 0| + p_1|1\rangle \langle 1|)\]

while if \(T_1 < T_2\):

\[\mathcal{E}(\rho ) = \mathrm{Tr}_\mathcal{X} \left[\Lambda_{\mathcal{X}\mathcal{Y}} (\rho_\mathcal{X}^T \otimes I_{\mathcal{Y}}) \right]\]

with

\[\begin{split}\Lambda = \begin{pmatrix} 1 - p_1 & 0 & 0 & e^{-t / T_2} \\ 0 & p_1 & 0 & 0 \\ 0 & 0 & p_0 & 0 \\ e^{-t / T_2} & 0 & 0 & 1 - p_0 \end{pmatrix}\end{split}\]

where \(p_0 = (1 - e^{-t / T_1})(1 - \eta )\), \(p_1 = (1 - e^{-t / T_1})\eta\), and \(p_z = (e^{-t / T_1} - e^{-t / T_2})/2\). Here \(\eta\) is the excited_population and \(t\) is the time, both controlled by the user. This gate is based on Qiskit’s thermal relaxation error channel.

Parameters:

qubit (int) – Qubit id that the noise channel acts on.
parameters (list) – list of 3 or 4 parameters (t_1, t_2, time, excited_population=0), where t_1 (float): T1 relaxation time. Should satisfy t_1 > 0. t_2 (float): T2 dephasing time. Should satisfy t_1 > 0 and t_2 < 2 * t_1. time (float): the gate time for relaxation error. excited_population (float): the population of the excited state at equilibrium. Default is 0.

Amplitude damping channel#

class qibo.gates.AmplitudeDampingChannel(qubit, gamma: float)[source]#

Single-qubit amplitude damping channel in its Kraus representation, i.e.

\[\begin{split}K_{0} = \begin{pmatrix} 1 & 0 \\ 0 & \sqrt{1 - \gamma} \\ \end{pmatrix} \,\, , \,\, K_{1} = \begin{pmatrix} 0 & \sqrt{\gamma} \\ 0 & 0 \\ \end{pmatrix}\end{split}\]

Parameters:

qubit (int) – Qubit id that the noise channel acts on.
gamma (float) – amplitude damping strength.

Phase damping channel#

class qibo.gates.PhaseDampingChannel(qubit, gamma: float)[source]#

Single-qubit phase damping channel in its Kraus representation, i.e.

\[\begin{split}K_{0} = \begin{pmatrix} 1 & 0 \\ 0 & \sqrt{1 - \gamma} \\ \end{pmatrix} \,\, , \,\, K_{1} = \begin{pmatrix} 0 & 0 \\ 0 & \sqrt{\gamma} \\ \end{pmatrix}\end{split}\]

Parameters:

qubit (int) – Qubit id that the noise channel acts on.
gamma (float) – phase damping strength.

Readout error channel#

class qibo.gates.ReadoutErrorChannel(qubits: Tuple[int, list, tuple], probabilities)[source]#

Readout error channel implemented as a quantum-to-classical channel.

Parameters:

qubits (int or list or tuple) – Qubit ids that the channel acts on.
probabilities (array) – row-stochastic matrix \(P\) with all readout transition probabilities.

Example

For 1 qubit, the transition matrix \(P\) would be

\[\begin{split}P = \begin{pmatrix} p(0 \, | \, 0) & p(1 \, | \, 0) \\ p(0 \, | \, 1) & p(1 \, | \, 1) \end{pmatrix} \, .\end{split}\]

Reset channel#

class qibo.gates.ResetChannel(qubit, probabilities)[source]#

Single-qubit reset channel.

Implements the following transformation:

\[\mathcal{E}(\rho ) = (1 - p_{0} - p_{1}) \rho + \mathrm{Tr}_{q}[\rho] \otimes (p_{0} \, |0\rangle \langle 0| + p_{1} \, |1\rangle \langle 1|),\]

Parameters:

qubit (int) – qubit id that the channel acts on.
probabilities (list or ndarray) – list \([p_{0}, p_{1}]\), where \(p_{0}\) and \(p_{1}\) are the probabilities to reset to 0 and 1, respectively.

Noise#

In Qibo it is possible to create a custom noise model using the class qibo.noise.NoiseModel. This enables the user to create circuits where the noise is gate and qubit dependent.

For more information on the use of qibo.noise.NoiseModel see How to perform noisy simulation?

class qibo.noise.NoiseModel[source]#

Class for the implementation of a custom noise model.

Example:

from qibo import Circuit, gates
from qibo.noise import NoiseModel, PauliError

# Build specific noise model with 2 quantum errors:
# - Pauli error on H only for qubit 1.
# - Pauli error on CNOT for all the qubits.

noise_model = NoiseModel()
noise_model.add(PauliError([("X", 0.5)]), gates.H, 1)
noise_model.add(PauliError([("Y", 0.5)]), gates.CNOT)

# Generate noiseless circuit.
circuit = Circuit(2)
circuit.add([gates.H(0), gates.H(1), gates.CNOT(0, 1)])

# Apply noise to the circuit according to the noise model.
noisy_circuit = noise_model.apply(circuit)

add(error, gate: Gate | None = None, qubits: int | tuple | None = None, conditions=None)[source]#

Add a quantum error for a specific gate and qubit to the noise model.

Parameters:

error – quantum error to associate with the gate. Possible choices are qibo.noise.PauliError, qibo.noise.DepolarizingError, qibo.noise.ThermalRelaxationError, qibo.noise.AmplitudeDampingError, qibo.noise.PhaseDampingError, qibo.noise.ReadoutError, qibo.noise.ResetError, qibo.noise.UnitaryError, qibo.noise.KrausError, and qibo.noise.CustomError.
gate (qibo.gates.Gate, optional) – gate after which the noise will be added. If None, the noise will be added after each gate except qibo.gates.Channel and qibo.gates.M.
qubits (int or tuple, optional) – qubits where the noise will be applied. If None, the noise will be added after every instance of the gate. Defaults to None.
condition (callable, optional) – function that takes qibo.gates.Gate object as an input and returns True if noise should be added to it.

Example:

import numpy as np
from qibo import Circuit, gates
from qibo.noise import NoiseModel, PauliError

# Check if a gate is RX(pi/2).
def is_sqrt_x(gate):
    return np.pi/2 in gate.parameters

# Build a noise model with a Pauli error on RX(pi/2) gates.
error = PauliError(list(zip(["X", "Y", "Z"], [0.01, 0.5, 0.1])))
noise = NoiseModel()
noise.add(PauliError([("X", 0.5)]), gates.RX, conditions=is_sqrt_x)

# Generate a noiseless circuit.
circuit = Circuit(1)
circuit.add(gates.RX(0, np.pi / 2))
circuit.add(gates.RX(0, 3 * np.pi / 2))
circuit.add(gates.X(0))

# Apply noise to the circuit.
noisy_circuit = noise.apply(circuit)

apply(circuit)[source]#

Generate a noisy quantum circuit according to the noise model built.

Parameters:

circuit (qibo.models.circuit.Circuit) – quantum circuit

Returns:

initial circuit with noise gates: added according to the noise model.

Return type:

Quantum errors#

The quantum errors available to build a noise model are the following:

class qibo.noise.KrausError(ops)[source]#

Quantum error associated with the qibo.gates.KrausChannel.

Parameters:: ops (list) – List of Kraus operators of type np.ndarray or tf.Tensor and of the same shape.

channel(qubits, options)[source]#: Returns the quantum channel associated to the quantum error.

class qibo.noise.UnitaryError(probabilities, unitaries)[source]#

Quantum error associated with the qibo.gates.UnitaryChannel.

Parameters:

probabilities (list) – List of floats that correspond to the probability that each unitary Uk is applied.
unitaries (list) – List of unitary matrices as np.ndarray/tf.Tensor of the same shape. Must have the same length as the given probabilities p.

channel(qubits, options)[source]#: Returns the quantum channel associated to the quantum error.

class qibo.noise.PauliError(operators)[source]#

Quantum error associated with the qibo.gates.PauliNoiseChannel.

Parameters:: operators (list) – see qibo.gates.PauliNoiseChannel

channel(qubits, options)[source]#: Returns the quantum channel associated to the quantum error.

class qibo.noise.DepolarizingError(lam)[source]#

Quantum error associated with the qibo.gates.DepolarizingChannel.

Parameters:: options (float) – see qibo.gates.DepolarizingChannel

class qibo.noise.ThermalRelaxationError(t1, t2, time, excited_population=0)[source]#

Quantum error associated with the qibo.gates.ThermalRelaxationChannel.

Parameters:: options (tuple) – see qibo.gates.ThermalRelaxationChannel

class qibo.noise.AmplitudeDampingError(gamma)[source]#

Quantum error associated with the qibo.gates.AmplitudeDampingChannel.

Parameters:: options (float) – see qibo.gates.AmplitudeDampingChannel

class qibo.noise.PhaseDampingError(gamma)[source]#

Quantum error associated with the qibo.gates.PhaseDampingChannel.

Parameters:: options (float) – see qibo.gates.PhaseDampingChannel

class qibo.noise.ReadoutError(probabilities)[source]#

Quantum error associated with :class:’qibo.gates;ReadoutErrorChannel’.

Parameters:: options (array) – see :class:’qibo.gates.ReadoutErrorChannel’

class qibo.noise.ResetError(p0, p1)[source]#

Quantum error associated with the qibo.gates.ResetChannel.

Parameters:: options (tuple) – see qibo.gates.ResetChannel

class qibo.noise.CustomError(channel)[source]#

Quantum error associated with the qibo.gates.Channel

Parameters:: channel (qibo.gates.Channel) – any channel

Example:

import numpy as np
from qibo.gates import KrausChannel
from qibo.noise import CustomError

# define |0><0|
a1 = np.array([[1, 0], [0, 0]])
# define |0><1|
a2 = np.array([[0, 1], [0, 0]])

# Create an Error associated with Kraus Channel
# rho -> |0><0| rho |0><0| + |0><1| rho |0><1|
error = CustomError(gates.KrausChannel((0,), [a1, a2]))

IBMQ noise model#

In Qibo, it is possible to build noisy circuits based on IBMQ’s reported noise model of for its quantum computer by using the qibo.noise.IBMQNoiseModel class. The noise model is built using a combination of the qibo.gates.ThermalRelaxationChannel and qibo.gates.DepolarizingChannel channels. . At the end of the circuit, if the qubit is measured, bitflips errors are set. Moreover, the model handles idle qubits by applying a thermal relaxation channel for the duration of the idle-time.

For more information on the qibo.noise.IBMQNoiseModel class, see the example on Simulating quantum hardware.

class qibo.noise.IBMQNoiseModel[source]#

Class for the implementation of a IBMQ noise model.

This noise model applies a qibo.gates.DepolarizingChannel followed by a qibo.gates.ThermalRelaxationChannel after each one- or two-qubit gate in the circuit. It also applies single-qubit qibo.gates.ReadoutErrorChannel before every measurement gate.

Example:

from qibo import Circuit, gates
from qibo.models.encodings import phase_encoder
from qibo.noise import DepolarizingError, ThermalRelaxationError, ReadoutError
from qibo.noise import IBMQNoiseModel, NoiseModel

nqubits = 4

# creating circuit
phases = list(range(nqubits))
circuit = phase_encoder(phases, rotation="RY")
circuit.add(gates.CNOT(qubit, qubit + 1) for qubit in range(nqubits - 1))
circuit.add(gates.M(qubit) for qubit in range(1, nqubits - 1))

# creating noise model from dictionary
parameters = {
    "depolarizing_one_qubit" : {"0": 0.1, "2": 0.04, "3": 0.15},
    "depolarizing_two_qubit": {"0-1": 0.2},
    "t1" : {"0": 0.1, "1": 0.2, "3": 0.01},
    "t2" : {"0": 0.01, "1": 0.02, "3": 0.0001},
    "gate_times" : (0.1, 0.2),
    "excited_population" : 0.1,
    "readout_one_qubit" : {"0": (0.1, 0.1), "1": 0.1, "3": [0.1, 0.1]},
    }

noise_model = IBMQNoiseModel()
noise_model.from_dict(parameters)
noisy_circuit = noise_model.apply(circuit)

from_dict(parameters: dict)[source]#

Method used to pass noise parameters as inside dictionary.

Parameters:

parameters (dict) –

Contains parameters necessary to initialise qibo.noise.DepolarizingError, qibo.noise.ThermalRelaxationError, and qibo.noise.ReadoutError.

The keys and values of the dictionary parameters are defined below:

"depolarizing_one_qubit" (int or float or dict): If int or
float, all qubits share the same single-qubit depolarizing parameter. If dict, expects qubit indexes as keys and their respective depolarizing parameter as values. See qibo.gates.channels.DepolarizingChannel for a detailed definition of depolarizing parameter.
"depolarizing_two_qubit" (int or float or dict): If int or
float, all two-qubit gates share the same two-qubit depolarizing parameter regardless in which pair of qubits the two-qubit gate is acting on. If dict, expects pair qubit indexes as keys separated by a hiphen (e.g. “0-1” for gate that has “0” as control and “1” as target) and their respective depolarizing parameter as values. See qibo.gates.channels.DepolarizingChannel for a detailed definition of depolarizing parameter.
"t1" (int or float or dict): If int or float, all qubits
share the same t1. If dict, expects qubit indexes as keys and its respective t1 as values. See qibo.gates.channels.ThermalRelaxationChannel for a detailed definition of t1. Note that t1 and t2 must be passed with the same type.
"t2" (int or float or dict): If int or float, all qubits share
the same t2. If dict, expects qubit indexes as keys and its respective t2 as values. See qibo.gates.channels.ThermalRelaxationChannel for a detailed definition of t2. Note that t2 and t1 must be passed with the same type.
"gate_times" (tuple or list): pair of gate times representing
gate times for ThermalRelaxationError following, respectively, one- and two-qubit gates.
"excited_population" (int or float): See
ThermalRelaxationChannel.
"readout_one_qubit" (int or float or dict): If int or float,
\(p(0|1) = p(1|0)\), and all qubits share the same readout error probabilities. If dict, expects qubit indexes as keys and values as tuple (or list) in the format \((p(0|1),\,p(1|0))\). If values are tuple or list of length 1 or float or int, then it is assumed that \(p(0|1) = p(1|0)\).

Hamiltonians#

The main abstract Hamiltonian object of Qibo is:

class qibo.hamiltonians.abstract.AbstractHamiltonian[source]#

Qibo abstraction for Hamiltonian objects.

abstract eigenvalues(k=6)[source]#

Computes the eigenvalues for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigvalsh() for more details.

abstract eigenvectors(k=6)[source]#

Computes a tensor with the eigenvectors for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigh() for more details.

ground_state()[source]#

Computes the ground state of the Hamiltonian.

Uses qibo.hamiltonians.AbstractHamiltonian.eigenvectors() and returns eigenvector corresponding to the lowest energy.

abstract exp(a)[source]#

Computes a tensor corresponding to \(\exp(-i \, a \, H)\).

Parameters:: a (complex) – Complex number to multiply Hamiltonian before exponentiation.

abstract expectation(state, normalize=False)[source]#

Computes the real expectation value for a given state.

Parameters:

state (ndarray) – state in which to calculate the expectation value.
normalize (bool, optional) – If True, the expectation value \(\ell_{2}\)-normalized. Defaults to False.

Returns:

real number corresponding to the expectation value.

Return type:

abstract expectation_from_samples(freq, qubit_map=None)[source]#

Computes the expectation value of a diagonal observable, given computational-basis measurement frequencies.

Parameters:

freq (collections.Counter) – the keys are the observed values in binary form and the values the corresponding frequencies, that is the number of times each measured value/bitstring appears.
qubit_map (tuple) – Mapping between frequencies and qubits. If None, then defaults to \([1, \, 2, \, \cdots, \, \mathrm{len}(\mathrm{key})]\). Defaults to None.

Returns:

real number corresponding to the expectation value.

Return type:

Matrix Hamiltonian#

The first implementation of Hamiltonians uses the full matrix representation of the Hamiltonian operator in the computational basis. For \(n\) qubits, this matrix has size \(2^{n} \times 2^{n}\). Therefore, its construction is feasible only when \(n\) is small.

Alternatively, the user can construct this Hamiltonian using a sparse matrices. Sparse matrices from the scipy.sparse module are supported by the numpy and qibojit backends while the tensorflow.sparse can be used for tensorflow. Scipy sparse matrices support algebraic operations (addition, subtraction, scalar multiplication), linear algebra operations (eigenvalues, eigenvectors, matrix exponentiation) and multiplication to dense or other sparse matrices. All these properties are inherited by qibo.hamiltonians.Hamiltonian objects created using sparse matrices. Tensorflow sparse matrices support only multiplication to dense matrices. Both backends support calculating Hamiltonian expectation values using a sparse Hamiltonian matrix.

class qibo.hamiltonians.Hamiltonian(nqubits, matrix, backend=None)[source]#

Hamiltonian based on a dense or sparse matrix representation.

Parameters:

nqubits (int) – number of quantum bits.
matrix (ndarray) – Matrix representation of the Hamiltonian in the computational basis as an array of shape \(2^{n} \times 2^{n}\). Sparse matrices based on scipy.sparse for numpy / qibojit backends (or on tf.sparse for the tensorflow backend) are also supported.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

property matrix#

Returns the full matrix representation.

For \(n\) qubits, can be a dense \(2^{n} \times 2^{n}\) array or a sparse matrix, depending on how the Hamiltonian was created.

eigenvalues(k=6)[source]#

Computes the eigenvalues for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigvalsh() for more details.

eigenvectors(k=6)[source]#

Computes a tensor with the eigenvectors for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigh() for more details.

exp(a)[source]#

Computes a tensor corresponding to \(\exp(-i \, a \, H)\).

Parameters:: a (complex) – Complex number to multiply Hamiltonian before exponentiation.

expectation(state, normalize=False)[source]#

Computes the real expectation value for a given state.

Parameters:

state (ndarray) – state in which to calculate the expectation value.
normalize (bool, optional) – If True, the expectation value \(\ell_{2}\)-normalized. Defaults to False.

Returns:

real number corresponding to the expectation value.

Return type:

expectation_from_samples(freq, qubit_map=None)[source]#

Computes the expectation value of a diagonal observable, given computational-basis measurement frequencies.

Parameters:

freq (collections.Counter) – the keys are the observed values in binary form and the values the corresponding frequencies, that is the number of times each measured value/bitstring appears.
qubit_map (tuple) – Mapping between frequencies and qubits. If None, then defaults to \([1, \, 2, \, \cdots, \, \mathrm{len}(\mathrm{key})]\). Defaults to None.

Returns:

real number corresponding to the expectation value.

Return type:

eye(dim: int | None = None)[source]#: Generate Identity matrix with dimension dim

energy_fluctuation(state)[source]#

Evaluate energy fluctuation:

\[\Xi_{k}(\mu) = \sqrt{\bra{\mu} \, H^{2} \, \ket{\mu} - \bra{\mu} \, H \, \ket{\mu}^2} \, .\]

for a given state \(\ket{\mu}\).

Parameters:: state (ndarray) – quantum state to be used to compute the energy fluctuation.
Returns:: Energy fluctuation value.
Return type:: float

Symbolic Hamiltonian#

Qibo allows the user to define Hamiltonians using sympy symbols. In this case the full Hamiltonian matrix is not constructed unless this is required. This makes the implementation more efficient for larger qubit numbers. For more information on constructing Hamiltonians using symbols we refer to the How to define custom Hamiltonians using symbols? example.

class qibo.hamiltonians.SymbolicHamiltonian(form: Expr, nqubits: int | None = None, backend: Backend | None = None)[source]#

Hamiltonian based on a symbolic representation.

Calculations using symbolic Hamiltonians are either done directly using the given sympy expression as it is (form) or by parsing the corresponding terms (which are qibo.core.terms.SymbolicTerm objects). The latter approach is more computationally costly as it uses a sympy.expand call on the given form before parsing the terms. For this reason the terms are calculated only when needed, for example during Trotterization. The dense matrix of the symbolic Hamiltonian can be calculated directly from form without requiring terms calculation (see qibo.core.hamiltonians.SymbolicHamiltonian.calculate_dense() for details).

Parameters:

form (sympy.Expr) – Hamiltonian form as a sympy.Expr. Ideally the Hamiltonian should be written using Qibo symbols. See How to define custom Hamiltonians using symbols? example for more details.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

property dense: MatrixHamiltonian#: Creates the equivalent Hamiltonian matrix.

property terms#

List of terms of which the Hamiltonian is a sum of.

Terms will be objects of type qibo.core.terms.HamiltonianTerm.

property matrix#

Returns the full matrix representation.

Consisting of \(2^{n} \times 2^{n}`\) elements.

eigenvalues(k=6)[source]#

Computes the eigenvalues for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigvalsh() for more details.

eigenvectors(k=6)[source]#

Computes a tensor with the eigenvectors for the Hamiltonian.

Parameters:: k (int) – Number of eigenvalues to calculate if the Hamiltonian was created using a sparse matrix. This argument is ignored if the Hamiltonian was created using a dense matrix. See qibo.backends.abstract.AbstractBackend.eigh() for more details.

ground_state()[source]#

Computes the ground state of the Hamiltonian.

Uses qibo.hamiltonians.AbstractHamiltonian.eigenvectors() and returns eigenvector corresponding to the lowest energy.

exp(a)[source]#

Computes a tensor corresponding to \(\exp(-i \, a \, H)\).

Parameters:: a (complex) – Complex number to multiply Hamiltonian before exponentiation.

expectation(state, normalize=False)[source]#

Computes the real expectation value for a given state.

Parameters:

state (ndarray) – state in which to calculate the expectation value.
normalize (bool, optional) – If True, the expectation value \(\ell_{2}\)-normalized. Defaults to False.

Returns:

real number corresponding to the expectation value.

Return type:

qibo.hamiltonians.Hamiltonian or qibo.hamiltonians.SymbolicHamiltonian

expectation_from_circuit(circuit: Circuit, nshots: int = 1000) → float[source]#

Calculate the expectation value from a circuit. This even works for observables not completely diagonal in the computational basis, but only diagonal at a term level in a defined basis. Namely, for an observable of the form :math:H = \sum_i H_i, where each :math:H_i consists in a n-qubits pauli operator \(P_0 \otimes P_1 \otimes \cdots \otimes P_n\), the expectation value is computed by rotating the input circuit in the suitable basis for each term :math:H_i thus extracting the term-wise expectations that are then summed to build the global expectation value. Each term of the observable is treated separately, by measuring in the correct basis and re-executing the circuit.

Parameters:

circuit (Circuit) – input circuit.
nshots (int) – number of shots, defaults to 1000.

Returns:

the calculated expectation value.

Return type:

(float)

expectation_from_samples(freq: dict, qubit_map: list = None) → float[source]#

Calculate the expectation value from the samples. The observable has to be diagonal in the computational basis.

Parameters:

freq (dict) – input frequencies of the samples.
qubit_map (list) – qubit map.

Returns:

the calculated expectation value.

Return type:

(float)

apply_gates(state, density_matrix=False)[source]#

Applies gates corresponding to the Hamiltonian terms.

Gates are applied to the given state.

Helper method for qibo.hamiltonians.SymbolicHamiltonian.__matmul__().

circuit(dt, accelerators=None)[source]#

Circuit that implements a Trotter step of this Hamiltonian.

Parameters:

dt (float) – Time step used for Trotterization.
accelerators (dict, optional) – Dictionary with accelerators for distributed circuits. Defaults to None.

When a qibo.hamiltonians.SymbolicHamiltonian is used for time evolution then Qibo will automatically perform this evolution using the Trotter of the evolution operator. This is done by automatically splitting the Hamiltonian to sums of commuting terms, following the description of Sec. 4.1 of arXiv:1901.05824. For more information on time evolution we refer to the How to simulate time evolution? example.

In addition to the abstract Hamiltonian models, Qibo provides the following pre-coded Hamiltonians:

Non-interacting Pauli-X#

class qibo.hamiltonians.X(nqubits, dense: bool = True, backend=None)[source]#

Non-interacting Pauli-\(X\) Hamiltonian.

\[H = - \sum _{k=0}^N \, X_{k} \, .\]

Parameters:

nqubits (int) – number of qubits.
dense (bool, optional) – If True it creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian. Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Non-interacting Pauli-Y#

class qibo.hamiltonians.Y(nqubits, dense: bool = True, backend=None)[source]#

Non-interacting Pauli-\(Y\) Hamiltonian.

\[H = - \sum _{k=0}^{N} \, Y_{k} \, .\]

Parameters:

nqubits (int) – number of qubits.
dense (bool) – If True it creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Non-interacting Pauli-Z#

class qibo.hamiltonians.Z(nqubits, dense: bool = True, backend=None)[source]#

Non-interacting Pauli-\(Z\) Hamiltonian.

\[H = - \sum _{k=0}^{N} \, Z_{k} \, .\]

Parameters:

nqubits (int) – number of qubits.
dense (bool) – If True it creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Transverse field Ising model#

class qibo.hamiltonians.TFIM(nqubits, h: float = 0.0, dense: bool = True, backend=None)[source]#

Transverse field Ising model with periodic boundary conditions.

\[H = - \sum _{k=0}^{N} \, \left(Z_{k} \, Z_{k + 1} + h \, X_{k}\right) \, .\]

Parameters:

nqubits (int) – number of qubits.
h (float, optional) – value of the transverse field. Defaults to \(0.0\).
dense (bool, optional) – If True it creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian. Defaults to True.

Max Cut#

class qibo.hamiltonians.MaxCut(nqubits, dense: bool = True, adj_matrix: list[list[float]] | ndarray | None = None, backend: Backend | None = None)[source]#

Max Cut Hamiltonian.

\[H = -\frac{1}{2} \, \sum _{j, k = 0}^{N} \, \left(1 - Z_{j} \, Z_{k}\right) \, .\]

Parameters:

nqubits (int) – number of qubits.
dense (bool) – If True it creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian.
adj_matrix (list[list[float]] | np.ndarray) – Adjecency matrix of the graph. Defaults to a homogeneous fully connected graph with all edges having an equal 1.0 weight.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Note

All pre-coded Hamiltonians can be created as qibo.hamiltonians.Hamiltonian using dense=True or qibo.hamiltonians.SymbolicHamiltonian using the dense=False. In the first case the Hamiltonian is created using its full matrix representation of size (2 ** n, 2 ** n) where n is the number of qubits that the Hamiltonian acts on. This matrix is used to calculate expectation values by direct matrix multiplication to the state and for time evolution by exact exponentiation. In contrast, when dense=False the Hamiltonian contains a more compact representation as a sum of local terms. This compact representation can be used to calculate expectation values via a sum of the local term expectations and time evolution via the Trotter decomposition of the evolution operator. This is useful for systems that contain many qubits for which constructing the full matrix is intractable.

Heisenberg model#

class qibo.hamiltonians.Heisenberg(nqubits, coupling_constants: float | int | list | tuple, external_field_strengths: float | int, dense: bool = True, backend=None)[source]#

Heisenberg model on a \(1\)-dimensional periodic lattice.

The general \(n\)-qubit Hamiltonian is given by

\[\begin{split}\begin{align} H &= -\sum_{k = 1}^{n} \, \left( J_{x} \, X_{k} \, X_{k + 1} + J_{y} \, Y_{k} \, Y_{k + 1} + J_{z} \, Z_{k} \, Z_{k + 1} \right) \\ &\quad\,\, - \sum_{k = 1}^{n} \left( h_{x} \, X_{k} + h_{y} \, Y_{k} + h_{z} \, Z_{k} \right) \, , \end{align}\end{split}\]

where \(\{J_{x}, \, J_{y}, \, J_{z}\}\) are called the coupling constants, \(\{h_{x}, \, h_{y}, \, h_{z}\}\) are called the external field strengths, and \(\{X, \, Y, \, Z\}\) are the usual Pauli operators.

Parameters:

nqubits (int) – number of qubits.
coupling_constants (list or tuple or float or int) – list or tuple with the three coupling constants \(\{J_{x}, J_{y}, J{z}\}\). If int or float, then \(J_{x} = J_{y} = J_{z}\).
external_field_strength (list or tuple or float or int) – list or tuple with the external magnetic field strengths \(\{h_{x}, \, h_{y}, \, h_{z}\}\). If int or float, then \(h_{x} = h_{y} = h_{z}\).
dense (bool, optional) – If True, creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian. Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Heisenberg Hamiltonian.

Return type:

Heisenberg XXX#

class qibo.hamiltonians.XXX(nqubits, coupling_constant: float | int = 1, external_field_strengths: float | int | list | tuple = [0.5, 0, 0], dense: bool = True, backend=None)[source]#

Heisenberg \(\mathrm{XXX}\) model with periodic boundary conditions.

The \(n\)-qubit \(\mathrm{XXX}\) Hamiltonian is given by

\[H = -J \, \sum_{k = 1}^{n} \, \left( X_{k} \, X_{k + 1} + Y_{k} \, Y_{k + 1} + Z_{k} \, Z_{k + 1} \right) - \sum_{k = 1}^{n} \left(h_{x} \, X_{k} + h_{y} \, Y_{k} + h_{z} \, Z_{k} \right) \, ,\]

where \(J\) is the coupling_constant, \(\{h_{x}, \, h_{y}, \, h_{z}\}\) are called the external field strengths, and \(\{X, \, Y, \, Z\}\) are the usual Pauli operators.

Parameters:

nqubits (int) – number of qubits.
coupling_constant (float or int, optional) – coupling constant \(J\). Defaults to \(1\).
external_field_strengths (float or int or list or tuple, optional) – list or tuple with the external magnetic field strengths \(\{h_{x}, \, h_{y}, \, h_{z}\}\). If int or float, then \(h_{x} = h_{y} = h_{z}\). Defaults to \([1/2, \, 0, \, 0]\).
dense (bool, optional) – If True, creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian. Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Heisenberg \(\mathrm{XXX}\) Hamiltonian.

Return type:

qibo.hamiltonians.Hamiltonian or qibo.hamiltonians.SymbolicHamiltonian

Heisenberg XXZ#

class qibo.hamiltonians.XXZ(nqubits, delta=0.5, dense: bool = True, backend=None)[source]#

Heisenberg \(\mathrm{XXZ}\) model with periodic boundary conditions.

\[H = \sum _{k=0}^N \, \left( X_{k} \, X_{k + 1} + Y_{k} \, Y_{k + 1} + \delta Z_{k} \, Z_{k + 1} \right) \, .\]

Example

from qibo.hamiltonians import XXZ
h = XXZ(3) # initialized XXZ model with 3 qubits

Parameters:

nqubits (int) – number of qubits.
delta (float, optional) – coefficient for the \(Z\) component. Defaults to \(0.5\).
dense (bool, optional) – If True, creates the Hamiltonian as a qibo.core.hamiltonians.Hamiltonian, otherwise it creates a qibo.core.hamiltonians.SymbolicHamiltonian. Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Heisenberg \(\mathrm{XXZ}\) Hamiltonian.

Return type:

qibo.hamiltonians.Hamiltonian or qibo.hamiltonians.SymbolicHamiltonian

Symbols#

Qibo provides a basic set of symbols which inherit the sympy.Symbol object and can be used to construct qibo.hamiltonians.SymbolicHamiltonian objects as described in the previous section.

class qibo.symbols.Symbol(q, matrix, name='Symbol', commutative=False, **assumptions)[source]#

Qibo specialization for sympy symbols.

These symbols can be used to create qibo.hamiltonians.hamiltonians.SymbolicHamiltonian. See How to define custom Hamiltonians using symbols? for more details.

Example

from qibo import hamiltonians
from qibo.symbols import X, Y, Z
# construct a XYZ Hamiltonian on two qubits using Qibo symbols
form = X(0) * X(1) + Y(0) * Y(1) + Z(0) * Z(1)
ham = hamiltonians.SymbolicHamiltonian(form)

Parameters:

q (int) – Target qubit id.
matrix (np.ndarray) – 2x2 matrix represented by this symbol.
name (str) – Name of the symbol which defines how it is represented in symbolic expressions.
commutative (bool) – If True the constructed symbols commute with each other. Default is False. This argument should be used with caution because quantum operators are not commutative objects and therefore switching this to True may lead to wrong results. It is useful for improving performance in symbolic calculations in cases where the user is sure that the operators participating in the Hamiltonian form are commuting (for example when the Hamiltonian consists of Z terms only).

property gate#: Qibo gate that implements the action of the symbol on states.

full_matrix(nqubits)[source]#

Calculates the full dense matrix corresponding to the symbol as part of a bigger system.

Parameters:

nqubits (int) – Total number of qubits in the system.
backend (Backend) – Optional backend to represent the matrix with. By default the global backend is used.

Returns:

Matrix of dimension (2^nqubits, 2^nqubits) composed of the Kronecker product between identities and the symbol’s single-qubit matrix.

class qibo.symbols.I(q, commutative=False, **assumptions)[source]#

Qibo symbol for the identity operator.

Parameters:: q (int) – Target qubit id.

class qibo.symbols.X(q, commutative=False, **assumptions)[source]#

Qibo symbol for the Pauli-X operator.

Parameters:: q (int) – Target qubit id.

class qibo.symbols.Y(q, commutative=False, **assumptions)[source]#

Qibo symbol for the Pauli-X operator.

Parameters:: q (int) – Target qubit id.

class qibo.symbols.Z(q, commutative=False, **assumptions)[source]#

Qibo symbol for the Pauli-X operator.

Parameters:: q (int) – Target qubit id.

Execution Outcomes#

Qibo circuits return different objects when executed depending on what the circuit contains and on the settings of the simulation. The following table summarizes which outcomes to expect depending on whether:

the circuit contains noise channels
the qubits are measured at the end of the execution
some collapse measurement is present in the circuit
density_matrix is set to True in simulation

Noise	Measurements	Collapse	Density Matrix	Outcome
❌	❌	❌	❌ / ✅	`qibo.result.QuantumState`
❌	✅	❌	❌ / ✅	`qibo.result.CircuitResult`
❌ / ✅	❌	❌ / ✅	✅	`qibo.result.QuantumState`
❌ / ✅	✅	❌ / ✅	❌	`qibo.result.MeasurementOutcomes`
❌ / ✅	✅	❌ / ✅	✅	`qibo.result.CircuitResult`

Therefore, one of the three objects qibo.result.QuantumState, qibo.result.MeasurementOutcomes or qibo.result.CircuitResult is going to be returned by the circuit execution. The first gives acces to the final state and probabilities via the qibo.result.QuantumState.state() and qibo.result.QuantumState.probabilities() methods, whereas the second allows to retrieve the final samples, the frequencies and the probabilities (calculated as frequencies/nshots) with the qibo.result.MeasurementOutcomes.samples(), qibo.result.MeasurementOutcomes.frequencies() and qibo.result.MeasurementOutcomes.probabilities() methods respectively. The qibo.result.CircuitResult object includes all the above instead.

Every time some measurement is performed at the end of the execution, the result will be a CircuitResult unless the final state could not be represented with the current simulation settings, i.e. if some stochasticity is present in the ciruit (via noise channels or collapse measurements) and density_matrix=False. In that case a simple MeasurementOutcomes object is returned.

If no measurement is appended at the end of the circuit, the final QuantumState is going to be provided as output. However, if the circuit is stochastic, density_matrix should be set to True in order to recover the final state, otherwise an error is raised.

The final result of the circuit execution can also be saved to disk and loaded back:

circuit = Circuit(2)
circuit.add(gates.M(0,1))
# this will be a CircuitResult object
result = circuit()
# save it to final_result.npy
result.dump('final_result.npy')
# can be loaded back
from qibo.result import load_result

loaded_result = load_result('final_result.npy')

class qibo.result.QuantumState(state, backend=None)[source]#

Data structure to represent the final state after circuit execution.

Parameters:

state (np.ndarray) – Input quantum state as np.ndarray.
backend (qibo.backends.AbstractBackend) – Backend used for the calculations. If not provided, the current backend is going to be used.

symbolic(decimals: int = 5, cutoff: float = 1e-10, max_terms: int = 20)[source]#

Dirac notation representation of the state in the computational basis.

Parameters:

decimals (int, optional) – Number of decimals for the amplitudes. Defaults to \(5\).
cutoff (float, optional) – Amplitudes with absolute value smaller than the cutoff are ignored from the representation. Defaults to 1e-10.
max_terms (int, optional) – Maximum number of terms to print. If the state contains more terms they will be ignored. Defaults to \(20\).

Returns:

A string representing the state in the computational basis.

Return type:

(str)

state(numpy: bool = False)[source]#

State’s tensor representation as a backend tensor.

Parameters:: numpy (bool, optional) – If True the returned tensor will be a numpy array, otherwise it will follow the backend tensor type. Defaults to False.
Returns:: The state in the computational basis.

probabilities(qubits: list | set | None = None)[source]#

Calculates measurement probabilities by tracing out qubits.

When noisy model is applied to a circuit and circuit.density_matrix=False, this method returns the average probability resulting from repeated execution. This probability distribution approximates the exact probability distribution obtained when circuit.density_matrix=True.

Parameters:: qubits (list or set, optional) – Set of qubits that are measured. If None, qubits equates the total number of qubits. Defauts to None.
Returns:: Probabilities over the input qubits.
Return type:: (np.ndarray)

to_dict()[source]#: Returns a dictonary containinig all the information needed to rebuild the QuantumState

dump(filename: str)[source]#

Writes to file the QuantumState for future reloading.

Parameters:: filename (str) – Path to the file to write to.

classmethod from_dict(payload: dict)[source]#

Builds a QuantumState object starting from a dictionary.

Parameters:: payload (dict) – Dictionary containing all the information to load the QuantumState object.
Returns:: Quantum state object..
Return type:: qibo.result.QuantumState

classmethod load(filename: str)[source]#

Builds the QuantumState object stored in a file.

Parameters:: filename (str) – Path to the file containing the QuantumState.
Returns:: Quantum state object.
Return type:: qibo.result.QuantumState

class qibo.result.MeasurementOutcomes(measurements, backend=None, probabilities=None, samples: int | None = None, nshots: int = 1000)[source]#

Object to store the outcomes of measurements after circuit execution.

Parameters:

measurements (qibo.gates.M) – Measurement gates.
backend (qibo.backends.AbstractBackend) – Backend used for the calculations. If None, then the current backend is used. Defaults to None.
probabilities (np.ndarray) – Use these probabilities to generate samples and frequencies.
samples (np.darray) – Use these samples to generate probabilities and frequencies.
nshots (int) – Number of shots used for samples, probabilities and frequencies generation.

frequencies(binary: bool = True, registers: bool = False)[source]#

Returns the frequencies of measured samples.

Parameters:

binary (bool, optional) – If True, returns frequency keys in binary form. If False, returns them in decimal form. Defaults to True.
registers (bool, optional) – Group frequencies according to registers. Defaults to False.

Returns:

A collections.Counter where the keys are the observed values and the values the corresponding frequencies, that is the number of times each measured value/bitstring appears.

If binary is True: the keys of the collections.Counter are in binary form, as strings of \(0\) and :math`1`.
If binary is False: the keys of the collections.Counter are integers.
If registers is True: a dict of collections.Counter is returned where keys are the name of each register.
If registers is False: a single collections.Counter is returned which contains samples from all the measured qubits, independently of their registers.

probabilities(qubits: list | set | None = None)[source]#

Calculate the probabilities as frequencies / nshots

Returns:: The array containing the probabilities of the measured qubits.

has_samples()[source]#

Check whether the samples are available already.

Returns:: True if the samples are available, False otherwise.
Return type:: (bool)

samples(binary: bool = True, registers: bool = False)[source]#

Returns raw measurement samples.

Parameters:

binary (bool, optional) – Return samples in binary or decimal form.
registers (bool, optional) – Group samples according to registers.

Returns:

If binary is True: samples are returned in binary form as a tensor of shape (nshots, n_measured_qubits).
If binary is False: samples are returned in decimal form as a tensor of shape (nshots,).
If registers is True: samples are returned in a dict where the keys are the register names and the values are the samples tensors for each register.
If registers is False: a single tensor is returned which contains samples from all the measured qubits, independently of their registers.

property measurement_gate#

Single measurement gate containing all measured qubits.

Useful for sampling all measured qubits at once when simulating.

apply_bitflips(p0: float, p1: float | None = None)[source]#

Apply bitflips to the measurements with probabilities p0 and p1

Parameters:

p0 (float) – Probability of the 0->1 flip.
p1 (float) – Probability of the 1->0 flip.

expectation_from_samples(observable)[source]#

Computes the real expectation value of a diagonal observable from frequencies.

Parameters:: observable (Hamiltonian/SymbolicHamiltonian) – diagonal observable in the computational basis.
Returns:: expectation value from samples.
Return type:: (float)

to_dict()[source]#: Returns a dictonary containinig all the information needed to rebuild the qibo.result.MeasurementOutcomes.

dump(filename: str)[source]#

Writes to file the qibo.result.MeasurementOutcomes for future reloading.

Parameters:: filename (str) – Path to the file to write to.

classmethod from_dict(payload: dict)[source]#

Builds a qibo.result.MeasurementOutcomes object starting from a dictionary.

Parameters:: payload (dict) – Dictionary containing all the information to load the qibo.result.MeasurementOutcomes object.
Returns:: A qibo.result.MeasurementOutcomes object.

classmethod load(filename: str)[source]#

Builds the qibo.result.MeasurementOutcomes object stored in a file.

Parameters:: filename (str) – Path to the file containing the qibo.result.MeasurementOutcomes.
Returns:: A qibo.result.MeasurementOutcomes object.

class qibo.result.CircuitResult(final_state, measurements, backend=None, samples=None, nshots=1000)[source]#

Object to store both the outcomes of measurements and the final state after circuit execution.

Parameters:

final_state (np.ndarray) – Input quantum state as np.ndarray.
measurements (qibo.gates.M) – The measurement gates containing the measurements.
backend (qibo.backends.AbstractBackend) – Backend used for the calculations. If not provided, then the current backend is going to be used.
probabilities (np.ndarray) – Use these probabilities to generate samples and frequencies.
samples (np.darray) – Use these samples to generate probabilities and frequencies.
nshots (int) – Number of shots used for samples, probabilities and frequencies generation.

probabilities(qubits: list | set | None = None)[source]#

Calculates measurement probabilities by tracing out qubits.

Parameters:: qubits (list or set, optional) – Set of qubits that are measured. If None, qubits equates the total number of qubits. Defauts to None.
Returns:: Probabilities over the input qubits.
Return type:: (np.ndarray)

to_dict()[source]#: Returns a dictonary containinig all the information needed to rebuild the CircuitResult.

classmethod from_dict(payload: dict)[source]#

Builds a CircuitResult object starting from a dictionary.

Parameters:: payload (dict) – Dictionary containing all the information to load the CircuitResult object.
Returns:: circuit result object.
Return type:: qibo.result.CircuitResult

Callbacks#

Callbacks provide a way to calculate quantities on the state vector as it propagates through the circuit. Example of such quantity is the entanglement entropy, which is currently the only callback implemented in qibo.callbacks.EntanglementEntropy. The user can create custom callbacks by inheriting the qibo.callbacks.Callback class. The point each callback is calculated inside the circuit is defined by adding a qibo.gates.CallbackGate. This can be added similarly to a standard gate and does not affect the state vector.

class qibo.callbacks.Callback[source]#

Base callback class.

Results of a callback can be accessed by indexing the corresponding object.

property nqubits#: Total number of qubits in the circuit that the callback was added in.

Entanglement entropy#

class qibo.callbacks.EntanglementEntropy(partition: List[int] | None = None, compute_spectrum: bool = False, base: float = 2, check_hermitian: bool = False)[source]#

Von Neumann entanglement entropy callback.

\[S = \mathrm{Tr} \left ( \rho \log _2 \rho \right )\]

Parameters:

partition (list) – List with qubit ids that defines the first subsystem for the entropy calculation. If partition is not given then the first subsystem is the first half of the qubits.
compute_spectrum (bool) – Compute the entanglement spectrum. Default is False.

Example

from qibo import Circuit, gates
from qibo.callbacks import EntanglementEntropy

# create entropy callback where qubit 0 is the first subsystem
entropy = EntanglementEntropy([0], compute_spectrum=True)
# initialize circuit with 2 qubits and add gates
circuit = Circuit(2)
# add callback gates between normal gates
circuit.add(gates.CallbackGate(entropy))
circuit.add(gates.H(0))
circuit.add(gates.CallbackGate(entropy))
circuit.add(gates.CNOT(0, 1))
circuit.add(gates.CallbackGate(entropy))
# execute the circuit
final_state = circuit()
print(entropy[:])
# Should print [0, 0, 1] which is the entanglement entropy
# after every gate in the calculation.
print(entropy.spectrum)
# Print the entanglement spectrum.

property nqubits#: Total number of qubits in the circuit that the callback was added in.

Norm#

class qibo.callbacks.Norm[source]#: State norm callback.

\[\mathrm{Norm} = \left \langle \Psi | \Psi \right \rangle = \mathrm{Tr} (\rho )\]

Overlap#

class qibo.callbacks.Overlap(state)[source]#

State overlap callback.

Calculates the overlap between the circuit state and a given target state:

\[\mathrm{Overlap} = |\left \langle \Phi | \Psi \right \rangle |\]

Parameters:

state (np.ndarray) – Target state to calculate overlap with.
normalize (bool) – If True the states are normalized for the overlap calculation.

Energy#

class qibo.callbacks.Energy(hamiltonian: hamiltonians.Hamiltonian)[source]#

Energy expectation value callback.

Calculates the expectation value of a given Hamiltonian as:

\[\left \langle H \right \rangle = \left \langle \Psi | H | \Psi \right \rangle = \mathrm{Tr} (\rho H)\]

assuming that the state is normalized.

Parameters:: hamiltonian (qibo.hamiltonians.Hamiltonian) – Hamiltonian object to calculate its expectation value.

Gap#

class qibo.callbacks.Gap(mode: str | int = 'gap', check_degenerate: bool = True)[source]#

Callback for calculating the gap of adiabatic evolution Hamiltonians.

Can also be used to calculate the Hamiltonian eigenvalues at each time step during the evolution. Note that this callback can only be added in qibo.evolution.AdiabaticEvolution models.

Parameters:

mode (str/int) – Defines which quantity this callback calculates. If mode == 'gap' then the difference between ground state and first excited state energy (gap) is calculated. If mode is an integer, then the energy of the corresponding eigenstate is calculated.
check_degenerate (bool) – If True the excited state number is increased until a non-zero gap is found. This is used to find the proper gap in the case of degenerate Hamiltonians. This flag is relevant only if mode is 'gap'. Default is True.

Example

from qibo import callbacks, hamiltonians
from qibo.models import AdiabaticEvolution
# define easy and hard Hamiltonians for adiabatic evolution
h0 = hamiltonians.X(3)
h1 = hamiltonians.TFIM(3, h=1.0)
# define callbacks for logging the ground state, first excited
# and gap energy
ground = callbacks.Gap(0)
excited = callbacks.Gap(1)
gap = callbacks.Gap()
# define and execute the ``AdiabaticEvolution`` model
evolution = AdiabaticEvolution(h0, h1, lambda t: t, dt=1e-1,
                               callbacks=[gap, ground, excited])
final_state = evolution(final_time=1.0)
# print results
print(ground[:])
print(excited[:])
print(gap[:])

Solvers#

Solvers are used to numerically calculate the time evolution of state vectors. They perform steps in time by integrating the time-dependent Schrodinger equation.

class qibo.solvers.BaseSolver(dt, hamiltonian)[source]#

Basic solver that should be inherited by all solvers.

Parameters:

dt (float) – Time step size.
hamiltonian (qibo.hamiltonians.abstract.AbstractHamiltonian) – Hamiltonian object that the state evolves under.

property t#: Solver’s current time.

class qibo.solvers.TrotterizedExponential(dt, hamiltonian)[source]#

Solver that uses Trotterized exponentials.

Created automatically from the qibo.solvers.Exponential if the given Hamiltonian object is a qibo.hamiltonians.hamiltonians.SymbolicHamiltonian.

class qibo.solvers.Exponential(dt, hamiltonian)[source]#

Solver that uses the matrix exponential of the Hamiltonian:

\[U(t) = e^{-i H(t) \delta t}\]

Calculates the evolution operator in every step and thus is compatible with time-dependent Hamiltonians.

class qibo.solvers.RungeKutta4(dt, hamiltonian)[source]#: Solver based on the 4th order Runge-Kutta method.

class qibo.solvers.RungeKutta45(dt, hamiltonian)[source]#: Solver based on the 5th order Runge-Kutta method.

Optimizers#

Optimizers are used automatically by the minimize methods of qibo.models.VQE and qibo.evolution.AdiabaticEvolution models. The user does not have to use any of the optimizer methods included in the current section, however the required options of each optimization method can be passed when calling the minimize method of the respective Qibo variational model.

qibo.optimizers.optimize(loss, initial_parameters, args=(), method='Powell', jac=None, hess=None, hessp=None, bounds=None, constraints=(), tol=None, callback=None, options=None, compile=False, processes=None, backend=None)[source]#

Main optimization method. Selects one of the following optimizers:

qibo.optimizers.cmaes()
qibo.optimizers.newtonian()
qibo.optimizers.sgd()

Parameters:

loss (callable) – Loss as a function of parameters and optional extra arguments. Make sure the loss function returns a tensor for method=sgd and numpy object for all the other methods.
initial_parameters (np.ndarray) – Initial guess for the variational parameters that are optimized.
args (tuple) – optional arguments for the loss function.
method (str) – Name of optimizer to use. Can be 'cma', 'sgd' or one of the Newtonian methods supported by qibo.optimizers.newtonian() and 'parallel_L-BFGS-B'. sgd is only available for backends based on tensorflow.
jac (dict) – Method for computing the gradient vector for scipy optimizers.
hess (dict) – Method for computing the hessian matrix for scipy optimizers.
hessp (callable) – Hessian of objective function times an arbitrary vector for scipy optimizers.
bounds (sequence or Bounds) – Bounds on variables for scipy optimizers.
constraints (dict) – Constraints definition for scipy optimizers.
tol (float) – Tolerance of termination for scipy optimizers.
callback (callable) – Called after each iteration for scipy optimizers.
options (dict) – Dictionary with options. See the specific optimizer bellow for a list of the supported options.
compile (bool) – If True the Tensorflow optimization graph is compiled. This is relevant only for the 'sgd' optimizer.
processes (int) – number of processes when using the parallel BFGS method.

Returns:

Final best loss value; best parameters obtained by the optimizer; extra: optimizer-specific return object. For scipy methods it returns the OptimizeResult, for 'cma' the CMAEvolutionStrategy.result, and for 'sgd' the options used during the optimization.

Return type:

(float, float, custom)

Example

import numpy as np
from qibo import Circuit, gates
from qibo.optimizers import optimize

# create custom loss function
# make sure the return type matches the optimizer requirements.
def myloss(parameters, circuit):
    circuit.set_parameters(parameters)
    return np.square(np.sum(circuit().state())) # returns numpy array

# create circuit ansatz for two qubits
circuit = Circuit(2)
circuit.add(gates.RY(0, theta=0))

# optimize using random initial variational parameters
initial_parameters = np.random.uniform(0, 2, 1)
best, params, extra = optimize(myloss, initial_parameters, args=(circuit))

# set parameters to circuit
circuit.set_parameters(params)

qibo.optimizers.cmaes(loss, initial_parameters, args=(), callback=None, options=None)[source]#

Genetic optimizer based on pycma.

Parameters:

loss (callable) – Loss as a function of variational parameters to be optimized.
initial_parameters (np.ndarray) – Initial guess for the variational parameters.
args (tuple) – optional arguments for the loss function.
callback (list[callable]) – List of callable called after each optimization iteration. According to cma-es implementation take CMAEvolutionStrategy instance as argument. See: https://cma-es.github.io/apidocs-pycma/cma.evolution_strategy.CMAEvolutionStrategy.html.
options (dict) – Dictionary with options accepted by the cma optimizer. The user can use import cma; cma.CMAOptions() to view the available options.

qibo.optimizers.newtonian(loss, initial_parameters, args=(), method='Powell', jac=None, hess=None, hessp=None, bounds=None, constraints=(), tol=None, callback=None, options=None, processes=None, backend=None)[source]#

Newtonian optimization approaches based on scipy.optimize.minimize.

For more details check the scipy documentation.

Note

When using the method parallel_L-BFGS-B the processes option controls the number of processes used by the parallel L-BFGS-B algorithm through the multiprocessing library. By default processes=None, in this case the total number of logical cores are used. Make sure to select the appropriate number of processes for your computer specification, taking in consideration memory and physical cores. In order to obtain optimal results you can control the number of threads used by each process with the qibo.set_threads method. For example, for small-medium size circuits you may benefit from single thread per process, thus set qibo.set_threads(1) before running the optimization.

Parameters:

loss (callable) – Loss as a function of variational parameters to be optimized.
initial_parameters (np.ndarray) – Initial guess for the variational parameters.
args (tuple) – optional arguments for the loss function.
method (str) – Name of method supported by scipy.optimize.minimize and 'parallel_L-BFGS-B' for a parallel version of L-BFGS-B algorithm.
jac (dict) – Method for computing the gradient vector for scipy optimizers.
hess (dict) – Method for computing the hessian matrix for scipy optimizers.
hessp (callable) – Hessian of objective function times an arbitrary vector for scipy optimizers.
bounds (sequence or Bounds) – Bounds on variables for scipy optimizers.
constraints (dict) – Constraints definition for scipy optimizers.
tol (float) – Tolerance of termination for scipy optimizers.
callback (callable) – Called after each iteration for scipy optimizers.
options (dict) – Dictionary with options accepted by scipy.optimize.minimize.
processes (int) – number of processes when using the parallel BFGS method.

qibo.optimizers.sgd(loss, initial_parameters, args=(), callback=None, options=None, compile=False, backend=None)[source]#

Stochastic Gradient Descent (SGD) optimizer using Tensorflow backpropagation.

See tf.keras.Optimizers for a list of the available optimizers for Tensorflow. See torch.optim for a list of the available optimizers for PyTorch.

Parameters:

loss (callable) – Loss as a function of variational parameters to be optimized.
initial_parameters (np.ndarray) – Initial guess for the variational parameters.
args (tuple) – optional arguments for the loss function.
callback (callable) – Called after each iteration.
options (dict) –
Dictionary with options for the SGD optimizer. Supports the following keys:
- 'optimizer' (str, default: 'Adagrad'): Name of optimizer.
- 'learning_rate' (float, default: '1e-3'): Learning rate.
- 'nepochs' (int, default: 1e6): Number of epochs for optimization.
- 'nmessage' (int, default: 1e3): Every how many epochs to print a message of the loss function.

Parameter#

It can be useful to define custom parameters in an optimization context. For example, the rotational angles which encodes information in a Quantum Neural Network are usually built as a combination of features and trainable parameters. For doing this, the qibo.parameter.Parameter class can be used. It allows to define custom parameters which can be inserted into a qibo.models.circuit.Circuit. Moreover, it automatically precomputes the analytical derivative of the parameter function, which can be used to calculate the derivatives of a variational model with respect to its parameters.

qibo.parameter.calculate_derivatives(func)[source]#: Calculates derivatives w.r.t. to all parameters of a target function func.

class qibo.parameter.Parameter(func, trainable=None, features=None)[source]#

Object which allows for variational gate parameters. Several trainable parameters and possibly features are linked through a lambda function which returns the final gate parameter. All possible analytical derivatives of the lambda function are calculated at the object initialisation using Sympy.

Example:

from qibo.parameter import Parameter
param = Parameter(
        lambda x, th1, th2, th3: x**2 * th1 + th2 * th3**2,
        features=[7.0],
        trainable=[1.5, 2.0, 3.0],
    )

partial_derivative = param.get_partial_derivative(3)

param.update_parameters(trainable=[15.0, 10.0, 7.0], feature=[5.0])
param_value = param()

Parameters:

func (function) – lambda function which builds the gate parameter. If both features and trainable parameters compose the function, it must be passed by first providing the features and then the parameters, as described in the code example above.
features (list or np.ndarray) – array containing possible input features x.
trainable (list or np.ndarray) – array with initial trainable parameters theta.

property nparams#: Returns the number of trainable parameters

property nfeat#: Returns the number of features

property ncomponents#: Return the number of elements which compose the Parameter

trainable_parameter_indices(start_index)[source]#: Return list of respective indices of trainable parameters within the larger trainable parameter list of a circuit for example

unaffected_by(trainable_idx)[source]#: Retrieve constant term of lambda function with regard to a specific trainable parameter

partial_derivative(trainable_idx)[source]#: Get derivative w.r.t a trainable parameter

Gradients#

In the context of optimization, particularly when dealing with Quantum Machine Learning problems, it is often necessary to calculate the gradients of functions that are to be minimized (or maximized). Hybrid methods, which are based on the use of classical techniques for the optimization of quantum computation procedures, have been presented in the previous section. This approach is very useful in simulation, but some classical methods cannot be used when using real circuits: for example, in the context of neural networks, the Back-Propagation algorithm is used, where it is necessary to know the value of a target function during the propagation of information within the network. Using a real circuit, we would not be able to access this information without taking a measurement, causing the state of the system to collapse and losing the information accumulated up to that moment. For this reason, in qibo we have also implemented methods for calculating the gradients which can be performed directly on the hardware, such as the Parameter Shift Rule.

qibo.derivative.parameter_shift(circuit, hamiltonian, parameter_index, initial_state=None, scale_factor=1, nshots=None)[source]#

In this method the parameter shift rule (PSR) is implemented. Given a circuit \(U\) and an observable \(H\), the PSR allows to calculate the derivative of the expected value of \(H\) on the final state with respect to a variational parameter of the circuit. There is also the possibility of setting a scale factor. It is useful when a circuit’s parameter is obtained by combination of a variational parameter and an external object, such as a training variable in a Quantum Machine Learning problem. For example, performing a re-uploading strategy to embed some data into a circuit, we apply to the quantum state rotations whose angles are in the form \(\theta^{\prime} = x \, \theta\), where \(\theta\) is a variational parameter, and \(x\) an input variable. The PSR allows to calculate the derivative with respect to \(\theta^{\prime}\). However, if we want to optimize a system with respect to its variational parameters, we need to “free” this procedure from the \(x\) depencency. If the scale_factor is not provided, it is set equal to one and doesn’t affect the calculation. If the PSR is needed to be executed on a real quantum device, it is important to set nshots to some integer value. This enables the execution on the hardware by calling the proper methods.

Parameters:

circuit (qibo.models.circuit.Circuit) – custom quantum circuit.
hamiltonian (qibo.hamiltonians.Hamiltonian) – target observable. if you want to execute on hardware, a symbolic hamiltonian must be provided as follows (example with Pauli-\(Z\) and \(n = 1\)): SymbolicHamiltonian(np.prod([ Z(i) for i in range(1) ])).
parameter_index (int) – the index which identifies the target parameter in the circuit.get_parameters() list.
initial_state (ndarray, optional) – initial state on which the circuit acts. If None, defaults to the zero state \(\ket{\mathbf{0}}\). Defaults to None.
scale_factor (float, optional) – parameter scale factor. Defaults to \(1\).
nshots (int, optional) – number of shots if derivative is evaluated on hardware. If None, the simulation mode is executed. Defaults to None.

Returns:

Value of the derivative of the expectation value of the hamiltonian: with respect to the target variational parameter.

Return type:

Example

import qibo
import numpy as np
from qibo import Circuit, gates, hamiltonians
from qibo.derivative import parameter_shift

# defining an observable
def hamiltonian(nqubits = 1):
    m0 = (1/nqubits)*hamiltonians.Z(nqubits).matrix
    ham = hamiltonians.Hamiltonian(nqubits, m0)

    return ham

# defining a dummy circuit
def circuit(nqubits = 1):
    c = Circuit(nqubits = 1)
    c.add(gates.RY(q = 0, theta = 0))
    c.add(gates.RX(q = 0, theta = 0))
    c.add(gates.M(0))

    return c

# initializing the circuit
c = circuit(nqubits = 1)

# some parameters
test_params = np.random.randn(2)
c.set_parameters(test_params)

test_hamiltonian = hamiltonian()

# running the psr with respect to the two parameters
grad_0 = parameter_shift(circuit=c, hamiltonian=test_hamiltonian, parameter_index=0)
grad_1 = parameter_shift(circuit=c, hamiltonian=test_hamiltonian, parameter_index=1)

qibo.derivative.finite_differences(circuit, hamiltonian, parameter_index, initial_state=None, step_size=1e-07)[source]#

Calculate derivative of the expectation value of hamiltonian on the final state obtained by executing circuit on initial_state with respect to the variational parameter identified by parameter_index in the circuit’s parameters list. This method can be used only in exact simulation mode.

Parameters:

circuit (qibo.models.circuit.Circuit) – custom quantum circuit.
hamiltonian (qibo.hamiltonians.Hamiltonian) – target observable. To execute on hardware, a symbolic hamiltonian must be provided as follows (example with Pauli-\(Z\) and \(n = 1\)): SymbolicHamiltonian(np.prod([ Z(i) for i in range(1) ])).
parameter_index (int) – the index which identifies the target parameter in the qibo.models.Circuit.get_parameters() list.
initial_state (ndarray, optional) – initial state on which the circuit acts. If None, defaults to the zero state \(\ket{\mathbf{0}}\). Defaults to None.
step_size (float, optional) – step size used to evaluate the finite difference. Defaults to \(10^{-7}\).

Returns:

Value of the derivative of the expectation value of the hamiltonian: with respect to the target variational parameter.

Return type:

(qibo.quantum_info.clifford.Clifford)

Quantum Information#

This module provides tools for generation and analysis of quantum (and classical) information.

Basis#

Set of functions related to basis and basis transformations.

Pauli basis#

qibo.quantum_info.pauli_basis(nqubits: int, normalize: bool = False, vectorize: bool = False, sparse: bool = False, order: str | None = None, pauli_order: str = 'IXYZ', backend=None)[source]#

Creates the nqubits-qubit Pauli basis.

Parameters:

nqubits (int) – number of qubits.
normalize (bool, optional) – If True, normalized basis is returned. Defaults to False.
vectorize (bool, optional) – If False, returns a nested array with all Pauli matrices. If True, retuns an array where every row is a vectorized Pauli matrix. Defaults to False.
sparse (bool, optional) – If True, retuns Pauli basis in a sparse representation. Defaults to False.
order (str, optional) – If "row", vectorization of Pauli basis is performed row-wise. If "column", vectorization is performed column-wise. If "system", system-wise vectorization is performed. If vectorization=False, then order=None is forced. Defaults to None.
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to "IXYZ".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

all Pauli matrices forming the basis. If sparse=True: and vectorize=True, tuple is composed of an array of non-zero elements and an array with their row-wise indexes.

Return type:

ndarray or tuple

Computational basis to Pauli basis#

qibo.quantum_info.comp_basis_to_pauli(nqubits: int, normalize: bool = False, sparse: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Unitary matrix \(U\) that converts operators from the Liouville representation in the computational basis to the Pauli-Liouville representation.

The unitary \(U\) is given by

\[U = \sum_{k = 0}^{d^{2} - 1} \, |k)(P_{k}| \,\, ,\]

where \(|P_{k})\) is the vectorization of the \(k\)-th Pauli operator \(P_{k}\), and \(|k)\) is the vectorization of the \(k\)-th computational basis element. For a definition of vectorization, see qibo.quantum_info.vectorization().

Example

from qibo.quantum_info import random_density_matrix, vectorization, comp_basis_to_pauli
nqubits = 2
d = 2**nqubits
rho = random_density_matrix(d)
U_c2p = comp_basis_to_pauli(nqubits)
rho_liouville = vectorization(rho, order="system")
rho_pauli_liouville = U_c2p @ rho_liouville

Parameters:

nqubits (int) – number of qubits.
normalize (bool, optional) – If True, converts to the Pauli basis. Defaults to False.
sparse (bool, optional) – If True, returns unitary matrix in sparse representation. Defaults to False.
order (str, optional) – If "row", vectorization of Pauli basis is performed row-wise. If "column", vectorization is performed column-wise. If "system", system-wise vectorization is performed. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to "IXYZ".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Unitary matrix \(U\). If sparse=True,: tuple is composed of array of non-zero elements and an array with their row-wise indexes.

Return type:

ndarray or tuple

Pauli basis to computational basis#

qibo.quantum_info.pauli_to_comp_basis(nqubits: int, normalize: bool = False, sparse: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Unitary matrix \(U\) that converts operators from the Pauli-Liouville representation to the Liouville representation in the computational basis.

The unitary \(U\) is given by

\[U = \sum_{k = 0}^{d^{2} - 1} \, |P_{k})(b_{k}| \, ,\]

Parameters:

nqubits (int) – number of qubits.
normalize (bool, optional) – If True, converts to the Pauli basis. Defaults to False.
sparse (bool, optional) – If True, returns unitary matrix in sparse representation. Defaults to False.
order (str, optional) – If "row", vectorization of Pauli basis is performed row-wise. If "column", vectorization is performed column-wise. If "system", system-wise vectorization is performed. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to "IXYZ".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Unitary matrix \(U\). If sparse=True,: tuple is composed of array of non-zero elements and an array with their row-wise indexes.

Return type:

ndarray or tuple

Phase-space Representation of Stabilizer States#

A stabilizer state \(\ketbra{\psi}{\psi}\) can be uniquely defined by the set of its stabilizers, i.e. those unitary operators \(U\) that have \(\psi\) as an eigenstate with eigenvalue \(1\). In general, \(n\)-qubit stabilizer states are stabilized by \(d = 2^n\) Pauli operators on said \(n\) qubits. However, it is known that the set of \(d\) Paulis can be generated by only \(n\) unique members of the set. In that case, indeed, the number of operators needed to represent a stabilizer state reduces to \(n\). Each one of these \(n\) Pauli generators takes \(2n + 1\) bits to specify, yielding a \(n(2n+1)\) total number of bits needed. In particular, Aaronson and Gottesman (2004) demonstrated that the application of Clifford gates on stabilizer states can be efficiently simulated in this representation at the cost of storing the generators of the destabilizers, in addition to the stabilizers.

A \(n\)-qubit stabilizer state is uniquely defined by a symplectic matrix of the form

where \((x_{kl},z_{kl})\) are the bits encoding the \(n\)-qubits Pauli generator as

\[P_{k} = \bigotimes_{l=1}^{n} \, i^{x_{kl} \, \oplus \, z_{kl}} \, X_{l}^{x_{kl}} \, Z_{l}^{z_{kl}}.\]

The qibo.quantum_info.clifford.Clifford object is in charge of storing the phase-space representation of a stabilizer state. This object is automatically created after the execution of a Clifford circuit through the qibo.backends.clifford.CliffordBackend, but it can also be created by directly passing a symplectic matrix to the constructor.

The generators of the stabilizers can be extracted with the qibo.quantum_info.clifford.Clifford.generators() method, or the complete set of \(d = 2^{n}\) stabilizers operators can be extracted through the qibo.quantum_info.clifford.Clifford.stabilizers() method.

generators, phases = clifford.generators()
stabilizers = clifford.stabilizers()

The destabilizers can be extracted analogously with qibo.quantum_info.clifford.Clifford.destabilizers().

We provide integration with the stim package. It is possible to run Clifford circuits using stim as an engine:

from qibo.backends import CliffordBackend
from qibo.quantum_info import Clifford, random_clifford

clifford_backend = CliffordBackend(engine="stim")

circuit = random_clifford(nqubits)
result = clifford_backend.execute_circuit(circuit)

## Note that the execution above is equivalent to the one below

result = Clifford.from_circuit(circuit, engine="stim")

Object storing the results of a circuit execution with the qibo.backends.clifford.CliffordBackend.

Parameters:

data (ndarray or qibo.models.circuit.Circuit) – If ndarray, it is the symplectic matrix of the stabilizer state in phase-space representation. If qibo.models.circuit.Circuit, it is a circuit composed only of Clifford gates and computational-basis measurements.
nqubits (int, optional) – number of qubits of the state.
measurements (list, optional) – list of measurements gates qibo.gates.M. Defaults to None.
nshots (int, optional) – number of shots used for sampling the measurements. Defaults to \(1000\).
engine (str, optional) –
engine to use in the execution of the qibo.backends.CliffordBackend. It accepts "numpy", "numba", "cupy", and "stim" (see stim). If None, defaults to the corresponding engine from the current backend. Defaults to None.

classmethod from_circuit(circuit: Circuit, initial_state: ndarray | None = None, nshots: int = 1000, engine: str | None = None)[source]#

Allows to create a qibo.quantum_info.clifford.Clifford object by executing the input circuit.

Parameters:

circuit (qibo.models.circuit.Circuit) – Clifford circuit to run.
initial_state (ndarray, optional) – symplectic matrix of the initial state. If None, defaults to the symplectic matrix of the zero state. Defaults to None.
nshots (int, optional) – number of measurement shots to perform if circuit has measurement gates. Defaults to \(10^{3}\).
engine (str, optional) –
engine to use in the execution of the qibo.backends.CliffordBackend. It accepts "numpy", "numba", "cupy", and "stim" (see stim). If None, defaults to the corresponding engine from the current backend. Defaults to None.

Returns:

Object storing the result of the circuit execution.

Return type:

to_circuit(algorithm: str | None = 'AG04')[source]#

Converts symplectic matrix into a Clifford circuit.

Parameters:: algorithm (str, optional) – If AG04, uses the decomposition algorithm from Aaronson & Gottesman (2004). If BM20 and Clifford.nqubits <= 3, uses the decomposition algorithm from Bravyi & Maslov (2020). Defaults to AG04.
Returns:: circuit composed of Clifford gates.
Return type:: qibo.models.circuit.Circuit

generators(return_array: bool = False)[source]#

Extracts the generators of stabilizers and destabilizers.

Parameters:: return_array (bool, optional) – If True returns the generators as ndarray. If False, their representation as strings is returned. Defaults to False.
Returns:: Generators and their corresponding phases, respectively.
Return type:: (list, list)

stabilizers(symplectic: bool = False, return_array: bool = False)[source]#

Extracts the stabilizers of the state.

Parameters:

symplectic (bool, optional) – If True, returns the rows of the symplectic matrix that correspond to the \(n\) generators of the \(2^{n}\) total stabilizers, independently of return_array.
return_array (bool, optional) – To be used when symplectic = False. If True returns the stabilizers as ndarray. If False, returns stabilizers as strings. Defaults to False.

Returns:

Stabilizers of the state.

Return type:

(ndarray or list)

destabilizers(symplectic: bool = False, return_array: bool = False)[source]#

Extracts the destabilizers of the state.

Parameters:

symplectic (bool, optional) – If True, returns the rows of the symplectic matrix that correspond to the \(n\) generators of the \(2^{n}\) total destabilizers, independently of return_array.
return_array (bool, optional) – To be used when symplectic = False. If True returns the destabilizers as ndarray. If False, their representation as strings is returned. Defaults to False.

Returns:

Destabilizers of the state.

Return type:

(ndarray or list)

state()[source]#

Builds the density matrix representation of the state.

Note

This method is inefficient in runtime and memory for a large number of qubits.

Returns:: Density matrix of the state.
Return type:: (ndarray)

property measurement_gate#

Single measurement gate containing all measured qubits.

Useful for sampling all measured qubits at once when simulating.

samples(binary: bool = True, registers: bool = False)[source]#

Returns raw measurement samples.

Parameters:

binary (bool, optional) – If False, return samples in binary form. If True, returns samples in decimal form. Defalts to True.
registers (bool, optional) – If True, groups samples according to registers. Defaults to False.

Returns:

If binary is True: samples are returned in binary form as a tensor of shape (nshots, n_measured_qubits).
If binary is False: samples are returned in decimal form as a tensor of shape (nshots,).
If registers is True: samples are returned in a dict where the keys are the register names and the values are the samples tensors for each register.
If registers is False: a single tensor is returned which contains samples from all the measured qubits, independently of their registers.

frequencies(binary: bool = True, registers: bool = False)[source]#

Returns the frequencies of measured samples.

Parameters:

binary (bool, optional) – If True, return frequency keys in binary form. If False, return frequency keys in decimal form. Defaults to True.
registers (bool, optional) – If True, groups frequencies according to registers. Defaults to False.

Returns:

A collections.Counter where the keys are the observed values and the values the corresponding frequencies, that is the number of times each measured value/bitstring appears.

If binary is True: the keys of the collections.Counter are in binary form, as strings of \(0\) and :math`1`.
If binary is False: the keys of the collections.Counter are integers.
If registers is True: a dict of collections.Counter is returned where keys are the name of each register.
If registers is False: a single collections.Counter is returned which contains samples from all the measured qubits, independently of their registers.

probabilities(qubits: tuple | list | None = None)[source]#

Computes the probabilities of the selected qubits from the measured samples.

Parameters:: qubits (tuple or list, optional) – Qubits for which to compute the probabilities.
Returns:: Measured probabilities.
Return type:: (ndarray)

copy(deep: bool = False)[source]#

Returns copy of qibo.quantum_info.clifford.Clifford object.

Parameters:: deep (bool, optional) – If True, creates another copy in memory. Defaults to False.
Returns:: copy of original Clifford object.
Return type:: qibo.quantum_info.clifford.Clifford

Entanglement measures#

Set of functions to calculate entanglement measures.

Concurrence#

qibo.quantum_info.concurrence(state, bipartition, check_purity: bool = True, backend=None)[source]#

Calculates concurrence of a pure bipartite quantum state \(\rho \in \mathcal{H}_{A} \otimes \mathcal{H}_{B}\) as

\[C(\rho) = \sqrt{2 \, (\text{tr}^{2}(\rho) - \text{tr}(\rho_{A}^{2}))} \, ,\]

where \(\rho_{A} = \text{tr}_{B}(\rho)\) is the reduced density operator obtained by tracing out the qubits in the bipartition \(B\).

Parameters:

state (ndarray) – statevector or density matrix.
bipartition (list or tuple or ndarray) – qubits in the subsystem to be traced out.
check_purity (bool, optional) – if True, checks if state is pure. If False, it assumes state is pure . Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Concurrence of \(\rho\).

Return type:

Entanglement of formation#

qibo.quantum_info.entanglement_of_formation(state, bipartition, base: float = 2, check_purity: bool = True, backend=None)[source]#

Calculates the entanglement of formation \(E_{f}\) of a pure bipartite quantum state \(\rho\), which is given by

\[E_{f} = H([1 - x, x]) \, ,\]

where

\[x = \frac{1 + \sqrt{1 - C^{2}(\rho)}}{2} \, ,\]

\(C(\rho)\) is the qibo.quantum_info.concurrence() of \(\rho\), and \(H\) is the qibo.quantum_info.entropies.shannon_entropy().

Parameters:

state (ndarray) – statevector or density matrix.
bipartition (list or tuple or ndarray) – qubits in the subsystem to be traced out.
base (float) – the base of the log in qibo.quantum_info.entropies.shannon_entropy(). Defaults to \(2\).
check_purity (bool, optional) – if True, checks if state is pure. If False, it assumes state is pure . Default: True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

entanglement of formation of state \(\rho\).

Return type:

Negativity#

qibo.quantum_info.negativity(state, bipartition, backend=None)[source]#

Calculates the negativity of a bipartite quantum state.

Given a bipartite state \(\rho \in \mathcal{H}_{A} \otimes \mathcal{H}_{B}\), the negativity \(\operatorname{Neg}(\rho)\) is given by

\[\operatorname{Neg}(\rho) = \frac{1}{2} \, \left( \norm{\rho_{B}}_{1} - 1 \right) \, ,\]

where \(\rho_{B}\) is the reduced density matrix after tracing out qubits in partition \(A\), and \(\norm{\cdot}_{1}\) is the Schatten \(1\)-norm (also known as nuclear norm or trace norm).

Parameters:

state (ndarray) – statevector or density matrix.
bipartition (list or tuple or ndarray) – qubits in the subsystem to be traced out.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses it uses the current backend. Defaults to None.

Returns:

Negativity \(\operatorname{Neg}(\rho)\) of state \(\rho\).

Return type:

Entanglement fidelity#

qibo.quantum_info.entanglement_fidelity(channel, nqubits: int, state=None, check_hermitian: bool = False, backend=None)[source]#

Entanglement fidelity \(F_{\mathcal{E}}\) of a channel \(\mathcal{E}\) on state \(\rho\) is given by

\[F_{\mathcal{E}}(\rho) = F(\rho_{f}, \rho)\]

where \(F\) is the qibo.quantum_info.fidelity() function for states, and \(\rho_{f} = \mathcal{E}_{A} \otimes I_{B}(\rho)\) is the state after the channel \(\mathcal{E}\) was applied to partition \(A\).

Parameters:

channel (qibo.gates.channels.Channel) – quantum channel acting on partition \(A\).
nqubits (int) – total number of qubits in state.
state (ndarray, optional) – statevector or density matrix to be evolved by channel. If None, defaults to the maximally entangled state \(\frac{1}{2^{n}} \, \sum_{k} \, \ket{k}\ket{k}\), where \(n\) is nqubits. Defaults to None.
check_hermitian (bool, optional) – if True, checks if the final state \(\rho_{f}\) is Hermitian. If False, it assumes it is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Entanglement fidelity \(F_{\mathcal{E}}\).

Return type:

Meyer-Wallach entanglement#

qibo.quantum_info.meyer_wallach_entanglement(state, backend=None)[source]#

Compute the Meyer-Wallach entanglement \(Q\) of a state,

\[Q(\rho) = 2\left(1 - \frac{1}{N} \, \sum_{k} \, \text{tr}\left(\rho_{k}^{2}\right)\right) \, ,\]

where \(\rho_{k}^{2}\) is the reduced density matrix of qubit \(k\), and \(N\) is the total number of qubits in state. We use the definition of the Meyer-Wallach entanglement as the average purity proposed in Brennen (2003), which is equivalent to the definition introduced in Meyer and Wallach (2002).

Parameters:

state (ndarray) – statevector or density matrix.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Meyer-Wallach entanglement \(Q\).

Return type:

References

1. G. K. Brennen, An observable measure of entanglement for pure states of multi-qubit systems, Quantum Information and Computation, vol. 3 (6), 619-626 (2003).

2. D. A. Meyer and N. R. Wallach, Global entanglement in multiparticle systems, J. Math. Phys. 43, 4273–4278 (2002).

Entanglement capability#

qibo.quantum_info.entangling_capability(circuit, samples: int, seed=None, backend=None)[source]#

Return the entangling capability \(\text{Ent}\) of a parametrized circuit.

It is defined as the average Meyer-Wallach entanglement \(Q\) (qibo.quantum_info.meyer_wallach_entanglement()) of the circuit, i.e.

\[\text{Ent} = \frac{2}{|\mathcal{S}|}\sum_{\theta_{k} \in \mathcal{S}} \, Q(\rho_{k}) \, ,\]

where \(\mathcal{S}\) is the set of sampled circuit parameters, and \(\rho_{k}\) is the state prepared by the circuit with uniformily-sampled parameters \(\theta_{k}\).

Note

Currently, function does not work with circuit that contains noisy channels.

Parameters:

circuit (qibo.models.Circuit) – Parametrized circuit.
samples (int) – number of sampled circuit parameter vectors \(|S|\)
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Entangling capability \(\text{Ent}\).

Return type:

Entropy measures#

Set of functions to calculate entropy measures.

Shannon entropy#

qibo.quantum_info.shannon_entropy(prob_dist, base: float = 2, backend=None)[source]#

Calculate the Shannon entropy of a probability array \(\mathbf{p}\), which is given by

\[H(\mathbf{p}) = - \sum_{k = 0}^{d^{2} - 1} \, p_{k} \, \log_{b}(p_{k}) \, ,\]

where \(d = \text{dim}(\mathcal{H})\) is the dimension of the Hilbert space \(\mathcal{H}\), \(b\) is the log base (default 2), and \(0 \log_{b}(0) \equiv 0\).

Parameters:

prob_dist (ndarray or list) – a probability array \(\mathbf{p}\).
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Shannon entropy \(H(\mathcal{p})\).

Return type:

Classical relative entropy#

qibo.quantum_info.classical_relative_entropy(prob_dist_p, prob_dist_q, base: float = 2, backend=None)[source]#

Calculates the relative entropy between two discrete probability distributions.

For probabilities \(\mathbf{p}\) and \(\mathbf{q}\), it is defined as

\[D(\mathbf{p} \, \| \, \mathbf{q}) = \sum_{x} \, \mathbf{p}(x) \, \log\left( \frac{\mathbf{p}(x)}{\mathbf{q}(x)} \right) \, .\]

The classical relative entropy is also known as the Kullback-Leibler (KL) divergence.

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Classical relative entropy between \(\mathbf{p}\) and \(\mathbf{q}\).

Return type:

Classical mutual information#

qibo.quantum_info.classical_mutual_information(prob_dist_joint, prob_dist_p, prob_dist_q, base: float = 2, backend=None)[source]#

Calculates the classical mutual information of two random variables.

Given two random variables \((X, \, Y)\), their mutual information is given by

\[I(X, \, Y) \equiv H(p(x)) + H(q(y)) - H(p(x, \, y)) \, ,\]

where \(p(x, \, y)\) is the joint probability distribution of \((X, Y)\), \(p(x)\) is the marginal probability distribution of \(X\), \(q(y)\) is the marginal probability distribution of \(Y\), and \(H(\cdot)\) is the qibo.quantum_info.entropies.shannon_entropy().

Parameters:

prob_dist_joint (ndarray) – joint probability distribution \(p(x, \, y)\).
prob_dist_p (ndarray) – marginal probability distribution \(p(x)\).
prob_dist_q (ndarray) – marginal probability distribution \(q(y)\).
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Mutual information \(I(X, \, Y)\).

Return type:

Classical Rényi entropy#

qibo.quantum_info.classical_renyi_entropy(prob_dist, alpha: float | int, base: float = 2, backend=None)[source]#

Calculates the classical Rényi entropy \(H_{\alpha}\) of a discrete probability distribution.

For \(\alpha \in (0, \, 1) \cup (1, \, \infty)\) and probability distribution \(\mathbf{p}\), the classical Rényi entropy is defined as

\[H_{\alpha}(\mathbf{p}) = \frac{1}{1 - \alpha} \, \log\left( \sum_{x} \, \mathbf{p}^{\alpha}(x) \right) \, .\]

A special case is the limit \(\alpha \to 1\), in which the classical Rényi entropy coincides with the qibo.quantum_info.entropies.shannon_entropy().

Another special case is the limit \(\alpha \to 0\), where the function is reduced to \(\log\left(|\mathbf{p}|\right)\), with \(|\mathbf{p}|\) being the support of \(\mathbf{p}\). This is known as the Hartley entropy (also known as Hartley function or max-entropy).

In the limit \(\alpha \to \infty\), the function reduces to \(-\log(\max_{x}(\mathbf{p}(x)))\), which is called the min-entropy.

Parameters:

prob_dist (ndarray) – discrete probability distribution.
alpha (float or int) – order of the Rényi entropy.
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Classical Rényi entropy \(H_{\alpha}\).

Return type:

Classical Rényi relative entropy#

qibo.quantum_info.classical_relative_renyi_entropy(prob_dist_p, prob_dist_q, alpha: float | int, base: float = 2, backend=None)[source]#

Calculates the classical relative Rényi entropy between two discrete probability distributions.

This function is also known as Rényi divergence.

For \(\alpha \in (0, \, 1) \cup (1, \, \infty)\) and probability distributions \(\mathbf{p}\) and \(\mathbf{q}\), the classical relative Rényi entropy is defined as

\[H_{\alpha}(\mathbf{p} \, \| \, \mathbf{q}) = \frac{1}{\alpha - 1} \, \log\left( \sum_{x} \, \frac{\mathbf{p}^{\alpha}(x)} {\mathbf{q}^{\alpha - 1}(x)} \right) \, .\]

A special case is the limit \(\alpha \to 1\), in which the classical Rényi divergence coincides with the qibo.quantum_info.entropies.classical_relative_entropy().

Another special case is the limit \(\alpha \to 1/2\), where the function is reduced to \(-2 \log\left(\sum_{x} \, \sqrt{\mathbf{p}(x) \, \mathbf{q}(x)} \right)\). The sum inside the \(\log\) is known as the Bhattacharyya coefficient.

In the limit \(\alpha \to \infty\), the function reduces to \(\log(\max_{x}(\mathbf{p}(x) \, \mathbf{q}(x))\).

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
alpha (float or int) – order of the Rényi entropy.
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Classical relative Rényi entropy \(H_{\alpha}(\mathbf{p} \, \| \, \mathbf{q})\).

Return type:

Classical Tsallis entropy#

qibo.quantum_info.classical_tsallis_entropy(prob_dist, alpha: float, base: float = 2, backend=None)[source]#

Calculates the classical Tsallis entropy for a discrete probability distribution.

This is defined as

\[S_{\alpha}(\mathbf{p}) = \frac{1}{\alpha - 1} \, \left(1 - \sum_{x} \, \mathbf{p}^{\alpha}(x) \right)\]

Parameters:

prob_dist (ndarray) – discrete probability distribution.
alpha (float or int) – entropic index.
base (float) – the base of the log. Used when alpha=1.0. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Classical Tsallis entropy \(S_{\alpha}(\mathbf{p})\).

Return type:

Classical Tsallis relative entropy#

qibo.quantum_info.classical_relative_tsallis_entropy(prob_dist_p, prob_dist_q, alpha: float, base: float = 2, backend=None)[source]#

Calculate the classical relative Tsallis entropy between two discrete probability distributions.

Given a discrete random variable \(\chi\) that has values \(x\) in the set \(\mathcal{X}\) with probability \(\mathrm{p}(x)\) and a discrete random variable \(\upsilon\) that has the values \(x\) in the same set \(\mathcal{X}\) with probability \(\mathrm{q}(x)\), their relative Tsallis entropy is given by

\[D_{\alpha}^{\text{ts}}(\chi \, \| \, \upsilon) = \sum_{x \in \mathcal{X}} \, \mathrm{p}^{\alpha}(x) \, \ln_{\alpha} \left( \frac{\mathrm{p}(x)}{\mathrm{q}(x)} \right) \, ,\]

where \(\ln_{\alpha}(x) \equiv \frac{x^{1 - \alpha} - 1}{1 - \alpha}\) is the so-called \(\alpha\)-logarithm. When \(\alpha = 1\), it reduces to qibo.quantum_info.entropies.classical_relative_entropy.

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
alpha (float) – entropic index.
base (float) – the base of the log used when \(\alpha = 1\). Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Tsallis relative entropy \(D_{\alpha}^{\text{ts}}\).

Return type:

von Neumann entropy#

qibo.quantum_info.von_neumann_entropy(state, base: float = 2, check_hermitian: bool = False, return_spectrum: bool = False, backend=None)[source]#

Calculates the von-Neumann entropy \(S(\rho)\) of a quantum state \(\rho\).

It is given by

\[S(\rho) = - \text{tr}\left[\rho \, \log(\rho)\right]\]

Parameters:

state (ndarray) – statevector or density matrix.
base (float, optional) – the base of the log. Defaults to \(2\).
check_hermitian (bool, optional) – if True, checks if state is Hermitian. If False, it assumes state is Hermitian . Defaults to False.
return_spectrum – if True, returns entropy and \(-\log_{\textup{b}}(\textup{eigenvalues})\), where \(b\) is base. If False, returns only entropy. Default is False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

The von-Neumann entropy \(S\) of state \(\rho\).

Return type:

Note

check_hermitian flag allows the user to choose if the function will check if input state is Hermitian or not. Default option is check_hermitian=False, i.e. the assumption of Hermiticity. This is faster and, more importantly, this function are intended to be used on Hermitian inputs. When check_hermitian=True and state is non-Hermitian, an error will be raised when using cupy backend.

Relative von Neumann entropy#

qibo.quantum_info.relative_von_neumann_entropy(state, target, base: float = 2, check_hermitian: bool = False, precision_tol: float = 1e-14, backend=None)[source]#

Calculates the relative von Neumann entropy between two quantum states.

Also known as quantum relative entropy, \(S(\rho \, \| \, \sigma)\) is given by

\[S(\rho \, \| \, \sigma) = \text{tr}\left[\rho \, \log(\rho)\right] - \text{tr}\left[\rho \, \log(\sigma)\right]\]

where state \(\rho\) and target \(\sigma\) are two quantum states.

Parameters:

state (ndarray) – statevector or density matrix \(\rho\).
target (ndarray) – statevector or density matrix \(\sigma\).
base (float, optional) – the base of the log. Defaults to \(2\).
check_hermitian (bool, optional) – If True, checks if state is Hermitian. If False, it assumes state is Hermitian . Defaults to False.
precision_tol (float, optional) – Used when entropy is calculated via engenvalue decomposition. Eigenvalues that are smaller than precision_tol in absolute value are set to \(0\). Defaults to \(10^{-14}\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Relative (von-Neumann) entropy \(S(\rho \, \| \, \sigma)\).

Return type:

Note

check_hermitian flag allows the user to choose if the function will check if input state is Hermitian or not. Default option is check_hermitian=False, i.e. the assumption of Hermiticity. This is faster and, more importantly, this function are intended to be used on Hermitian inputs. When check_hermitian=True and either state or target is non-Hermitian, an error will be raised when using cupy backend.

Mutual information#

qibo.quantum_info.mutual_information(state, partition, base: float = 2, check_hermitian: bool = False, backend=None)[source]#

Calculates the mutual information of a bipartite state.

Given a qubit partition \(A\), the mutual information of state \(\rho\) is given by

\[I(\rho) \equiv S(\rho_{A}) + S(\rho_{B}) - S(\rho) \, ,\]

where \(B\) is the remaining qubits that are not in partition \(A\), and \(S(\cdot)\) is the qibo.quantum_info.von_neumann_entropy().

Parameters:

state (ndarray) – statevector or density matrix.
partition (Union[List[int], Tuple[int]]) – indices of qubits in partition \(A\).
base (float, optional) – the base of the log. Defaults to \(2\).
check_hermitian (bool, optional) – if True, checks if state is Hermitian. If False, it assumes state is Hermitian . Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Mutual information \(I(\rho)\) of state \(\rho\).

Return type:

Rényi entropy#

qibo.quantum_info.renyi_entropy(state, alpha: float | int, base: float = 2, backend=None)[source]#

Calculates the Rényi entropy \(H_{\alpha}\) of a quantum state \(\rho\).

For \(\alpha \in (0, \, 1) \cup (1, \, \infty)\), the Rényi entropy is defined as

\[H_{\alpha}(\rho) = \frac{1}{1 - \alpha} \, \log\left( \rho^{\alpha} \right) \, .\]

A special case is the limit \(\alpha \to 1\), in which the Rényi entropy coincides with the qibo.quantum_info.entropies.entropy().

Another special case is the limit \(\alpha \to 0\), where the function is reduced to \(\log\left(d\right)\), with \(d = 2^{n}\) being the dimension of the Hilbert space in which state \(\rho\) lives in. This is known as the Hartley entropy (also known as Hartley function or max-entropy).

In the limit \(\alpha \to \infty\), the function reduces to \(-\log(\|\rho\|_{\infty})\), with \(\|\cdot\|_{\infty}\) being the spectral norm. This is known as the min-entropy.

Parameters:

state (ndarray) – statevector or density matrix.
alpha (float or int) – order of the Rényi entropy.
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Rényi entropy \(H_{\alpha}\).

Return type:

Relative Rényi entropy#

qibo.quantum_info.relative_renyi_entropy(state, target, alpha: float | int, base: float = 2, backend=None)[source]#

Calculates the relative Rényi entropy between two quantum states.

For \(\alpha \in (0, \, 1) \cup (1, \, \infty)\) and quantum states \(\rho\) and \(\sigma\), the relative Rényi entropy is defined as

\[H_{\alpha}(\rho \, \| \, \sigma) = \frac{1}{\alpha - 1} \, \log\left( \textup{tr}\left( \rho^{\alpha} \, \sigma^{1 - \alpha} \right) \right) \, .\]

A special case is the limit \(\alpha \to 1\), in which the Rényi entropy coincides with the qibo.quantum_info.entropies.relative_von_neumann_entropy().

In the limit \(\alpha \to \infty\), the function reduces to \(-2 \, \log(\|\sqrt{\rho} \, \sqrt{\sigma}\|_{1})\), with \(\|\cdot\|_{1}\) being the Schatten 1-norm. This is known as the min-relative entropy.

Note

Function raises NotImplementedError when target \(\sigma\) is a pure state and \(\alpha > 1\). This is due to the fact that it is not possible to calculate \(\sigma^{1 - \alpha}\) when \(\alpha > 1\) and \(\sigma\) is a projector, i.e. a singular matrix.

Parameters:

state (ndarray) – statevector or density matrix \(\rho\).
target (ndarray) – statevector or density matrix \(\sigma\).
alpha (float or int) – order of the Rényi entropy.
base (float) – the base of the log. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Relative Rényi entropy \(H_{\alpha}(\rho \, \| \, \sigma)\).

Return type:

Tsallis entropy#

qibo.quantum_info.tsallis_entropy(state, alpha: float, base: float = 2, backend=None)[source]#

Calculates the Tsallis entropy of a quantum state.

\[S_{\alpha}(\rho) = \frac{1}{1 - \alpha} \, \left( \text{tr}(\rho^{\alpha}) - 1 \right)\]

When \(\alpha = 1\), the functions defaults to qibo.quantum_info.entropies.entropy().

Parameters:

state (ndarray) – statevector or density matrix.
alpha (float or int) – entropic index.
base (float, optional) – the base of the log. Used when alpha=1.0. Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Tsallis entropy \(S_{\alpha}(\rho)\).

Return type:

Relative Tsallis entropy#

qibo.quantum_info.relative_tsallis_entropy(state, target, alpha: float | int, base: float = 2, check_hermitian: bool = False, backend=None)[source]#

Calculate the relative Tsallis entropy between two quantum states.

For \(\alpha \in [0, \, 2]\) and quantum states \(\rho\) and \(\sigma\), the relative Tsallis entropy is defined as

\[\Delta_{\alpha}^{\text{ts}}(\rho, \, \sigma) = \frac{1 - \text{tr}\left(\rho^{\alpha} \, \sigma^{1 - \alpha}\right)}{1 - \alpha} \, .\]

A special case is the limit \(\alpha \to 1\), in which the Tsallis entropy coincides with the qibo.quantum_info.entropies.relative_von_neumann_entropy().

Parameters:

state (ndarray) – statevector or density matrix \(\rho\).
target (ndarray) – statevector or density matrix \(\sigma\).
alpha (float or int) – entropic index \(\alpha \in [0, \, 2]\).
base (float, optional) – the base of the log used when \(\alpha = 1\). Defaults to \(2\).
check_hermitian (bool, optional) – Used when \(\alpha = 1\). If True, checks if state is Hermitian. If False, it assumes state is Hermitian . Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses qibo.backends.GlobalBackend. Defaults to None.

Returns:

Relative Tsallis entropy \(\Delta_{\alpha}^{\text{ts}}\).

Return type:

References

1. S. Abe, Nonadditive generalization of the quantum Kullback-Leibler divergence for measuring the degree of purification, Phys. Rev. A 68, 032302.

2. S. Furuichi, K. Yanagi, and K. Kuriyama, Fundamental properties of Tsallis relative entropy, J. Math. Phys., Vol. 45, Issue 12, pp. 4868-4877 (2004) .

Entanglement entropy#

qibo.quantum_info.entanglement_entropy(state, bipartition, base: float = 2, check_hermitian: bool = False, return_spectrum: bool = False, backend=None)[source]#

Calculates the entanglement entropy \(S\) of bipartition \(A\) of state \(\rho\). This is given by

\[S(\rho_{A}) = -\text{tr}(\rho_{A} \, \log(\rho_{A})) \, ,\]

where \(\rho_{A} = \text{tr}_{B}(\rho)\) is the reduced density matrix calculated by tracing out the bipartition \(B\).

Parameters:

state (ndarray) – statevector or density matrix.
bipartition (list or tuple or ndarray) – qubits in the subsystem to be traced out.
base (float, optional) – the base of the log. Defaults to :math: 2.
check_hermitian (bool, optional) – if True, checks if \(\rho_{A}\) is Hermitian. If False, it assumes state is Hermitian . Default: False.
return_spectrum – if True, returns entropy and eigenvalues of state. If False, returns only entropy. Default is False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Entanglement entropy \(S\) of state \(\rho\).

Return type:

Note

check_hermitian flag allows the user to choose if the function will check if the reduced density matrix resulting from tracing out bipartition from input state is Hermitian or not. Default option is check_hermitian=False, i.e. the assumption of Hermiticity. This is faster and, more importantly, this function are intended to be used on Hermitian inputs. When check_hermitian=True and the reduced density matrix is non-Hermitian, an error will be raised when using cupy backend.

Metrics#

Set of functions that are used to calculate metrics of states, (pseudo-)distance measures between states, and distance measures between quantum channels.

Purity#

qibo.quantum_info.purity(state, backend=None)[source]#

Purity of a quantum state \(\rho\).

This is given by

\[\text{purity}(\rho) = \text{tr}(\rho^{2}) \, .\]

Parameters:: state (ndarray) – statevector or density matrix.
Returns:: Purity of quantum state \(\rho\).
Return type:: float

Impurity#

qibo.quantum_info.impurity(state, backend=None)[source]#

Impurity of quantum state \(\rho\).

This is given by \(1 - \text{purity}(\rho)\), where \(\text{purity}\) is defined in qibo.quantum_info.purity().

Parameters:: state (ndarray) – statevector or density matrix.
Returns:: impurity of state \(\rho\).
Return type:: float

Trace distance#

qibo.quantum_info.trace_distance(state, target, check_hermitian: bool = False, backend=None)[source]#

Trace distance between two quantum states, \(\rho\) and \(\sigma\):

\[T(\rho, \sigma) = \frac{1}{2} \, \|\rho - \sigma\|_{1} = \frac{1}{2} \, \text{tr}\left[ \sqrt{(\rho - \sigma)^{\dagger}(\rho - \sigma)} \right] \, ,\]

where \(\|\cdot\|_{1}\) is the Schatten 1-norm.

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
check_hermitian (bool, optional) – if True, checks if \(\rho - \sigma\) is Hermitian. If False, it assumes the difference is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Trace distance between state \(\rho\) and target \(\sigma\).

Return type:

Note

check_hermitian flag allows the user to choose if the function will check if difference between inputs, state - target, is Hermitian or not. Default option is check_hermitian=False, i.e. the assumption of Hermiticity, because it is faster and, more importantly, the functions are intended to be used on Hermitian inputs. When check_hermitian=True and state - target is non-Hermitian, an error will be raised when using cupy backend.

Hilbert-Schmidt inner product#

qibo.quantum_info.hilbert_schmidt_inner_product(operator_A, operator_B, backend=None)[source]#

Calculate the Hilbert-Schmidt inner product between two operators.

Given two operators \(A, \, B \in \mathcal{H}\), the Hilbert-Schmidt inner product between the two is given by

\[\braket{A, \, B}_{\text{HS}} = \text{tr}\left(A^{\dagger} \, B\right) \, .\]

Parameters:

operator_A (ndarray) – operator \(A\).
operator_B (ndarray) – operator \(B\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hilbert-Schmidt inner product \(\braket{A, \, B}_{\text{HS}}\).

Return type:

Hilbert-Schmidt distance#

qibo.quantum_info.hilbert_schmidt_distance(state, target, backend=None)[source]#

Calculate the Hilbert-Schmidt distance between two quantum states:

\[\braket{\rho - \sigma, \, \rho - \sigma}_{\text{HS}} = \text{tr}\left((\rho - \sigma)^{2}\right) \, ,\]

where \(\braket{\cdot, \, \cdot}_{\text{HS}}\) is the qibo.quantum_info.hilbert_schmidt_inner_product().

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hilbert-Schmidt distance between state \(\rho\) and target \(\sigma\).

Return type:

References

1. P. J. Coles, M. Cerezo, and L. Cincio, Strong bound between trace distance and Hilbert-Schmidt distance for low-rank states, Phys. Rev. A 100, 022103 (2019).

Fidelity#

qibo.quantum_info.fidelity(state, target, check_hermitian: bool = False, backend=None)[source]#

Fidelity \(F(\rho, \sigma)\) between state \(\rho\) and target state \(\sigma\). In general,

\[F(\rho, \sigma) = \text{tr}^{2}\left( \sqrt{\sqrt{\sigma} \, \rho^{\dagger} \, \sqrt{\sigma}} \right) \, .\]

However, when at least one of the states is pure, then

\[F(\rho, \sigma) = \text{tr}(\rho \, \sigma)\]

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
check_hermitian (bool, optional) – if True, checks if state is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Fidelity between state \(\rho\) and target \(\sigma\).

Return type:

Infidelity#

qibo.quantum_info.infidelity(state, target, check_hermitian: bool = False, backend=None)[source]#

Infidelity between state \(\rho\) and target state \(\sigma\), which is given by

\[1 - F(\rho, \, \sigma) \, ,\]

where \(F(\rho, \, \sigma)\) is the qibo.quantum_info.fidelity() between state and target.

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
check_hermitian (bool, optional) – if True, checks if state is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Infidelity between state \(\rho\) and target \(\sigma\).

Return type:

Bures angle#

qibo.quantum_info.bures_angle(state, target, check_hermitian: bool = False, backend=None)[source]#

Calculates the Bures angle \(D_{A}\) between a state \(\rho\) and a target state \(\sigma\). This is given by

\[D_{A}(\rho, \, \sigma) = \text{arccos}\left(\sqrt{F(\rho, \, \sigma)}\right) \, ,\]

where \(F(\rho, \sigma)\) is the qibo.quantum_info.fidelity() between state and target.

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
check_hermitian (bool, optional) – if True, checks if state is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Bures angle between state and target.

Return type:

Bures distance#

qibo.quantum_info.bures_distance(state, target, check_hermitian: bool = False, backend=None)[source]#

Calculates the Bures distance \(D_{B}\) between a state \(\rho\) and a target state \(\sigma\). This is given by

\[D_{B}(\rho, \, \sigma) = \sqrt{2 \, \left(1 - \sqrt{F(\rho, \, \sigma)}\right)}\]

where \(F(\rho, \sigma)\) is the qibo.quantum_info.fidelity() between state and target.

Parameters:

state (ndarray) – statevector or density matrix.
target (ndarray) – statevector or density matrix.
check_hermitian (bool, optional) – if True, checks if state is Hermitian. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Bures distance between state and target.

Return type:

Process fidelity#

qibo.quantum_info.process_fidelity(channel, target=None, check_unitary: bool = False, backend=None)[source]#

Process fidelity between a quantum channel \(\mathcal{E}\) and a target unitary channel \(U\). The process fidelity is defined as

\[F_{\text{pro}}(\mathcal{E}, \mathcal{U}) = \frac{1}{d^{2}} \, \text{tr}(\mathcal{E}^{\dagger} \, \mathcal{U})\]

Parameters:

channel – quantum channel \(\mathcal{E}\).
target (optional) – quantum channel \(U\). If None, target is the Identity channel. Defaults to None.
check_unitary (bool, optional) – if True, checks if one of the input channels is unitary. Default: False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Process fidelity between channel and target.

Return type:

Process infidelity#

qibo.quantum_info.process_infidelity(channel, target=None, check_unitary: bool = False, backend=None)[source]#

Process infidelity between quantum channel \(\mathcal{E}\) and a target unitary channel \(U\). The process infidelity is defined as

\[1 - F_{\text{pro}}(\mathcal{E}, \mathcal{U}) \, ,\]

where \(F_{\text{pro}}\) is the qibo.quantum_info.process_fidelity().

Parameters:

channel – quantum channel \(\mathcal{E}\).
target (optional) – quantum channel \(U\). If None, target is the Identity channel. Defaults to None.
check_unitary (bool, optional) – if True, checks if one of the input channels is unitary. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Process infidelity between channel \(\mathcal{E}\) and target \(U\).

Return type:

Average gate fidelity#

qibo.quantum_info.average_gate_fidelity(channel, target=None, check_unitary: bool = False, backend=None)[source]#

Average gate fidelity between a quantum channel \(\mathcal{E}\) and a target unitary channel \(U\). The average gate fidelity is defined as

\[F_{\text{avg}}(\mathcal{E}, \mathcal{U}) = \frac{d \, F_{pro}(\mathcal{E}, \mathcal{U}) + 1}{d + 1}\]

where \(d\) is the dimension of the channels and \(F_{pro}(\mathcal{E}, \mathcal{U})\) is the process_fidelily() of channel \(\mathcal{E}\) with respect to the unitary channel \(\mathcal{U}\).

Parameters:

channel – quantum channel \(\mathcal{E}\).
target (optional) – quantum channel \(\mathcal{U}\). If None, target is the Identity channel. Defaults to None.
check_unitary (bool, optional) – if True, checks if one of the input channels is unitary. Default: False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Process fidelity between channel \(\mathcal{E}\) and target unitary channel \(\mathcal{U}\).

Return type:

Gate error#

qibo.quantum_info.gate_error(channel, target=None, check_unitary: bool = False, backend=None)[source]#

Gate error between a quantum channel \(\mathcal{E}\) and a target unitary channel \(U\), which is defined as

\[E(\mathcal{E}, \mathcal{U}) = 1 - F_{\text{avg}}(\mathcal{E}, \mathcal{U}) \, ,\]

where \(F_{\text{avg}}(\mathcal{E}, \mathcal{U})\) is the qibo.quantum_info.average_gate_fidelity().

Parameters:

channel – quantum channel \(\mathcal{E}\).
target (optional) – quantum channel \(\mathcal{U}\). If None, target is the Identity channel. Defaults to None.
check_unitary (bool, optional) – if True, checks if one of the input channels is unitary. Default: False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Gate error between channel \(\mathcal{E}\) and target \(\mathcal{U}\).

Return type:

Diamond Norm#

qibo.quantum_info.diamond_norm(channel, target=None, backend=None, **kwargs)[source]#

Calculates the diamond norm \(\|\mathcal{E}\|_{\diamond}\) of channel \(\mathcal{E}\), which is given by

\[\|\mathcal{E}\|_{\diamond} = \max_{\rho} \, \| \left(\mathcal{E} \otimes I_{d^{2}}\right)(\rho) \|_{1} \, ,\]

where \(I_{d^{2}}\) is the \(d^{2} \times d^{2}\) Identity operator, \(d = 2^{n}\), \(n\) is the number of qubits, and \(\|\cdot\|_{1}\) denotes the trace norm.

If a target channel \(\Lambda\) is specified, then it calculates \(\| \mathcal{E} - \Lambda\|_{\diamond}\).

Example:

from qibo.quantum_info import diamond_norm, random_unitary, to_choi

nqubits = 1
dim = 2**nqubits

unitary = random_unitary(dim)
unitary = to_choi(unitary, order="row")

unitary_2 = random_unitary(dim)
unitary_2 = to_choi(unitary_2, order="row")

dnorm = diamond_norm(unitary, unitary_2)

Parameters:

channel (ndarray) – row-vectorized Choi representation of a quantum channel.
target (ndarray, optional) – row-vectorized Choi representation of a target quantum channel. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.
kwargs – optional arguments to pass to CVXPY solver. For more information, please visit CVXPY’s API documentation.

Returns:

diamond norm of either channel or channel - target.

Return type:

Note

This function requires the optional CVXPY package to be installed.

Expressibility of parameterized quantum circuits#

qibo.quantum_info.expressibility(circuit, power_t: int, samples: int, order: int | float | str | None = 2, backend=None)[source]#

Returns the expressibility \(\|A\|\) of a parametrized circuit, where

\[A = \int_{\text{Haar}} d\psi \, \left(|\psi\rangle\right.\left. \langle\psi|\right)^{\otimes t} - \int_{\Theta} d\psi \, \left(|\psi_{\theta}\rangle\right.\left. \langle\psi_{\theta}|\right)^{\otimes t}\]

Parameters:

circuit (qibo.models.Circuit) – Parametrized circuit.
power_t (int) – power that defines the \(t\)-design.
samples (int) – number of samples to estimate the integrals.
order (int or float or str, optional) – order of the norm \(\|A\|\). For specifications, see qibo.backends.abstract.calculate_norm(). Defaults to \(2\).
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Expressibility of parametrized circuit.

Return type:

Frame Potential#

qibo.quantum_info.frame_potential(circuit, power_t: int, samples: int = None, backend=None)[source]#

Returns the frame potential of a parametrized circuit under uniform sampling of the parameters.

For \(n\) qubits and moment \(t\), the frame potential \(\mathcal{F}_{\mathcal{U}}^{(t)}\) if given by [1]

\[\mathcal{F}_{\mathcal{U}}^{(t)} = \int_{U,V \in \mathcal{U}} \, \text{d}U \, \text{d}V \, \bigl| \, \text{tr}(U^{\dagger} \, V) \, \bigr|^{2t} \, ,\]

where \(\mathcal{U}\) is the group of unitaries defined by the parametrized circuit. The frame potential is approximated by the average

\[\mathcal{F}_{\mathcal{U}}^{(t)} \approx \frac{1}{N} \, \sum_{k=1}^{N} \, \bigl| \, \text{tr}(U_{k}^{\dagger} \, V_{k}) \, \bigr|^{2t} \, ,\]

where \(N\) is the number of samples.

Parameters:

circuit (qibo.models.circuit.Circuit) – Parametrized circuit.
power_t (int) – power that defines the \(t\)-design.
samples (int) – number of samples to estimate the integral.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Frame potential of the parametrized circuit.

Return type:

qibo.quantum_info.quantum_networks.QuantumNetwork

References

1. M. Liu et al., Estimating the randomness of quantum circuit ensembles up to 50 qubits. arXiv:2205.09900 [quant-ph].

Quantum Fisher Information Matrix#

qibo.quantum_info.quantum_fisher_information_matrix(circuit, parameters=None, initial_state=None, return_complex: bool = True, backend=None)[source]#

Calculate the Quantum Fisher Information Matrix (QFIM) of a parametrized circuit.

Given a set of parameters \(\theta = \{\theta_{k}\}_{k\in[M]}\) and a parameterized unitary circuit \(U(\theta)\) acting on an initial_state \(\ket{\phi}\), the QFIM is such that its elements can be calculated as

\[\mathbf{F}_{jk} = 4 \, \text{Re}\left\{ \braket{\partial_{j} \psi | \partial_{k} \psi} - \braket{\partial_{j} \psi | \psi}\!\braket{\psi | \partial_{k} \psi} \right\} \, ,\]

where we have used the short notations \(\ket{\psi} \equiv \ket{\psi(\theta)} = U(\theta) \ket{\phi}\), and \(\ket{\partial_{k} \psi} \equiv \frac{\partial} {\partial\theta_{k}} \ket{\psi(\theta)}\). If the initial_state \(\ket{\phi}\) is not specified, it defaults to \(\ket{0}^{\otimes n}\).

Parameters:

circuit (qibo.models.circuit.Circuit) – parametrized circuit \(U(\theta)\).
parameters (ndarray, optional) – parameters whose QFIM to calculate. If None, QFIM is calculated with the paremeters from circuit, i.e. parameters = circuit.get_parameters(). Defaults to None.
initial_state (ndarray, optional) – Initial configuration. It can be specified by the setting the state vector using an array or a circuit. If None, the initial state is \(\ket{0}^{\otimes n}\). Defaults to None.
return_complex (bool, optional) – If True, calculates the Jacobian matrix of real and imaginary parts of \(\ket{\psi(\theta)}\). If False, calculates only the Jacobian matrix of the real part. Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses qibo.backends.GlobalBackend. Defaults to None.

Returns:

Quantum Fisher Information \(\mathbf{F}\).

Return type:

ndarray

Linear Algebra Operations#

Collection of linear algebra operations that are commonly used in quantum information theory.

Commutator#

qibo.quantum_info.commutator(operator_1, operator_2)[source]#

Returns the commutator of operator_1 and operator_2.

The commutator of two matrices \(A\) and \(B\) is given by

\[[A, B] = A \, B - B \, A \,.\]

Parameters:

operator_1 (ndarray) – First operator.
operator_2 (ndarray) – Second operator.

Returns:

Commutator of operator_1 and operator_2.

Return type:

ndarray

Anticommutator#

qibo.quantum_info.anticommutator(operator_1, operator_2)[source]#

Returns the anticommutator of operator_1 and operator_2.

The anticommutator of two matrices \(A\) and \(B\) is given by

\[\{A, B\} = A \, B + B \, A \,.\]

Parameters:

operator_1 (ndarray) – First operator.
operator_2 (ndarray) – Second operator.

Returns:

Anticommutator of operator_1 and operator_2.

Return type:

ndarray

Partial trace#

qibo.quantum_info.partial_trace(state, traced_qubits: List[int] | Tuple[int, ...], backend=None)[source]#

Returns the density matrix resulting from tracing out traced_qubits from state.

Total number of qubits is inferred by the shape of state.

Parameters:

state (ndarray) – density matrix or statevector.
traced_qubits (Union[List[int], Tuple[int]]) – indices of qubits to be traced out.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Density matrix of the remaining qubit(s).

Return type:

ndarray

Partial transpose#

qibo.quantum_info.partial_transpose(operator, partition: List[int] | Tuple[int, ...], backend=None)[source]#

Return matrix after the partial transposition of partition qubits in operator.

Given a \(n\)-qubit operator \(O \in \mathcal{H}_{A} \otimes \mathcal{H}_{B}\), the partial transpose with respect to partition \(B\) is given by

\[\begin{split}\begin{align} O^{T_{B}} &= \sum_{jklm} \, O_{lm}^{jk} \, \ketbra{j}{k} \otimes \left(\ketbra{l}{m}\right)^{T} \\ &= \sum_{jklm} \, O_{lm}^{jk} \, \ketbra{j}{k} \otimes \ketbra{m}{l} \\ &= \sum_{jklm} \, O_{ml}^{jk} \, \ketbra{j}{k} \otimes \ketbra{l}{m} \, , \end{align}\end{split}\]

where the superscript \(T\) indicates the transposition operation, and \(T_{B}\) indicates transposition on partition \(B\). The total number of qubits is inferred by the shape of operator.

Parameters:

operator (ndarray) – \(1\)- or \(2\)-dimensional operator, or an array of \(1\)- or \(2\)-dimensional operators,
partition (Union[List[int], Tuple[int, ...]]) – indices of qubits to be transposed.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses it uses the current backend. Defaults to None.

Returns:

Partially transposed operator(s) \(\O^{T_{B}}\).

Return type:

ndarray

Matrix exponentiation#

qibo.quantum_info.matrix_exponentiation(phase: float | complex, matrix, eigenvectors=None, eigenvalues=None, backend=None)[source]#

Calculates the exponential of a matrix.

Given a matrix \(H\) and a phase \(\theta\), it returns the exponential of the form

\[\exp\left(-i \, \theta \, H \right) \, .\]

If the eigenvectors and eigenvalues are given, the matrix diagonalization is used for the exponentiation.

Parameters:

phase (float or complex) – phase that multiplies the matrix.
matrix (ndarray) – matrix to be exponentiated.
eigenvectors (ndarray, optional) – _if not None, eigenvectors are used to calculate matrix exponentiation as part of diagonalization. Must be used together with eigenvalues. Defaults to None.
eigenvalues (ndarray, optional) – if not None, eigenvalues are used to calculate matrix exponentiation as part of diagonalization. Must be used together with eigenvectors. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

matrix exponential of \(-i \, \theta \, H\).

Return type:

ndarray

Matrix power#

qibo.quantum_info.matrix_power(matrix, power: float | int, precision_singularity: float = 1e-14, backend=None)[source]#

Given a matrix \(A\) and power \(\alpha\), calculate \(A^{\alpha}\).

Parameters:

matrix (ndarray) – matrix whose power to calculate.
power (float or int) – power to raise matrix to.
precision_singularity (float, optional) – If determinant of matrix is smaller than precision_singularity, then matrix is considered to be singular. Used when power is negative.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

matrix power \(A^{\alpha}\).

Return type:

ndarray

Singular value decomposition#

qibo.quantum_info.singular_value_decomposition(matrix, backend=None)[source]#

Calculate the Singular Value Decomposition (SVD) of matrix.

Given an \(M \times N\) complex matrix \(A\), its SVD is given by

where \(U\) and \(V\) are, respectively, an \(M \times M\) and an \(N \times N\) complex unitary matrices, and \(S\) is an \(M \times N\) diagonal matrix with the singular values of \(A\).

Parameters:

matrix (ndarray) – matrix whose SVD to calculate.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Singular value decomposition of \(A\), i.e. \(U\), \(S\), and \(V^{\dagger}\), in that order.

Return type:

ndarray, ndarray, ndarray

Schmidt decomposition#

qibo.quantum_info.schmidt_decomposition(state, partition: List[int] | Tuple[int, ...], backend=None)[source]#

Return the Schmidt decomposition of a \(n\)-qubit bipartite pure quantum state.

Given a bipartite pure state \(\ket{\psi}\in\mathcal{H}_{A}\otimes\mathcal{H}_{B}\), its Schmidt decomposition is given by

\[\ket{\psi} = \sum_{k = 1}^{\min\{a, \, b\}} \, c_{k} \, \ket{\phi_{k}} \otimes \ket{\nu_{k}} \, ,\]

with \(a\) and \(b\) being the respective cardinalities of \(\mathcal{H}_{A}\) and \(\mathcal{H}_{B}\), and \(\{\phi_{k}\}_{k\in[\min\{a, \, b\}]} \subset \mathcal{H}_{A}\) and \(\{\nu_{k}\}_{k\in[\min\{a, \, b\}]} \subset \mathcal{H}_{B}\) being orthonormal sets. The coefficients \(\{c_{k}\}_{k\in[\min\{a, \, b\}]}\) are real, non-negative, and unique up to re-ordering.

The decomposition is calculated using qibo.quantum_info.singular_value_decomposition(), resulting in

\[\ketbra{\psi}{\psi} = U \, S \, V^{\dagger} \, ,\]

where \(U\) is an \(a \times a\) unitary matrix, \(V\) is an \(b \times b\) unitary matrix, and \(S\) is an \(a \times b\) positive semidefinite diagonal matrix that contains the singular values of \(\ketbra{\psi}{\psi}\).

Parameters:

state (ndarray) – stevector or density matrix.
partition (Union[List[int], Tuple[int, ...]]) – indices of qubits in one of the two partitions. The other partition is inferred as the remaining qubits.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses qibo.backends.GlobalBackend. Defaults to None.

Returns:

Respectively, the matrices \(U\), \(S\), and \(V^{\dagger}\).

Return type:

ndarray, ndarray, ndarray

Lanczos algorithm#

qibo.quantum_info.lanczos(matrix, steps: int = None, initial_vector=None, precision_tol: float = 1e-08, seed=None, backend=None)[source]#

Lanczos iterative method to tridiagonalize a Hermitian matrix.

Given a \(N \times N\) Hermitian matrix \(H\) and a number of iterations \(m \leq N\), the Lanczos algorithm outputs a \(N \times m\) orthonormal matrix \(U\) and a \(m \times m\) tridiagonal real symmetric matrix \(T = U^{\dagger} \, H \, U\). If \(m = N\), then \(U\) is an unitary matrix. The eigenvalues of \(T\) and \(H\) coincide, while \(U \ket{\mathbf{x}}\) are the eigenvectors of \(H\), with \(\ket{\mathbf{x}}\) being the eigenvectors of \(T\).

This reduces the problem of diagonalization of \(H\) to constructing the matrix \(U\) and diagonalizing \(T\).

With \(\|\cdot\|_{2}\) being the Euclidean norm, the algorithm goes as follows:

Generate random \(\ket{v_{1}} \in \mathbb{C}^{N}\) such that \(\|\ket{v_{1}}\|_{2} = 1\)
\(\ket{\omega_{1}^{\prime}} = H \ket{v_{1}}\)
\(\alpha_{1} = \braket{\omega_{1}^{\prime} | v_{1}}\)
\(\ket{\omega_{1}} = H \ket{v_{1}} - \alpha_{1} \ket{v_{1}}\)
For \(j = 2, \dots, m - 1\):
1. \(\beta_{j} = \|\omega_{j-1}\|_{2}\)
2. \(\ket{v_{j}} = \ket{\omega_{j-1}} \, / \, \beta_{j}\) If \(\beta_{j} \neq 0\) else generate random \(\ket{v_{j}}\) such that \(\ket{v_{j}} \perp \{\ket{v_{j^{\prime}}}\}_{j^{\prime} \in [1, j-1]}\)
3. \(\ket{\omega_{j}^{\prime}} = H \ket{v_{j}}\)
4. \(\alpha_{j} = \braket{\omega_{j}^{\prime} | v_{j}}\)
5. \(\ket{\omega_{j}} = \ket{\omega_{j}^{\prime}} - \alpha_{j} \ket{v_{j}} - \beta_{j} \ket{v_{j-1}}\)

The columns of the orthogonal matrix \(U\) are the Lanczos vectors \(\{\ket{v_{j}}\}_{j\in[1, m]}\).

Parameters:

matrix (ndarray) – square Hermitian matrix to be tridiagonalized.
steps (int, optional) – number of iterations \(m\). If None, defaults to the size of matrix. Defaults to None.
initial_vector (ndarray, optional) – vector to be used as the initial Lanczos vector \(\ket{v_{1}}\). If None, array is uniformly sampled. Defaults to None.
precision_tol (float, optional) – precision threshold such that for \(\beta_{j}\) smaller than precision_tol, it is considered to be zero.
seed (int or numpy.random.Generator, optional) – Seed for the initial random vector \(\ket{v_{1}}\) Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Tridiagonal matrix and the orthogonal matrix of Lanczos vectors, respectively.

Return type:

(ndarray, ndarray)

References

1. Lanczos, C. An iteration method for the solution of the eigenvalue problem of linear differential and integral operators, Journal of Research of the National Bureau of Standards. 45 (4): 255–282 (1950).

Quantum Networks#

Quantum network is an object that unifies the representation of quantum states, channels, observables, and higher-order quantum operators.

For more details, see G. Chiribella et al., Theoretical framework for quantum networks, Physical Review A 80.2 (2009): 022339.

class qibo.quantum_info.quantum_networks.QuantumNetwork(tensor, partition: List[int] | Tuple[int] | None = None, system_input: List[bool] | Tuple[bool] | None = None, pure: bool = False, backend=None)[source]#

This class stores the representation of the quantum network as a tensor. This is a unique representation of the quantum network.

A minimum quantum network is a quantum channel, which is a quantum network of the form \(J[n \to m]\), where \(n\) is the dimension of the input system , and \(m\) is the dimension of the output system. A quantum state is a quantum network of the form \(J: 1 \to n\), such that the input system is trivial. An observable is a quantum network of the form \(J: n \to 1\), such that the output system is trivial.

A quantum network may contain multiple input and output systems. For example, a “quantum comb” is a quantum network of the form \(J: n', n \to m, m'\), which convert a quantum channel of the form \(J: n \to m\) to a quantum channel of the form \(J: n' \to m'\).

Parameters:

tensor (ndarray) – input Choi operator.
partition (List[int] or Tuple[int]) – partition of tensor.
system_input (List[bool] or Tuple[bool], optional) – mask on the output system of the Choi operator. If None, defaults to (True,False,True,False,...), where len(system_input)=len(partition). Defaults to None.
pure (bool, optional) – True when tensor is a “pure” representation (e.g. a pure state, a unitary operator, etc.), False otherwise. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

classmethod from_operator(operator, partition: List[int] | Tuple[int] | None = None, system_input: List[bool] | Tuple[bool] | None = None, pure: bool = False, backend=None)[source]#

Construct a qibo.quantum_info.QuantumNetwork object from a ndarray.

This method converts a Choi operator to the internal representation of qibo.quantum_info.quantum_networks.QuantumNetwork. The input array can be a pure state, a Choi operator, a unitary operator, etc.

Parameters:

arr (ndarray) – input numpy array.
partition (List[int] or Tuple[int], optional) – partition of arr. If None, defaults to the shape of arr. Defaults to None.
system_input (List[bool] or Tuple[bool], optional) – mask on the input system of the Choi operator. If None, defaults to (True,False,True,False...), where len(system_input)=len(partition). Defaults to None.
pure (bool, optional) – True when arr is a “pure” representation (e.g. a pure state, a unitary operator, etc.), False otherwise. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

Returns:

quantum network constructed from the input Choi operator.

Return type:

operator(full: bool = False, backend=None)[source]#

Returns the Choi operator of the quantum network.

The shape of the returned operator is \((*self.partition, *self.partition)\).

Parameters:

full (bool, optional) – If this is False, and the network is pure, the method will only return the eigenvector (unique when the network is pure). If True, returns the full tensor of the quantum network. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used to return the Choi operator. If None, defaults to the backend defined when initializing the qibo.quantum_info.quantum_networks.QuantumNetwork object. Defaults to None.

Returns:

Choi operator of the quantum network.

Return type:

ndarray

matrix(backend=None)[source]#

Returns the Choi operator of the quantum network in the matrix form. The shape of the returned operator is \((self.dims, self.dims)\).

Parameters:: backend (qibo.backends.abstract.Backend, optional) – Backend to be used to return the Choi operator. If None, defaults to the backend defined when initializing the qibo.quantum_info.quantum_networks.QuantumNetwork object. Defaults to None.
Returns:: Choi operator of the quantum network.
Return type:: ndarray

is_pure()[source]#: Returns bool indicading if the Choi operator of the network is pure.

is_hermitian(order: int | str | None = None, precision_tol: float = 1e-08)[source]#

Returns bool indicating if the Choi operator \(\mathcal{J}\) is Hermitian.

Hermicity is calculated as distance between \(\mathcal{J}\) and \(\mathcal{J}^{\dagger}\) with respect to a given norm. Default is the Hilbert-Schmidt norm (also known as Frobenius norm).

For specifications on the other possible values of the parameter order for the tensorflow backend, please refer to tensorflow.norm. For all other backends, please refer to numpy.linalg.norm.

Parameters:

order (str or int, optional) – order of the norm. Defaults to None.
precision_tol (float, optional) – threshold \(\epsilon\) that defines if Choi operator of the network is \(\epsilon\)-close to Hermicity in the norm given by order. Defaults to \(10^{-8}\).

Returns:

Hermiticity condition. If the adjoint of the Choi operator is equal to the: Choi operator, the method returns True. If the input is pure, the its always Hermitian.

Return type:

qibo.quantum_info.quantum_networks.QuantumNetwork

is_positive_semidefinite(precision_tol: float = 1e-08)[source]#

Returns bool indicating if Choi operator \(\mathcal{J}\) is positive-semidefinite.

Parameters:: precision_tol (float, optional) – threshold value used to check if eigenvalues of the Choi operator \(\mathcal{J}\) are such that \(\textup{eigenvalues}(\mathcal{J}) >= - \textup{precision_tol}\). Note that this parameter can be set to negative values. Defaults to \(0.0\).
Returns:: Positive-semidefinite condition.
Return type:: bool

link_product(subscripts: str, second_network)[source]#

Link product between two quantum networks.

The link product is not commutative. Here, we assume that \(A.\textup{link_product}(B)\) means “applying \(B\) to \(A\)”. However, the link_product is associative, so we override the @ operation in order to simplify notation.

Parameters:

subscripts (str, optional) – Specifies the subscript for summation using the Einstein summation convention. For more details, please refer to numpy.einsum.
second_network (qibo.quantum_info.quantum_networks.QuantumNetwork) – Quantum network to be applied to the original network.

Returns:

Quantum network resulting: from the link product between two quantum networks.

Return type:

copy()[source]#: Returns a copy of the qibo.quantum_info.QuantumNetwork object.

conj()[source]#: Returns the conjugate of the quantum network.

full(update: bool = False, backend=None)[source]#

Convert the internal representation to the full tensor of the network.

Parameters:

update (bool, optional) – If True, updates the internal representation of the network to the full tensor. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

Returns:

full reprentation of the quantum network.

Return type:

ndarray

class qibo.quantum_info.quantum_networks.QuantumComb(tensor, partition: List[int] | Tuple[int] | None = None, system_input: List[bool] | Tuple[bool] | None = None, pure: bool = False, backend=None)[source]#

Stores a Quantum comb, which is a network in which the systems follows a sequential order.

It is also called the non-Markovian quantum process in many literatures. A quantum comb is a quantum network of the form \(J[┍i1┑,┕o1┙,┍i2┑,┕o2┙, ...]\), where the process first take an input state from system \(i1\), then output a state to system \(o1\), and so on. This is a non-Markovian process as the output of the system \(o2\) may depend on what happened in systems \(i1\), and \(o1\).

A quantum channel is a special case of quantum comb, where there are only one input system and one output system.

Parameters:

tensor (ndarray) – the tensor representations of the quantum Comb.
partition (List[int] or Tuple[int]) – partition of matrix.
system_input (List[bool] or Tuple[bool], optional) – mask on the input system of the Choi operator. If None, defaults to (True,False,True,False,...), where len(system_input)=len(partition). Defaults to None.
pure (bool, optional) – True when tensor is a “pure” representation (e.g. a pure state, a unitary operator, etc.), False otherwise. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

is_causal(order: int | str | None = None, precision_tol: float = 1e-08)[source]#

Returns bool indicating if the Choi operator \(\mathcal{J}\) satisfies causal order

Causality is calculated based on a recursive constrains. This method reduce a n-comb to a (n-1)-comb at each step, and checks if the reduced comb is independent on the last output system.

Parameters:

order (str or int, optional) – order of the norm. Defaults to None.
precision_tol (float, optional) – threshold \(\epsilon\) that defines if Choi operator of the network is \(\epsilon\)-close to causality in the norm given by order. Defaults to \(10^{-8}\).

Returns:

Causal order condition.

Return type:

qibo.quantum_info.quantum_networks.QuantumNetwork

classmethod from_operator(operator, partition=None, inverse=False, pure=False, backend=None)[source]#

Construct a qibo.quantum_info.QuantumNetwork object from a ndarray.

Parameters:

arr (ndarray) – input numpy array.
partition (List[int] or Tuple[int], optional) – partition of arr. If None, defaults to the shape of arr. Defaults to None.
system_input (List[bool] or Tuple[bool], optional) – mask on the input system of the Choi operator. If None, defaults to (True,False,True,False...), where len(system_input)=len(partition). Defaults to None.
pure (bool, optional) – True when arr is a “pure” representation (e.g. a pure state, a unitary operator, etc.), False otherwise. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

Returns:

quantum network constructed from the input Choi operator.

Return type:

class qibo.quantum_info.quantum_networks.QuantumChannel(tensor, partition: List[int] | Tuple[int] | None = None, system_input: List[bool] | Tuple[bool] | None = None, pure: bool = False, backend=None)[source]#

Stores a Quantum channel, which is a special case of quantum comb.

A quantum channel is a quantum comb with only one input and one output. This class includes all quantum channels, unitary operators, and quantum states.

To construct a QuantumChannel object, one can use the QuantumNetwork.from_nparray method. Note: if one try to construct a quantum network from a unitary operator or Choi operator, the first system will be the output. However, here we assume the first system is the input system. It is important to specify inverse=True when constructing by QuantumNetwork.from_nparray.

Parameters:

tensor (ndarray) – the tensor representations of the quantum comb.
partition (List[int] or Tuple[int], optional) – partition of matrix. If not provided and system_input is None, assume the input is a quantum state, whose input is a trivial system. If system_input is set to True, assume the input is an observable, whose output is a trivial system.
system_input (List[bool] or Tuple[bool], optional) – mask on the input system of the Choi operator. If None the default is (True,False). Defaults to None.
pure (bool, optional) – True when tensor is a “pure” representation (e.g. a pure state, a unitary operator, etc.), False otherwise. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – Backend to be used in calculations. If None, defaults to the current backend. Defaults to None.

is_unital(order: int | str | None = None, precision_tol: float = 1e-08)[source]#

Returns bool indicating if the Choi operator \(\mathcal{J}\) is unital.

A map is unital if it preserves the identity operator. Unitality is calculated as distance between the partial trace of \(\mathcal{J}\) and the Identity operator \(I\), with respect to a given norm. Default is the Hilbert-Schmidt norm (also known as Frobenius norm).

For specifications on the other possible values of the parameter order for the tensorflow backend, please refer to tensorflow.norm. For all other backends, please refer to numpy.linalg.norm.

Parameters:

order (str or int, optional) – order of the norm. Defaults to None.
precision_tol (float, optional) – threshold \(\epsilon\) that defines if Choi operator of the network is \(\epsilon\)-close to unitality in the norm given by order. Defaults to \(10^{-8}\).

Returns:

Unitality condition.

Return type:

is_channel(order: int | str | None = None, precision_tol_causal: float = 1e-08, precision_tol_psd: float = 1e-08)[source]#

Returns bool indicating if Choi operator \(\mathcal{E}\) is a channel.

Parameters:

order (int or str, optional) – order of the norm used to calculate causality. Defaults to None.
precision_tol_causal (float, optional) – threshold \(\epsilon\) that defines if Choi operator of the network is \(\epsilon\)-close to causality in the norm given by order. Defaults to \(10^{-8}\).
precision_tol_psd (float, optional) – threshold value used to check if eigenvalues of the Choi operator \(\mathcal{E}\) are such that \(\textup{eigenvalues}(\mathcal{E}) >= \textup{precision_tol_psd}\). Note that this parameter can be set to negative values. Defaults to \(0.0\).

Returns:

Channel condition.

Return type:

apply(state)[source]#

Apply the Choi operator \(\mathcal{E}\) to state \(\varrho\).

It is assumed that state \(\varrho\) is a density matrix.

Parameters:: state (ndarray) – density matrix of a state.
Returns:: Resulting state \(\mathcal{E}(\varrho)\).
Return type:: ndarray

Random Ensembles#

Functions that can generate random quantum objects.

Haar-random \(U_{3}\)#

qibo.quantum_info.uniform_sampling_U3(ngates: int, seed=None, backend=None)[source]#

Samples parameters for Haar-random qibo.gates.U3.

Parameters:

ngates (int) – Total number of \(U_{3}\) gates to be sampled.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

array of shape (ngates, \(3\)).

Return type:

ndarray

Random Gaussian matrix#

qibo.quantum_info.random_gaussian_matrix(dims: int, rank: int | None = None, mean: float = 0, stddev: float = 1, seed=None, backend=None)[source]#

Generates a random Gaussian Matrix.

Gaussian matrices are matrices where each entry is sampled from a Gaussian probability distribution

with mean \(\mu\) and standard deviation \(\sigma\).

Parameters:

dims (int) – dimension of the matrix.
rank (int, optional) – rank of the matrix. If None, then rank == dims. Default: None.
mean (float, optional) – mean of the Gaussian distribution. Defaults to 0.
stddev (float, optional) – standard deviation of the Gaussian distribution. Defaults to 1.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Default: None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Random Gaussian matrix with dimensions (dims, rank).

Return type:

ndarray

Random Hermitian matrix#

qibo.quantum_info.random_hermitian(dims: int, semidefinite: bool = False, normalize: bool = False, seed=None, backend=None)[source]#

Generates a random Hermitian matrix \(H\), i.e. a random matrix such that \(H = H^{\dagger}.\)

Parameters:

dims (int) – dimension of the matrix.
semidefinite (bool, optional) – if True, returns a Hermitian matrix that is also positive semidefinite. Defaults to False.
normalize (bool, optional) – if True and semidefinite=False, returns a Hermitian matrix with eigenvalues in the interval \([-1, \, 1]\). If True and semidefinite=True, interval is \([0, \, 1]\). Defaults to False.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hermitian matrix \(H\) with dimensions (dims, dims).

Return type:

ndarray

Random unitary matrix#

qibo.quantum_info.random_unitary(dims: int, measure: str | None = None, seed=None, backend=None)[source]#

Returns a random Unitary operator \(U\), i.e. a random operator such that \(U^{-1} = U^{\dagger}\).

Parameters:

dims (int) – dimension of the matrix.
measure (str, optional) – probability measure in which to sample the unitary from. If None, functions returns \(\exp{(-i \, H)}\), where \(H\) is a Hermitian operator. If "haar", returns an Unitary matrix sampled from the Haar measure. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Unitary matrix \(U\) with dimensions (dims, dims).

Return type:

ndarray

Random quantum channel#

qibo.quantum_info.random_quantum_channel(dims: int, representation: str = 'liouville', measure: str | None = None, rank: int | None = None, order: str = 'row', normalize: bool = False, precision_tol: float | None = None, validate_cp: bool = True, nqubits: int | None = None, initial_state_env=None, seed=None, backend=None)[source]#

Creates a random superoperator from an unitary operator in one of the supported superoperator representations.

Parameters:

dims (int) – dimension of the \(n\)-qubit operator, i.e. \(\text{dims}=2^{n}\).
representation (str, optional) – If "chi", returns a random channel in the Chi representation. If "choi", returns channel in Choi representation. If "kraus", returns Kraus representation of channel. If "liouville", returns Liouville representation. If "pauli", returns Pauli-Liouville representation. If “pauli-<pauli_order>” or “chi-<pauli_order>”, (e.g. “pauli-IZXY”), returns it in the Pauli basis with the corresponding order of single-qubit Pauli elements (see qibo.quantum_info.pauli_basis()). If "stinespring", returns random channel in the Stinespring representation. Defaults to "liouville".
measure (str, optional) – probability measure in which to sample the unitary from. If None, functions returns \(\exp{(-i \, H)}\), where \(H\) is a Hermitian operator. If "haar", returns an Unitary matrix sampled from the Haar measure. If "bcsz", it samples an unitary from the BCSZ distribution with Kraus rank. Defaults to None.
rank (int, optional) – used when measure=="bcsz". Rank of the matrix. If None, then rank==dims. Defaults to None.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Defaults to "row".
normalize (bool, optional) – used when representation="chi" or representation="pauli". If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
precision_tol (float, optional) – if representation="kraus", it is the precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
validate_cp (bool, optional) – used when representation="stinespring". If True, checks if the Choi representation of superoperator used as intermediate step is a completely positive map. If False, it assumes that it is completely positive (and Hermitian). Defaults to True.
nqubits (int, optional) – used when representation="stinespring". Total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits that Kraus representation of the system superoperator acts on. If None, defaults to the number of qubits in the Kraus operators. Defauts to None.
initial_state_env (ndarray, optional) – used when representation="stinespring". Statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Superoperator representation of a random unitary gate.

Return type:

ndarray

Random statevector#

qibo.quantum_info.random_statevector(dims: int, seed=None, backend=None)[source]#

Creates a random statevector \(\ket{\psi}\).

\[\ket{\psi} = \sum_{k = 0}^{d - 1} \, \sqrt{p_{k}} \, e^{i \phi_{k}} \, \ket{k} \, ,\]

where \(d\) is dims, and \(p_{k}\) and \(\phi_{k}\) are, respectively, the probability and phase corresponding to the computational basis state \(\ket{k}\).

Parameters:

dims (int) – dimension of the matrix.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Random statevector \(\ket{\psi}\).

Return type:

ndarray

Random density matrix#

qibo.quantum_info.random_density_matrix(dims: int, rank: int | None = None, pure: bool = False, metric: str = 'hilbert-schmidt', basis: str | None = None, normalize: bool = False, order: str = 'row', seed=None, backend=None)[source]#

Creates a random density matrix \(\rho\). If pure=True,

\[\rho = \ketbra{\psi}{\psi} \, ,\]

where \(\ket{\psi}\) is a qibo.quantum_info.random_statevector(). If pure=False, then

\[\rho = \sum_{k} \, p_{k} \, \ketbra{\psi_{k}}{\psi_{k}} \, .\]

is a mixed state.

Parameters:

dims (int) – dimension of the matrix.
rank (int, optional) – rank of the matrix. If None, then rank == dims. Defaults to None.
pure (bool, optional) – if True, returns a pure state. Defaults to False.
metric (str, optional) – metric to sample the density matrix from. Options: "hilbert-schmidt", "ginibre", and "bures". Note that, by definition, rank defaults to None when metric=="hilbert-schmidt". Defaults to "hilbert-schmidt".
basis (str, optional) – if None, returns random density matrix in the computational basis. If "pauli-<pauli_order>", (e.g. "pauli-IZXY"), returns it in the Pauli basis with the corresponding order of single-qubit Pauli elements (see qibo.quantum_info.pauli_basis()). Defaults to None.
normalize (bool, optional) – used when basis="pauli-<pauli-order>". If True returns random density matrix in the normalized Pauli basis. If False, returns state in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – used when basis="pauli-<pauli-order>". If "row", vectorization of Pauli basis is performed row-wise. If "column", vectorization is performed column-wise. If "system", system-wise vectorization is performed. Default is "row".
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Random density matrix \(\rho\).

Return type:

ndarray

Random Clifford#

qibo.quantum_info.random_clifford(nqubits: int, return_circuit: bool = True, density_matrix: bool = False, seed=None, backend=None)[source]#

Generates a random \(n\)-qubit Clifford operator, where \(n\) is nqubits. For the mathematical details, see Reference [1].

Parameters:

nqubits (int) – number of qubits.
return_circuit (bool, optional) – if True, returns a qibo.models.Circuit object. If False, returns an ndarray object. Defaults to True.
density_matrix (bool, optional) – used when return_circuit=True. If True, the circuit would evolve density matrices. Defaults to False.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Random Clifford operator.

Return type:

(ndarray or qibo.models.Circuit)

Reference:

S. Bravyi and D. Maslov, Hadamard-free circuits expose the structure of the Clifford group. arXiv:2003.09412 [quant-ph].

Random Pauli#

qibo.quantum_info.random_pauli(qubits, depth: int, max_qubits: int | None = None, subset: list | None = None, return_circuit: bool = True, density_matrix: bool = False, seed=None, backend=None)[source]#

Creates random Pauli operator(s).

Pauli operators are sampled from the single-qubit Pauli set \(\{I, \, X, \, Y, \, Z\}\).

Parameters:

qubits (int or list or ndarray) – if int and max_qubits=None, the number of qubits. If int and max_qubits != None, qubit index in which the Pauli sequence will act. If list or ndarray, indexes of the qubits for the Pauli sequence to act.
depth (int) – length of the sequence of Pauli gates.
max_qubits (int, optional) – total number of qubits in the circuit. If None, max_qubits = max(qubits). Defaults to None.
subset (list, optional) – list containing a subset of the 4 single-qubit Pauli operators. If None, defaults to the complete set. Defaults to None.
return_circuit (bool, optional) – if True, returns a qibo.models.Circuit object. If False, returns an ndarray with shape (qubits, depth, 2, 2) that contains all Pauli matrices that were sampled. Defaults to True.
density_matrix (bool, optional) – used when return_circuit=True. If True, the circuit would evolve density matrices. Defaults to False.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

all sampled Pauli operators.

Return type:

(ndarray or qibo.models.Circuit)

Random Pauli Hamiltonian#

qibo.quantum_info.random_pauli_hamiltonian(nqubits: int, max_eigenvalue: int | float | None = None, normalize: bool = False, pauli_order: str = 'IXYZ', seed=None, backend=None)[source]#

Generates a random Hamiltonian in the Pauli basis.

Parameters:

nqubits (int) – number of qubits.
max_eigenvalue (int or float, optional) – fixes the value of the largest eigenvalue. Defaults to None.
normalize (bool, optional) – If True, fixes the gap of the Hamiltonian as 1.0. Moreover, if True, then max_eigenvalue must be > 1.0. Defaults to False.
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements in the basis. Defaults to “IXYZ”.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a generator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hamiltonian in the Pauli basis and its corresponding eigenvalues.

Return type:

tuple(ndarray, ndarray)

Random stochastic matrix#

qibo.quantum_info.random_stochastic_matrix(dims: int, bistochastic: bool = False, diagonally_dominant: bool = False, precision_tol: float | None = None, max_iterations: int | None = None, seed=None, backend=None)[source]#

Creates a random stochastic matrix.

Parameters:

dims (int) – dimension of the matrix.
bistochastic (bool, optional) – if True, matrix is row- and column-stochastic. If False, matrix is row-stochastic. Defaults to False.
diagonally_dominant (bool, optional) – if True, matrix is strictly diagonally dominant. Defaults to False.
precision_tol (float, optional) – tolerance level for how much each probability distribution can deviate from summing up to 1.0. If None, it defaults to qibo.config.PRECISION_TOL. Defaults to None.
max_iterations (int, optional) – when bistochastic=True, maximum number of iterations used to normalize all rows and columns simultaneously. If None, defaults to qibo.config.MAX_ITERATIONS. Defaults to None.
seed (int or numpy.random.Generator, optional) – Either a generator of random numbers or a fixed seed to initialize a generator. If None, initializes a statevectorgenerator with a random seed. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

a random stochastic matrix.

Return type:

ndarray

Superoperator Transformations#

Functions used to convert superoperators among their possible representations. For more in-depth theoretical description of the representations and transformations, we direct the reader to Wood, Biamonte, and Cory, Quant. Inf. Comp. 15, 0579-0811 (2015).

Vectorization#

qibo.quantum_info.vectorization(state, order: str = 'row', backend=None)[source]#

Returns state \(\rho\) in its Liouville representation \(|\rho)\).

If order="row", then:

\[|\rho) = \sum_{k, l} \, \rho_{kl} \, \ket{k} \otimes \ket{l} \, .\]

If order="column", then:

\[|\rho) = \sum_{k, l} \, \rho_{kl} \, \ket{l} \otimes \ket{k} \, .\]

If state is a 3-dimensional tensor, it is interpreted as a batch of states.

Parameters:

state (ndarray) – statevector, density matrix, an array of statevectors, or an array of density matrices.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Liouville representation of state.

Return type:

ndarray

Note

Due to numpy limitations on handling transposition of tensors, this function will not work when the number of qubits \(n\) is such that \(n > 16\).

Unvectorization#

qibo.quantum_info.unvectorization(state, order: str = 'row', backend=None)[source]#

Returns state \(\rho\) from its Liouville representation \(|\rho)\). This operation is the inverse function of vectorization(), i.e.

\[\begin{split}\begin{align} \rho &= \text{unvectorization}(|\rho)) \nonumber \\ &= \text{unvectorization}(\text{vectorization}(\rho)) \nonumber \end{align}\end{split}\]

Parameters:

state – quantum state in Liouville representation.
order (str, optional) – If "row", unvectorization is performed row-wise. If "column", unvectorization is performed column-wise. If "system", system-wise vectorization is performed. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Density matrix of state.

Return type:

ndarray

Note

Due to numpy limitations on handling transposition of tensors, this function will not work when the number of qubits \(n\) is such that \(n > 16\).

To Choi#

qibo.quantum_info.to_choi(channel, order: str = 'row', backend=None)[source]#

Converts quantum channel \(U\) to its Choi representation \(\Lambda\).

\[\Lambda = | U ) ( U | \, ,\]

where \(| \cdot )\) is the qibo.quantum_info.vectorization() operation.

Parameters:

channel (ndarray) – quantum channel.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Default is "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

quantum channel in its Choi representation.

Return type:

ndarray

To Liouville#

qibo.quantum_info.to_liouville(channel, order: str = 'row', backend=None)[source]#

Converts quantum channel \(U\) to its Liouville representation \(\mathcal{E}\). It uses the Choi representation as an intermediate step.

Parameters:

channel (ndarray) – quantum channel.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Default is "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

quantum channel in its Liouville representation.

Return type:

ndarray

To Pauli-Liouville#

qibo.quantum_info.to_pauli_liouville(channel, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts quantum channel \(U\) to its Pauli-Liouville representation \(\mathcal{E}\). It uses the Liouville representation as an intermediate step.

Parameters:

channel (ndarray) – quantum channel.
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Default is "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Default is “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

quantum channel in its Pauli-Liouville representation.

Return type:

ndarray

To Chi#

qibo.quantum_info.to_chi(channel, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts quantum channel \(U\) to its \(\chi\)-representation.

Parameters:

channel (ndarray) – quantum channel.
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", vectorization is performed row-wise. If "column", vectorization is performed column-wise. If "system", a block-vectorization is performed. Default is "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Default is “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

quantum channel in its \(\chi\)-representation.

Return type:

ndarray

To Stinespring#

qibo.quantum_info.to_stinespring(channel, partition: List[int] | Tuple[int, ...] | None = None, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Convert quantum channel \(U\) to its Stinespring representation \(U_{0}\).

It uses the Kraus representation as an intermediate step.

Parameters:

channel (ndarray) – quantum channel.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits channel acts on. If None, defaults to the number of qubits in channel. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses qibo.backends.GlobalBackend. Defaults to None.

Returns:

Quantum channel in its Stinespring representation \(U_{0}\).

Return type:

ndarray

Choi to Liouville#

qibo.quantum_info.choi_to_liouville(choi_super_op, order: str = 'row', backend=None)[source]#

Converts Choi representation \(\Lambda\) of quantum channel to its Liouville representation \(\mathcal{E}\).

If order="row", then:

\[\Lambda_{\alpha\beta, \, \gamma\delta} \mapsto \Lambda_{\alpha\gamma, \, \beta\delta} \equiv \mathcal{E}\]

If order="column", then:

\[\Lambda_{\alpha\beta, \, \gamma\delta} \mapsto \Lambda_{\delta\beta, \, \gamma\alpha} \equiv \mathcal{E}\]

Parameters:

choi_super_op – Choi representation of quantum channel.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Liouville representation of quantum channel.

Return type:

ndarray

Choi to Pauli-Liouville#

qibo.quantum_info.choi_to_pauli(choi_super_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Choi representation \(\Lambda\) of a quantum channel to its Pauli-Liouville representation.

Parameters:

choi_super_op (ndarray) – superoperator in the Choi representation.
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", it assumes choi_super_op is in row-vectorization. If "column", it assumes column-vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

superoperator in the Pauli-Liouville representation.

Return type:

ndarray

Choi to Kraus#

qibo.quantum_info.superoperator_transformations.choi_to_kraus(choi_super_op, precision_tol: float | None = None, order: str = 'row', validate_cp: bool = True, backend=None)[source]#

Converts Choi representation \(\Lambda\) of a quantum channel \(\mathcal{E}\) into Kraus operators \(\{ K_{\alpha} \}_{\alpha}\).

If \(\mathcal{E}\) is a completely positive (CP) map, then

\[\Lambda = \sum_{\alpha} \, \lambda_{\alpha}^{2} \, |\tilde{K}_{\alpha})(\tilde{K}_{\alpha}| \, .\]

where \(|\cdot)\) is the qibo.quantum_info.vectorization() operation.

This is the spectral decomposition of \(\Lambda\), Hence, the set \(\{\lambda_{\alpha}, \, \tilde{K}_{\alpha}\}_{\alpha}\) is found by diagonalization of \(\Lambda\). The Kraus operators \(\{K_{\alpha}\}_{\alpha}\) are defined as

\[K_{\alpha} = \lambda_{\alpha} \, \text{unvectorization}(|\tilde{K}_{\alpha})) \, .\]

If \(\mathcal{E}\) is not CP, then spectral composition is replaced by a singular value decomposition (SVD), i.e.

\[\Lambda = U \, S \, V^{\dagger} \, ,\]

where \(U\) is a \(d^{2} \times d^{2}\) unitary matrix, \(S\) is a \(d^{2} \times d^{2}\) positive diagonal matrix containing the singular values of \(\Lambda\), and \(V\) is a \(d^{2} \times d^{2}\) unitary matrix. The Kraus coefficients are replaced by the square root of the singular values, and \(U\) (\(V\)) determine the left-generalized (right-generalized) Kraus operators.

Parameters:

choi_super_op – Choi representation of a quantum channel.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

The set \(\{K_{\alpha}, \, \lambda_{\alpha} \}_{\alpha}\) of Kraus operators representing the quantum channel and their respective coefficients. If map is non-CP, then function returns the set \(\{ \{K_{L}, \, K_{R}\}_{\alpha}, \, \lambda_{\alpha} \}_{\alpha}\), with the left- and right-generalized Kraus operators as well as the square root of their corresponding singular values.

Return type:

tuple(ndarray, ndarray)

Note

Due to the spectral decomposition subroutine in this function, the resulting Kraus operators \(\{K_{\alpha}\}_{\alpha}\) might contain global phases. That implies these operators are not exactly equal to the “true” Kraus operators \(\{K_{\alpha}^{(\text{ideal})}\}_{\alpha}\). However, since these are global phases, the operators’ actions are the same, i.e.

\[K_{\alpha} \, \rho \, K_{\alpha}^{\dagger} = K_{\alpha}^{\text{(ideal)}} \, \rho \,\, (K_{\alpha}^{\text{(ideal)}})^{\dagger} \,\,\,\,\, , \,\, \forall \, \alpha\]

Note

User can set validate_cp=False in order to speed up execution by not checking if input map choi_super_op is completely positive (CP) and Hermitian. However, that may lead to erroneous outputs if choi_super_op is not guaranteed to be CP. We advise users to either set this flag carefully or leave it in its default setting (validate_cp=True).

Choi to Chi-matrix#

qibo.quantum_info.choi_to_chi(choi_super_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Choi representation \(\Lambda\) of quantum channel to its \(\chi\)-matrix representation.

\[\chi = \text{liouville_to_pauli}(\Lambda)\]

Parameters:

choi_super_op – Choi representation of a quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Chi-matrix representation of the quantum channel.

Return type:

ndarray

Choi to Stinespring#

qibo.quantum_info.choi_to_stinespring(choi_super_op, precision_tol: float | None = None, order: str = 'row', validate_cp: bool = True, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Converts Choi representation \(\Lambda\) of quantum channel to its Stinespring representation \(U_{0}\). It uses the Kraus representation as an intermediate step.

Parameters:

choi_super_op – Choi representation of a quantum channel.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits kraus_ops acts on. If None, defaults to the number of qubits in kraus_ops. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of quantum channel.

Return type:

ndarray

Kraus to Choi#

qibo.quantum_info.kraus_to_choi(kraus_ops, order: str = 'row', backend=None)[source]#

Converts Kraus representation \(\{K_{\alpha}\}_{\alpha}\) of quantum channel to its Choi representation \(\Lambda\).

\[\Lambda = \sum_{\alpha} \, |K_{\alpha})( K_{\alpha}|\]

where \(|K_{\alpha})\) is the vectorization of the Kraus operator \(K_{\alpha}\). For a definition of vectorization, see qibo.quantum_info.vectorization().

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of the Kraus channel.

Return type:

ndarray

Kraus to Liouville#

qibo.quantum_info.kraus_to_liouville(kraus_ops, order: str = 'row', backend=None)[source]#

Converts from Kraus representation \(\{K_{\alpha}\}_{\alpha}\) of quantum channel to its Liouville representation \(\mathcal{E}\). It uses the Choi representation as an intermediate step.

\[\mathcal{E} = \text{choi_to_liouville}(\text{kraus_to_choi} (\{K_{\alpha}\}_{\alpha}))\]

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Liouville representation of quantum channel.

Return type:

ndarray

Kraus to Pauli-Liouville#

qibo.quantum_info.kraus_to_pauli(kraus_ops, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Kraus representation \(\{K_{\alpha}\}_{\alpha}\) of a quantum channel to its Pauli-Liouville representation.

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", intermediate step for Choi representation is done in row-vectorization. If "column", step is done in column-vectorization. If "system", block-vectorization is performed. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

superoperator in the Pauli-Liouville representation.

Return type:

ndarray

Kraus to Chi-matrix#

qibo.quantum_info.kraus_to_chi(kraus_ops, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Convert Kraus representation \(\{K_{\alpha}\}_{\alpha}\) of quantum channel to its \(\chi\)-matrix representation.

\[\chi = \sum_{\alpha} \, |c_{\alpha})( c_{\alpha}|,\]

where \(|c_{\alpha}) \cong |K_{\alpha})\) in Pauli-Liouville basis, and \(| \cdot )\) is the qibo.quantum_info.vectorization() operation.

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements in the Pauli basis. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Chi-matrix representation of the Kraus channel.

Return type:

ndarray

Kraus to Stinespring#

qibo.quantum_info.kraus_to_stinespring(kraus_ops, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Converts Kraus representation \(\{K_{\alpha}\}_{\alpha}\) of quantum channel to its Stinespring representation \(U_{0}\), i.e.

\[U_{0} = \sum_{\alpha} \, K_{\alpha} \otimes \ketbra{\alpha}{v_{0}} \, ,\]

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits kraus_ops acts on. If None, defaults to the number of qubits in kraus_ops. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Stinespring representation (restricted unitary) of the Kraus channel.

Return type:

ndarray

Liouville to Choi#

qibo.quantum_info.liouville_to_choi(super_op, order: str = 'row', backend=None)[source]#

Converts Liouville representation of quantum channel \(\mathcal{E}\) to its Choi representation \(\Lambda\). Indexing \(\mathcal{E}\) as \(\mathcal{E}_{\alpha\beta, \, \gamma\delta} \,\,\), then

If order="row":

\[\Lambda = \sum_{k, l} \, \ketbra{k}{l} \otimes \mathcal{E}(\ketbra{k}{l}) \equiv \mathcal{E}_{\alpha\gamma, \, \beta\delta}\]

If order="column", then:

\[\Lambda = \sum_{k, l} \, \mathcal{E}(\ketbra{k}{l}) \otimes \ketbra{k}{l} \equiv \mathcal{E}_{\delta\beta, \, \gamma\alpha}\]

Parameters:

super_op – Liouville representation of quantum channel.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of quantum channel.

Return type:

ndarray

Liouville to Pauli-Liouville#

qibo.quantum_info.liouville_to_pauli(super_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Liouville representation \(\mathcal{E}\) of a quantum channel to its Pauli-Liouville representation.

Parameters:

super_op (ndarray) – superoperator in the Liouville representation._
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", it assumes super_op is in row-vectorization. If "column", it assumes column-vectorization. If "system", it assumes block-vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements in the basis. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

superoperator in the Pauli-Liouville representation.

Return type:

ndarray

Liouville to Kraus#

qibo.quantum_info.liouville_to_kraus(super_op, precision_tol: float | None = None, order: str = 'row', backend=None)[source]#

Converts Liouville representation \(\mathcal{E}\) of a quantum channel to its Kraus representation \(\{K_{\alpha}\}_{\alpha}\). It uses the Choi representation as an intermediate step.

\[\{K_{\alpha}, \, \lambda_{\alpha}\}_{\alpha} = \text{choi_to_kraus}(\text{liouville_to_choi}(\mathcal{E}))\]

Parameters:

super_op (ndarray) – Liouville representation of quantum channel.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda < \text{precision_tol}\) is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Kraus operators of quantum channel and their respective coefficients.

Return type:

(ndarray, ndarray)

Note

\[K_{\alpha} \, \rho \, K_{\alpha}^{\dagger} = K_{\alpha}^{\text{(ideal)}} \, \rho \,\, (K_{\alpha}^{\text{(ideal)}})^{\dagger} \,\,\,\,\, , \,\, \forall \, \alpha\]

Liouville to Chi-matrix#

qibo.quantum_info.liouville_to_chi(super_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Liouville representation of quantum channel \(\mathcal{E}\) to its \(\chi\)-matrix representation. It uses the Choi representation as an intermediate step.

\[\chi = \text{liouville_to_pauli}(\text{liouville_to_choi}(\mathcal{E}))\]

Parameters:

super_op – Liouville representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements in the basis. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Chi-matrix representation of quantum channel.

Return type:

ndarray

Liouville to Stinespring#

qibo.quantum_info.liouville_to_stinespring(super_op, order: str = 'row', precision_tol: float | None = None, validate_cp: bool = True, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Converts Liouville representation \(\mathcal{E}\) of quantum channel to its Stinespring representation \(U_{0}\). It uses the Choi representation \(\Lambda\) as intermediate step.

Parameters:

super_op – Liouville representation of quantum channel.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits kraus_ops acts on. If None, defaults to the number of qubits in kraus_ops. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Stinespring representation of quantum channel.

Return type:

ndarray

Pauli-Liouville to Liouville#

qibo.quantum_info.pauli_to_liouville(pauli_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Pauli-Liouville representation of a quantum channel to its Liouville representation \(\mathcal{E}\).

Parameters:

pauli_op (ndarray) – Pauli-Liouville representation of a quantum channel.
normalize (bool, optional) – If True assumes pauli_op is represented in the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", returns Liouville representation in row-vectorization. If "column", returns column-vectorized superoperator. If "system", superoperator will be in block-vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

superoperator in the Liouville representation.

Return type:

ndarray

Pauli-Liouville to Choi#

qibo.quantum_info.pauli_to_choi(pauli_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Pauli-Liouville representation of a quantum channel to its Choi representation \(\Lambda\).

Parameters:

pauli_op (ndarray) – superoperator in the Pauli-Liouville representation.
normalize (bool, optional) – If True assumes pauli_op is represented in the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", returns Choi representation in row-vectorization. If "column", returns column-vectorized superoperator. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of the superoperator.

Return type:

ndarray

Pauli-Liouville to Kraus#

qibo.quantum_info.pauli_to_kraus(pauli_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', precision_tol: float | None = None, backend=None)[source]#

Converts Pauli-Liouville representation of a quantum channel to its Kraus representation \(\{K_{\alpha}\}_{\alpha}\).

Parameters:

pauli_op (ndarray) – superoperator in the Pauli-Liouville representation.
normalize (bool, optional) – If True assumes pauli_op is represented in the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – vectorization order of the Liouville and Choi intermediate steps. If "row", row-vectorizationcis used for both representations. If "column", column-vectorization is used. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Kraus operators and their coefficients.

Return type:

(ndarray, ndarray)

Pauli-Liouville to Chi-matrix#

qibo.quantum_info.pauli_to_chi(pauli_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Pauli-Liouville representation of a quantum channel to its \(\chi\)-matrix representation.

Parameters:

pauli_op (ndarray) – superoperator in the Pauli-Liouville representation.
normalize (bool, optional) – If True assumes pauli_op is represented in the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", returns Choi representation in row-vectorization. If "column", returns column-vectorized superoperator. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Chi-matrix representation of the quantum channel.

Return type:

ndarray

Pauli-Liouville to Stinespring#

qibo.quantum_info.pauli_to_stinespring(pauli_op, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', precision_tol: float | None = None, validate_cp: bool = True, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Converts Pauli-Liouville representation \(\mathcal{E}_{P}\) of quantum channel to its Stinespring representation \(U_{0}\). It uses the Liouville representation \(\mathcal{E}\) as intermediate step.

Parameters:

pauli_op (ndarray) – Pauli-Liouville representation of a quantum channel.
normalize (bool, optional) – If True assumes pauli_op is represented in the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", returns Liouville representation in row-vectorization. If "column", returns column-vectorized superoperator. If "system", superoperator will be in block-vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits kraus_ops acts on. If None, defaults to the number of qubits in kraus_ops. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Stinestring representation of quantum channel.

Return type:

ndarray

Chi-matrix to Choi#

qibo.quantum_info.chi_to_choi(chi_matrix, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Convert the \(\chi\)-matrix representation of a quantum channel to its Choi representation \(\Lambda\).

\[\Lambda = \text{pauli_to_liouville}(\chi)\]

Parameters:

chi_matrix – Chi-matrix representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of quantum channel.

Return type:

ndarray

Chi-matrix to Liouville#

qibo.quantum_info.chi_to_liouville(chi_matrix, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts the \(\chi\)-matrix representation of a quantum channel to its Liouville representation \(\mathcal{E}\).

\[\mathcal{E} = \text{pauli_to_liouville}(\text{choi_to_liouville}(\chi))\]

Parameters:

chi_matrix – Chi-matrix representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Liouville representation of quantum channel.

Return type:

ndarray

Chi-matrix to Pauli-Liouville#

qibo.quantum_info.chi_to_pauli(chi_matrix, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Convert \(\chi\)-matrix representation of a quantum channel to its Pauli-Liouville representation \(\mathcal{E}_P\).

\[\mathcal{E}_P = \text{choi_to_pauli}(\text{chi_to_choi}(\chi))\]

Parameters:

chi_matrix – Chi-matrix representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

superoperator in the Pauli-Liouville representation.

Return type:

ndarray

Chi-matrix to Kraus#

qibo.quantum_info.chi_to_kraus(chi_matrix, normalize: bool = False, precision_tol: float | None = None, order: str = 'row', pauli_order: str = 'IXYZ', validate_cp: bool = True, backend=None)[source]#

Converts the \(\chi\)-matrix representation of a quantum channel to its Kraus representation \(\{K_{\alpha}\}_{\alpha}\).

\[\mathcal{E}_P = \text{choi_to_kraus}(\text{chi_to_choi}(\chi))\]

Parameters:

chi_matrix – Chi-matrix representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Kraus operators and their coefficients.

Return type:

(ndarray, ndarray)

Note

\[K_{\alpha} \, \rho \, K_{\alpha}^{\dagger} = K_{\alpha}^{\text{(ideal)}} \, \rho \,\, (K_{\alpha}^{\text{(ideal)}})^{\dagger} \,\,\,\,\, , \,\, \forall \, \alpha\]

Note

User can set validate_cp=False in order to speed up execution by not checking if the Choi representation obtained from the input chi_matrix is completely positive (CP) and Hermitian. However, that may lead to erroneous outputs if choi_super_op is not guaranteed to be CP. We advise users to either set this flag carefully or leave it in its default setting (validate_cp=True).

Chi-matrix to Stinespring#

qibo.quantum_info.chi_to_stinespring(chi_matrix, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', precision_tol: float | None = None, validate_cp: bool = True, nqubits: int | None = None, initial_state_env=None, backend=None)[source]#

Converts \(\chi\)-representation of quantum channel to its Stinespring representation \(U_{0}\). It uses the Choi representation \(\Lambda\) as intermediate step.

Parameters:

chi_matrix – Chi-matrix representation of quantum channel.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
precision_tol (float, optional) – Precision tolerance for eigenvalues found in the spectral decomposition problem. Any eigenvalue \(\lambda <\) precision_tol is set to 0 (zero). If None, precision_tol defaults to qibo.config.PRECISION_TOL=1e-8. Defaults to None.
order – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
validate_cp (bool, optional) – If True, checks if choi_super_op is a completely positive map. If False, it assumes that choi_super_op is completely positive (and Hermitian). Defaults to True.
nqubits (int, optional) – total number of qubits in the system that is interacting with the environment. Must be equal or greater than the number of qubits kraus_ops acts on. If None, defaults to the number of qubits in kraus_ops. Defauts to None.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Stinespring representation of quantum channel.

Return type:

ndarray

Stinespring to Choi#

qibo.quantum_info.stinespring_to_choi(stinespring, dim_env: int, initial_state_env=None, nqubits: int | None = None, order: str = 'row', backend=None)[source]#

Converts Stinespring representation \(U_{0}\) of quantum channel to its Choi representation \(\Lambda\).

\[\Lambda = \text{kraus_to_choi}(\text{stinespring_to_kraus}(U_{0}))\]

Parameters:

stinespring (ndarray) – quantum channel in the Stinespring representation.
dim_env (int) – dimension of the Hilbert space of the environment.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
nqubits (int, optional) – number of qubits in the system. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Choi representation of quantum channel.

Return type:

ndarray

Stinespring to Liouville#

qibo.quantum_info.stinespring_to_liouville(stinespring, dim_env: int, initial_state_env=None, nqubits: int | None = None, order: str = 'row', backend=None)[source]#

Converts Stinespring representation \(U_{0}\) of quantum channel to its Liouville representation \(\mathcal{E}\) via Stinespring Dilation, i.e.

\[\mathcal{E} = \text{kraus_to_liouville}(\text{stinespring_to_kraus}(U_{0}))\]

Parameters:

stinespring (ndarray) – quantum channel in the Stinespring representation.
dim_env (int) – dimension of the Hilbert space of the environment.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
nqubits (int, optional) – number of qubits in the system. Defaults to None.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Liouville representation of quantum channel.

Return type:

ndarray

Stinespring to Pauli-Liouville#

qibo.quantum_info.stinespring_to_pauli(stinespring, dim_env: int, initial_state_env=None, nqubits: int | None = None, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Stinespring representation \(U_{0}\) of quantum channel to its Pauli-Liouville representation \(\mathcal{E}_{P}\) via Stinespring Dilation, i.e.

\[\mathcal{E}_{P} = \text{kraus_to_pauli}(\text{stinespring_to_kraus}(U_{0}))\]

Parameters:

stinespring (ndarray) – quantum channel in the Stinespring representation.
dim_env (int) – dimension of the Hilbert space of the environment.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
nqubits (int, optional) – number of qubits in the system. Defaults to None.
normalize (bool, optional) – If True superoperator is returned in the normalized Pauli basis. If False, it is returned in the unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", intermediate step for Choi representation is done in row-vectorization. If "column", step is done in column-vectorization. If "system", block-vectorization is performed. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Pauli-Liouville representation of quantum channel.

Return type:

ndarray

Stinespring to Kraus#

qibo.quantum_info.stinespring_to_kraus(stinespring, dim_env: int, initial_state_env=None, nqubits: int | None = None, backend=None)[source]#

Converts the Stinespring representation \(U_{0}\) of quantum channel to its Kraus representation \(\{K_{\alpha}\}_{\alpha}\), i.e.

\[K_{\alpha} := \bra{\alpha} \, U_{0} \, \ket{v_{0}} \, ,\]

where \(\ket{v_{0}}\) is the initial state of the environment (initial_state_env), \(D\) is the dimension of the environment’s Hilbert space, and \(\{\ket{\alpha} \, : \, \alpha = 0, 1, \cdots, D - 1 \}\) is an orthonormal basis for the environment’s Hilbert space. Note that \(\text{dim}(\ket{\alpha}) = \text{dim}(\ket{v_{0}}) = D\), while \(\text{dim}(U) = 2^{n} \, D\), where \(n\) is nqubits.

Parameters:

stinespring (ndarray) – quantum channel in the Stinespring representation.
dim_env (int) – dimension of the Hilbert space of the environment.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
nqubits (int, optional) – number of qubits in the system. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Kraus operators.

Return type:

ndarray

Stinespring to Chi-matrix#

qibo.quantum_info.stinespring_to_chi(stinespring, dim_env: int, initial_state_env=None, nqubits: int | None = None, normalize: bool = False, order: str = 'row', pauli_order: str = 'IXYZ', backend=None)[source]#

Converts Stinespring representation \(U_{0}\) of quantum channel to its \(\chi\)-matrix representation via Stinespring Dilation, i.e.

\[\chi = \text{kraus_to_chi}(\text{stinespring_to_kraus}(U_{0}))\]

Parameters:

stinespring (ndarray) – quantum channel in the Stinespring representation.
dim_env (int) – dimension of the Hilbert space of the environment.
initial_state_env (ndarray, optional) – statevector representing the initial state of the enviroment. If None, it assumes the environment in its ground state. Defaults to None.
nqubits (int, optional) – number of qubits in the system. Defaults to None.
normalize (bool, optional) – If True assumes the normalized Pauli basis. If False, it assumes unnormalized Pauli basis. Defaults to False.
order (str, optional) – If "row", reshuffling is performed with respect to row-wise vectorization. If "column", reshuffling is performed with respect to column-wise vectorization. If "system", operator is converted to a representation based on row vectorization, reshuffled, and then converted back to its representation with respect to system-wise vectorization. Defaults to "row".
pauli_order (str, optional) – corresponds to the order of 4 single-qubit Pauli elements in the Pauli basis. Defaults to “IXYZ”.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

\(\chi\)-representation of quantum channel.

Return type:

ndarray

Kraus operators as probabilistic sum of unitaries#

qibo.quantum_info.kraus_to_unitaries(kraus_ops, order: str = 'row', precision_tol: float | None = None, backend=None)[source]#

Tries to convert Kraus operators into a probabilistc sum of unitaries.

Given a set of Kraus operators \(\{K_{\alpha}\}_{\alpha}\), returns an ensemble \(\{U_{\alpha}, p_{\alpha}\}\) that defines an qibo.gates.channels.UnitaryChannel that approximates the original channel up to a precision tolerance in Frobenius norm.

Parameters:

kraus_ops (list) – List of Kraus operators as pairs (qubits, Ak) where qubits refers the qubit ids that \(A_k\) acts on and \(A_k\) is the corresponding matrix as a np.ndarray.
order (str, optional) – _description_. Defaults to “row”.
precision_tol (float, optional) – Precision tolerance for the minimization of the Frobenius norm \(\| \mathcal{E}_{K} - \mathcal{E}_{U} \|_{F}\), where \(\mathcal{E}_{K}\) is the Liouville representation of the Kraus channel \(\{K_{\alpha}\}_{\alpha}\), and \(\mathcal{E}_{U}\) is the Liouville representaton of the qibo.gates.channels.UnitaryChannel that best approximates the original channel. If None, precision_tol defaults to 1e-7. Defaults to None.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Unitary operators and their associated probabilities.

Return type:

(ndarray, ndarray)

Note

It is not guaranteed that a good approximation will be found or that any approximation will be found at all. This functions will find good solutions for a limited set of operators. We leave to the user to decide how to best use this function.

Utility Functions#

Functions that can be used to calculate metrics and distance measures on classical probability arrays.

Hamming weight#

qibo.quantum_info.hamming_weight(bitstring: int | str | list | tuple, return_indexes: bool = False)[source]#

Calculates the Hamming weight of a bitstring.

The Hamming weight of a bistring is the number of :math:’1’s that the bistring contains.

Parameters:

bitstring (int or str or tuple or list) – bitstring to calculate the weight, either in binary or integer representation.
return_indexes (bool, optional) – If True, returns the indexes of the non-zero elements. Defaults to False.

Returns:

Hamming weight of bitstring or list of indexes of non-zero elements.

Return type:

int or list

Hamming distance#

Calculates the Hamming distance between two bistrings.

This is done by calculating the Hamming weight (qibo.quantum_info.utils.hamming_weight()) of | bitstring_1 - bitstring_2 |.

Parameters:

bitstring_1 (int or str or list or tuple) – fisrt bistring.
bitstring_2 (int or str or list or tuple) – second bitstring.
return_indexes (bool, optional) – If True, returns the indexes of the non-zero elements. Defaults to False.

Returns:

Hamming distance or list of indexes of non-zero elements.

Return type:

int or list

Hadamard Transform#

qibo.quantum_info.hadamard_transform(array, implementation: str = 'fast', backend=None)[source]#

Calculates the (fast) Hadamard Transform \(\text{HT}\) of a \(2^{n}\)-dimensional vector or \(2^{n} \times 2^{n}\) matrix \(A\), where \(n\) is the number of qubits in the system. If \(A\) is a vector, then

\[\text{HT}(A) = \frac{1}{2^{n / 2}} \, H^{\otimes n} \, A \,\]

where \(H\) is the qibo.gates.H gate. If \(A\) is a matrix, then

\[\text{HT}(A) = \frac{1}{2^{n}} \, H^{\otimes n} \, A \, H^{\otimes n} \, .\]

Parameters:

array (ndarray) – array or matrix.
implementation (str, optional) – if "regular", it uses the straightforward implementation of the algorithm with computational complexity of \(\mathcal{O}(2^{2n})\) for vectors and \(\mathcal{O}(2^{3n})\) for matrices. If "fast", computational complexity is \(\mathcal{O}(n \, 2^{n})\) in both cases.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

(Fast) Hadamard Transform of array.

Return type:

ndarray

Hellinger distance#

qibo.quantum_info.hellinger_distance(prob_dist_p, prob_dist_q, validate: bool = False, backend=None)[source]#

Calculates the Hellinger distance \(H\) between two discrete probability distributions.

For probabilities \(\mathbf{p}\) and \(\mathbf{q}\), it is defined as

\[H(\mathbf{p} \, , \, \mathbf{q}) = \frac{1}{\sqrt{2}} \, \| \sqrt{\mathbf{p}} - \sqrt{\mathbf{q}} \|_{2}\]

where \(\|\cdot\|_{2}\) is the Euclidean norm.

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
validate (bool, optional) – If True, checks if \(p\) and \(q\) are proper probability distributions. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hellinger distance \(H(p, q)\).

Return type:

(float)

Hellinger fidelity#

qibo.quantum_info.hellinger_fidelity(prob_dist_p, prob_dist_q, validate: bool = False, backend=None)[source]#

Calculates the Hellinger fidelity between two discrete probability distributions.

For probabilities \(p\) and \(q\), the fidelity is defined as

\[(1 - H^{2}(p, q))^{2} \, ,\]

where \(H(p, q)\) is the qibo.quantum_info.utils.hellinger_distance().

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
validate (bool, optional) – if True, checks if \(p\) and \(q\) are proper probability distributions. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hellinger fidelity.

Return type:

Hellinger shot error#

qibo.quantum_info.hellinger_shot_error(prob_dist_p, prob_dist_q, nshots: int, validate: bool = False, backend=None)[source]#

Calculates the Hellinger fidelity error between two discrete probability distributions estimated from finite statistics.

It is calculated propagating the probability error of each state of the system. The complete formula is:

\[\frac{1 - H^{2}(p, q)}{\sqrt{nshots}} \, \sum_{k} \, \left(\sqrt{p_{k} \, (1 - q_{k})} + \sqrt{q_{k} \, (1 - p_{k})}\right)\]

where \(H(p, q)\) is the qibo.quantum_info.utils.hellinger_distance(), and \(1 - H^{2}(p, q)\) is the square root of the qibo.quantum_info.utils.hellinger_fidelity().

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
nshots (int) – number of shots we used to run the circuit to obtain \(p\) and \(q\).
validate (bool, optional) – if True, checks if \(p\) and \(q\) are proper probability distributions. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Hellinger fidelity error.

Return type:

Total variation distance#

qibo.quantum_info.total_variation_distance(prob_dist_p, prob_dist_q, validate: bool = False, backend=None)[source]#

Calculate the total variation distance between two discrete probability distributions.

For probabilities \(p\) and \(q\), the total variation distance is defined as

\[\operatorname{TVD}(p, \, q) = \frac{1}{2} \, \|p - q\|_{1} = \frac{1}{2} \, \sum_{x} \, \left|p(x) - q(x)\right| \, ,\]

where \(\|\cdot\|_{1}\) detones the \(\ell_{1}\)-norm.

Parameters:

prob_dist_p (ndarray or list) – discrete probability distribution \(p\).
prob_dist_q (ndarray or list) – discrete probability distribution \(q\).
validate (bool, optional) – if True, checks if \(p\) and \(q\) are proper probability distributions. Defaults to False.
backend (qibo.backends.abstract.Backend, optional) – backend to be used in the execution. If None, it uses the current backend. Defaults to None.

Returns:

Total variation distance measure.

Return type: