True-Q™ Changelog

All notable changes to True-Q™ will be documented in this file.

[2.14.3] - 2023-08-24


  • Bumped the required NumPy version to 1.20.0.


  • Dropped support for Python 3.7.

[2.14.2] - 2022-12-20


  • Updated documentation.

[2.14.1] - 2022-10-24


  • Changed trueq.compilation.RCKak to allow randomly compiling with arbitrary multi-qudit gates, which was previously limited to qubits only.

[2.14.0] - 2022-10-06


  • Switched the licensing method used by True-Q to PathWave License Manager. Please see the Readme for new installation instructions and more information on Keysight Licensing.

[2.13.4] - 2022-10-04


  • Added support for trueq.CircuitCollection in trueq.compilation.Compiler.compile().


  • Improved the performance of trueq.compilation.Compiler.compile() when called with multiple instances of trueq.compilation.BackendPass.


  • Fixed a bug in trueq.CircuitCollection.append() where batch circuits were allowed to be passed into the argument without raising a value error.

[2.13.3] - 2022-09-28


  • Added analyze_dim to the options argument of so a user specified dimension can be used instead of the dimension of the circuit collection.

  • Added qudit support for trueq.Simulator.add_knr_noise().


  • Updated the minimum supported version of the optional dependency qiskit to 0.24.0.


  • Fixed a bug in trueq.compilation.Relabel where some keys of the relabeled circuit would not be updated correctly.

  • Fixed a bug in trueq.protocols.make_nox() where the input circuit was copied with results.

  • Fixed a bug in trueq.Simulator.predict_knr() where the simulator would improperly apply the noise to some cycles.

[2.13.2] - 2022-08-22


  • Added the optional argument n_marked to trueq.protocols.make_nox() to reduce the number of NOX circuits and speed up the execution.

  • Added trueq.Subsystems.limit_size() to generate new trueq.Subsystems with elements of length less than a given size.

  • Added optional scalings argument to trueq.compilation.FactoryNoiseTopology to facilitate, for example, radian to degree conversion.


  • Changed trueq.compilation.RCKak to allow randomly compiling with arbitrary multi-qubit gates. Previously, trueq.compilation.RCKak was limited to one- and two-qubit gates.


  • Fixed a bug in CB analysis where the targeted_errors key interacted incorrectly with the labels parameter of

  • Fixed a bug in the trueq.compiler.DeferredSwapper compiler pass that was clearing the circuit keys.

[2.13.1] - 2022-08-04


  • Added tools for fidelity-aware gate decomposition strategies, in particular the following classes were added: trueq.compiler.DecompStrategy, trueq.compiler.FactoryNoiseTopology, trueq.compiler.CPhaseStrategy, trueq.compiler.XYStrategy, trueq.compiler.CPhaseXYJointStrategy, and trueq.compiler.BestCostDecomposer.

  • Added the optional arguments include_vals and include_stds to trueq.estimate.Array.to_dataframe().


  • Changed trueq.protocols.make_nox() so that it also amplifies the noise of cycles that contain trueq.Prep().


  • Fixed a bug where would throw an error if results contained an unexpected outcome, e.g., a 2 in a qubit experiment.

  • Fixed trueq.estimate.Array.to_dataframe() when the array is 1D.

[2.13.0] - 2022-07-28


  • Added trueq.compilation.AllocateLabels and trueq.compilation.DeferredSwapper for compiling circuits to native topologies.

  • Added trueq.protocols.make_nox() to generate circuits for Noiseless Output Extrapolation (NOX).

  • Added options argument to to specify the observables to compute expectation values of when NOX circuits are present.

  • Added the trueq.CircuitCollection.dim property.

  • Added trueq.compilation.RCKak to allow randomly compiling cycles with arbitrary 2-qubit gates.


  • Changed the convention of the Weyl chamber of trueq.math.kak() to 90 >= x >= y >= abs(z) and z >= 0 whenever x == 90. Previously, it had been 180 >= x >= y >= z >= 0, x + y <= 180, and x <= 90 whenever z == 0.

  • Changed the trueq.Circuit.dim property to inherit the dimension of a circuit’s results when it has no cycles presents.

  • Changed trueq.Circuit.append() and trueq.Circuit.prepend() to only allow for insertion of cycles or circuits of the same subsystem dimension.

  • Changed trueq.CircuitCollection.append() to only allow for circuit collections with circuits of the same subsystem dimension.

  • Changed trueq.Results objects to be initialized with a dimension of None when not explicitly set through the dim or value arguments if there are no results.

  • Updated the minimum required MacOS version to Big Sur (11.0).


  • Removed deprecated trueq.EstimateCollection.values(), trueq.math.Frame, trueq.math.pauli_basis, the n_bodies argument of trueq.make_knr(), trueq.compilation.Merge.n_labels, and trueq.Simulator.add_povm().

[2.12.4] - 2022-07-05


  • Added an optional parameter to trueq.compilation.decompose_clifford() for specifying a root vertex of the graph.

  • Added trueq.visualization.Graph.ibmq_7() for creating graphs based on 7 qubit IBMQ devices.


  • Updated the minimum supported version of the optional dependency cirq to 0.8.0.

[2.12.3] - 2022-06-21


  • Added trueq.Subsystems.nearest_neighbour() to generate trueq.Subsystems objects from trueq.visualization.Graph objects.

  • Added edges and labels properties to trueq.visualization.Graph.

  • Added trueq.utils.delayed_import for importing optional packages when they are first invoked rather than at True-Q import time.

  • Added trueq.NormalEstimate.raw, which replaces trueq.NormalEstimate.decays.

  • Added trueq.interface.cirq.load(), trueq.interface.pyquil.load(), and trueq.interface.qiskit.load() for forcing an import of their respective optional third-party libraries, cirq, pyquil, and qiskit.

  • Added trueq.utils.dict_to_words() for converting dictionaries to strings.

  • Added trueq.EstimateCollection.array() for extracting rectangular data from estimate collections in terms of the new class trueq.EstimateArray.

  • Added ability to convert fit estimates to pandas.DataFrame via trueq.EstimateCollection.array().to_dataframe().

  • Added boolean error_bars option to trueq.Results.plot() and trueq.visualization.plot_results().

  • Added trueq.Gate.to_clifford() to generate the trueq.math.Clifford of Clifford gates.

  • Added the trueq.Gate.is_clifford property.


  • True-Q interfaces (Cirq, PyQuil, and Qiskit) no longer import their respective optional third-party libraries at True-Q import time. Instead, they are imported the first time they are required, raising an ImportError if the optional dependency is not available. This has the advantage of improving True-Q import time as unused interfaces will never have their dependency imported. However, it also means that to_trueq() converters cannot be attached to third-party circuit classes at True-Q import time—this is instead done when the third-party library is requested by the interface, including the new load() method on each interface (e.g. trueq.interface.pyquil.load()).

  • trueq.interface.cirq, trueq.interface.pyquil, trueq.interface.qasm, and trueq.interface.qiskit are no longer static classes, but instances of respective classes trueq.interface.cirq_interface.CirqInterface, trueq.interface.pyquil.PyQuilInterface, trueq.interface.qasm_interface.QasmInterface, and trueq.interface.qiskit_interface.QiskitInterface.

  • Instances of the Qiskit trueq.interface.Executor class now use their own instance of trueq.interface.qiskit_interface.QiskitInterface so that any modifications of the specialized conversion compiler no longer affect the interface in the main scope, such as trueq.Circuit.to_qiskit().

  • Updated trueq.compilation.decompose_clifford() to accept a list of labels and trueq.visualization.Graph as optional parameters.

  • The packages cvxpy, cvxopt, scs, qutip, ipywidgets, and IPython are now loaded via trueq.utils.delayed_import rather than trueq.utils.optional_import().


  • Deprecated trueq.NormalEstimate.decays.

  • Deprecated trueq.EstimateCollection.values() in favor of the new method trueq.EstimateCollection.array().


  • Fixed error in trueq.Key.from_dict() when some key value is an empty tuple.

  • Fixed a bug where would return an incorrect expectation value estimate for non-protocol circuits without an assigned measurement basis.

  • Updated trueq.compiler.Relabel to use trueq.math.Weyls objects instead of the string format that was used prior to version 2.12.0.

  • Fixed behavior of trueq.compilation.Merge for max_sys > 1 for cycles containing both single- and multi-qubit gates.

