Simulation¶

`trueq.Simulator`	A (noisy) quantum simulator for `Circuit` objects that can be used to compute the final `state()`, the total effective `operator()`, or simply `run()` them to `sample()` shots.
`trueq.Simulator.add_depolarizing`	Appends a noise source to this simulator that adds isotropic depolarizing noise to the simulation.
`trueq.Simulator.add_kraus`	Appends a noise source to this simulator that adds Kraus noise to the simulation.
`trueq.Simulator.add_overrotation`	Appends a noise source to this simulator that performs gate over/underrotation.
`trueq.Simulator.add_povm`	Appends measurement noise in the form of a positive operator-valued measurement (POVM).
`trueq.Simulator.add_prep`	Appends a state preparation description to this simulator that chooses which state to prepare whenever a `Prep` operator is encountered in a circuit.
`trueq.Simulator.add_readout_error`	Appends measurement classification error to this simulator, where errors are specified by confusion matrices.
`trueq.Simulator.add_relaxation`	Appends a noise source to this simulator that adds $T_1$ and $T_2$ relaxation noise to the simulation.
`trueq.Simulator.add_stochastic_pauli`	Appends a noise source to this simulator that introduces stochastic Pauli noise.
`trueq.Simulator.operator`	Returns the unitary or superoperator that results from simulating the given circuit.
`trueq.Simulator.run`	Updates the `results` attribute of each given circuit by simulating its final quantum state and sampling shots from it.
`trueq.Simulator.state`	Returns the quantum state that results from simulating the given circuit.
`trueq.Simulator.dressed_noise`	Computes the dressed noise of the given cycle for every list of labels in `labels_list`.
`trueq.Simulator.predict_cb`	Predicts the estimates that would be generated by simulating `make_cb()` with this simulator.
`trueq.Simulator.predict_irb`	Predicts the estimates that would be generated by simulating `make_irb()` with this simulator.
`trueq.Simulator.predict_knr`	Predicts the estimates that would be generated by simulating `make_knr()` with this simulator.
`trueq.Simulator.predict_srb`	Predicts the estimates that would be generated by simulating `make_srb()` with this simulator.
`trueq.simulation.simulator.CyclePropagator`	Wraps a function that mutates quantum states or operators by given circuit cycles.

Simulator¶

class trueq.Simulator¶

A (noisy) quantum simulator for Circuit objects that can be used to compute the final state(), the total effective operator(), or simply run() them to sample() shots.

import trueq as tq

# initialize a simulator with no noise present
sim = tq.Simulator()

# initialize a simulator with depolarizing noise at rate 1%
sim = tq.Simulator().add_depolarizing(0.01)

# initialize a simulator with depolarizing noise at rate 1%, and unitary
# overration by 5%
sim = tq.Simulator().add_depolarizing(0.01).add_overrotation(0.05)

# make some circuits and populate their results with random shots
circuits = tq.make_srb([0], [4, 60])
sim.run(circuits, n_shots=100)
circuits[0].results

Results({'0': 8, '1': 92})

append_cycle_noise(propagation_fn, noise_only=False, is_prep=False, is_meas=False, dim=None)¶

Appends a custom noise source to the simulator. A noise source is a function with arguments (cycle, state, cache) that takes a Cycle and uses it to modify a state, which is an instance of Tensor.

import trueq
import numpy as np

# create a circuit to test on
circuit = tq.Circuit([{0: tq.Prep()}, {0: tq.Gate.x}, {0: tq.Meas()}])

# an ideal pure state simulator with no caching
def fun(cycle, state, cache):
    for labels, gate in cycle.gates.items():
        state.apply_matrix(labels, gate.mat)
sim = trueq.Simulator()
results = sim.append_cycle_noise(fun).sample(circuit, 100)
print("Ideal example:", results)

# an ideal simulator that prepares the |+> state every time a Prep is found
def fun(cycle, state, cache):
    for label in cycle.prep_labels:
        state.update({(label,): [1 / np.sqrt(2), 1 / np.sqrt(2)]})
sim = trueq.Simulator()
results = sim.append_cycle_noise(fun, is_prep=True).sample(circuit, 100)
print("Prep example: ", results)

# simulator that applies a Kraus map iid to all qubits (note that
# Simulator.add_kraus is built-in and does the same thing)
kraus_ops = [np.sqrt(0.9)*np.eye(2), np.sqrt(0.1)*np.array([[0,1],[1,0]])]
S = sum(np.kron(a, a.conj().T) for a in kraus_ops)
def fun(cycle, state, cache):
    for labels, gate in cycle.gates.items():
        for label in labels:
            state.apply_matrix((label,), S)
sim = trueq.Simulator()
# the function prop does not apply gates in a cycle, so we are careful to
# set noise_only to True
results = sim.append_cycle_noise(fun, noise_only=True).sample(circuit, 100)
print("Kraus example:", results)

Ideal example: Results({'1': 100})
Prep example:  Results({'0': 52, '1': 48})
Kraus example: Results({'0': 9, '1': 91})

Parameters

