QCTraceSimulator Class


Quantum Computer Trace Simulator. Simulates a trace of the execution of a quantum program on a quantum computer without performing full quantum state simulation.

public class QCTraceSimulator : Microsoft.Quantum.Simulation.Simulators.QCTraceSimulators.Implementation.QCTraceSimulatorImpl
type QCTraceSimulator = class
    inherit QCTraceSimulatorImpl
Public Class QCTraceSimulator
Inherits QCTraceSimulatorImpl


The simulator collects metrics describing the performance of Q# operations and resource consumption by Q# operations. For example, these metrics include the number of qubits that an operation takes as an input; the number of qubits allocated by an operation; and the number of T gates executed by an operation. For the full list of metrics, see the MetricNames property and the PrimitiveOperationsGroupsNames and MetricsNames classes.

Q# operations may have different variants that are invoked using functors. Each operation in Q# can have up to four variants: body, adjoint, controlled, and controlled adjoint. Usually, the controlled version of an operation uses a different number of gates, has a different depth, and uses a different number of qubits than the body of the operation. For this reason, the simulator collects metrics separately for each operation variant.

The simulator collects metrics for each edge of the call graph. For example, if the adjoint variant of operation A calls the controlled variant of operation B, the edge (B: Controlled, A: Adjoint) will appear in the call graph with the adjoint variant of A as a caller of the controlled variant of B. The operations that are called by the Run method of the simulator are top-level. The metrics collected for top-level operations are obtained by their names without specifying the caller name.

The simulator can potentially collect multiple values of the same metric associated with the same call graph edge. For example, the adjoint variant of operation A can be called multiple times and with different parameters. The simulator does not store all collected values of the metrics. Instead, the simulator computes functions of the collected values of the metric on the fly. For example, the simulator computes minimum, maximum and average of the collected values. We call these functions statistics of the metric. To get the full list of statistics computed for a given metric use the GetMetricStatisticNames(String) method. The list of statistics is also available through the members of the StatisticsNames class.

Q# operations are mapped to C# types. For example, the C# type Microsoft.Quantum.Intrinsic.X corresponds to the Q# operation Microsoft.Quantum.Intrinsic.X. When the value of the metrics is requested for a Q# operation, the corresponding C# type is passed as type parameter.

When the maximum of all collected values of the metric is equal to the minimum, the metric value is well-defined and the methods GetMetric<TOperation>(String, OperationFunctor) and GetMetric<TOperation,TCaller>(String, OperationFunctor, OperationFunctor) can be used. Otherwise, the methods GetMetricStatistic<T>(String, String, OperationFunctor) and GetMetricStatistic<TOperation,TCaller>(String, String, OperationFunctor, OperationFunctor) must be used to retrieve the statistics of the metric.



Creates a new instance of the simulator with the default QCTraceSimulatorConfiguration.

QCTraceSimulator(QCTraceSimulatorConfiguration, Assembly)

Creates a new instance of the simulator with configuration given by the config parameter.



Array of the names of all of the metrics collected by this instance of the simulator. This array includes the members of PrimitiveOperationsGroupsNames and MetricsNames.



Returns a copy of the configuration used to create this instance of QCTraceSimulator.

GetMetric<TOperation,TCaller>(String, OperationFunctor, OperationFunctor)

Returns the value of a given metric associated with an edge of the call graph.

GetMetric<TOperation>(String, OperationFunctor)

Returns the value of a given metric for a top level operation.

GetMetricStatistic<T>(String, String, OperationFunctor)

Returns a statistic of a given metric for a top level operation.

GetMetricStatistic<TOperation,TCaller>(String, String, OperationFunctor, OperationFunctor)

Returns a statistic of a given metric associated with an edge of the call graph.


Returns the names of all statistics currently collected for a given metric.


Returns all collected metrics for each call graph edge in CSV format. The key in the dictionary is the name of metric counter
from MetricsCountersNames. The value for each key is a collection of statistics formatted as a string in CSV format. In the CSV format, columns names are formated as "MetricName:StatisticName", and rows correspond to call graph edges.

Applies to