[2.12.2] - 2022-05-17


  • Changed trueq.circuits.Circuit.get_probability() to accept lists of mixed strings of outcomes and observables to estimate the expectation values of.


  • Fixed the default size of the qiskit.QuantumRegister created when converting with trueq.Circuit.to_qiskit() to match the number of qubits in the circuit rather than the value of the largest qubit label.

  • Fixed a random failure in the SRB transpiler example.

  • Fixed trueq.Gate and trueq.math.Superop to properly comply with the NumPy array interface: np.array([x]) and np.array([np.array(x)]) now produce the same result for x of either type.

  • Fixed memory leaks in and trueq.compilation.Merge.

[2.12.1] - 2022-04-29


  • Added trueq.math.auto_base() to find subsystem dimensions from a total dimension.

  • Added trueq.compilation.decompose_control() for decomposing multi-qubit gates as unitaries controlled by a computational basis state on a subsystem.

  • Added dim option to trueq.Gate.controlled() to enable use when the base gate is 1-by-1.

  • Added support for new gates, such as XXPlusYYGate or XXMinusYYGate, that were introduced in Qiskit version 0.35.0.

  • Added trueq.visualization.plot_results() for comparing multiple trueq.Results objects in various styles.

  • Added a clip_to_zero option to trueq.Results.normalized() which allows to clip negative-valued outcomes to zero. The clipping is done by default.

  • Added trueq.CircuitCollection.prepend() to prepend cycles or circuits to a circuit.

  • Added the functions trueq.utils.get_schema(), trueq.utils.get_schema_validator(), and trueq.utils.add_schema_options() for specifying variadic keyword arguments as JSON schemas.

  • Added trueq.Subsystems class to implement lists of lists of labels, e.g., to specify which labels should be grouped together for analysis.

  • Added the ability to pass optional arguments to

  • Added the compiler pass trueq.compilation.MarkBlocks() for group-marking entire blocks of hard cycles.

  • Added trueq.compilation.decompose_clifford() for decomposing multi-qudit Cliffords into circuits of one- and two-qudit gates.

  • Added trueq.math.Stabilizers.apply() for applying Clifford operators to selected subsystems of trueq.math.Stabilizers, trueq.math.StabilizerGroup, or trueq.math.Clifford objects.

  • Added trueq.math.Clifford.swap() for constructing Clifford operations that swap subsystems by a provided permutation.

  • Added the & operator to trueq.math.Clifford for taking the Kronecker product of Clifford operations.

  • Added trueq.math.check_permutation() for checking if the input is a permutation vector.


  • By default, trueq.Results.normalized() removes negative-valued counts before normalizing.

  • Removed marker parameter from trueq.compilation.OneQuditDecomp.native_cycles.

  • Changed the n_bodies argument of trueq.make_knr() to subsystems, allowing for lists of user specified combinations of gate-bodies to be analyzed in addition to the previous functionality.

  • Changed the n_bodies argument of trueq.Simulator.predict_knr() to subsystems to match changes to trueq.make_knr().

  • Changed the compiler passes RCCycle and RCLocal so that when they are applied to circuits whose trueq.Keys contain the keyword "protocol", they do not overwrite the value of key.protocol.


  • Deprecated the n_bodies argument of trueq.make_knr() in favour of subsystems. KNR circuits loaded from previous versions of True-Q will have their n_bodies metadata automatically updated to a corresponding subsystems value to maintain backwards compatibility of fitting.


  • Fixed trueq.compilation.OneQuditDecomp pass so that all returned cycles maintain the marker of the input cycle.

  • Fixed bugs in trueq.interface.Executor that prevented circuits from being saved to a file and prevented the Executor threads from being terminated correctly.

  • Fixed trueq.Simulator.add_cycle_noise() to correctly infer the subsystem dimension to use during simulation.

  • Fixed trueq.Circuits.plot.irb_summary() to ignore irrelevant SRB and XRB experiments rather than raise an assertion error.


  • Removed trueq.backend.api.hide_warnings() and trueq.backend.local.hide_warnings().

  • Removed dim argument from trueq.Simulator.add_cycle_noise() as it should instead be inferred by a combination of the replacement cycle and the simulated cycle.

[2.12.0] - 2022-03-24


  • Added support for qudits throughout the library, e.g., in methods such as generation, analysis, randomized compiling, etc.

  • Added aliases for common qudit gates to trueq.Gate.ALIASES for qudits of dimension 3, 5 and 7.

  • Added trueq.circuits.Circuit.get_probability to estimate the probability of a circuit returning a given outcome.

  • Added trueq.math.Tensor.merge() for manually merging subsystems together.

  • Added trueq.Simulator.add_stochastic_weyl() as an alias to trueq.Simulator.add_stochastic_pauli().

  • Added the option exclusive to trueq.Gate.controlled() to toggle whether the control qubits dictate the exclusive condition for the application of the contolled unitary, or its power.

  • Added trueq.math.Clifford.inverse() for finding the inverse of a Clifford operator.

  • Added trueq.math.rotation.Rotation.from_weyl() as an alias to trueq.math.rotation.Rotation.from_pauli().

  • Added as an alias to trueq.Gate.rp().

  • Added convenience methods trueq.Gate.w(),, and trueq.Gate.fourier() to generate gates for qudits.

  • Added trueq.compilation.RemarkCycles pass which remarks all the marked cycles, in such a way that the new markers start from 1 and increment up for every marked cycle.

  • Added the static construction methods rigetti_octagon(), aspen_11(), and aspen_m_1() to trueq.visualization.Graph.

  • Added trueq.utils.min_max() for finding the minimum and maximum value of a collection of iterables.

  • Added trueq.math.Weyls.delete_duplicates() for deleting duplicate rows.


  • The method trueq.Simulator.dressed_noise() now returns the entire, complete superoperator (or the diagonal of its Pauli transfer matrix) instead of marginalizations to provided subsystems.

  • For all protocols and methods, the trueq.Key names "analyze_decays", "compiled_pauli", "measurement_basis", and "targeted_errors" have had their value type changed from str or tuple of str to trueq.math.Weyls.

  • Moved trueq.compilation.CompilationError to the new trueq.exceptions module.

  • Moved trueq.math.DecompError to the new trueq.exceptions module.

  • Expanded trueq.Simulator.add_stochastic_pauli() to allow multi-qubit and multi-qudit error models.

  • Expanded trueq.math.rotation.Rotation.from_pauli() and tq.Gate.from_generators() to allow qudit Weyl operators.

  • Added legend option to raw() plotter to control whether or not the legend should be plotted.

  • Changed trueq.interface.QiskitMetadata to additionally contain registers, and switched the mapping and meas_pair (renamed to meas_mapping) properties to reference indices of registers. This was done to accommodate the qiskit.Bit.register deprecation.


  • Orbit mixing in trueq.Simulator.dressed_noise() works for more general simulators and cycles.

  • Fixed KNR HTML fit rendering when subset() is used to restrict parameter names.

  • Fixed the basis used by trueq.math.Superop.from_chi(), trueq.math.Superop.chi, and trueq.math.Superop.plot_chi() to match the documentation for subsystem dimensions greater than two.


  • Removed trueq.utils.multiply_pauli_str() in favour of trueq.math.Weyls multiplication.

[2.11.7] - 2022-02-23


  • Added trueq.estimate.base.NormalEstimate.subset() for selecting subsets of parameters whose names match a given pattern.

  • Added trueq.math.Superop.herm_ptm, trueq.math.Superop.from_herm_ptm(), and trueq.math.Superop.plot_herm_ptm() for converting to, converting from, and visualizing the Hermitized Pauli (Weyl) matrix representation.

  • Added trueq.math.unitary_order() to compute the order of a unitary matrix.

  • Added trueq.math.Tensor.unify_structure() method to merge tensors into compatible separable structures.


  • Changed trueq.estimate.base.EstimateCollection.subset() by adding the option to select subsets of parameters whose names match a given pattern.

  • The function plot_mat() is now available in the main trueq namespace, as well as in the existing trueq.visualization namespace.

  • The arguments xlabels and ylabels of trueq.plot_mat() now try to automatically infer the subsystem dimension.


  • Fixed a bug where trueq.protocols.make_rcal() would sometimes generate duplicate circuits on single qubit systems.