propagation_fn (function) – A function with arguments (cycle, state, cache) that takes a Cycle and uses it to modify a state (an instance of Tensor). cache is a dictionary that is unique to this CyclePropagator that can be used in any way to cache computations.
noise_only (bool) – True if and only if this propagator only injects noise into the state, i.e. it does not attempt to actually implement the cycle.
is_prep (bool) – Whether this propagator is used as a state preparer. This propagator is applied before any other on each cycle.
is_meas (bool) – Whether this propagator is used to simulate measurement. This propagator is integrated with measurement sampling and is applied only at the last cycle.
dim (None | int) – The Hilbert space dimension of each subsystem expected by this propagator. A value of None indicates that this propagator can propagate cycles of any dimension.

Returns

This simulator instance

Return type

Simulator

Raises

ValueError – If the dim provided does not match the simulator’s dimension.

state(circuit)¶

Returns the quantum state that results from simulating the given circuit.

If this simulator contains only unitary errors and pure state preparations, a pure state will be simulated and returned, otherwise, a density matrix will be simulated and returned. Unless this simulator contains a special preparation (see e.g. add_prep()), every qubit in the circuit will be prepared with the state $|0\rangle$.

import trueq as tq

# make a circuit with two clock cycles
circuit = tq.Circuit([{(0, ): tq.Gate.h}, {(0, 1): tq.Gate.cnot}])

# simulate the circuit to find the final pure state
psi = tq.Simulator().state(circuit)
print("Pure state: ", psi.mat())

# if we add depolarizing noise we get a density matrix
rho = tq.Simulator().add_depolarizing(0.01).state(circuit)
print("Density matrix: ", rho.mat())

# we can get outcome probabilities from the state
print("Pure state probabilities:     ", psi.probabilities())
print("Density matrix probabilities: ", rho.probabilities())

# and we can convert them to Result objects
print("Pure state as results:     ", psi.probabilities().to_results())
print("Density matrix as results: ", rho.probabilities().to_results())

Pure state:  [0.70710678+0.j 0.        +0.j 0.        +0.j 0.70710678+0.j]
Density matrix:  [[0.495025 +0.j 0.       +0.j 0.       +0.j 0.4851495+0.j]
 [0.       +0.j 0.004975 +0.j 0.       +0.j 0.       +0.j]
 [0.       +0.j 0.       +0.j 0.004975 +0.j 0.       +0.j]
 [0.4851495+0.j 0.       +0.j 0.       +0.j 0.495025 +0.j]]
Pure state probabilities:      Tensor(<[(2,), ()] on labels [(0, 1)]>)
Density matrix probabilities:  Tensor(<[(2,), ()] on labels [(0, 1)]>)
Pure state as results:      Results({'00': 0.5000000000000001, '11': 0.5000000000000001})
Density matrix as results:  Results({'00': 0.49502500000000016, '01': 0.004975000000000002, '10': 0.004975000000000002, '11': 0.49502500000000016})

Parameters: circuit (Circuit) – A circuit to find the final state of.
Return type: StateTensor
Raises: NotImplementedError – If the circuit contains measurements before the final cycle.

operator(circuit, gates_only=True)¶

Returns the unitary or superoperator that results from simulating the given circuit.

If this simulator contains only unitary errors and pure state preparations, a unitary will be simulated and returned, otherwise, a superoperator will be simulated and returned.

import trueq as tq

# make a circuit with two clock cycles
circuit = tq.Circuit([{(0, ): tq.Gate.h}, {(0, 1): tq.Gate.cnot}])

# simulate the circuit to find the final unitary
u = tq.Simulator().operator(circuit)
tq.visualization.plot_mat(u.mat())

# if we add depolarizing noise we get a superoperator
s = tq.Simulator().add_depolarizing(0.01).operator(circuit)
print("Super operator shape: ", s.mat().shape)

Super operator shape:  (16, 16)

Note

By default, this method skips Prep and Meas operators.

Parameters

circuit (Circuit) – A circuit to find the final operator of.
gates_only (bool) – Whether all Prep and Meas operators found in obj should be skipped during simulation.

Return type

OperatorTensor

Raises

NotImplementedError – If the last cycle in the circuit contains measurements on some qubits but not all.

sample(circuit, n_shots=50)¶

Samples ditstrings from the final state of the simulated circuit. In contrast to run(), this method does not update the results of the circuit.

import trueq as tq

# make a circuit with two clock cycles and a measurement round
circuit = tq.Circuit([{(0, ): tq.Gate.h}, {(0, 1): tq.Gate.cnot}])
circuit.measure_all()

# instantiate a simulator with depolarizing and overrotation noise
sim = tq.Simulator().add_depolarizing(0.01).add_overrotation(0.04)

# sample 100 shots from the final state of the circuit
print(sim.sample(circuit, 100))

Results({'00': 51, '10': 1, '11': 48})

Parameters

circuit (Circuit) – A single circuit.
n_shots (int | float("inf")) – The number of shots to sample. The final state of the circuit is simulated once and shots are drawn from the resulting probability distribution. Or, if this value is infinity-like (e.g. float("inf") or numpy.inf) then results are populated with the exact simulated probabilities.

