Some questions about Q# compilation

[QuXing9]

Description

Hello! I am very interested in the Q# quantum language, It's really an amazing work. And I am a beginner in the Q#, there are three questions that confuse me a lot. Can you help me answer them? Thanks very much!

• How can I execute a QIR file?

  I noticed that QIR can be emitted by adding the project property <QirGeneration>true</QirGeneration>. After building the project successfully, I get a .ll file in qir folder. Then I want to compile the .ll into an executable using the command clang++ ./QSharpApplication1.ll, QSharpApplication1.ll is my generated QIR file, but it throws the following error:

  LINK : fatal error LNK1561: entry point must be defined
  clang++: error: linker command failed with exit code 1561 (use -v to see invocation)

  It seems that main() function was not found. I noticed the QIR generator does not currently create a main(argc, argv) as specified here. But how can I execute a QIR file through clang from the command line?

• What is the process of Q# program compilation and execution on the windows system?

  According to my understanding, when executing a Q# program, the qsharp-compiler first compiles it to QIR. Then QIR runtime uses QIR bridge to translate the QIR into Clang-IR. Finally, the Clang compiler will compile Clang-IR into a .exe file. Is my understanding correct? If not, please correct me.

• What is the role of the full state simulator in the process of executing the Q# program?

  I use the command dotnet run to run .qs files on Windows, the Q# file is finally compiled into a .exe file. In this process, What is the role of the simulator?

Looking forward to your reply! Thanks very much!

Environment

• Visual Studio 2019
• Windows，.NET Core 3.1
• QDK(0.15.2103133969)

[bettinaheim]

@QuXing9 Thank you for the great questions! I'll do my best to answer:

• How can I execute a QIR file?

We are currently working on setting up convenient tooling to do that, and also fully integrating it into the QDK such that simply building a project will generate the bitcode, link it with the runtime libraries to build the executable and execute it. I am happy to give more updates as we go. :) To create a main, we current use a separate entry point generator that creates a C++ entry point. We are working on packaging a dotnet command line tool that given the path to either a Q# dll or in the future also just directly the path to the QIR bitcode builds an executable. That work is still on a feature branch, however.

In the meantime, we have set up a project for the UnitaryHack that allows to generate and execute .ll files that you could leverage to start experimenting with it. Here are the issues that give instructions for how to easily do that: https://github.com/microsoft/qsharp-compiler/issues/1028 and https://github.com/microsoft/qsharp-compiler/issues/1030. Let me know if that gets you started, or what exactly you were hoping to do and I am happy to assist.

• What is the process of Q# program compilation and execution on the windows system?

Yes, by and large your understand is correct. The Q# compiler compiles the project to QIR, and the clang linker links that QIR with the compiled runtime libraries to create an executable. The QIR in particular contains declarations without an implementations for a) Q# callables that are declared as intrinsic (the QIR declarations start with quantumqis), and b) the used runtime functions that provide basic functionality (such as function for e.g. array creation) as defined in the QIR specs (the QIR declarations start with quantumrt). These declarations are expected to have an implementation in the runtime libraries that are linked. The QIR runtime package that we link contains compiled native libraries that implement the functions b). It also contains the implementation for a) for the intrinsic Q# callables that are used by the Q# standard libraries (the ones in the QSharp Core library).

The whole idea of this setup is that the quantum instruction set is fully configurable; say you would like to run Q# code on a particular hardware backend that implements a certain set of quantumqis__ functions. One can then use or write a Q# library that defines these functions as intrinsic and define this as the "target package". I realize this doesn't fully explain how this works, but I wanted to share the idea behind all this - hopefully we will be able to set up some nice docs on that in the future. In the meantime, let me know if you have some concrete ideas you would like to experiment with.

• What is the role of the full state simulator in the process of executing the Q# program?

The simulator is very similar to the runtime libraries in that it provides the implementation for the quantumqis__ functions and is linked with the QIR and other runtime libraries to create the executable.

Does that help? Let me know if you have more questions, or if you had anything specific in mind that you wanted to do, and we'll do our best to help. :)

[QuXing9]

@bettinaheim Thank you for your detailed answers! I will have a try as soon as possible!

[QuXing9]

Hi! @bettinaheim Thanks for your detailed explanation, I successfully executed the QIR code on the Windows system using the Clang compiler. At the same time, I met two new problems, I want to ask you for advice.

• How to execute a Q# code that has multiple entry points?

  I noticed that there are some Q# programs containing more than one @EntryPoint() attributes in qsharp's regression test cases. But when I executed them using the dotnet run command, I got an error Required command was not provided.

  For example, the following testcase has two entry points:

  namespace Microsoft.Quantum.Testing.QIR {
    open Microsoft.Quantum.Intrinsic;
  
    @EntryPoint()
    operation RunProgram() : Unit {
        Message("Hello");
        return ();
    }
  
    @EntryPoint()
    operation RunProgram2() : Unit {
        Message("Hello2");
        return ();
    }
  }

  when I execute it using the command:

  dotnet run

  dotnet fails to compile and reports an error:

  Required command was not provided.
  
  Usage:
  test2 [options] [command]
  
  Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information
  
  Commands:
  simulate    (default) Run the program using a local simulator.

  After that, I tried compiling the Q# code into QIR firstly and then specifying the multiple entry points in the Main.cpp manually, it really works.

  But I want to ask that Is there a way to execute the Q# code which contains multiple entry points without manually specifying the entry?

• Is there a way to get the AST of the Q# program?

  I want to do some analysis of the Q# language. Does the qsharp-compiler implement an interface for getting the AST of Q# program? Or are there other third-party tools that can do this job?

Looking forward to your reply. Thanks in advance!

[QuXing9]

Problem solved, thanks!