[2.11.6] - 2022-02-01


  • Added trueq.math.Superop.chi, trueq.math.Superop.from_chi(), and trueq.math.Superop.plot_chi() for converting to, converting from, and visualizing the chi matrix representation.

  • Added trueq.math.Weyls.indices() for computing a standardized index for each row.

  • Added trueq.Simulator.add_superop() for adding generic superoperator noise.

  • Added the ability for to save to a binary stream, in addition to the existing ability to open a specified filename and save to it.

  • Added individual reset functions for all settings in trueq.settings.

  • Added the method trueq.Results.normalized() which returns new, normalized results.

  • Added the method trueq.Results.__add__() and trueq.Results.__radd__() for taking the union of trueq.Results objects.


  • Changed the row separation character in trueq.math.WeylBase from "/" to "_".

  • Switched the implementation of trueq.Simulator.add_kraus() to a new trueq.simulation.NoiseSource named trueq.simulation.SuperopNoise.

  • The compiler passes RCCycle and RCLocal now issue warnings if they are called on non-trivial circuits, but no randomizations are inserted, likely due to forgotten inclusion of cycle markers.

  • Moved the RCCycle and RCLocal compiler passes from trueq.compilation.common to the new submodule trueq.compilation.rc.

  • Updated documentation.


  • The Qiskit interface no longer raises an error while converting a True-Q circuit to Qiskit format if the provided metadata specifies more qubits than what the True-Q circuit acts on.

  • Fixed trueq.interface.pyquil.defgate_to_factory() for PyQuil DefGates with no parameters.


  • Removed trueq.simulation.KrausNoise in favor of trueq.simulation.SuperopNoise.

[2.11.5] - 2021-12-14


  • Added trueq.math.Clifford.fourier(), and functions to generate Fourier, CZ and CX trueq.math.Clifford gates for qudits.

  • Added trueq.Gate.embed() for embedding gates into larger Hilbert spaces.

  • Added the conversion method trueq.interface.pyquil.defgate_to_factory().

  • Added the modules trueq.simulation.backend and trueq.simulation.propagation_backend.

  • Added the static method trueq.math.Superop.depolarizing() for constructing depolarizing channels.


  • Changed the phase convention of the ** operator on trueq.Gate to be more standard.

  • The attributes trueq.math.Superop.kraus and trueq.math.Superop.rowstack_subsys are now memoized when first accessed.

  • Changed trueq.make_irb() and trueq.make_srb() to return circuits with keys containing measurement_basis explicitly.

  • The actual simulation of a circuit has been separated into a new abstract trueq.simulation.SimulationBackend class with a concrete implementation trueq.simulation.PropagationBackend. A trueq.Simulator can now select a simulation backend during construction.

  • Changed trueq.Simulator.add_readout_error() to additionally support POVMs.

  • Improved the performance of trueq.compilation.Merge, changed its behaviour to never output empty cycles, changed its parent class to trueq.compilation.MarkerPass, and renamed the property n_labels to max_sys.


  • trueq.Simulator.add_povm() has been deprecated in favour of trueq.Simulator.add_readout_error().

  • Deprecated trueq.compilation.Merge.n_labels, it is now called max_sys.

  • Deprecated support for macOS versions older than 11.0 (Big Sur).


  • The PyQuil interface now converts parametric DefGates found inside of programs to trueq.config.GateFactorys while converting to the True-Q circuit format.

  • trueq.interface.Interface.set_config() now checks if it was given a factory that is not allowed.

[2.11.4] - 2021-11-19


  • Added the compiler pass trueq.compilation.RCLocal to perform randomized compiling localized to entangling gates.

  • Added the boolean option enforce_disjoint to trueq.Twirl.union().

  • Added trueq.utils.UpgradePath class.

  • Added the sqrt property and the controlled() method to trueq.Gate objects.


  • trueq.math.Frame and trueq.math.pauli_basis have been deprecated in favor of using trueq.math.WeylDecomp.


  • Updated tests and examples to comply with new argument requirements for matplotlib.subplot() in matplotlib>=3.5.0.

  • Updated Iterable to be imported from rather than collections.

  • Fix tie-breaking edge case in x-label orderings of trueq.CircuitCollection.plot.knr_heatmap().

[2.11.3] - 2021-11-09


  • Fixed bugs in trueq.interface.Executor that occured when submitting circuits to premium or mock Qiskit backends.

[2.11.2] - 2021-11-08


  • Added the class trueq.math.WeylDecomp for decomposing multi-qudit operators in the Weyl operator basis.


  • Allowed functions passed to trueq.Simulator.add_cycle_noise to have a second argument which receives all labels of the circuit currently being simulated.

  • Changed trueq.simulation.CycleMatch to also accept dictionaries as the cycle.

  • Renamed the sys_dim argument to dim in trueq.config.GateFactory constructors and class methods.


  • Fixed HTML display of trueq.Gate inside JupyterLab.


  • Removed the dim argument from trueq.math.general.reshuffle() which is now inferred automatically.

[2.11.1] - 2021-10-25


  • Added trueq.math.make_confusion_matrix() for easily constructing confusion matrices from error probabilities.

  • Added the classes trueq.math.Clifford, StabilizerGroup, and trueq.math.Stabilizers for efficiently storing and manipulating Clifford operations and stabilizer objects.

  • Added trueq.estimate.EstimateCollection.from_dict_list() to pair with to_dict_list() on the same class.

  • Added trueq.Config.from_dict() to pair with to_dict() on the same class.


  • Changed trueq.Simulator.add_readout_error() to construct confusion matrices for qudit systems when given single error rates or vectors, when appropriate.

  • Changed trueq.estimate.Estimate.to_dict() to additionally store the class name.


  • Updated trueq.interface.cirq to match upstream changes when converting measurements.

[2.11.0] - 2021-10-12


  • Added a subsystem dimension to the trueq.math.Superop class. This is entered as an optional argument dim to the constructor and the from_* methods that construct a superoperator from an object that does not specify the dimension. The related properties dim, total_dim, and n_sys were also added.

  • Added a subsystem dimension to the trueq.math.Superop class. This is entered as an optional argument dim to the constructor and the from_* methods that construct a superoperator from an object that does not specify the dimension. The related properties dim, total_dim, and n_sys were also added.

  • Added the static methods eye(), zero(), random_bcsz(), random_constrained_cptp(), random_constrained_unitary(), random_decoherent(), random_stochastic(), and random_unitary() to the trueq.math.Superop class for constructing new superoperators.

  • Added the functions constrained_stick_breaking(), random_constrained_diagonal() and random_constrained_unitary() to trueq.math which return random arrays.

  • Added trueq.utils.flatten() for flattening nested Iterables.

  • Added the arguments xgrid, ygrid, and blocks to trueq.visualization.plot_mat() for drawing guidelines around matrix elements.

  • Added trueq.algorithms.algorithms.bernstein_vazirani() for generating circuits implementing the Bernstein-Vazirani algorithm.

  • Added trueq.algorithms.algorithms.simon() for generating circuits implementing Simon’s algorithm.

  • Added the method trueq.interface.base.Interface.pair_from_trueq_circ() for viewing the trueq.Circuit immediately before it is converted into an external format.

  • Added the argument store_compiled to trueq.interface.Executor which provides the option of saving the compiled circuits to disk, rather than the uncompiled.

  • Added trueq.interface.Executor.block() function that blocks the main thread until all circuits have completed acquisition on the backend.

  • Added Python dependency asteval>=0.9.25 to the requirements.

  • Added the method trueq.KeySet.one_or_none() for retrieving the single value common to a keyword, when it exists.

  • Added the class trueq.math.WeylSet for a set of Weyls whose order does not matter.

  • Allowed trueq.math.WeylBase and subclass constructors to pass another trueq.math.WeylBase in place of a powers matrix and dimension.


  • Updated the trueq.interface.Executor rich display with more features.


  • Fixed various deprecation warnings and errors when working with certain backends in trueq.interface.Executor.


  • Removed trueq.interface.Executor.results().

  • Removed Python dependency simpleeval from the requirements.

  • Removed deprecated d argument of trueq.Simulator.add_depolarizing().


  • Fixed a bug in trueq.math.Superop.is_cp for certain superoperators with non-Hermitian Choi matrices.