Return type

Results

run(circuits, n_shots=50, overwrite=None)¶

Updates the results attribute of each given circuit by simulating its final quantum state and sampling shots from it.

import trueq as tq

# make a circuit with two clock cycles and a measurement round
circuit = tq.Circuit([{(0, ): tq.Gate.h}, {(0, 1): tq.Gate.cnot}])
circuit.measure_all()

# initialize a simulator with no noise
sim = tq.Simulator()

# run the circuit on the simulator 100 times to populate the results
sim.run(circuit, n_shots=100)
print(circuit.results)

# instantiate a simulator with depolarizing and overrotation noise
sim = tq.Simulator().add_depolarizing(0.01).add_overrotation(0.04)

# we can also use run to evaluate circuit collections generated by protocols
# like CB, SRB, IRB, and XRB on a simulator:
circuits = tq.make_srb([0], [5, 50, 100], 30)
sim.run(circuits, n_shots=100)
circuits.plot.raw()

Results({'00': 59, '11': 41})

Parameters

circuits (Circuit | Iterable) – A single circuit or an iterable of circuits.
n_shots (int | float("inf")) – The number of shots to sample. The final state of the circuit is simulated once and shots are drawn from the resulting probability distribution. Or, if this value is infinity-like (e.g. float("inf") or numpy.inf) then results are populated with the exact simulated probabilities.
overwrite (bool | None) – If False, a circuit that already has results will have new simulation results added to the old results. If True or None, old results will be erased and replaced with new results, though a warning will be raised in the latter case of None (default).

add_depolarizing(p, d=2, noisy_labels=None, noisy_gates=None)¶

Appends a noise source to this simulator that adds isotropic depolarizing noise to the simulation. By default, noise is added every time a gate is encountered, however, by specifying noisy_labels and/or noisy_gates, the user can design a noise profile which is gate- and/or qubit-dependent. The noise map for a given gate is defined by

\[\mathcal{D}(\rho) = (1-p) \rho + p \text{Tr}(\rho) \mathcal{I} / d\]

where $d=2$ for qubits. If, for example, a two-qubit gate is encountered, the tensor product of two one-qubit depolarizing channels will be simulated. By default, depolarizing noise is applied to every system being acted on by a gate in a given cycle. For example, if qubits (0,1) get a CNOT, and qubit 3 gets an X in a given cycle, then depolarizing noise is applied to only these three qubits, even if the preceeding cycle acted on qubit 2.

Note that this is noise only—it does not try to implement the cycle in question, but only adds noise to it.

import trueq

circuit = tq.Circuit([{(0,1): tq.Gate.cx, 2: tq.Gate.h}])

# make a simulator with depolarizing noise with p=0.02 acting at every
# location where a gate is applied
sim = tq.Simulator().add_depolarizing(0.02)
print(sim.sample(circuit, 1000))

# make a simulator where depolarizing noise acts only on locations where
# gates act on qubit 5
sim = tq.Simulator().add_depolarizing(0.04, noisy_labels = {5})
print(sim.sample(circuit, 1000))

Results({'000': 474, '001': 496, '010': 11, '011': 8, '100': 4, '101': 7})
Results({'000': 511, '001': 489})

Parameters

p (float) – The depolarizing parameter, as defined in the equation above.
d (int) – The subsystem dimension, 2 for qubits.
noisy_labels (int | Iterable) – An integer or iterable of integers specifying which qubit labels are affected by this noise process. All of a gate’s labels must be a subset of the noisy labels in order for it to be impacted by the noise. By default, noisy_labels is None which causes all qubits to undergo this noise process.
noisy_gates (Gate | Iterable) – A gate or iterable of gates which are affected by this noise process. By default, noisy_gates is None and all gates will be acted upon by this noise process.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

Raises

NotImplementedError – If not called for qubits.

add_kraus(kraus_ops, noisy_labels=None, noisy_gates=None)¶

Appends a noise source to this simulator that adds Kraus noise to the simulation. By default, the noise is added every time a gate is encountered. This noise is gate-independent (though it may depend on size of the gate, described below) and the noise map is defined by

\[\mathcal{K}(\rho) = \sum_{i} K_i \rho K_i^\dagger\]

Note that this is noise only—it does not try to implement a given cycle in question, but only adds noise to it.

By default, Kraus noise is applied to every system being acted on by a gate in a given cycle. For example, if qubits (0,1) get a CNOT, and qubit 3 gets an X in a given cycle, then Kraus noise is applied to only these three qubits, even if the preceeding cycle acted on qubit 2.

Optionally, every gate size (determined by the number of labels it acts on) can specify its own set of Kraus operators. If an applicable gate is encountered whose size is not present in the collection of Kraus operators, then the single system (n_sys=1) Kraus operators are applied to every system that the gate acts on.

import trueq as tq
import numpy as np

circuit = tq.Circuit([{(0,1): tq.Gate.cx, 2: tq.Gate.h}])

