True-Q™ Changelog

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

[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().


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

  • Removed GateFactory.find_closest().


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

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

[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().


  • Removed unused function trueq.utils.cycle_to_str.


  • 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

[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.


  • Removed make_nr().

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


  • Fixed bugs in Cirq and Qiskit interfaces.