Práce s Q# projekty

Ve verzi Azure Quantum Development Kitmůžete definovat Q# projekty, což jsou struktury složek s více Q# soubory, které mají přístup k prostředkům ostatních. Projekty jsou užitečné při vytváření opakovaně použitelných knihoven a logickém uspořádání zdrojového kódu.

Projekt Q# obsahuje soubor manifestu Q# s názvem qsharp.json a jeden nebo více souborů *.qs v zadané struktuře složek. Když uživatel otevře soubor *.qs v editoru VS Code nebo nastaví project_root soubor v Jupyter Notebook nebo Pythonu, kompilátor vyhledá soubor manifestu v okolní hierarchii složek a určí obor projektu. Pokud není nalezen žádný soubor manifestu, kompilátor funguje v režimu jednoho souboru. Projekt Q# je možné vytvořit ručně nebo přímo ve VS Code.

Požadavky

• Pracovní prostor Azure Quantum ve vašem předplatném Azure. Informace o vytvoření pracovního prostoru najdete v tématu Create pracovního prostoru Azure Quantum.
• Prostředí Pythonu s nainstalovaným Pythonem a Pipem .
• Visual Studio Code s nainstalovaným rozšířením Azure Quantum Development Kit a Python .
• Azure Quantum qsharp a azure-quantum balíčky.

Q# Definování projektu

Q# Projekt je definován přítomností souboru manifestu qsharp.json a složky src (která obsahuje Q# zdrojové soubory), které musí být v kořenové složce projektu. U Q# programů Q# kompilátor rozpozná složku projektu automaticky. Pro programy Python a poznámkové bloky Jupyter musíte zadat Q# složku projektu s voláním qsharp.init . Struktura složek pro Q# projekt ale zůstává stejná pro všechny typy programů.

Q# Použití programu

Definování složky projektu (Q# programy)

Při otevření souboru *.qs v editoru Q# VS Code hledá kompilátor soubor manifestu qsharp.json směrem nahoru ve struktuře složek. Pokud kompilátor najde soubor manifestu, vyhledá soubory *.qs ve všech podsložkách adresáře src a uloží všechny operace nebo funkce do mezipaměti a zpřístupní tyto operace a funkce pro všechny soubory *.qs podle pravidel vyloučení souboru manifestu.

Například s ohledem na tuto strukturu složek:

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

Když otevřete soubor /src/TeleportOperation/PrepareState/PrepareState.qs, Q# kompilátor:

1. Zkontroluje soubor qsharp.json /src/TeleportOperation/PrepareState/.
2. Zkontroluje qsharp.json v /src/TeleportOperation.
3. Zkontroluje qsharp.json/src.
4. Kontroluje /qsharp.json.
5. / Vytvoří se jako kořenový adresář projektu a zahrne všechny soubory *.qs v kořenovém adresáři v projektu podle nastavení souboru manifestu.

Použití Pythonu nebo Jupyter Notebook

Definování složky projektu (programy Python a Jupyter Notebook)

Pokud pro přístup k Q# prostředkům používáte program v Pythonu nebo Jupyter Notebook buňku, musíte nastavit kořenový adresář projektu přímo pomocí qsharp.init příkazu . Použití stejné struktury složek jako v předchozím příkladu

• Teleportation_project
  • qsharp.json
  • src
  • MyPythonProgram.py
    • RunTeleport.qs
    • Teleportoperations
      • Teleport.qs
      • PrepareState
        • PrepareState.qs

byste nastavili před project_root voláním jakékoli Q# operace.

Za předpokladu, že se váš program v Pythonu nachází ve Q# složce projektu

import qsharp

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

Cesta ke kořenové složce je relativní vzhledem k souboru, který ji nastavuje, což znamená, že Q# složka projektu může být kdekoli a volající program nemusí být nutně v projektu. Platná cesta může být './MyProjects/Teleportation_project'také , nebo ../../Teleportation_project.

Kompilátor Q# ověří, že v zadané kořenové složce existuje platný soubor qsharp.json , a zpřístupní všechny prostředky *.qs ve složce src pro referenci podle pravidel vyloučení souboru manifestu.

Create souboru manifestu

Soubor manifestu je jednoduchý soubor .json s názvem qsharp.json , který může volitelně obsahovat pole autor, licence a .ints . Minimální realizovatelný soubor manifestu je řetězec {}. Při vytváření projektu v editoru Q# VS Code se pro vás vytvoří minimální soubor manifestu.

{}

Příklady souborů manifestu

Následuje několik příkladů, jak soubory manifestu můžou definovat rozsah projektu Q# .

V tomto příkladu je autor jediným zadaným polem, a proto jsou do projektu zahrnuty Q# všechny soubory *.qs v tomto adresáři a všechny jeho podadresáře.

{
    "author":"Microsoft"
}

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

Q# V rámci projektu můžete také použít soubor manifestu k vyladění nastavení Linteru VS CodeQ#. Ve výchozím nastavení jsou tři pravidla Linteru:

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

Pomocí souboru manifestu můžete každé pravidlo nastavit například na allow, warnnebo error.

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

Q# požadavky a vlastnosti projektu

Následující požadavky a konfigurace platí pro všechny Q# projekty.

• Všechny soubory *.qs, které chcete zahrnout do projektu, musí být ve složce s názvem src, která musí být v Q# kořenové složce projektu. Když vytvoříte projekt v editoru Q#/src VS Code, složka se vytvoří automaticky.
• Soubor manifestu qsharp.json by měl být na stejné úrovni jako složka src . Když vytvoříte projekt v editoru Q# VS Code, automaticky se vytvoří soubor qsharp.json .
• K operacím a funkcím v dostupných zdrojových souborech je možné přistupovat pomocí open příkazů:

open MyMathLib;
...
    Multiply(x,y);

nebo na ně odkazujete pomocí oboru názvů:

MyMathLib.Multiply(x,y);

Pouze pro Q# programy

• Pouze jeden soubor *.qs v Q# projektu může mít @EntryPoint() definovaný.
• Soubor *.qs s definicí @EntryPoint() se může nacházet na libovolné úrovni pod souborem manifestu.
• Jakákoli operace nebo funkce, které jsou uložené v mezipaměti ze souboru *.qs kdekoli v projektu, se v editoru Q# VS Code zobrazí v prediktivním textu.
• Pokud ještě nebyl přidán obor názvů pro vybranou operaci nebo funkci, VS Code automaticky přidá potřebný open příkaz.

Postup vytvoření Q# projektu

1. V průzkumníku souborů VS Code klikněte pravým tlačítkem na složku, kterou chcete použít pro Q# kořenovou složku projektu, a vyberte Create Q# projektu nebo složku otevřete a vyberte Zobrazit > paletu >Q#příkazů: Create Q# projektu....

2. VS Code vytvoří ve složce minimální qsharp.json soubor manifestu a přidá /src složku se souborem Main.qs šablony.

3. Podle potřeby upravte soubor manifestu. Viz Příklady souborů manifestu.

4. Přidejte a uspořádejte Q# zdrojové soubory ve /src složce .

5. Pokud k projektu přistupujete Q# z programu v Pythonu nebo Jupyter Notebook, nastavte cestu ke kořenové složce pomocí qsharp.initpříkazu . Tento příklad předpokládá, že se váš program nachází ve stejné složce jako kořenová složka Q# projektu:

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

6. Pokud v nástroji VS Code používáte pouze Q# soubory, kompilátor při otevření Q# souboru vyhledá soubor manifestu qsharp.json , určí kořenovou složku projektu a pak v podsložce vyhledá soubory *.qs.

Poznámka

Soubor manifestu a /src složku můžete vytvořit také ručně v kroku 2.

Příklad projektu

Tento kvantový teleportační program je příkladem projektu založeného Q# na struktuře složek uvedené výše a běží na místním simulátoru v nástroji VS Code. Pokud chcete program spustit na hardwaru Azure Quantum nebo simulátorech třetích stran, přečtěte si téma Začínáme s Q# programy a VSCode , kde najdete postup kompilace programu a připojení k pracovnímu prostoru Azure.

V příkladu se používá tato adresářová struktura:

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

Soubor manifestu qsharp.json obsahuje pole autora a licence :

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

Q# zdrojové soubory

S jedním drobným rozdílem @EntryPoint() – příkazem – jsou zdrojové soubory pro program, program v Pythonu nebo Jupyter Notebook stejnéQ#.

Hlavní soubor RunTeleport.qs obsahuje vstupní bod a odkazuje na TeleportLib obor názvů v 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 definuje Teleport() operaci a zavolá ji PrepareBellPair() z 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);
    }
}