# define qubit dephasing kraus operators
kraus_ops = [np.sqrt(0.99)*np.eye(2), np.sqrt(0.01)*np.diag([1,-1])]

# initialize a simulator in which qubit dephasing noise acts on every
# location where gates are applied
sim = tq.Simulator().add_kraus(kraus_ops)
print(sim.sample(circuit, 1000))

# qubit dephasing for single qubit gates, but some other kraus channel for
# two-qubit gates
kraus_ops = {
    1: [np.sqrt(0.999) * np.eye(2), np.sqrt(0.001) * np.diag([1, -1])],
    2: [
        np.sqrt(0.99) * np.eye(4),
        np.sqrt(0.01) * np.fliplr(np.diag([1, 1, 1, 1]))
    ],
}

# initialize a simulator with the noise defined above acting at
# every location where a gate acts
sim = tq.Simulator().add_kraus(kraus_ops)
print(sim.sample(circuit, 1000))

# initialize a simulator which applies the above noise when a gate acts
# on qubit 0
sim = tq.Simulator().add_kraus(kraus_ops, noisy_labels={2})
print(sim.sample(circuit, 1000))

# initialize a simulator which applies the above noise when an X gate acts
# on qubit 2 or 3
sim=tq.Simulator()
sim.add_kraus(kraus_ops, noisy_labels={2, 3}, noisy_gates={tq.Gate.x})
print(sim.sample(circuit, 1000))

Results({'000': 497, '001': 503})
Results({'000': 495, '001': 485, '110': 10, '111': 10})
Results({'000': 527, '001': 473})
Results({'000': 515, '001': 485})

Parameters

kraus_ops (list | dict) – Either a list-like of square matrices, each having the dimension of a single system; or, a dictionary whose keys are n_sys and whose values are list-likes of square matrices, specifying the Kraus operators for gates with that value of n_sys.
noisy_labels (int | Iterable) – An integer or iterable of integers specifying which qubit labels are affected by this noise process. All of a gate’s labels must be a subset of the noisy labels in order for it to be impacted by the noise. By default, noisy_labels is None which causes all qubits to undergo this noise process.
noisy_gates (Gate | Iterable) – A gate or iterable of gates which are affected by this noise process. By default, noisy_gates is None and all gates will be acted upon by this noise process.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

Raises

ValueError – If kraus_ops has the wrong dimension or is not a list of square matrices.

add_overrotation(single_sys=0, multi_sys=0, noisy_labels=None, noisy_gates=None)¶

Appends a noise source to this simulator that performs gate over/underrotation. This is done by propagating by the matrix power $U_{err}=U^{(1+\epsilon)}$ instead of the ideal gate $U$.

import trueq as tq

circuit = tq.Circuit([{(0,1): tq.Gate.cx, 2: tq.Gate.h}])

# initialize a simulator in which every single qubit gate is overrotated by
# epsilon=0.01
sim = tq.Simulator().add_overrotation(single_sys=0.01)
print(sim.sample(circuit, 1000))

# initialize a simulator in which every single qubit gate is overrotated by
# epsilon=0.02 and every multi-qubit gate by epsilon=0.04
sim = tq.Simulator().add_overrotation(single_sys=0.02, multi_sys=0.04)
print(sim.sample(circuit, 1000))

# initialize a simulator in which overrotations are applied whenever a gate
# acts on any qubits in {0, 2}
sim = tq.Simulator()
sim.add_overrotation(single_sys=0.02, multi_sys=0.01, noisy_labels={0, 2})
print(sim.sample(circuit, 1000))

Results({'000': 497, '001': 503})
Results({'000': 475, '001': 525})
Results({'000': 526, '001': 474})

Parameters

single_sys (float) – The amount of over/underrotation to apply to gates that act on a single subsystem (ie. single-qubit). A value of 0 corresponds to no overrotation, a negative value corresponds to underrotation, and a positive value corresponds to overrotatian.
multi_sys (float) – The amount of over/underrotation to apply to gates that act on a multiple subsystems (ie. multi-qubit). A value of 0 corresponds to no overrotation, a negative value corresponds to underrotation, and a positive value corresponds to overrotatian.
noisy_labels (int | Iterable) – Which qubit labels are affected by this noise process. All of a gate’s labels must be a subset of the noisy labels in order for it to be impacted by the noise. By default, noisy_labels is None which causes all qubits to undergo this noise process.
noisy_gates (Gate | Iterable) – A gate or iterable of gates which are affected by this noise process. By default, noisy_gates is None and all gates will be acted upon by this noise process.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

add_povm(povm)¶

Appends measurement noise in the form of a positive operator-valued measurement (POVM). This is entered as a Tensor with shape ((k,), (d, d)) where k is the number of outcomes per qubit, and d is the Hilbert state dimension, which must match the simulation. A sum over the k axis must produce the identity matrix for a probability preserving POVM.

import trueq as tq
import numpy as np

# define a set of ideal POVM operators
ideal = np.array([[[1, 0], [0, 0]], [[0, 0], [0, 1]]])

# define a unitary rotation about X by 5 degrees
U = tq.Gate.from_generators("X", 5).mat

