Share via

Praca z projektami Q#

  • Artykuł

Wraz z wydaniem platformy Azure Quantum Development Kitmożna zdefiniować Q# projekty, które są strukturami folderów z wieloma Q# plikami, które mogą uzyskiwać dostęp do zasobów nawzajem. Projekty są przydatne do tworzenia bibliotek wielokrotnego użytku i logicznego organizowania kodu źródłowego.

Q# Projekt zawiera plik manifestu Q# o nazwie qsharp.json i co najmniej jeden plik *.qs w określonej strukturze folderów. Gdy użytkownik otworzy plik *.qs w programie VS Code lub ustawi project_root element w pliku Jupyter Notebook lub Python, kompilator przeszukuje otaczającą hierarchię folderów dla pliku manifestu i określa zakres projektu. Jeśli plik manifestu nie zostanie znaleziony, kompilator działa w trybie pojedynczego pliku. Projekt Q# można utworzyć ręcznie lub bezpośrednio w programie VS Code.

Wymagania wstępne

Definiowanie Q# projektu

Projekt Q# jest definiowany przez obecność pliku manifestu qsharp.json i folderu src (zawierającego Q# pliki źródłowe), który musi znajdować się w folderze głównym projektu. W przypadku Q# programów Q# kompilator automatycznie wykrywa folder projektu. W przypadku programów języka Python i notesów Jupyter Notebook należy określić Q# folder projektu z wywołaniem qsharp.init . Jednak struktura folderów dla Q# projektu pozostaje taka sama dla wszystkich typów programów.

Obraz przedstawiający hierarchię Q# folderów dla projektu.

