Freigeben über

Arbeiten mit Q# Projekten

  • Artikel

Mit Azure Quantum Development Kitkönnen Sie Projekte definierenQ#, bei denen es sich um Ordnerstrukturen mit mehreren Q# Dateien handelt, die auf die Vorgänge und Funktionen der anderen zugreifen können. Projekte sind hilfreich, um Ihren Quellcode logisch zu organisieren. Sie können Projekte auch als externe Abhängigkeiten oder benutzerdefinierte Bibliotheken verwenden, auf die von externen Quellen zugegriffen werden kann.

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

Ein externes Q# Projekt ist ein Standardprojekt Q# , das sich in einem anderen Verzeichnis oder in einem öffentlichen GitHub-Repository befindet und Anweisungen verwendet export , um zu definieren, auf welche Funktionen und Vorgänge von externen Programmen zugegriffen werden kann. Programme definieren das externe Projekt als Abhängigkeit in ihrer Manifestdatei und verwenden import Anweisungen für den Zugriff auf die Elemente (Vorgänge, Funktionen, Strukturen und Namespaces) im externen Projekt. Weitere Informationen finden Sie unter Verwenden von Projekten als externe Abhängigkeiten.

Voraussetzungen

  • Ein Azure Quantum-Arbeitsbereich in Ihrem Azure-Abonnement. Zur Erstellung eines Arbeitsbereichs, siehe bitte Erstellen eines Azure Quantum Arbeitsbereichs.
  • Visual Studio Code mit der installierten AzureQuantum Development Kit- und Python-Erweiterung.
  • Ein GitHub-Konto, wenn Sie planen, Ihr externes Projekt in einem öffentlichen GitHub-Repository zu veröffentlichen.

Für die Ausführung von Python-Programmen benötigen Sie auch Folgendes:

Definieren eines Q# Projekts

Ein Q# Projekt wird durch das Vorhandensein einer Manifestdatei namens qsharp.json und eines src-Ordners (der die Q# Quelldateien enthält) definiert, die sich beide im Stammordner des Projekts befinden müssen. Bei Q# Programmen und externen Projekten erkennt der Q# Compiler den Projektordner automatisch. Für Python-Programme und Jupyter-Notizbücher müssen Sie den Q# Projektordner mit einem qsharp.init Aufruf angeben. Die Ordnerstruktur für ein Q# Projekt bleibt jedoch für alle Arten von Programmen 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 Manifestdatei. Wenn eine Manifestdatei gefunden wird, enthält der Compiler dann alle Q# Dateien im Verzeichnis "/src" oder in einem seiner Unterverzeichnisse. Die Elemente jeder Datei werden allen anderen Dateien innerhalb des Projekts zur Verfügung gestellt.

Beispiel:

  • Teleportation_project
    • qsharp.json
    • src
      • Main.qs
      • TeleportOperations
        • TeleportLib.qs
        • PrepareState
          • PrepareStateLib.qs

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

  1. Überprüft /src/TeleportOperation/PrepareState/ auf qsharp.json.
  2. Überprüft /src/TeleportOperation auf qsharp.json.
  3. Überprüft /src auf qsharp.json.
  4. Sucht / nach qsharp.json.
  5. Richtet / als Stammverzeichnis des Projekts ein 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 mit dem Namen qsharp.json, die optional Autoren-, Lizenz- und Lintsfelder enthalten kann. Die mindestfähige Manifestdatei ist die Zeichenfolge {}. Wenn Sie ein Q# Projekt in VS Code erstellen, wird eine minimale Manifestdatei für Sie erstellt.

{}

Manifestdateibeispiele

Im Folgenden finden Sie einige Beispiele dafür, wie Manifestdateien den Umfang Ihres Q# Projekts definieren können.

  • In diesem Beispiel ist Author das einzige angegebene Feld, und daher werden alle *.qs-Dateien in diesem Verzeichnis und alle unterverzeichnisse im Q# Projekt enthalten.

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

  • In einem Q# Projekt 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

    Mit der Manifestdatei können Sie jede Regel entweder allowauf , , warnoder error, z. B.

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

  • Sie können die Manifestdatei auch verwenden, um ein externes Q# Projekt als Abhängigkeits- und Remotezugriffsvorgänge und -funktionen in diesem externen Projekt zu definieren. Weitere Informationen finden Sie unter Verwenden von Projekten als externe Abhängigkeiten.

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 mit dem Namen src befinden, der sich unter dem Stammordner der Datei Q#befinden muss. Wenn Sie ein Q# Projekt in VS Code erstellen, wird der /src Ordner automatisch erstellt.

  • Die Manifestdatei sollte sich auf derselben Ebene wie der Ordner "src " befinden. Wenn Sie ein Q# Projekt in VS Code erstellen, wird automatisch eine minimale Datei erstellt.

  • Verwenden Sie import Anweisungen zum Verweisen auf Vorgänge und Funktionen aus anderen Dateien im Projekt.

    import MyMathLib.*;  //imports all the callables in the MyMathLib namespace