# define noisy POVM operators by rotating the ideal POVM operators by U
twisted = [U @ x @ U.conj().T for x in ideal]

# specify how the operations defined above will impact the simulation
# in this instance, the ideal POVMs will act on every qubit, except for
# qubit 0, which will have the twisted POVM (rotation about X)
povm = tq.math.Tensor(
    2, (2, 2),             # num of POVMs, (dimensions of qubit subsystems)
    spawn=ideal,           # default measurement operation
    value={(0,): twisted}, # measurement operation on qubit 0
    dtype=np.complex128    # tensor is real by default
)

# initialize a simulator with the above POVM specifications.
sim = tq.Simulator().add_povm(povm)

# initialize a circuit
circuit = tq.Circuit([{(0, ): tq.Gate.h}, {(0, 1): tq.Gate.cnot}])
circuit.measure_all()

# run the circuit on the simulator
sim.sample(circuit, 100)

Results({'00': 52, '11': 48})

Parameters: povm (Tensor) – A tensor describing a POVM.
Returns: This simulator instance so that add_*() calls can be chained.
Return type: Simulator

add_prep(state)¶

Appends a state preparation description to this simulator that chooses which state to prepare whenever a Prep operator is encountered in a circuit.

A state to add can be specified in any of the following formats:

A number between 0 and 1, representing a bitflip error probability of the ideal preparation $|0\rangle$

A length-$d$ vector, representing a pure state

A $d\times d$ matrix, representing a density matrix

If only one of the above is provided, it is used every time a Prep object is encountered. One can also specify that different subsystems get different errors by providing a dictionary mapping whose values are combination of the above formats; see the examples below.

import trueq as tq

circuit = tq.Circuit([{i: tq.Prep() for i in range(3)}])

# add 5% bitflip error to any qubit
sim = tq.Simulator().add_prep(0.05)
print(sim.sample(circuit, float("inf")))

# add 2% bitflip error by default, but 5% for qubits 1 and 2
sim = tq.Simulator().add_prep({None: 0.02, 2: 0.05, 1: 0.05})
print(sim.sample(circuit, float("inf")))

# add specific density matrix to qubit 1, but 1% bitflip error by default
sim = tq.Simulator().add_prep({None: 0.01, 1: [[0.8, 0.1], [0.1, 0.2]]})
print(sim.sample(circuit, float("inf")))

Results({'000': 0.8573749999999999, '001': 0.045125, '010': 0.045125, '011': 0.0023750000000000004, '100': 0.045125, '101': 0.0023750000000000004, '110': 0.0023750000000000004, '111': 0.00012500000000000003})
Results({'000': 0.8844499999999998, '001': 0.04655, '010': 0.04655, '011': 0.0024500000000000004, '100': 0.01805, '101': 0.00095, '110': 0.00095, '111': 5e-05})
Results({'000': 0.78408, '001': 0.00792, '010': 0.19602, '011': 0.00198, '100': 0.00792, '101': 8e-05, '110': 0.00198, '111': 2e-05})

For state simulation, if a Prep operator is encountered on a subsystem that has previously been initialized, then the register is traced-out and the state is replaced with a new one. For operator simulation, Prep objects are taken as the partial-trace-with-replacement channel $\rho\mapsto\mathrm{Tr}_\text{i}(\rho)\otimes\rho'$ where $i$ is the subsystem label being prepared, $\rho$ is the old state on all subsystems, and $\rho'$ is the new state being prepared on $i$. Although, note that operator() skips preparation objects by default.

Parameters: state (float | numpy.ndarray-like | dict) – A description of quantum states to initialize with.
Returns: This simulator instance so that add_*() calls can be chained.
Return type: Simulator
Raises: ValueError – If inconsistent dimensions are provided.

add_readout_error(default_error=None, errors=None)¶

Appends measurement classification error to this simulator, where errors are specified by confusion matrices. For qubits, errors can instead be specified by a single misclassification probability (symmetric readout error), or a pair of readout errors (asymmetric readout error, where the probability of misclassifying $|0\rangle$ is different than $|1\rangle$).

Errors can differ on individual qubits by singling out their labels in the second argument, see the example below. Similarly, correlated errors can be added by specifying larger confusion matrices and the qubits they act on.

import trueq as tq

# make a test circuit that measures 4 qubits
circuit = tq.Circuit([{range(4): tq.Meas()}])

# all qubits get 1% readout error
sim = tq.Simulator().add_readout_error(0.01)
print(sim.sample(circuit, 200))

# all qubits get 1% readout error, except qubit 1 gets 5% readout error
sim  = tq.Simulator().add_readout_error(0.01, {1: 0.05})
print(sim.sample(circuit, 200))

# all qubits get 1% readout error, except qubit 1 get 5% readout error,
# and qubit 3 get asymmetric readout error of 1% on |0> and 7% on |1>
sim = tq.Simulator().add_readout_error(0.01, {1: 0.05, 3: [0.01,0.07]})
print(sim.sample(circuit, 200))