Soubor PrepareState.qs obsahuje standardní opakovaně použitelnou operaci pro vytvoření páru bell.

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

Spuštění programů

Vyberte kartu pro prostředí, ve kterém program spouštíte.

Q# Spuštění programu

Pokud chcete tento program spustit, otevřete soubor RunTeleport.qs ve VS Code a vyberte Spustit.

Spuštění Jupyter Notebook

Pro Jupyter Notebook program zdrojové soubory nevyžadují @EntryPoint() atribut . Soubory fungují jenom jako zdrojové knihovny.

Pokud chcete tento program spustit v poznámkovém bloku Juptyer, otevřete nový poznámkový blok a spusťte následující buňky:

import qsharp

# set the root folder for the Q# project
# make adjustments to the path depending on where your program is saved

# this example assumes your program is in the same folder as the root folder
qsharp.init(project_root = './Teleportation_project')

Pokud je vaše cesta platná, zobrazí se potvrzovací zpráva. Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Spusťte program zavoláním hlavní operace pomocí %%qsharp příkazu magic.

%%qsharp
// call the main operation
RunTeleport.RunTeleportationExample();

nebo pomocí qsharp.eval() příkazu

print (qsharp.eval("RunTeleport.RunTeleportationExample()"));

Spuštění programu v Pythonu

Pro program v Pythonu zdrojové soubory nevyžadují @EntryPoint() atribut . Soubory fungují jenom jako zdrojové knihovny.

Chcete-li spustit tento program, spusťte následující příkazy:

import qsharp

# set the root folder for the Q# project
# make adjustments to the path depending on where your program is saved

# this example assumes your program is in the same folder as the root folder
qsharp.init(project_root = '/.Teleportation_project')

Pokud je vaše cesta platná, zobrazí se potvrzovací zpráva. Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Spusťte program voláním hlavní operace pomocí příkazu qsharp.eval()

print (qsharp.eval("RunTeleport.RunTeleportationExample()"));