[2.10.3] - 2021-09-10


  • Added a convenience method for loading the documentation.

  • Added trueq.compilation.OneQuditDecomp for decompiling cycles of arbitrary single-qudit gates into diagonal gates and rotations between adjacent subspaces.

  • Added trueq.math.weyl.WeylBase.eye() for generating the identity instance.

  • Added trueq.math.weyl.WeylBase.random() for generating random instances.

  • Added trueq.math.Weyls.all() for generating all possible Weyl operators.

  • Added trueq.math.Weyls.herm_mat for generating Hermitian matrices.

  • Added trueq.math.Weyls.iter_sys for iterating over subsystems.

  • Added trueq.math.prime_base() for computing the base prime in a prime power.

  • Added arbitrary subsystem dimension support to trueq.Simulator.add_depolarizing().

  • Added optional argument local to trueq.Simulator.add_depolarizing() for switching between local and global depolarizing noise.

  • Added support for qudit PTMs to trueq.math.Superop.from_ptm() and related properties and methods.


  • Renamed trueq.utils.ProtectedUnpickler to trueq.utils.TrueQUnpickler.


  • Deprecated d argument of trueq.Simulator.add_depolarizing() because the dimension is now inferred automatically.


  • trueq.Key no longer restricts use of the keyword "cycle".

  • Updated obsolete "cycle" keyword to "cycles" in tq.Simulator.predict_*().

  • Fixed a bug in trueq.Cycle equality when cycles are empty but have different dimensions.

  • Fixed a bug in for empty cycles.

[2.10.2] - 2021-08-24


  • Added a method trueq.algorithms.subroutines.qft() which generates a circuit implementing the quantum Fourier transform.

  • Added trueq.math.Superop.lkpd and trueq.math.Superop.plot_lkpd() for leading Kraus polar decompositions.

  • Added the estimate class trueq.estimate.KnrBodyEstimate.

  • Added a dim attribute to trueq.Twirl.

  • Added the class trueq.math.weyl.base.WeylBase.

  • Added the module trueq.settings containing global settings get_dim(), set_dim(), get_cl(), and set_cl().

  • Added the compiler pass trueq.compilation.OneQuditDecomp for decomposing cycles of arbitrary single-qudit gates into subspace rotations.


  • A fit of KNR data now returns trueq.estimate.KnrBodyEstimate instances instead of instances of the more generic trueq.estimate.NormalEstimate class.

  • The first argument of trueq.make_srb(), trueq.make_xrb(), and trueq.make_crosstalk_diagnostics() can now all accept a list of sets of labels, or a trueq.Twirl instance. This behaviour replaces the optional twirl argument of these functions, which has been removed.

  • Renamed the class trueq.math.Weyl to trueq.math.Weyls.


  • Fixed a formatting issue with some fit() HTML displays.

[2.10.1] - 2021-07-16


  • Added trueq.utils.ProtectedUnpickler which safely loads files saved in older versions of True-Q™ containing removed classes.

  • Added dim argument to the constructor of trueq.Cycle.


  • Empty trueq.Cycles now have a default dimension of 2.

  • Changed pyQuil required version to >= 3.0.0 due to upstream changes.

  • Changed Qiskit required version to >= 0.28.0 due to upstream changes.

  • Updated documentation.


  • Updated trueq.inteface.pyquil_interface to support pyQuil v3.


  • trueq.Block was removed.

  • trueq.math.frame.Frame.sparse_superoperator was removed.

  • trueq.math.Weyl.symplectic_dot() was removed.

[2.10.0] - 2021-06-22


  • Added trueq.utils.cached_property decorator for creating class properties whose values are memoized.

  • Extended the allowed replacement types of trueq.Simulator.add_gate_replace() to include trueq.math.superop.Superops, and matrix representations of gates and super operators.

  • Added a parser to convert from the OPENQASM 2.0 format into trueq.Circuits.


  • Updated the minimum required Linux libstdc++ version to 9.3.0.

  • Updated the minimum required MacOS version to Catalina (10.15).

  • Updated the minimum required Windows Microsoft Visual C++ 2015-2019 Redistributable (x64) version to 14.29.30037.


  • Fixed a potential bug when opening a file that was saved by a user without gzip.

  • Fixed various bugs in the QASM interface.


  • Dropped support for Python 3.6.

  • Removed warnings when loading files saved in different versions of True-Q™.

  • Old trueq.compilation.Pass API was removed.

  • Old trueq.Config YAML format support was removed.

  • Old trueq.config.GateFactory API was removed.

  • trueq.compilation.CycleSandwich was removed.

  • trueq.compilation.get_transpiler() was removed.

  • trueq.compilation.Native2QFastDecomp was removed.

  • trueq.compile() was removed.

  • trueq.Compiler.DEFAULT_PASSES was removed.

  • trueq.interface.base.Interface.get_priority_list was removed.

  • trueq.interface.base.Interface.set_priority_list was removed.

  • trueq.math.decompose_su4 was removed.

  • trueq.math.split_gate was removed.

[2.9.5] - 2021-06-08


  • Changed powers of trueq.Gate such that a global phase is deterministically fixed before exponentiation.


  • Fixed a caching bug caused by global phase ambiguities in the noise source trueq.Simulator.add_overrotation().

[2.9.4] - 2021-06-01


  • Added trueq.EstimateCollection.to_dict_list(), which converts an estimate collection into a list of dictionary representations.

  • Added trueq.math.Weyl class for storing lists of Weyl/Pauli operators.


  • Fixed a bug in trueq.Simulator.add_knr_noise() if using an estimate with a failed exponential fit.

  • Fixed a bug preventing the noise trueq.Simulator.add_cycle_noise() from being pickled for simulator multiprocessing.

[2.9.3] - 2021-04-23


  • Added trueq.simulation.match.BaseCycleMatch, trueq.simulation.match.AssociativeCycleMatch, trueq.simulation.match.AndCycleMatch, and trueq.simulation.match.OrCycleMatch classes designed for more general matching conditions to cycles during simulation.

  • Added lag parameter to trueq.simulation.match.CycleMatch to allow matching past cycles.

  • Added trueq.Simulator.add_cycle_noise() which can insert and replace entire cycles with other cycles or noise operations during simulation.


  • Changed trueq.simulation.match.CycleMatch to inherit from the newly added trueq.simulation.match.BaseCycleMatch class, and it now only accepts a single cycle during initialization.

  • Changed all trueq.simulation.Match.iter() functions to accept a history of cycle wrappers.

  • Split trueq.simulation.add_common into trueq.simulation.add_basic and trueq.simulation.add_cycle_noise.


  • Deprecated support for Python 3.6.

[2.9.2] - 2021-03-31


  • Added property is_upgraded to trueq.math.StateTensor and trueq.math.OperatorTensor.

  • Added trueq.math.split_cycle which attempts to split all gates in a cycle into gates that act on as few subsystems as possible.


  • Increased the speed of the trueq.Simulator by improving caching.

  • The method trueq.simulation.NoiseSource.apply() now receives a list of cycles rather than the latest cycle to allow non-Markovian noise in the future.


  • Deprecated trueq.math.split_gate and replaced it by trueq.math.split_cycle.


  • Fixed a regression that caused key.compiled_paulis to not be randomized correctly in protocol generation functions, such as trueq.make_cb().

  • Fixed a bug in KNR analysis which incorrectly analyzed cycles with gate labels out of order, e.g. tq.Cycle({(1, 0): tq.Gate.cnot}).

[2.9.1] - 2021-03-22


  • Added trueq.Circuit.copy() for making copies of circuits.

  • Added trueq.CircuitCollection.copy() for making copies of circuit collections.

  • Added max_resets argument to trueq.math.decompose_unitary() and the trueq.compilation.NativeDecomp compiler pass.

  • Added hashing and equality functions to trueq.config.GateFactory, trueq.math.rotation.Rotation, and trueq.math.rotation.FixedRotation.

  • Added an optional entangler argument to trueq.randomly_compile() for randomly compiling circuits into a specified entangling gate.

  • Added trueq.compilation.UnmarkCycles pass which sets all cycle markers to 0.

  • Added trueq.compilation.InsertIdentity pass which pads a group of marked cycles with cycles of identity gates.

  • Added trueq.Gate.get_alias() which returns alias of a given gate if it is aliased.

  • Added connectivity as an optional keyword argument for trueq.Config.basic.

  • Added alternate allowed povm format to trueq.Simulator.add_povm(povm) and trueq.math.StateTensor.probabilities(povm).

  • Added standardized epsilon constants to trueq.utils.


  • trueq.compilation.CycleReplacement now also accepts dictionaries as arguments for target and replacement cycles.

  • trueq.compilation.Justify is now a trueq.compilation.MarkerPass and works on multiple cycles at once, fixing the traffic jam issue it previously experienced.

  • trueq.compilation.RemoveEmptyCycle behavior has changed, it now works on groups of cycles with matching markers.

  • Updated documentation.

  • Changed the order of initialization arguments in trueq.Config, and made factories a required argument.

  • Changed implementation of trueq.Simulator.add_readout_error() to be more memory efficient.

  • Construction of trueq.NativeGate now requires a valid name.


  • Deprecated trueq.Block.


  • Fixed a bug in trueq.simulation.add_spam.classification_povm() for multi-system classification matrices when the number of outcomes is greater than the number of dimensions.

  • Fixed index ordering bug in trueq.math.StateTensor.marginalize().

  • Fixed typo and index ordering bug in trueq.math.OperatorTensor.marginalize().


  • Removed stagger and independent arguments from trueq.make_rcal.

