# Quantum Trace Simulator

The Microsoft quantum computer trace simulator executes a quantum program without actually simulating the state of a quantum computer. For this reason, the trace simulator can execute quantum programs that use thousands of qubits. It is useful for two main purposes:

- Debugging classical code that is part of a quantum program.
- Estimating the resources required to run a given instance of a quantum program on a quantum computer.

The trace simulator relies on additional information provided by the user when measurements must be performed. See Section Providing the probability of measurement outcomes for more details on this.

## Providing the Probability of Measurement Outcomes

There are two kinds of measurements that appear in quantum algorithms. The first
kind plays an auxiliary role where the user usually knows the
probability of the outcomes. In this case the user can write
`AssertProb`

from the `Microsoft.Quantum.Primitive`

namespace to express this knowledge. The following example illustrates this:

```
operation Teleportation (source : Qubit, target : Qubit) : () {
body {
using (ancillaRegister = Qubit[1]) {
let ancilla = ancillaRegister[0];
H(ancilla);
CNOT(ancilla, target);
CNOT(source, ancilla);
H(source);
AssertProb([PauliZ], [source], Zero, 0.5, "Outcomes must be equally likely", 1e-5);
AssertProb([PauliZ], [ancilla], Zero, 0.5, "Outcomes must be equally likely", 1e-5);
if (M(source) == One) { Z(target); X(source); }
if (M(ancilla) == One) { X(target); X(ancilla); }
}
}
}
```

When the trace simulator executes `AssertProb`

it will record that measuring
`PauliZ`

on `source`

and `ancilla`

should be given an outcome of `Zero`

with probability
0.5. When the simulator executes `M`

later, it will find the recorded values of
the outcome probabilities and `M`

will return `Zero`

or `One`

with probability
0.5. When the same code is executed on a simulator that keeps track of the
quantum state, such a simulator will check that the provided probabilities in
`AssertProb`

are correct.

## Running your Program with the Quantum Computer Trace Simulator

The quantum computer trace simulator may be viewed as just another target machine. The C# driver program for using it is very similar to the one for any other quantum Simulator:

```
using Microsoft.Quantum.Simulation.Core;
using Microsoft.Quantum.Simulation.Simulators;
using Microsoft.Quantum.Simulation.Simulators.QCTraceSimulators;
namespace Quantum.MyProgram
{
class Driver
{
static void Main(string[] args)
{
QCTraceSimulator sim = new QCTraceSimulator();
var res = MyQuantumProgram.Run().Result;
System.Console.WriteLine("Press any key to continue...");
System.Console.ReadKey();
}
}
}
```

Note that if there is at least one measurement not annotated using `AssertProb`

or `ForceMeasure`

the simulator will throw `UnconstraintMeasurementException`

from the `Microsoft.Quantum.Simulation.QCTraceSimulatorRuntime`

namespace. See the API documentation on UnconstraintMeasurementException for more details.

In addition to running quantum programs, the trace simulator comes with five components for detecting bugs in programs and performing quantum program resource estimates:

- Distinct Inputs Checker
- Invalidated Qubits Use Checker
- Primitive Operations Counter
- Circuit Depth Counter
- Circuit Width Counter

Each of these components may be enabled by setting appropriate flags in
`QCTraceSimulatorConfiguration`

. More details about using each of these
components are provided in the corresponding reference files. See the API documentation on QCTraceSimulatorConfiguration for specific details.

## See also

The quantum computer trace simulator C# reference