...
    Multiply(x,y);

    oder einzeln mit dem Namespace darauf verweisen

    MyMathLib.Multiply(x,y);

Nur für Q# Projekte

  • Nur eine *.qs-Datei in einem Q# Projekt kann einen Einstiegspunkt definieren, der durch einen einzelnen Main() Vorgang definiert ist.
  • Die Datei "*.qs" mit der Einstiegspunktdefinition kann sich auf einer beliebigen Ebene unterhalb der Manifestdatei befinden.
  • Alle Vorgänge oder Funktionen, die von einer *.qs-Datei an einer beliebigen Stelle im Q# Projekt zwischengespeichert werden, werden im Vorhersagetext in VS Code angezeigt.
  • Wenn der Namespace für einen ausgewählten Vorgang oder eine ausgewählte Funktion noch nicht importiert wird, fügt VS Code automatisch die erforderliche import Anweisung hinzu.

Schritte zum Erstellen eines Q# Projekts

Diese Schritte gelten für alle Q# Projekte.

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

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

  3. Bearbeiten Sie die Manifestdatei nach Bedarf. Siehe Manifestdateibeispiele.

  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-Notizbuch auf das Q# Projekt zugreifen, legen Sie den Pfad des Stammordners mithilfe von qsharp.init. In diesem Beispiel wird davon ausgegangen, dass sich Ihr Programm im Ordner "/src" 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 einer Manifestdatei, bestimmt den Stammordner des Projekts und durchsucht dann den Unterordner nach *.qs-Dateien.

Hinweis

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

Beispielprojekt

Dieses Quantenteleportationsprogramm ist ein Beispiel für ein Q# Projekt, das auf der zuvor gezeigten einzelnen 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 Q# Programmen und VSCode ", um Ihr Programm zu kompilieren und eine Verbindung mit Ihrem Azure-Arbeitsbereich herzustellen.

Im Beispiel wird diese Verzeichnisstruktur verwendet:

  • Teleportation_project
    • qsharp.json
    • src
      • Main.qs
      • TeleportOperations
        • TeleportLib.qs
        • PrepareState
          • PrepareStateLib.qs

Die Manifestdatei enthält die Autoren - und Lizenzfelder :

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

Q# Quelldateien

Die Hauptdatei "Main.qs" enthält den Einstiegspunkt und verweist auf den TeleportOperations.TeleportLib Namespace von TeleportLib.qs.


    import TeleportOperations.TeleportLib.Teleport;   // references the Teleport operation from TeleportLib.qs

    operation Main() : Unit {
        use msg = Qubit();
        use target = Qubit();

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

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

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


    import TeleportOperations.PrepareState.PrepareStateLib.*;     // references the namespace in PrepareStateLib.qs
 
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

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

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

        Reset(here);
    }

Die Datei PrepareStateLib.qs enthält einen standardmäßigen wiederverwendbaren Vorgang zum Erstellen eines Bell-Paares .

    
    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.

Um dieses Programm auszuführen, öffnen Sie die Datei "Main.qs" in VS Code, und wählen Sie "Ausführen" aus.

Konfigurieren von Q# Projekten als externe Abhängigkeiten

Ein Q# Projekt kann auch als externe Abhängigkeit für andere Projekte konfiguriert werden, ähnlich wie eine Bibliothek, in der die Funktionen und Vorgänge im externen Q# Projekt für mehrere Q# Projekte zur Verfügung gestellt werden. Eine externe Abhängigkeit kann sich auf einer Laufwerkfreigabe befinden oder in einem öffentlichen GitHub-Repository veröffentlicht werden.