# we specify correlated measurement errors on qubits (3, 2) with a 4x4
# confusion matrix (row/column order is 00, 01, 10, 11). all other qubits
# get 1% symmetric classification error.
confusion = [
        [0.81, 0.72, 0.72, 0.64],
        [0.09, 0.18, 0.08, 0.16],
        [0.06, 0.08, 0.18, 0.16],
        [0.04, 0.02, 0.02, 0.04]
    ]
sim = tq.Simulator().add_readout_error(0.01, {(3,2):confusion})
print(sim.sample(circuit, 200))

# here we add asymmetric qutrit classification error to all three levels,
# where |0> is reported as a '0' 99% of the time, |1> is reported as a '1'
# 92% of the time, and |2> is reported as a '2' 80% of the time.
# off-diagonals are the probabilities of misclassification into specific
# outcomes corresponding to the row they are located in. we add this error
# specifically to qutrit 2, the rest of the qutrits have ideal measurements.
confusion = [[0.99, 0.03, 0.02], [0.005, 0.92, 0.18], [0.005, 0.05, 0.8]]
sim = tq.Simulator().add_readout_error(errors={2: confusion})
print(sim.sample(circuit, 200))

# classify qutrit measurements into binary outcomes. this situation arises,
# for example, in superconducting qubits when there is leakage into the
# third level of the anharmonic oscillator, but readout always reports a '0'
# or a '1'. we use a rectangular confusion matrix where |2> is classified as
# a '0' 70% of the time, and as a '1' 30% of the time.
confusion = [[0.99, 0.08, 0.7], [0.01, 0.92, 0.3]]
sim = tq.Simulator().add_readout_error(confusion)
print(sim.sample(circuit, 200))

Results({'0000': 196, '0010': 2, '1000': 2})
Results({'0000': 183, '0001': 1, '0010': 4, '0100': 11, '1000': 1})
Results({'0000': 185, '0010': 3, '0100': 10, '1000': 2})
Results({'0000': 151, '0010': 24, '0001': 15, '0011': 7, '0100': 2, '1000': 1})
Results({'0000': 198, '0010': 1, '0020': 1}, dim=3)
Results({'0000': 192, '0001': 4, '0010': 1, '1000': 3})

Parameters

default_error (numpy.ndarray-like | float | float) – Default readout error specificed as a confusion matrix to be applied to all qubits that don’t receive special errors in errors. For qubits, the confusion matrix can be replaced by a single number or pair of numbers for symmetric and asymmetric classification error, respectively. The default no error.
errors (dict) – A dictionary mapping tuples of qubit labels to confusion matrices. For qubits, confusion matrices can be replaced by a single number or pair of numbers for symmetric and asymmetric classification error, respectively.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

Raises

ValueError – For any inconsistencies in the input arguments.

add_relaxation(t1, t2, t_single, t_multi, excited_pop=0)¶

Appends a noise source to this simulator that adds $T_1$ and $T_2$ relaxation noise to the simulation. Specifically, for every cycle in a circuit, this noise source adds error to every qubit in the state defined by the Choi matrix:

\[\begin{split}C = \begin{pmatrix} 1-p(1-e^{-t/T_1}) & 0 & 0 & e^{-t/T_2} \\ 0 & (1-p)e^{-t/T_1} & 0 & 0 \\ 0 & 0 & pe^{-t/T_1} & 0 \\ e^{-t/T_2} & 0 & 0 & 1-(1-p)e^{-t/T_1} \end{pmatrix}\end{split}\]

where $t$ is the time of the longest gate in the cycle (i.e. either t_single or t_multi for an entire cycle).

import trueq

circuit = tq.Circuit([{(0,1): tq.Gate.cx, 2: tq.Gate.h}])

# make a simulator with relaxation noise with t1=100e-6, t2=50e-6,
# single-qubit gate time 25e-9, two qubit gate time 100e-9 and an excited
# equilibrium population 0.01.
sim = tq.Simulator().add_relaxation(100e-6, 50e-6, 25e-9, 100e-9, 0.01)
print(sim.sample(circuit, 1000))

# make a simulator with relaxation noise with t1=10us, single-qubit gate
# time 25ns and two qubit gate time 100ns. t2=5us on all qubits except qubit
# 0 which has t2=2.5us.
t2 = {None: 5e-6, 0: 2.5e-6}
sim = tq.Simulator().add_relaxation(10e-6, t2, 25e-9, 100e-9)
# plot the final state
tq.visualization.plot_mat(sim.state(circuit).mat())

Results({'000': 500, '001': 500})

Parameters

t1 (float | dict) – The $T_1$ time, i.e. the characteristic time of relaxation. These can vary from qubit to qubit, see the example above.
t2 (float | dict) – The $T_2$ time, i.e. the characteristic time of dephasing. These can vary from qubit to qubit, see the example above.
t_single (float) – The time for a single-qubit gate.
t_multi (float) – The time for a multi-qubit gate.
excited_pop (float | dict) – The excited state population at equilibrium.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

add_stochastic_pauli(px=0, py=0, pz=0, noisy_labels=None, noisy_gates=None)¶