[2.9.0] - 2021-03-01


  • A new base class trueq.interface.base.Interface for all interfaces.

  • Added trueq.Simulator.add_rcal_noise(), which adds readout error to a simulator by reconstructing the noise from RCAL results.

  • Added support for fixed parameter values to trueq.config.GateFactory.

  • trueq.Compiler.SIMPLIFY_PASSES, trueq.Compiler.HARDWARE_PASSES, trueq.Compiler.RC_PASSES, trueq.Compiler.NATIVE2Q_PASSES were added, each of which defines a list of useful compiler passes.

  • Added trueq.Cycle.same_structure() and trueq.Circuit.same_structure() methods for checking identical placement of operations, with possibly different gate parameter values.

  • Added trueq.utils.DisplayWrapper to allow SVGs to be displayed in both the documentation’s example gallery and python notebooks.


  • Complete rewrite of all interfaces: trueq.interface.cirq, trueq.interface.pyquil, trueq.interface.qiskit, trueq.interface.QASM.

  • The trueq.compilation.CycleSandwich pass was replaced by trueq.compilation.CycleReplacement.

  • trueq.Config.factories is now a list, not a dictionary.

  • trueq.Config YAML format has changed slightly to allow multiple gate definitions of the same name.

  • trueq.compilation.Native2QFastDecomp was changed to trueq.compilation.NativeDecomp, and support for multi-qubit gates was added.

  • trueq.math.decompose_su4 was changed to trueq.math.decompose_unitary, and support for multi-qubit gates was added.

  • Default compiler behavior has been altered, the compiler now uses the trueq.Compiler.HARDWARE_PASSES pass list by default.

  • Changed the return type of trueq.Circuit.draw() to a new class trueq.utils.DisplayWrapper.


  • trueq.compilation.compile(config, circuit, passes) deprecated in favour of trueq.Compiler.from_config(config, passes).compile(circuit).

  • trueq.compilation.get_transpiler() deprecated in favour of trueq.Compiler.from_config().

  • trueq.Compiler.DEFAULT_PASSES pass list was deprecated.

  • trueq.compilation.Native2QFastDecomp was deprecated, see trueq.compilation.NativeDecomp.

  • trueq.math.decompose_su4 was deprecated, see trueq.math.decompose_unitary.


  • trueq.Key.to_dict() and trueq.Key.from_dict() were fixed to correctly invoke trueq.Twirl.to_dict() and trueq.Twirl.from_dict().

  • Fixed a bug in trueq.compilation.Merge when n_labels is more than 1.


  • Removed trueq.interface.qiskit.RCPass Qiskit compiler pass.

  • Removed deprecated functions trueq.Config.from_params() and trueq.Config.make_config().

  • Removed support for deprecated input "SU" to trueq.Twirl.__init__().

[2.8.6] - 2021-02-10


  • A new class trueq.utils.ItemSet.

  • The estimates returned by trueq.Simulator.predict_knr() now include the Pauli decay parameters.

  • Added trueq.math.Rotation.id_scale() and trueq.math.Rotation.find_closest() to the trueq.math.Rotation class.

  • Added trueq.Simulator.add_knr_noise(), which adds noise to a simulator by reconstructing the noise from KNR results.


  • Aside from KNR, benchmarking protocols can now benchmark subcircuits consisting of multiple cycles; see their individual documentation for more details.

  • If x is a trueq.KeySet, then x.keyname now returns an ItemSet rather than a set.

  • Changed trueq.compilation.NativeExact to work with parameterized trueq.config.GateFactorys.

  • Changed the order of operations in trueq.compilation.Native1Q to prefer trueq.compilation.Native1QMode over trueq.compilation.NativeExact.

  • Moved trueq.compilation.one_qubit.unitary_to_u3args() to trueq.math.unitary_to_u3args().

  • Changed trueq.config.GateFactorys initialization and added the following methods: trueq.config.GateFactory.from_matrix(), trueq.config.GateFactory.from_hamiltonian(), and trueq.config.GateFactory.from_function().

  • trueq.config.GateFactory.layers is now an accessible property.

  • Generalized trueq.simulation.CycleMatch to accept multiple cycles.

  • Added a note to KNR tables if an estimate is omitted from visualization.

  • trueq.compilation.RCCycle can now auto-instantiate a twirl for each circuit it encounters based on the qubit labels present.


  • Fixed a bug in the standard deviation reported by trueq.Results.tvd().

  • Fixed an edge case in KNR analysis so that it properly reports estimates for extra subsystems that are specified in the twirl but not the cycle, assuming that they are acted on by identity gates.

  • Fixed an edge case when using "C1" twirling group in combination with propagate_correction flag when benchmarking a cycle using CB or KNR.


  • Removed trueq.compilation.Native1QUGates, the logic now exists in trueq.compilation.NativeExact.

[2.8.5] - 2021-01-18


  • Added trueq.Simulator.add_gate_replace() which allows a user defined function to replace gates or modify matched gates.

  • Added trueq.simulation.NativeMatch for matching noise to NativeGates by specifying their name.


  • Changed the kraus_ops argument of trueq.Simulator.add_kraus() to no longer allow a dictionary whose keys are n_sys. The dim of a subsystem should now be specified, its default value is 2.


  • Fixed an edge case in trueq.compilation.MarkCycles where some cycles could receive non-unique markers.

[2.8.4] - 2021-01-12


  • Added the method trueq.KeySet.table() for organizing keys.

  • Added trueq.Compiler.from_config().

  • Added trueq.Compiler.basic().


  • Made trueq.compilation.Compiler accessible at trueq.Compiler.

  • Moved trueq.compilation.DEFAULT_PASSES to trueq.Compiler.DEFAULT_PASSES.

  • Compiler passes no longer accept Config objects, and instead accept lists of GateFactorys.

  • trueq.compilation.Native1Q and trueq.compilation.Native1QMode now accept the kwarg mode.

  • Cycles loaded from trueq<=2.8.0 will have their immutable flag converted to an int and assigned to marker.

  • Slices of trueq.CircuitCollection will return new circuit collections rather than lists.


  • Fixed an edge case in KAK decomposition caused by numerical instabilities.

[2.8.3] - 2021-01-06


  • Fixed an edge case in trueq.randomly_compile() that occurs when using a non-Pauli twirl and a circuit containing more than one consecutive cycle with equal markers.

  • Fixed a bug in the Qiskit Executor interface enabling support for the new IBMQ hardware gateset.

[2.8.2] - 2021-01-05


  • Added Match and child classes which define rules for conditional simulator noise.

  • Added NoiseSource and child classes, which abstract the notion of a noise source during simulation.

  • Added trueq.CircuitCollection.shuffle().

  • Added several trueq.visualization.Graph.ibmq_*() methods for creating predefined graphs based on IBMQ devices.

  • Added trueq.math.Superop.*_subsys() methods for subsystem-wise row-stacking.

  • Added support for glob wildcards in trueq.load().

  • Added support for Qiskit version 0.23.2.


  • Updated the minimum required Microsoft Visual C++ 2015-2019 Redistributable (x64) version for Windows to 14.27.29334.

  • Replaced noisy_gates and noisy_labels arguments in the trueq.Simulator.add_* methods with the match argument.


  • Fixed a bug in trueq.Circuit() and trueq.Circuit.results that allowed adding results to empty circuits.

[2.8.1] - 2020-12-09


  • The Pattern class was renamed to Pass with specializations MarkerPass and NCyclePass.

  • Randomized Compiling now supports twirling sets of cycles at once, in addition to individual cycles.

  • OperationPattern was renamed to OperationReplacement.


  • NativeGates whose parameters appear to be integer-like are now rounded.


  • Removed support for reverse traversal and repeated traversal by the compiler and its passes.

