Arbeiten mit Q# Projekten

  • Artikel

Mit der Veröffentlichung von Azure Quantum Development Kitkönnen Sie Projekte definierenQ#, bei denen es sich um Ordnerstrukturen mit mehreren Q# Dateien handelt, die auf die Ressourcen des anderen zugreifen können. Projekte sind hilfreich, um wiederverwendbare Bibliotheken zu erstellen und Ihren Quellcode logisch zu organisieren.

Ein Q# Projekt enthält eine Q# Manifestdatei mit dem Namen qsharp.json und mindestens eine *.qs-Datei in einer angegebenen Ordnerstruktur. Wenn ein Benutzer eine *.qs-Datei in VS Code öffnet oder in project_root einer Jupyter Notebook- oder Python-Datei festlegt, durchsucht der Compiler die umgebende Ordnerhierarchie nach der Manifestdatei und bestimmt den Bereich des Projekts. Wenn keine Manifestdatei gefunden wird, arbeitet der Compiler in einem einzelnen Dateimodus. Ein Q# Projekt kann manuell oder direkt in VS Code erstellt werden.

Voraussetzungen

Definieren eines Q# Projekts

Ein Q# Projekt wird durch das Vorhandensein einer qsharp.json Manifestdatei und eines src-Ordners (der die Q# Quelldateien enthält) definiert, die sich beide im Stammordner des Projekts befinden müssen. Bei Q# Programmen erkennt der Q# Compiler den Projektordner automatisch. Für Python-Programme und Jupyter Notebooks müssen Sie den Q# Projektordner mit einem qsharp.init Aufruf angeben. Die Ordnerstruktur für ein Q# Projekt bleibt jedoch für alle Programmtypen gleich.

Abbildung der Ordnerhierarchie für ein Q# Projekt.