Um ein Q# Projekt als externe Abhängigkeit zu verwenden, müssen Sie:

  • Fügen Sie das externe Projekt als Abhängigkeit in der Manifestdatei des aufrufenden Projekts hinzu.
  • Wenn das externe Projekt auf GitHub veröffentlicht wird, fügen Sie der Manifestdatei des externen Projekts die Eigenschaft "files" hinzu.
  • Fügen Sie dem externen Projekt Anweisungen hinzu export .
  • Fügen Sie dem aufrufenden Projekt Anweisungen hinzu import .

Konfigurieren der Manifestdateien

Externe Q# Projekte können sich auf einer lokalen oder Netzwerklaufwerkfreigabe befinden oder in einem öffentlichen GitHub-Repository veröffentlicht werden.

Die aufrufende Projektmanifestdatei

Um einem externen Projekt eine Abhängigkeit zu einer Laufwerkfreigabe hinzuzufügen, definieren Sie die Abhängigkeit in der Manifestdatei des aufrufenden Projekts.

{
    "author": "Microsoft",
    "license": "MIT",
    "dependencies": {
        "MyDependency": {
            "path": "/path/to/project/folder/on/disk"
        }
    }
}

dabei ist "MyDependency" eine benutzerdefinierte Zeichenfolge, die den Namespace beim Aufrufen eines Vorgangs identifiziert. Wenn Sie beispielsweise eine Abhängigkeit mit dem Namen "MyMathFunctions" erstellen, würden Sie eine Funktion aus dieser Abhängigkeit aufrufen.MyMathFunctions.MyFunction()

So fügen Sie einem Projekt, das in einem öffentlichen GitHub-Repository veröffentlicht wird, eine Abhängigkeit hinzu