Appends a noise source to this simulator that introduces stochastic Pauli noise. This is done by applying the following single-qubit Kraus operators to every qubit that is explicitly acted upon by a gate in a given cycle:

\[\begin{split}K_1 &= \sqrt{1-p_x-p_y-p_z} \mathcal{I} \\ K_2 &= \sqrt{p_x} \sigma_x \\ K_3 &= \sqrt{p_y} \sigma_y \\ K_4 &= \sqrt{p_z} \sigma_z\end{split}\]

Note that this is noise only—it does not try to implement the cycle in question, but only adds noise to it.

By default, this noise is applied to every system being acted on by a gate in a given cycle. For example, if qubits (0,1) get a CNOT, and qubit 3 gets an X in a given cycle, then stochastic Pauli noise is applied to only these three qubits, even if the preceeding cycle acted on qubit 2. However, noisy_labels and noisy_gates allow users to specify which gates and/or qubits are impacted by the noise. For example, if noisy_labels={0, 1} and noisy_gates={tq.Gate.x, tq.Gate.cz} then noise will only be applied in locations where an X gate acts on qubit 0 or 1 and where a CZ gate acts on qubits 0 and 1.

import trueq as tq

circuit = tq.Circuit([{(0,1): tq.Gate.cx, 2: tq.Gate.x, 3: tq.Gate.h}])

# initialize a simulator in which every location where a gate acts undergoes
# Pauli noise with px=0.01 and py=0.04
sim = tq.Simulator().add_stochastic_pauli(px=0.01, py=0.04)
print(sim.sample(circuit, 1000))

# initialize a simulator where every X gate undergoes Pauli noise with
# py=pz=0 and px=0.04
sim = tq.Simulator().add_stochastic_pauli(px=0.04, noisy_gates=tq.Gate.x)
print(sim.sample(circuit, 1000))

Results({'0000': 18, '0001': 13, '0010': 451, '0011': 412, '0101': 2, '0110': 26, '0111': 24, '1001': 1, '1010': 28, '1011': 24, '1111': 1})


Results({'0000': 21, '0001': 16, '0010': 473, '0011': 490})

Parameters

px (float) – The probability of an X error.
py (float) – The probability of a Y error.
pz (float) – The probability of a Z error.
noisy_labels (int | Iterable) – An integer or iterable of integers specifying which qubit labels are affected by this noise process. All of a gate’s labels must be a subset of the noisy labels in order for it to be impacted by the noise. By default, noisy_labels is None which causes all qubits to undergo this noise process.
noisy_gates (Gate | Iterable) – A gate or iterable of gates which are affected by this noise process. By default, noisy_gates is None and all gates will be acted upon by this noise process.

Returns

This simulator instance so that add_*() calls can be chained.

Return type

Simulator

Raises

ValueError – If the probabilities of X, Y, and Z errors sum to more than 1.

dressed_noise(cycle, labels_list, n_randomizations=None, twirl='P', compiler=None)¶

Computes the dressed noise of the given cycle for every list of labels in labels_list. The dressed noise superoperator is defined as

\[\mathcal{E} = \mathbb{E}[ \mathcal{T}^\dagger \mathcal{C}^\dagger \tilde{\mathcal{C}} \tilde{\mathcal{T}} ]\]

where $\mathcal{C}$ is the cycle of interest, $\tilde{\mathcal{C}}$ its noisy simulation, $\mathcal{T}$ an element of the twirling group, $\tilde{\mathcal{T}}$ its noisy simulation, and where the expectation is taken uniformly over the twirling group.

The expectation value is taken in one of two ways. If n_randomizations=None, twirling operations are assumed to be perfect so that the expectation value is a simple function of the diagonal elements of the superoperator $\mathcal{C}^\dagger \tilde{\mathcal{C}}$ in the Pauli vectorization basis. Otherwise, the expectation is computed using n_randomizations Monte-Carlo samples from the twirling group, each of which is simulated with this simulator.

Parameters

cycle (Cycle) – The cycle to find the dressed noise of.
labels_list (Iterable) – A list of lists of labels. Simulations are performed once on all labels present, and marginalizations are performed on each of these lists afterwards.
n_randomizations (int | None) – The number of random twirls to average over. If None, the twirling group is assumed to have a perfect implementation.
twirl (Twirl | str) – The twirling group to use.
compiler (Compiler) – A compiler to run all cycles through before simulating them.

Returns

A list of Tensors, corresponding to the given labels_list. The tensors report Pauli probabilities of the Pauli Kraus map.

Return type

list

predict_cb(cycle, labels=None, n_randomizations=50, targeted_errors=None, twirl='P', compiler=None)¶

Predicts the estimates that would be generated by simulating make_cb() with this simulator.

import trueq as tq

sim = tq.Simulator().add_stochastic_pauli(px=0.01).add_overrotation(0.04)

sim.predict_cb({0: tq.Gate.id, (1,2): tq.Gate.cnot})

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

CB

Paulis

(0,) : Gate.id

(1, 2) : Gate.cx

${e}_{F}$