Definieren des Projektordners (Q# Programme)

Wenn eine *.qs-Datei in VS Code geöffnet wird, sucht der Q# Compiler in der Ordnerstruktur nach oben nach einer qsharp.json Manifestdatei. Wenn er eine Manifestdatei findet, durchsucht der Compiler dann alle Unterordner des src-Verzeichnisses nach *.qs-Dateien, speichert alle Vorgänge oder Funktionen zwischen und macht diese Vorgänge und Funktionen gemäß den Ausschlussregeln der Manifestdatei für alle *.qs-Dateien verfügbar.

Beispiel:

  • Teleportation_project
    • qsharp.json
    • src
      • RunTeleport.qs
      • TeleportOperationen
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

wenn Sie die Datei /src/TeleportOperation/PrepareState/PrepareState.qs öffnen, wird der Compiler wiederhergestellt Q# :

  1. Überprüft /src/TeleportOperation/PrepareState/ auf eine qsharp.json Datei.
  2. Überprüft /src/TeleportOperation auf qsharp.json.
  3. Überprüft /src auf qsharp.json.
  4. Überprüft /, ob qsharp.json.
  5. Wird / als Stammverzeichnis des Projekts eingerichtet und enthält alle *.qs-Dateien unter dem Stamm im Projekt gemäß den Einstellungen der Manifestdatei.

So erstellen Sie eine Manifestdatei

Eine Manifestdatei ist eine einfache .json-Datei namens qsharp.json , die optional Autoren-, Lizenz- und INTS-Felder enthalten kann. Die minimale praktikable Manifestdatei ist die Zeichenfolge {}. Wenn Sie ein Q# Projekt in VS Code erstellen, wird eine minimale Manifestdatei für Sie erstellt.

{}

Beispiele für Manifestdateien

Im Folgenden finden Sie einige Beispiele, wie Manifestdateien den Bereich Ihres Q# Projekts definieren können.

In diesem Beispiel ist author das einzige angegebene Feld, und daher sind alle *.qs-Dateien in diesem Verzeichnis und alle zugehörigen Unterverzeichnisse im Q# Projekt enthalten.

{
    "author":"Microsoft"
}

{
    "author":"Microsoft",
    "license":"MIT"
}

Innerhalb eines Q# Projekts können Sie auch die Manifestdatei verwenden, um die VS Code Q# Linter-Einstellungen zu optimieren. Standardmäßig sind die drei Linter-Regeln:

  • needlessParens: default = allow
  • divisionByZero: default = warn
  • redundantSemicolons: default = warn

Mithilfe der Manifestdatei können Sie jede Regel entweder allowauf , warnoder errorfestlegen, z. B.

{
    "author":"Microsoft",
    "lints": [
        {
          "lint": "needlessParens",
          "level": "allow"
        },
        {
          "lint": "redundantSemicolons",
          "level": "warn"
        },
        {
          "lint": "divisionByZero",
          "level": "error"
        }
      ]
}

Q# Projektanforderungen und -eigenschaften

Die folgenden Anforderungen und Konfigurationen gelten für alle Q# Projekte.

  • Alle *.qs-Dateien, die sie in das Projekt einbeziehen möchten, müssen sich unter einem Ordner namens src befinden, der sich unter dem Q# Projektstammordner befinden muss. Wenn Sie ein Q# Projekt in VS Code erstellen, wird der /src Ordner automatisch erstellt.
  • Die qsharp.json Manifestdatei sollte sich auf der gleichen Ebene wie der Ordner src befinden. Wenn Sie ein Q# Projekt in VS Code erstellen, wird die qsharp.json-Datei automatisch erstellt.
  • Auf Vorgänge und Funktionen in verfügbaren Quelldateien kann mithilfe von open Anweisungen zugegriffen werden:
open MyMathLib;
...
    Multiply(x,y);

oder verweisen sie mit dem Namespace auf sie:

MyMathLib.Multiply(x,y);

Nur für Q# Programme

  • Nur eine *.qs-Datei in einem Q# Projekt kann definiert @EntryPoint() sein.
  • Die *.qs-Datei mit der @EntryPoint() Definition kann sich auf einer beliebigen Ebene unterhalb der Manifestdatei befinden.
  • Alle Vorgänge oder Funktionen, die aus einer *.qs-Datei irgendwo im Q# Projekt zwischengespeichert werden, werden in VS Code als Vorhersagetext angezeigt.
  • Wenn der Namespace für einen ausgewählten Vorgang oder eine ausgewählte Funktion noch nicht hinzugefügt wurde, fügt VS Code automatisch die erforderliche open Anweisung hinzu.

Schritte zum Erstellen eines Q# Projekts

  1. Klicken Sie im VS Code-Datei-Explorer mit der rechten Maustaste auf den Ordner, den Sie für den Q# Projektstammordner verwenden möchten, und wählen Sie Create Q# Projekt aus, oder öffnen Sie den Ordner, und wählen Sie Befehlspalette >Q#anzeigen>: Create projektQ#... aus.

  2. VS Code erstellt eine minimale qsharp.json Manifestdatei im Ordner und fügt einen /src Ordner mit einer Vorlagendatei hinzu Main.qs .

  3. Bearbeiten Sie die Manifestdatei nach Bedarf. Weitere Informationen finden Sie unter Beispiele für Manifestdateien.

  4. Fügen Sie Ihre Q# Quelldateien unter dem Ordner hinzu, und organisieren Sie sie /src .

  5. Wenn Sie über ein Python-Programm oder Jupyter Notebook auf das Q# Projekt zugreifen, legen Sie den Stammordnerpfad mithilfe von qsharp.initfest. In diesem Beispiel wird davon ausgegangen, dass sich Ihr Programm im selben Ordner wie der Stammordner des Q# Projekts befindet:

    qsharp.init(project_root = './Teleportation_project')

  6. Wenn Sie nur Q# Dateien in VS Code verwenden, sucht der Compiler beim Öffnen einer Q# Datei nach der qsharp.json Manifestdatei, bestimmt den Projektstammordner und durchsucht dann den Unterordner auf *.qs-Dateien.

Hinweis

Sie können die Manifestdatei und den /src Ordner in Schritt 2 auch manuell erstellen.

Beispielprojekt

Dieses Quantenteleportationsprogramm ist ein Beispiel für ein Q# Projekt, das auf der zuvor gezeigten Ordnerstruktur basiert und auf dem lokalen Simulator in VS Code ausgeführt wird. Informationen zum Ausführen des Programms auf Azure Quantum-Hardware oder Simulatoren von Drittanbietern finden Sie unter Erste Schritte mit Programmen und VSCode, wie Sie Ihr Programm kompilieren und eine Verbindung mit Q# Ihrem Azure-Arbeitsbereich herstellen können.

Im Beispiel wird die folgende Verzeichnisstruktur verwendet:

  • Teleportation_project
    • qsharp.json
    • src
      • RunTeleport.qs
      • TeleportOperationen
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

Die qsharp.json Manifestdatei enthält die Felder Autor und Lizenz :

{
    "author":"Microsoft",
    "license":"MIT"
}

Q# Quelldateien

Mit einem geringfügigen Unterschied - der @EntryPoint() -Anweisung - sind die Quelldateien für ein Q# Programm, ein Python-Programm oder eine Jupyter Notebook identisch.

Die Standard-Datei RunTeleport.qs enthält den Einstiegspunkt und verweist auf den TeleportLib Namespace in Teleport.qs.

namespace RunTeleport {

    open TeleportLib;   // references the TeleportLib namespace in Teleport.qs

    @EntryPoint()       // @EntryPoint() not necessary for Python or Jupyter Notebook programs
    operation RunTeleportationExample() : Unit {
        use msg = Qubit();
        use target = Qubit();

        H(msg);
        Teleport(msg, target);    // calls the Teleport() operation from Teleport.qs
        H(target);

        if M(target) == Zero {
            Message("Teleported successfully!");
        
        Reset(msg);
        Reset(target);
        }
    }
}

Teleport.qs definiert den Teleport() Vorgang und ruft den PrepareBellPair() Vorgang von PrepareState.qs auf.

namespace TeleportLib {

    open PrepareBell;     // references the PrepareBell namespace in PrepareState.qs
 
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

        PrepareBellPair(here, target);      // calls the PrepareBellPair() operation from PrepareState.qs
        Adjoint PrepareBellPair(msg, here);

        if M(msg) == One { Z(target); }
        if M(here) == One { X(target); }

        Reset(here);
    }
}

Die Datei PrepareState.qs enthält einen wiederverwendbaren Standardvorgang zum Erstellen eines Bell-Paares.

namespace PrepareBell {    
    
    operation PrepareBellPair(left : Qubit, right : Qubit) : Unit is Adj + Ctl {
        H(left);
        CNOT(left, right);
    }
}

Ausführen der Programme

Wählen Sie die Registerkarte für die Umgebung aus, in der Sie ihr Programm ausführen.

Öffnen Sie zum Ausführen dieses Programms die Datei RunTeleport.qs in VS Code, und wählen Sie Ausführen aus.