{
    "author": "Microsoft",
    "dependencies": {
        "MyDependency": {
            "github": {
                "owner": "GitHubUser",
                "repo": "GitHubRepoName",
                "ref": "CommitHash",
                "path": "/path/to/dependency"
            }
        }
}
  • Bei GitHub-Abhängigkeiten bezieht sich "ref" auf eine GitHub-Referenz. Microsoft empfiehlt, immer einen Commit-Hash zu verwenden, sodass Sie sich auf eine bestimmte Version Ihrer Abhängigkeit verlassen können.

Die Manifestdatei des externen Projekts

Wenn Ihr externes Q# Projekt in einem öffentlichen GitHub-Repository veröffentlicht wird, müssen Sie der Manifestdatei des externen Projekts die Dateieigenschaft hinzufügen, einschließlich aller im Projekt verwendeten Dateien.

{
    "author": "Microsoft",
    "license": "MIT",
    "files": [ "src/MyMathFunctions.qs", "src/Strings/MyStringFunctions.qs" ]
}

Die Eigenschaft "files" ist optional für ein externes Projekt, über "path" das importiert wird (d. s. einen lokalen dateipathbasierten Import). Es ist nur für Projekte erforderlich, die auf GitHub veröffentlicht wurden.

Verwenden der Export-Anweisung

Um Funktionen und Vorgänge in einem externen Projekt für das Aufrufen von Projekten zugänglich zu machen, verwenden Sie die export Anweisung. Sie können alle aufrufbaren Elemente in der Datei exportieren. Die Syntax für Wildcards wird nicht unterstützt, Sie müssen die einzelnen Aufrufe angeben, die exportiert werden können.

operation Operation_A() : Unit {
...
}
operation Operation_B() : Unit  {
...
}

// makes just Operation_A available to calling programs
export Operation_A;           

// makes Operation_A and Operation_B available to calling programs         
export Operation_A, Operation_B, etc.; 

// makes Operation_A available as 'OpA'
export Operation_A as OpA;

Verwenden der Import-Anweisung

Im aufrufenden Programm verwenden import Sie Anweisungen, um Elemente aus einer externen Abhängigkeit verfügbar zu machen. import Anweisungen verwenden den Namespace, der für die Abhängigkeit in der Manifestdatei definiert ist. Beispiel: Für diese Abhängigkeit

{
    "author": "Microsoft",
    "license": "MIT",
    "dependencies": {
        "MyMathFunctions": {
            "path": "/path/to/project/folder/on/disk"
        }
    }
}

Sie importieren Aufrufables als

import MyMathFunctions.MyFunction;  // imports "MyFunction()" from the namespace
...

Die import Anweisung unterstützt auch die Syntax und Aliase für Wildcards.

// imports all items from the "MyMathFunctions" namespace
import MyMathFunctions.*;        

// imports the namespace as "Math", all items are accessible via "Math.<callable>"
import MyMathFunctions as Math;   

// imports a single item, available in the local scope as "Add"
import MyMathFunctions.MyFunction as Add;        

// imports can be combined on one line
import MyMathFunctions.MyFunction, MyMathFunctions.AnotherFunction as Multiply;

Hinweis

Die derzeit verwendete open Anweisung in Q#, die zum Verweisen auf Bibliotheken und Namespaces verwendet wird, wird weiterhin unterstützt, wird aber schließlich nicht mehr unterstützt. In der Zwischenzeit können Sie ihre aktuellen Dateien optional aktualisieren, um die import Anweisung zu verwenden. Beispielsweise kann open Microsoft.Quantum.Diagnostics; durch import Microsoft.Quantum.Diagnostics.*;ersetzt werden. Beachten Sie außerdem, dass Sie beim Verwenden der import Anweisung mit den Standardbibliotheken Q# den Stammnamespace Stdauf " kürzen können. So kann z. B. import Microsoft.Quantum.Diagnostics.*; als import Std.Diagnostics.*; geschrieben werden.

Beispiel für ein externes Projekt

In diesem Beispiel verwenden Sie das gleiche Teleportierungsprogramm wie im vorherigen Beispiel, trennen aber das Anrufprogramm und die Aufrufewerte in verschiedene Projekte.

  1. Erstellen Sie zwei Ordner auf Ihrem lokalen Laufwerk, z. B. "Project_A" und "Project_B".

  2. Erstellen Sie ein Q# Projekt in jedem Ordner, indem Sie die Schritte zum Erstellen eines Q# Projekts ausführen.

  3. Kopieren Sie in Project_A das aufrufende Programm den folgenden Code in die Manifestdatei, und bearbeiten Sie den Pfad nach Bedarf für Project_B

    {
  "author": "Microsoft",
  "license": "MIT",
  "dependencies": {
    "MyTeleportLib": {
      "path": "/Project_B" 
      }
    }
  }

  4. Kopieren Sie in Project_A den folgenden Code in "Main.qs".

    import MyTeleportLib.Teleport;   // imports the Teleport operation from the MyTeleportLib namespace defined in the manifest file

operation Main() : Unit {
    use msg = Qubit();
    use target = Qubit();

    H(msg);
    Teleport(msg, target);    // calls the Teleport() operation from the MyTeleportLib namespace
    H(target);

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

    Reset(msg);
    Reset(target);
    }
}

  5. Kopieren Sie in Project_B den folgenden Code in "Main.qs".

    
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

        PrepareBellPair(here, target); 
        Adjoint PrepareBellPair(msg, here);

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

        Reset(here);
    }

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

    export Teleport;       //  makes the Teleport operation available to external programs

    Hinweis

    Beachten Sie, dass der PrepareBellPair Vorgang nicht exportiert werden muss, da er nicht direkt aus Ihrem Programm in Project_A aufgerufen wird. Da sie sich im lokalen Bereich von Project_B befindet, kann bereits über den Teleport Vorgang darauf zugegriffen werden.

  6. Um das Programm auszuführen, öffnen Sie "/Project_A/Main.qs" in VS Code, und wählen Sie "Ausführen" aus.

Projekte und implizite Namespaces

Wenn Q# in Projekten kein Namespace in einem *.qs-Programm angegeben ist, verwendet der Compiler den Dateinamen als Namespace. Wenn Sie auf eine aufrufbare Aus einer externen Abhängigkeit verweisen, wird dann die Syntax <"dependencyName>" verwendet.<namespace>.<kann aufgerufen werden>. Wenn die Datei jedoch "Main.qs" heißt, geht der Compiler davon aus, dass der Namespace und die aufrufende Syntax "dependencyName>" lautet<.<kann aufgerufen werden>, wie im vorherigen Beispiel. import MyTeleportLib.Teleport

Da es nicht ungewöhnlich ist, mehrere Projektdateien zu haben, müssen Sie beim Verweisen auf aufrufbare Elemente die richtige Syntax berücksichtigen. Beispiel: in einem Projekt mit der folgenden Dateistruktur

  • src/
    • Main.qs
    • MathFunctions.qs

Aufrufe an die externe Abhängigkeit wären

import MyTeleportLib.MyFunction;        // "Main" namespace is implied

import MyTeleportLib.MathFunctions.MyFunction;   // "Math" namespace must be explicit

Weitere Informationen zum Namespaceverhalten finden Sie unter Benutzernamespaces.