[2.8.0] - 2020-11-17


  • Added a twirling group, "C1", to conveniently initialize trueq.Twirl with single-qubit Cliffords, regardless whether or not the cycle or labels contain multi-qubit gates.

  • Added trueq.visualization.Graph.sycamore() for making diagonal grid layouts.

  • Added mapping argument to trueq.visualization.Graph along with the methods to_label() and from_label() for converting and displaying different label systems by a new allowed value to the option show_labels.

  • Added trueq.utils.multiply_pauli_str() function.

  • Added trueq.compilation.RCCycle and trueq.compilation.CompilePaulis compiler passes.

  • Added marker to trueq.Cycle, and the marker kwarg to its constructor.

  • Added MarkCycles compiler pattern that marks cycles which contain multi-qubit gates if all of the existing cycles in the circuit have the default marker 0.

  • Added Gate.rx(), Gate.ry(), Gate.rz(), and Gate.rp() for creating gates which are Pauli rotations.

  • Added trueq.math.QubitMode.ZYZYZ to the set of known single qubit decompositions.

  • Added string representations of EstimateCollection and Estimate subtypes, NormalEstimate and RCalEstimate.

  • Added trueq.utils.parallel_map().

  • Added max_workers argument to for parallelization over circuits.


  • Renamed "SU" twirling group to "U" in trueq.Twirl.

  • Changed the kwarg of trueq.Results.plot() from sparse to sparse_cutoff.

  • Moved trueq.config.rotation to trueq.math.rotation.

  • Bumped the required NumPy version to 1.18.0.

  • Changed trueq.Cycle so that instances are always immutable

  • Compilation tools may only recompile a list of cycles with equal markers.

  • The compiler passes RemoveEmptyCycle, RemoveId, Merge, Justify had their kwargs modified to use the marker keyword.

  • Removed name from the Config object, along with all references to it in GateFactory and NativeGate.

  • Renamed several methods of Config, specifically Config.__init__ became Config.from_yaml, Config.from_params is now Config.__init__, and Config.make_config is now Config.from_parameterized.

  • Methods that generate benchmarking circuits will no longer throw an error when propagate_correction=True and the last cycle cannot be factored. Beware that this can result circuits whose last cycle has gates acting on more than two qubits.

  • Improved speed of the simulator.

  • Improved speed of the compiler.


  • Deprecated Config.from_params() and Config.make_config().

  • Deprecated "SU" twirling group specification in favour of "U" in trueq.Twirl.


  • Fixed an edge-case bug in trueq.compiler.PhaseTrack.

  • Fixed overlapping plot labels in trueq.Results.plot().

  • Improved the default cutoff of trueq.Results.plot() when shown in sparse mode.

  • Adjusted Native2QKAK numerical precision so that certain gates are correctly identified as identical. Before, in very specific instances, this lead to additional unnecessary two-qubit gates.

  • Fixed a bug in trueq.compiler.Merge which would result in a sub-optimal gate count in rare scenarios.


  • The compress kwarg was removed from trueq.randomly_compile().

  • Removed add(), immutable, and pop() from trueq.Cycle, along with the constructor’s immutable kwarg (replaced by marker).

  • Removed trueq.math.QubitMode.frame_change.

  • Removed deprecated trueq.Circuit.add_cycle(), which was renamed to trueq.Circuit.append().

  • Removed deprecated trueq.make_readout_calibration(), which was renamed to trueq.make_rcal().

[2.7.6] - 2020-10-21


  • Added the following attributes and methods to trueq.math.Superop: adj, avg_gate_fidelity, avg_gate_infidelity, coherent_infidelity, fidelity, infidelity, norm, dnorm, stochastic_infidelity, unitary_fraction, and unitarity.

  • Added a new compiled_pauli flag to control or specify which Paulis are compiled at the end of the circuits generated by benchmarking protocols (default is True).


  • Changed the default rank of trueq.math.random_bcsz() to dim**2.


  • Fixed the plotting extents in raw() plotter.

  • Qiskit version 0.23 is now supported. Due to upstream changes, conversion to the cz gate is only supported from Qiskit version 0.23 or greater, versions below this will raise a warning on import.

[2.7.5] - 2020-10-15


  • Added a BadModule class that raises an ImportError when an optional module that is called is either outdated or not installed.

  • Added the option include_final_virtual to the PhaseTrack compiler pattern.

  • Added ZYZ to known trueq.math.QubitMode single qubit decompositions.

  • Added a new Twirl class to streamline management of twirling groups in generation and analysis.

  • Added trueq.math.random_bcsz() function to generate random CPTP superoperators.

  • Added trueq.estimates.RCalEstimate.apply_correction() for directly correcting bitstring distributions by readout calibration matrices.

  • Added Simulator.predict_*() methods to estimate the outcomes of protocols without simulating their circuit collections.

  • Added labels option to the trueq.math.Tensor.mat() method.

  • Added the method trueq.math.Tensor.apply_to_all().


  • Updated the minimum required Microsoft Visual C++ 2015-2019 Redistributable (x64) version for Windows to 14.27.29112.

  • Renamed the twirling_group argument of make_*() and randomly_compile_qiskit() functions to twirl.

  • Moved random_density() and random_unitary() from trueq.math.general to new module trueq.math.random.

  • trueq.math.Tensor.marginalize() now accepts the labels to keep, rather than those to remove.

  • Switched to a slightly more accurate estimate of e_S in XRB.

  • Updated documentation.


  • Fixed a bug in trueq.math.Superop.is_tp.

  • Fixed a transpose bug in the HTML display of trueq.Gate.


  • Removed trueq.utils.auto_twirl(), trueq.utils.pretty_twirl(), and trueq.utils.twirls_equal().

[2.7.4] - 2020-09-11


  • Added conversion functions to/from true.math.Superop from/to qutip.Qobj.


  • GateFactory was refactored to be represented as a sequence of static and single-parameter rotations called layers. The abstract class Layer was added with children Rotation (fast matrix exponentiation of a generator matrix times a free parameter) and FixedRotation (a fixed unitary).

  • Renamed GateFactory.dim to GateFactory.width for consistency with Gate.width.

  • Renamed GateFactory.get_gate() to GateFactory.make_gate().


  • Native2QKAK now correctly decomposes tensor products of single qubit gates.

  • Circuit.draw() now displays parameters in NativeGate popups.


  • trueq.math.QubitMode.validate_factories was removed and its logic moved directly into decomposition patterns in the compiler.

  • Removed GateFactory.find_closest().

[2.7.3] - 2020-08-25


  • Updated documentation.


  • The process infidelity estimate name was renamed from e_P to e_F.

  • QASM and Cirq conversion now use gate labels as they appear in circuits, instead of mapping ordered labels to 0, 1, ..., n_qubits-1.

[2.7.2] - 2020-08-18


  • Added a number of new compiler patterns, Parallel, TryInOrder, RemoveEmptyCycle, NativeExact, Native1QUGates, Native1QRRZ, Native1QMode, Native2QCX, Native2QFastDecomp, Native2QKAK. Many of these are the result of splitting the previous Native1Q, and Native2Q into individual components.

  • Added trueq.compilation.base.OperationPattern which is essentially a Pattern which only performs calculations on individual operations, not full cycles.

  • Added a fallback method to grab versions of optional imports.


  • Significant refactor of one and two qubit compilation tools, increasing the customizability of the compiler. Specifically one and two qubit decompositions were broken up into a number of separate compiler patterns. Default compiler options should result in identical outcomes to the previous defaults in the majority of cases.

  • Contents of trueq.compilation.compiler moved to trueq.compilation.base.


  • Fixed an edge case in compilation where circuits may have been over-simplified in rare instances for some diagnostic protocols.

  • Updated trueq.interface.qiskit.Executor to work with Qiskit version 0.20.0.

  • Fixed trueq.Circuit.results setter to maintain last_modified attribute.

[2.7.1] - 2020-08-07


  • Added the method trueq.EstimateCollection.update_keys().

  • Added the method trueq.EstimateCollection.values() for extracting values of the same name across estimates.

  • Added subplot titles to compare() plotter.


  • Simplified and unified arguments of trueq.Key.copy(), trueq.KeySet.copy(), trueq.CircuitCollection.update_keys().


  • Fixed bug in trueq.KeySet.similar_keys() when invert=True and not all keys have all names in common.

  • Fixed a bug in raw() plotter when data are ragged.

  • Removed empty subplots that sometimes occur in compare() plotter.

  • Fixed a bug in the calculation of upper and lower bounds of e_P in IRB.

  • Fixed a bug in the variance calculation for e_S in XRB.

