Better targeting-related error messages for multi-project Q# applications

[rmshaffer]

Is your feature request related to a problem? Please describe.

When building a Q# application for Azure Quantum with multiple local projects, targeting-related error messages point to the source code in the executable project. This is not very informative, as the actual error may be in a referenced local library project, and the error doesn't tell me specifically what I'm doing that is unsupported.

For example, if I have a library project with the following code:

namespace AzureTestLibrary {
    open Microsoft.Quantum.Canon;
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Arrays;
    open Microsoft.Quantum.Convert;
    open Microsoft.Quantum.Measurement;

    operation MeasureEqualSuperposition() : Result[] {
        using (qubits = Qubit[3])
        {
            ApplyToEach(H, qubits);
            let results = ResultArrayAsBoolArray(MultiM(qubits));
            return BoolArrayAsResultArray(results);
        }
    }
}

and an executable project targeting ionq.simulator, referencing the above project, with the following code:

namespace AzureTestExecutable {
    open Microsoft.Quantum.Canon;
    open Microsoft.Quantum.Intrinsic;

    @EntryPoint()
    operation GenerateRandomNumber() : Result[] {
        return AzureTestLibrary.MeasureEqualSuperposition();
    }
}

then I get the following compilation error:

C:\QDK\Test\AzureTestExecutable\Program.qs(7,16): error QS5027: The callable MeasureEqualSuperposition requires runtime capabilities that are not supported by the target IonQProcessor. [C:\QDK\Test\AzureTestExecutable\AzureTestExecutable.csproj]

Describe the solution you'd like

It would be much better if these error messages pointed to the source code in the local library that actually needs to be changed. For example, I'd hope to get something like:

C:\QDK\Test\AzureTestLibrary\Library.qs(12,27): error QS5027: The callable ResultArrayAsBoolArray requires runtime capabilities that are not supported by the target IonQProcessor. [C:\QDK\Test\AzureTestLibrary\AzureTestLibrary.csproj]

Describe alternatives you've considered

The only alternative I am aware of would be to put all of the code in a single executable project. But for code-sharing purposes, this is not a practical solution.

Additional context

This is also necessary in order to merge microsoft/iqsharp#362, which will improve the experience for Azure Quantum users in Python and Jupyter. IQ# uses a similar project structure as described above - the user code is compiled into one or more library assemblies, and then a targeted executable references those library assemblies.

[bamarsha]

The callable MeasureEqualSuperposition requires runtime capabilities that are not supported by the target IonQProcessor.

This error message has been changed for the November release to mention the specific capability required, although it is probably not informative enough for this purpose. It'll be something like:

The callable MeasureEqualSuperposition requires the FullComputation runtime capability, which is not supported by the target IonQProcessor.

---

It would be much better if these error messages pointed to the source code in the local library that actually needs to be changed. For example, I'd hope to get something like:

C:\QDK\Test\AzureTestLibrary\Library.qs(12,27): error QS5027: The callable ResultArrayAsBoolArray requires runtime capabilities that are not supported by the target IonQProcessor. [C:\QDK\Test\AzureTestLibrary\AzureTestLibrary.csproj]

I'm not sure that there is an easy way in the Q# compiler to distinguish between libraries loaded via ProjectReference (where the user can edit the source), and libraries loaded via PackageReference (where the source can't be edited), or if we should have that distinction. Also, showing only the library location in the error message would not be correct, because the error is really in the executable, not the library. Libraries are allowed to use any runtime capability.

Maybe a different solution would be to continue showing the original error message, but also generate additional info diagnostics for the library callable itself? Something like

C:\QDK\Test\AzureTestExecutable\Program.qs(7,16): error QS5027: The callable MeasureEqualSuperposition requires the FullComputation runtime capability, which is not supported by the target IonQProcessor. [C:\QDK\Test\AzureTestExecutable\AzureTestExecutable.csproj]
C:\QDK\Test\AzureTestLibrary\Library.qs(12,27): info QS9999: MeasurementEqualSuperposition requires the FullComputation runtime capability because: The callable ResultArrayAsBoolArray requires the FullComputation runtime capability.[C:\QDK\Test\AzureTestLibrary\AzureTestLibrary.csproj]

[rmshaffer]

@SamarSha thanks for the response! Yes, I like your proposed solution much better than my proposal.

As for the ProjectReference vs. PackageReference distinction - I'm not sure of the technical implementation details there, but I certainly agree it wouldn't be particularly useful to add a pointer to source code that the user can't edit. In an ideal world we could show the error in source code that the user controls, and hide it for source code that they don't control. But I do appreciate that it may be hard to answer that question at compile time.

[cgranade]

…but I certainly agree it wouldn't be particularly useful to add a pointer to source code that the user can't edit.

I think there's some precedent for doing this and for that in fact being valuable to users; e.g.: SourceLink can be used in some cases to provide links to public GitHub repos containing code so that error messages can be traced back to publicly available code. I'd suspect that's out of scope or infeasible here, but at least in principle it's not so absurd to link back to library code.

[bamarsha]

@rmshaffer Related to showing the original .qs file name in the library as part of the error message: I think IQ# uses snippet_.qs for all filenames? Is it possible for IQ# to use different file names for each cell, so it's easier to find which cell the message is referring to? Or is it better to not show the filename at all, and rely only on the callable name of the parent callable?

[rmshaffer]

@SamarSha Yes, IQ# uses snippet.qs (sometimes also with a GUID included) for any Q# code written directly within the notebook. But it does use the actual filenames and paths for .qs files loaded from outside the notebook, whether in the same folder or imported from a different folder via %project. So it'd be nice to maintain that behavior.

And yes, it's definitely a reasonable feature request for IQ# to do something nicer for errors in snippets (the Q# code in the notebook). It can sometimes be hard to figure out even which cell an error message is referring to (or, worse, the code in question may have already been deleted from the notebook).