Improvements to M.Q.Diagnostics namespace

[cgranade]

This PR (still in draft for early feedback and API review) provides a number of improvements to the Microsoft.Quantum.Diagnostics namespace in the Microsoft.Quantum.Standard package:

• New visualization support
  This PR provides a new package, Microsoft.Quantum.Standard.Visualization, that uses the runtime emulation feature to interpret diagnostics sent to the MaybeDisplayDiagnostic event, allowing for improved diagnostics support in IQ#. This architecture reduces cross-repo dependencies, as visualizations can be provided in library runtime emulation classes, without requiring modifications to the runtime or to IQ#.
• New DumpOperation callable
  This PR provides a new operation, DumpOperation, that uses the Choi–Jamiłkowski isomorphism and DumpRegister together to extract a unitary representation of adjointable operations and to display this representation as a diagnostic. On machines that do not support this representation, but that support the H and CNOT intrinsics and DumpMachine, the Choi–Jamiłkowski state for the given operation is shown instead. On machines that support neither, the operation can be safely ignored.

• New Allow* callables
  This PR also provides operations using a new verb, Allow*, representing that a condition must hold inside of the apply arm of a within/apply block. For example, this functionality can in principle be used in some oracle-based katas by enforcing that a given oracle operation is not called more than once within a given apply. Similarly, AllowAtMostNQubits fails when more than a given number of qubits is allocated inside of an apply block.

Remaining work:

• API review
• C# documentation comments
• Unit testing
  NB: unit testing may require the legacy Q# unit testing framework, so as to allow for ShouldFail tests.
• Remove extension method placeholder for Make GetOptionOrDefault public. iqsharp#239 by updating to latest beta.

+@tcNickolas for possible application to oracle-based katas, +@rmshaffer for IQ# impact.
+@guenp and @msoeken for API review.

[msoeken]

Just left some comments for the current draft PR.

[cgranade]

Looks like the test process crashed, will rerun on the next commit.

[cgranade]

@anpaz-msft: It looks like the Linux test host is crashing pretty frequently again, would you have any suggestions? Thanks!

The active test run was aborted. Reason: Test host process crashed

[rmshaffer]

Looked primarily at the visualization code here; looks good to me! Will allow other domain experts to give their approval on the PR.

[rmshaffer]

Just a reminder about this TODO.

[cgranade]

Thanks for catching that, @rmshaffer, I did indeed forget to update after microsoft/iqsharp#239 completed.

[tcNickolas]

I made a pass and left some comments, mostly about documentation, tests and examples. Looks very promising! We might be able to retire parts of CounterSimulator, if not all of it.

I'm assuming that DumpOperation works in command line Q# as well as in Jupyter notebooks, right? I'd love to finally update DumpUnitary to dump the real unitary and not the column-by-column approximation!

[tcNickolas]

If this exception upon calling Adjoint AllowAtMostNCallsCA, I'd suggest adding the number of times the operation was called to the message; it can be helpful to troubleshooting if you know by how much exactly you overuse the operation.

[tcNickolas]

I would also add a special message for nTimes = 0 - it's easier to read something like "You are not allowed to call ... in this code" than "more than the allowed 0 times"

[cgranade]

If this exception upon calling Adjoint AllowAtMostNCallsCA, I'd suggest adding the number of times the operation was called to the message; it can be helpful to troubleshooting if you know by how much exactly you overuse the operation.

It fails on the (n +1)st call, as soon as the required condition fails; I agree, it may make sense to defer until the end of the allow-block, though.

[tcNickolas]

Is there a way to add a functionality to get the number of calls of the specified operation? The context is similar to this one - sometimes I want to check that at most X calls to a group of similar operations have been done, but it could be one or another. I don't quite see how to get this functionality with the existing implementation

[cgranade]

Agreed, there's no way to do exactly that using this feature as currently written. Given the short timescale until the next release, it may make sense to defer that as a feature request for September?

[cgranade]

I made a pass and left some comments, mostly about documentation, tests and examples. Looks very promising!

Thanks for the feedback @tcNickolas, I appreciate it!

We might be able to retire parts of CounterSimulator, if not all of it.

Given your comments, it looks like there may be some usecases still left (e.g.: enforcing constraints on groups of operations), but yeah; my goal was to be able to consolidate that logic in a simulator-independent fashion, so that oracle counting policies could be applied against the Toffoli simulator, or even against third-party simulators.

I'm assuming that DumpOperation works in command line Q# as well as in Jupyter notebooks, right?

That should be the case, yes. In particular, the QuantumSimulator class outputs the unitary representation of the given operation through the SimulatorBase.OnDisplayableDiagnostic event. Python and IQ# pick that up automatically and converts those diagnostics to either something Jupyter Notebook can read, or for command-line use. For C# host programs, adding a listener to that of the form sim.OnDisplayableDiagnostic += Console.Out.WriteLine should do it.

For Q# standalone programs, I'm not sure if that event is wired up automatically. It looks like https://github.com/microsoft/qsharp-runtime/blob/master/src/Simulation/CsharpGeneration/EntryPoint.fs#L120 may need modified to add a listener to the OnDisplayableDiagnostic event. Alternatively, SimulatorBase.cs could be modified to add that listener by default and to disable it when SimulatorBase.DisableLogToConsole is called. Any thoughts, @bettinaheim?

In any case, I've added a ToString override DisplayableUnitary to make it easier to print the dumped diagnostics to the command line.

I'd love to finally update DumpUnitary to dump the real unitary and not the column-by-column approximation!

That's one of the big advantages of using the Choi–Jamiołkowski isomorphism (also known in this case as AAPT) to find unitary representations; any relative phases between the various states in an input basis are directly captured by the use of a reference register, so that only phases that are truly global factor out. Still happy to share more about that if you're interested some time.

In the meantime, I've made a pass on your feedback and will update the PR accordingly. Thanks!

[msoeken]

Just left one small comment. Thanks

Dismissing stale review. Remaining comments deferred to #312.

[vadym-kl]

Thank you @cgranade, this is very nice addition to the diagnostics namespace. It looks like there could be situations where DumpOperation might have several dump formats. For example, in a Clifford simulator one might what to dump operation as a unitary matrix and also as an images of generators of n-qubit Pauli group. Do you have any thoughts on how to make DumpOperation a bit more feature proof for that?

[cgranade]

Thank you @cgranade, this is very nice addition to the diagnostics namespace. It looks like there could be situations where DumpOperation might have several dump formats. For example, in a Clifford simulator one might what to dump operation as a unitary matrix and also as an images of generators of n-qubit Pauli group. Do you have any thoughts on how to make DumpOperation a bit more feature proof for that?

Thanks for the kind words! Agreed, different simulators will likely have different formats for dumping operators; just as https://github.com/qsharp-community/chp-sim overrides DumpRegister and DumpMachine to show stabilizer tableaus, I'd love to see that project outputting Cliffords as tables of Pauli mappings, similar to what http://www.cgranade.com/python-quaec/ does. Similarly, I'd love to hook up ToffoliSimulator to output truth tables.

From that perspective, the design of this feature is intended to allow simulators defined downstream from Microsoft.Quantum.Standard to override DumpOperation, and for the DumpOperation emulation class add support for simulators defined upstream from Microsoft.Quantum.Standard.