[2.7.0] - 2020-07-23


  • Added Python dependency mako>=1.1.2 to the requirements.

  • Added trueq.Circuit.draw() function which generates an interactive SVG representation of the circuit which has been tested in all major browsers.

  • Calling on circuit collections with readout calibration circuits now returns the estimated single qubit confusion matrix for each qubit. These are automatically applied in fits of protocols to correct for readout errors in a scalable manner.

  • Added trueq.Descriptions which provides text descriptions of all parameters returned from fitting the various protocols which True-Q™ provides.

  • Added trueq.Simulator.sample to sample from the output distribution without updating the results of the circuit.

  • Added trueq.Circuit.to_qasm to convert a circuit into an openQASM 2.0 representation. Non-standard QASM may also be used, and additional documentation may be found in trueq.interface.QASM.

  • Added a new plotter compare_pauli_infidelities().

  • Added an optional targeted_errors parameter to trueq.make_cb() that replaces the functionality of trueq.make_tnr().


  • Analysis underwent a significant re-write, which dramatically decreased analysis times. As a part of this rewrite trueq.parameters and all subclasses were removed, and in their place trueq.estimate and all subclasses will be used to return information from fits. The interface for fitting has changed slightly, with an emphasis now placed on subsetting circuit collections before calling fit. Analysis and plotting of KNR data now correctly handles degeneracies present in some fits.

  • Increased IPython HTML support with more interactivity in both Jupyter or Colab.

  • Plotting of KNR data was changed, nr_cmap and nr_bar were removed in favor of knr_heatmap which has improved functionality over nr_cmap.

  • Updated and improved the documentation.

  • Moved trueq.config.make_config() to be a static method of trueq.Config.

  • Improved the fitting technique for XRB data.

  • Merged trueq.assessments into trueq.protocols and added the functions within into the main namespace for convenience.

  • Reduced arguments to make_crosstalk_diagnostics for simplicity.

  • trueq.Config and trueq.config.GateFactory now preserve capitalization of names.

  • Order of parameters can now be optionally specified in trueq.config.GateFactory.

  • trueq.CircuitCollection.update_keys() now returns itself for convenience.

  • Changed trueq.Cycle.operators to trueq.Cycle.operations and truq.Cycle.n_operators to truq.Cycle.n_operations for consistency.

  • Changed trueq.utils.load() to optionally accept a list of saved True-Q™ object files and combine them into a single collection.

  • Renamed trueq.make_readout_calibration() to trueq.make_rcal().

  • Renamed trueq.Circuit.add_cycle() to trueq.Circuit.append() with additional functionality.

  • The append() method of trueq.Circuit, trueq.CircuitCollection, and trueq.EstimateCollection are all now aliased to +=.

  • Split comparison() plotter into compare() and compare_twirl().

  • Renamed infidelity_comparison() plotter to compare_rb().


  • no longer fails when asked to measure a strict subset of the qubits addressed by a circuit.

  • Fixed bugs in trueq.Gate.is_identity and trueq.Gate.is_unitary for non-unitary matrices.

  • Fixed a bug in that broke the installer on a machine without Git.

  • Updated trueq.interface.cirq to match upstream changes when converting measurements.


  • trueq.Circuit.expectation_values() was removed.

  • trueq.CircuitCollection.plot.incoherence() was removed.

  • trueq.Gate no longer accepts dictionary instantiation.

  • trueq.KeyMap was removed.

  • trueq.make_tnr() was removed and its functionality was incorporated into trueq.make_cb().

  • trueq.parameters and all subclasses were removed.

  • trueq.protocols.CircuitAggregator was removed.

  • trueq.protocols.QueueBackend was removed.

[2.6.13] - 2020-06-05


  • Added trueq.Config.basic as a way to construct a simple Config object.

  • Added trueq.Simulator.add_relaxation as a way to add relaxation errors to the simulator.

  • Added helper functions trueq.utils.auto_twirl() and trueq.backend.api.random_twirl().


  • trueq.utils.optional_import now handles edge cases where of a package is incorrectly configured.

  • Fixed a bug in in the case where a measurement error is defined (e.g. via Simulator.add_readout_error()) on a qubit not appearing in a circuit.

  • Added trueq.Results to API documentation.

  • Fixed a shape bug in trueq.math.tensor.OperatorTensor.upgrade().


  • Removed get_cur_mem(), get_max_mem(), and set_max_mem() from trueq.backend.api.

[2.6.12] - 2020-05-08


  • Added trueq.visualization.Graph for embedding device topology graphs in figures.


  • Bumped required Cirq version to 0.7.0 and made compatible with version 0.8.0.

[2.6.11] - 2020-05-01


  • Updated documentation.


  • Changed the sort order of cycles; gate count at each size is now most important.

  • trueq.compilation.Merge no longer removes identity gates.

  • Changed Qiskit required version to >=0.19 due to upstream changes.


  • Fixed a bug in conversion to the Cirq PhasedXPow gate.

[2.6.10] - 2020-04-28


  • Added abs_max option to trueq.visualization.plot_mat() (and other functions which call this plotter) which sets the opacity scale of colors.

  • Added trueq.compilation.DecomposeRRZ, a compilation pattern to decompose single qubit gates into 2 R(a) = Z(a)X(90)Z(-a) gates and 1 final Z(t) gate.

  • Added support for the PhasedXPow gate to the Cirq interface.

[2.6.9] - 2020-04-13


  • Added trueq.compilation.InvolvingRestrictions pattern which enforces involving restrictions as defined in a config through a greedy algorithm.


  • Fixed a bug in trueq.Cycle.__getitem__() in the presence of a single-qubit block.

[2.6.8] - 2020-04-09


  • Added an inequality comparison operator to trueq.Cycle.

  • Updated documentation.


  • Switched deprecated SciPy functions to their NumPy equivalents.

[2.6.7] - 2020-04-06


  • Added the method trueq.Results.plot() that makes a bar plot of the results.

  • Added the compiler pattern trueq.compilation.PhaseTrack to accumulate virtual phases through a circuit and use them to parameterize native gates.

  • Updated documentation.


  • Renamed trueq.math.Tensor.dag() to trueq.math.Tensor.adj().

  • Dimension on trueq.Result will now increase if new ditstrings contain higher numbers than the existing stored dimension; previously this raised an exception.


  • Fixed an ordering bug in trueq.results.merge_results().

  • Fixed a bug that occurred while averaging CB results.

[2.6.6] - 2020-03-27


  • Fixed a bug in trueq.compilation.Relabel, where relabeling would only work on permutations, it now works for any valid arbitrary labels.

[2.6.5] - 2020-03-17


  • Added interface support for Qiskit based gates which do not define a .to_matrix().


  • Custom keys are now preserved when the circuits which contain them are passed to analysis or randomized compiling.

  • Changed default priority list for the Qiskit interface.

[2.6.4] - 2020-03-09


  • Added the trueq.math.Superop class for representing superoperators.

  • Added the function trueq.math.random_density() to generate random density matrices.


  • trueq.compilation.RemoveId can now optionally remove the identity gate from immutable cycles.

  • trueq.compilation.DEFAULT_PATTERNS final RemoveId now removes all identities, even in immutable cycles.

[2.6.3] - 2020-02-27


  • Fixed a bug in which was introduced in the previous release.

[2.6.2] - 2020-02-26


  • Added axis_size option to the nr_bar() plotting function.

  • Added support to trueq.Simulator for subsystem dimensions greater than 2, thereby adding support for leakage noise models.

  • Added dim attribute to trueq.Circuit.

  • Added function trueq.math.embed_unitary().

  • Added support for pip and wheel installations.

  • Updated documentation.


  • Changed the internals of trueq.Cycle to reduce memory usage (this should not change any behaviour).

[2.6.1] - 2020-02-20


  • trueq.compilation.Native1Q and Native2Q have been optimized slightly for speed.

  • trueq.CircuitCollection.append() now returns itself after appending.

  • Improved the performance of protocol generation functions, e.g. trueq.make_knr().


  • Fixed a backwards compatibility bug with trueq.load().

  • Made more robust by first saving to a temporary location.

  • Fixed issue with set_priority_list where it could result in an empty list.