6.6e-02 (0.0e+00)

${e}_{III}$

9.3e-01 (0.0e+00)

Parameters

labels (Iterable) – A list of which sets of system labels are to be twirled together in each circuit, e.g. [3, [1, 2], 4].
n_randomizations (int | None) – The number of random twirls to average over. If None, the twirling group is assumed to have a perfect implementation.
twirl (Twirl | str) – The twirling group to use.
compiler (Compiler) – A compiler to run all cycles through before simulating them.

Return type

EstimateCollection

Raises

ValueError – If targeted_errors are not all Pauli strings of the correct length.

predict_irb(cycle, n_randomizations=50, targeted_errors=None, twirl='C', compiler=None)¶

Predicts the estimates that would be generated by simulating make_irb() with this simulator.

import trueq as tq

sim = tq.Simulator().add_stochastic_pauli(px=0.01).add_overrotation(0, 0.1)

sim.predict_irb({0: tq.Gate.id, (1,2): tq.Gate.cnot})

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

IRB

Cliffords

(0,) : Gate.id

(1, 2) : Gate.cx

Cliffords

(0,) : Gate.id

(1, 2) : Gate.cx

${e}_{F}$

2.0e-02 (0.0e+00)

8.5e-02 (0.0e+00)

${p}$

9.8e-01 (0.0e+00)

9.1e-01 (0.0e+00)

Parameters

labels (Iterable) – A list of which sets of system labels are to be twirled together in each circuit, e.g. [3, [1, 2], 4].
n_randomizations (int | None) – The number of random twirls to average over. If None, the twirling group is assumed to have a perfect implementation.
twirl (Twirl | str) – The twirling group to use.
compiler (Compiler) – A compiler to run all cycles through before simulating them.

Return type

EstimateCollection

predict_knr(cycle, n_bodies=1, n_randomizations=50, twirl='P', compiler=None)¶

Predicts the estimates that would be generated by simulating make_knr() with this simulator.

import trueq as tq

sim = tq.Simulator().add_stochastic_pauli(px=0.01).add_overrotation(0, 0.1)

cycle = {0: tq.Gate.h, (1,2): tq.Gate.cnot}
prediction = sim.predict_knr(cycle, n_bodies=2)
prediction.plot.knr_heatmap()

Parameters

labels (dict | Cycle) – The cycle to make the prediction for.
n_randomizations (int | None) – The number of random twirls to average over. If None, the twirling group is assumed to have a perfect implementation.
twirl (Twirl | str) – The twirling group to use.
compiler (Compiler) – A compiler to run all cycles through before simulating them.

Return type

EstimateCollection

predict_srb(labels, n_randomizations=50, twirl='C', compiler=None)¶

Predicts the estimates that would be generated by simulating make_srb() with this simulator.

import trueq as tq

sim = tq.Simulator().add_stochastic_pauli(px=0.01).add_overrotation(0.04)

prediction = sim.predict_srb([0, [1,2]])
prediction += sim.predict_srb([0])
prediction += sim.predict_srb([[1, 2]])
prediction.plot.compare_rb()

Parameters

labels (Iterable) – A list of which sets of system labels are to be twirled together in each circuit, e.g. [3, [1, 2], 4].
n_randomizations (int | None) – The number of random twirls to average over. If None, the twirling group is assumed to have a perfect implementation.
twirl (Twirl | str) – The twirling group to use.
compiler (Compiler) – A compiler to run all cycles through before simulating them.

Return type

EstimateCollection

CyclePropagator¶

class trueq.simulation.simulator.CyclePropagator(propagation_fn, noise_only=False, dim=None)¶

Wraps a function that mutates quantum states or operators by given circuit cycles. This is a helper class for Simulator.

from trueq.simulation.simulator import CyclePropagator

# an ideal pure state simulator with no caching
def prop(cycle, state, cache):
    for labels, gate in cycle:
        state.apply_matrix(labels, gate.mat)
cycle_prop = CyclePropagator(prop)

Parameters

propagation_fn (function) – A function with arguments (cycle, state, cache) that takes a Cycle and uses it to modify a state (an instance of Tensor). cache is a dictionary that is unique to this CyclePropagator that can be used in any way to cache computations.
noise_only (bool) – True if and only if this propagator only injects noise into the state, i.e. it does not attempt to actually implement the cycle. See also the documentation of noise_only.
dim (None | int) – The Hilbert space dimension of each subsystem expected by this propagator. A value of None indicates that this propagator can propagate cycles of any dimension.

property dim¶

The Hilbert space dimension of each subsystem expected by this propagator.

Type: int

property noise_only¶

Whether this propagator only injects noise, as opposed to making an attempt to implement operations in a given cycle.

An example of a noise-only propagator is one that multiplies the state or superoperator by a depolarizing channel everytime a gate is encountered; it makes no attempt to actually simulate the gate.

An example of non-noisy-only propagator is an overrotation propagator that simulates the occurence of a gate $G$ with $G^{1+\epsilon}$; if $\epsilon$ is small, it does implement a gate close to $G$.

Type: bool