Definiowanie folderu projektu (Q# programy)

Po otwarciu pliku *.qs w programie VS Code Q# kompilator wyszukuje w górę strukturę folderów dla pliku manifestu qsharp.json . Jeśli znajdzie plik manifestu, kompilator przeszukuje w dół wszystkie podfoldery katalogu src dla plików *.qs i buforuje wszystkie operacje lub funkcje oraz udostępnia te operacje i funkcje wszystkim plikom *.qs zgodnie z regułami wykluczania pliku manifestu.

Na przykład biorąc pod uwagę tę strukturę folderów:

  • Teleportation_project
    • qsharp.json
    • Src
      • RunTeleport.qs
      • TeleportOperations
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

podczas otwierania pliku /src/TeleportOperation/PrepareState/PrepareState.qsQ# kompilator:

  1. Sprawdza /src/TeleportOperation/PrepareState/ dla pliku qsharp.json .
  2. Sprawdza /src/TeleportOperation dla qsharp.json.
  3. Sprawdza /src pod kątem qsharp.json.
  4. Sprawdza / qsharp.json.
  5. / Ustanawia jako katalog główny projektu i zawiera wszystkie pliki *.qs w katalogu głównym w projekcie zgodnie z ustawieniami pliku manifestu.

Tworzenie pliku manifestu

Plik manifestu to prosty plik .json o nazwie qsharp.json , który opcjonalnie może zawierać pola author, license i .ints . Minimalny realny plik manifestu to ciąg {}. Podczas tworzenia Q# projektu w programie VS Code zostanie utworzony minimalny plik manifestu.

{}

Przykłady plików manifestu

Poniżej przedstawiono kilka przykładów sposobu, w jaki pliki manifestu mogą definiować zakres Q# projektu.

W tym przykładzie autor jest jedynym określonym polem i dlatego wszystkie pliki *.qs w tym katalogu i wszystkie jego podkatalogi są uwzględnione w projekcie Q# .

{
    "author":"Microsoft"
}

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

W projekcie Q# można również użyć pliku manifestu, aby dostosować ustawienia linter programu VS Code Q# . Domyślnie trzy reguły lintera to:

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

Za pomocą pliku manifestu można ustawić każdą regułę na allow, warnlub error, na przykład

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

Q# wymagania i właściwości projektu

Następujące wymagania i konfiguracje mają zastosowanie do wszystkich Q# projektów.

  • Wszystkie pliki *.qs, które mają być zawarte w projekcie, muszą znajdować się w folderze o nazwie src, który musi znajdować się w Q# folderze głównym projektu. Podczas tworzenia Q# projektu w programie VS Code /src folder jest tworzony automatycznie.
  • Plik manifestu qsharp.json powinien być na tym samym poziomie co folder src . Podczas tworzenia Q# projektu w programie VS Code plik qsharp.json jest tworzony automatycznie.
  • Dostęp do operacji i funkcji dostępnych plików źródłowych można uzyskać za pomocą open instrukcji:
open MyMathLib;
...
    Multiply(x,y);

lub odwoływanie się do nich za pomocą przestrzeni nazw:

MyMathLib.Multiply(x,y);

Tylko w przypadku Q# programów

  • Zdefiniowany może być @EntryPoint() tylko jeden plik *.qs w projekcieQ#.
  • Plik *.qs z definicją @EntryPoint() można znaleźć na dowolnym poziomie poniżej pliku manifestu.
  • Każda operacja lub funkcja buforowana z pliku *.qs w dowolnym miejscu projektu Q# jest wyświetlana w tekście predykcyjnym w programie VS Code.
  • Jeśli przestrzeń nazw dla wybranej operacji lub funkcji nie została jeszcze dodana, program VS Code automatycznie dodaje niezbędną open instrukcję.

Kroki tworzenia Q# projektu

  1. W Eksploratorze plików programu VS Code kliknij prawym przyciskiem myszy folder, którego chcesz użyć dla Q# folderu głównego projektu, a następnie wybierz polecenie Utwórz Q# projekt lub otwórz folder i wybierz polecenie Wyświetl > paletę Q#>Q#poleceń: Utwórz projekt....

  2. Program VS Code tworzy minimalny plik manifestu qsharp.json w folderze i dodaje /src folder z plikiem szablonu Main.qs .

  3. Edytuj plik manifestu zgodnie z potrzebami. Zobacz Przykłady plików manifestu.

  4. Dodaj i organizuj Q# pliki źródłowe w folderze /src .

  5. Jeśli uzyskujesz dostęp do Q# projektu z poziomu programu w języku Python lub notesu Jupyter Notebook, ustaw ścieżkę folderu głównego przy użyciu polecenia qsharp.init. W tym przykładzie przyjęto założenie, że program znajduje się w tym samym folderze co folder Q# główny projektu:

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

  6. Jeśli używasz tylko Q# plików w programie VS Code, podczas otwierania Q# pliku kompilator wyszukuje plik manifestu qsharp.json , określa folder główny projektu, a następnie skanuje podfolder plików *.qs.

Uwaga

Możesz również ręcznie utworzyć plik manifestu /src i folder w kroku 2.

Przykładowy projekt

Ten program teleportacji kwantowej jest przykładem Q# projektu opartego na strukturze folderów pokazanej wcześniej i działa na lokalnym symulatorze w programie VS Code. Aby uruchomić program na sprzęcie Azure Quantum lub symulatorach innych firm, zobacz Wprowadzenie do Q# programów i programu VSCode , aby uzyskać instrukcje kompilowania programu i nawiązywania połączenia z obszarem roboczym platformy Azure.

W przykładzie użyto tej struktury katalogów:

  • Teleportation_project
    • qsharp.json
    • Src
      • RunTeleport.qs
      • TeleportOperations
        • Teleport.qs
        • PrepareState
          • PrepareState.qs

Plik manifestu qsharp.json zawiera pola autorów i licencji:

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

Q# pliki źródłowe

Z jedną drobną różnicą — @EntryPoint() instrukcja — pliki źródłowe są takie same w Q# przypadku programu, programu w języku Python lub notesu Jupyter Notebook.

Główny plik RunTeleport.qs zawiera punkt wejścia i odwołuje się do TeleportLib przestrzeni nazw w pliku 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 definiuje operację Teleport() i wywołuje operację PrepareBellPair() z pliku PrepareState.qs.

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);
    }
}

Plik PrepareState.qs zawiera standardową operację wielokrotnego użytku w celu utworzenia pary bell.

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

Uruchamianie programów

Wybierz kartę środowiska, w którym jest uruchomiony program.

Aby uruchomić ten program, otwórz plik RunTeleport.qs w programie VS Code i wybierz pozycję Uruchom.