[2.6.0] - 2020-02-14


  • Added labels option to the infidelity_comparison() plotting function.


  • Significant refactor of trueq.interface interfaces, which fixes ambiguities in the gate conversion process (run help(trueq.interface) for details).

  • Moved trueq.circuits.Cycle to a new module, trueq.cycle.Cycle.

  • Moved trueq.math.NUM_PRECISION constant to trueq.utils.NUM_PRECISION.

  • trueq.make_readout_calibration() now flattens input labels to avoid confusion.

  • Default compiler patterns tweaked slightly; the final Justify step has been removed. See trueq.compilation.DEFAULT_PATTERNS for the default compiler steps.

  • Reduced default value of n_bodies argument in trueq.make_knr() to 1.

  • Improved internal logic of trueq.config.GateFactory for future changes in compilation and interface code.

  • Updated documentation.


  • Fixed trueq.math.find_kak_equivalent and added tests.

[2.5.0] - 2020-02-11


  • Added trueq.math.Frame.plot_arr() and trueq.math.Frame.plot_superoperator() for plotting matrices expressed in different bases.

  • Added trueq.Gate.is_identity for checking if a gate is identity.

  • Added trueq.Cycle.is_equivalent for checking if two cycles are equivalent.

  • Added options ignore_imm and ignore_id to trueq.compilation.CycleSandwich.


  • trueq.config.fsim_factory fSim definition now matches Cirq definition.

  • circuits.plot.nr_bar() now shows error contributions in the legend instead of below the x-labels.


  • Fixed a bug in trueq.Circuit.update_keys().

  • Fixed rich display of trueq.Operation, trueq.Gate, trueq.NativeGate, trueq.Cycle, and trueq.Circuit in Colab.

  • Fixed the efficiency of trueq.make_tnr() for many input targeted errors.

  • Fixed rare conversion error in PyQuil interface where single qubit identity gates could have potentially failed to convert after altering default behavior.

[2.4.5] - 2020-02-06


  • Added more caching to portions of trueq.interface to speed up conversion.

  • Added trueq.Cycle.to_dict() and trueq.Cycle.from_dict().

  • Added trueq.Results.to_dict() and trueq.Results.from_dict().


  • Cycles and results in circuits are now properly serialized.

[2.4.4] - 2020-02-05


  • Added compatibility with Python 3.8.


  • Fixed minor CSS bugs in _repr_html_().

  • Fixed a rare DLL loading bug.

[2.4.3] - 2020-02-04


  • Added assets to


  • Fixed a bug in trueq.Circuit.to_dict().

[2.4.2] - 2020-02-04


  • Added trueq.Gate.random(dim), which creates a random unitary gate of size dim.

  • Added trueq.Gate.adj, which returns the adjoint of the existing Gate as a new Gate.

  • Added trueq.Gate.plot(), which plots the matrix representation of a Gate.

  • Added trueq.math.random_unitary which generates Haar random unitary matrix.

  • Added _repr_html_() to trueq.Operation, trueq.Gate, trueq.NativeGate, trueq.Cycle, and trueq.Circuit for rich display in Jupyter notebooks.


  • Simplified trueq.visualization.plotters.PlottingSuite mechanics.

  • Added a flag, join_meas=True, to Cirq conversion so parallel measurements can optionally be combined into single Cirq measurement object inside of a moment.

  • Changed the way trueq.Cycle is serialized by trueq.Key.to_dict().


  • Fixed ordering of subplots in CircuitCollection.plot.nr_bar().

  • Solved division by zero error when no data present in plotters.

  • Fixed behavior of trueq.Gate.generators when called on identity gates.

  • Cirq conversion now casts angles to real values, where previously complex 0.0 were potentially being passed.

  • Cirq conversion now assigns qubits to a device consistently.

  • Fixed a bug in


  • Removed unused function trueq.utils.cycle_to_str.

[2.4.1] - 2020-01-23


  • Added trueq.compilation.CycleSandwich compiler pattern.

  • Added the convenience attributes Cycle.gates_single and Cycle.gates_multi.


  • trueq.inteface.qiskit.Executor now adds backend=backendname to each circuit key.

  • trueq.inteface.qiskit.Executor now has default n_shots=128 (previously 1024).


  • Fixed bug in Gate.is_unitary.

  • Fixed superfluous warnings.

[2.4.0] - 2020-01-17


  • Added trueq.compilation.Relabel pattern that relabels qubits in a circuit.

  • Added trueq.compile(), which enables simple standard compilation and transpilation.

  • Added the option to select noisy labels and gates in many of the simulator’s noise models, e.g. Simulator().add_depolarizing(0.1, noisy_labels=[0, 3, 5]).

  • Added trueq.Circuit.n_meas property, equal to len(circuit.meas_locs).

  • Added support to Cycle.add() for inserting multiple like 1-qubit gates.

  • Added trueq.Config.connectivity property which gives the connectivity graph associated with the factories in the config.

  • Added trueq.Results.decompiled_results() to undo the effect of a compiled pauli.

  • Added the convenience function trueq.CircuitCollection.sum_results().

  • Added the convenience function trueq.CircuitCollection.update_keys().

  • Added clip=False option to trueq.math.Tensor.to_results().

  • Added xlabels and ylabels options to trueq.visualization.plot_mat().

  • Added trueq.math.int_base() for integer solutions to b**n == x for b.

  • Added the trueq.Cycle.dim attribute.

  • Added common_ylim=True option to Circuit.plot.nr_bar().


  • make_readout_calibration() now makes mutable instead of immutable cycles.

  • Refactored some portions of the interface code for Qiskit, Cirq, and PyQuil for simplicity and improved customization.

  • Renamed trueq.compilation.SubstitutionCompiler to trueq.compilation.Compiler

  • Generalized allowed input type to Results.marginal().

  • Updated documentation.

  • Changed underlying datatype of trueq.Gate from dict to np.ndarray.

  • Qiskit Executor now has a default max_submissions=5 down from 25, to match upstream changes from IBM.

  • Modified trueq.math.int_log() to be faster, to have no default value, and to return None rather than error when no solution is found.

  • Removed attributes trueq.Gate.n_sys and trueq.Gate.dim; a major step toward gates containing no label information whatsoever.


  • Fixed ordering bug in Tensor.to_results() and Tensor.sample().

  • Fixed return type bug for void backend functions.

  • Fixed PyQuil interface for pyquil>=2.16.0.

[2.3.0] - 2019-12-10


  • Removed nr_cmap() and nr_bar() plotting for circuits with key.protocol="TNR".

  • Added input validation to nr_cmap() and nr_bar().

  • Compiler speed improvements.

  • Various improvements to the documentation and examples.

  • Bumped qiskit-terra optional dependency to >=0.11.


  • Fixed simulator probability clipping issue.

  • Fixed compiler to accept lists of cycles.

[2.2.3] - 2019-11-19


  • accepts n_shots=float("inf") as a possible input.

  • Speed improvements to for many shots.

[2.2.2] - 2019-11-06


  • Added circuits.plot.irb_summary() to plot parameters related to IRB.

[2.2.1] - 2019-11-01


  • Added aliases for single qubit clifford gates, available through e.g. Gate.cliff0.

  • Added make_qcap() and qcap_bound() for Quantum Capacity (QCAP) assessment.

  • Added Tensor.to_results() which returns a Results object.

  • Added Results.tvd() to compute total variation distance (TVD) between results.

  • Added circuits.plot.timestamps() plotter showing Results.last_modified.

  • Added case to trueq.compilation.Native1Q that will now directly compile into a fixed angle gate if there is one present in the config file.

  • Added TotalTime for estimating experiment time based on gate lengths, etc.


  • Moved make_crosstalk_diagnostics() to trueq.assessments.

  • Modified the arguments of CircuitCollection.batch().


  • Fixed an exponential blowup in the analysis of make_knr() circuits.

  • Fixed a bug in readout calibration.

  • Fixed a memory reporting bug in macOS (enterprise version only).

[2.2.0] - 2019-10-21


  • Added make_knr() for K-body noise reconstruction (KNR).

  • Added make_tnr() for Targeted noise reconstruction (TNR).

  • Added interface.qiskit.Executor for submission of circuits to a Qiskit backend.

  • Added convenient specification of twirling groups using P, C, SU, etc.

  • Added CircuitAggregator context to build circuit collections from multiple protocols using only one call to the backend.


  • Changed return type of randomly_compile() to a circuit collection of randomizations, and removed its ability to accept circuit collections as input.

  • Improved plotting and saving functions.

  • Updated documentation.


  • Fixed bugs in Cirq and Qiskit interfaces.


  • Removed make_nr().

  • Removed reconstruct_pauli_errors() (its functionality was intergrated into fit()).