Jak pracovat s Q# projekty

V Azure Quantum Development Kitmůžete definovat Q# projekty, což jsou struktury složek s více Q# soubory, které mají přístup k operacím a funkcím ostatních. Projekty jsou užitečné pro logické uspořádání zdrojového kódu. Projekty můžete použít také jako externí závislosti nebo vlastní knihovny, ke kterým lze přistupovat z externích zdrojů.

Q# Projekt 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 ve VS Code nebo nastaví project_root soubor Jupyter Notebook nebo Python, kompilátor prohledá okolní hierarchii složek soubor manifestu a určí obor projektu. Pokud se nenajde žádný soubor manifestu, kompilátor pracuje v jednom režimu souboru. Projekt Q# lze vytvořit ručně nebo přímo ve VS Code.

Externí Q# projekt je standardní Q# projekt, který se nachází v jiném adresáři nebo ve veřejném úložišti GitHub a používá export příkazy k definování funkcí a operací, ke kterým mají externí programy přístup. Programy definují externí projekt jako závislost v souboru manifestu a používají import příkazy pro přístup k položkám (operace, funkce, struktury a obory názvů) v externím projektu. Další informace najdete v tématu Použití projektů jako externích závislostí.

Požadavky

• Pracovní prostor Azure Quantum ve vašem předplatném Azure Pokud chcete vytvořit pracovní prostor, přečtěte si téma Vytvoření pracovního prostoru Azure Quantum.
• Visual Studio Code s nainstalovaným rozšířením Azure Quantum Development Kit a Python .
• Pokud plánujete publikovat externí projekt do veřejného úložiště GitHub, účet GitHubu.

Pro spouštění programů v Pythonu potřebujete také:

• Prostředí Pythonu s nainstalovaným Pythonem a Pipem
• Azure Quantum qsharp a azure-quantum balíčky.

Q# Definování projektu

Projekt Q# je definován přítomností souboru manifestu s názvem qsharp.json a složkou src (která obsahuje Q# zdrojové soubory), z nichž obě musí být v kořenové složce projektu. U Q# programů a externích projektů Q# kompilátor rozpozná složku projektu automaticky. V případě programů Pythonu a jupyter Notebook musíte zadat Q# složku projektu s voláním qsharp.init . Struktura složek projektu Q# však zůstává stejná pro všechny typy programů.

import qsharp

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

Vytvoření souboru manifestu

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

{}

Příklady souborů manifestu

Následuje několik příkladů, jak mohou soubory manifestu 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",
      "license": "MIT"
  }
  

• Q# V rámci projektu můžete také použít soubor manifestu k vyladění nastavení Linter v editoru 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 na allow, warnnebo error, například

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

• Pomocí souboru manifestu můžete také definovat externí Q# projekt jako závislost a vzdáleně přistupovat k operacím a funkcím v daném externím projektu. Další informace najdete v tématu Použití projektů jako externích závislostí.

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 pod složkou s názvem src, která musí být v kořenové složce Q#. Při vytváření Q# projektu ve VS Code se /src složka vytvoří automaticky.

• Soubor manifestu by měl být na stejné úrovni jako složka src . Při vytváření Q# projektu ve VS Code se automaticky vytvoří minimální soubor.

• Pomocí import příkazů můžete odkazovat na operace a funkce z jiných souborů v projektu.

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

  nebo na ně odkazovat jednotlivě pomocí oboru názvů

  MyMathLib.Multiply(x,y);  
  

Pouze pro Q# projekty

• V projektu může být definovaný pouze jeden soubor Q# *.qs, který definuje jedna Main() operace.
• Soubor *.qs s definicí vstupního bodu lze nalézt na libovolné úrovni pod souborem manifestu.
• Jakákoli operace nebo funkce uložená v mezipaměti ze souboru *.qs kdekoli v projektu se zobrazí v prediktivním textu v editoru Q# VS Code.
• Pokud se obor názvů pro vybranou operaci nebo funkci ještě neimportuje, VS Code automaticky přidá potřebný import příkaz.

Postup vytvoření Q# projektu

Tyto kroky platí pro všechny Q# projekty.

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

2. VS Code vytvoří ve složce minimální 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 do /src složky.

5. Pokud k projektu přistupujete Q# z programu Pythonu nebo jupyter Notebooku, nastavte cestu ke kořenové složce pomocí qsharp.init. Tento příklad předpokládá, že váš program je ve složce Q# /src projektu:

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

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

Ukázkový projekt

Tento kvantový teleportační program je příkladem projektu založeného Q# na dříve zobrazené struktuře složek a běží na místním simulátoru v editoru 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.

Příklad používá tuto adresářovou strukturu:

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

Soubor manifestu obsahuje pole autora a licence :

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

Q# zdrojové soubory

Hlavní soubor Main.qs obsahuje vstupní bod a odkazuje na TeleportOperations.TeleportLib obor názvů z 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 definuje Teleport() operaci a volá PrepareBellPair() operaci z PrepareStateLib.qs.

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

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

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

Spuštění programů

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

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 /src folder
qsharp.init(project_root = '../Teleportation_project')

%%qsharp
// call the main operation
Main.Main();

print (qsharp.eval("Main.Main()"))

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')

print (qsharp.eval("Main.Main()"))

Konfigurace Q# projektů jako externích závislostí

Projekt Q# lze také nakonfigurovat jako externí závislost pro jiné projekty, podobně jako knihovna, kde jsou funkce a operace v externím Q# projektu zpřístupněny více Q# projektům. Externí závislost se může nacházet ve sdílené složce jednotky nebo publikovaná ve veřejném úložišti GitHub.

Pokud chcete projekt použít Q# jako externí závislost, musíte:

• Přidejte externí projekt jako závislost do souboru manifestu volajícího projektu.
• Pokud je externí projekt publikovaný na GitHubu, přidejte vlastnost "files" do souboru manifestu externího projektu.
• Přidejte export příkazy do externího projektu.
• Přidejte import příkazy do volajícího projektu.

Konfigurace souborů manifestu

Externí Q# projekty se můžou nacházet ve sdílené složce místní nebo síťové jednotky nebo publikované ve veřejném úložišti GitHub.

Soubor manifestu volajícího projektu

Pokud chcete přidat závislost do externího projektu ve sdílené složce jednotky, definujte závislost v souboru manifestu volajícího projektu.

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

where "MyDependency" je uživatelem definovaný řetězec, který identifikuje obor názvů při volání operace. Pokud například vytvoříte závislost s názvem "MyMathFunctions", zavoláte funkci z této závislosti pomocí MyMathFunctions.MyFunction().

Přidání závislosti do projektu publikovaného do veřejného úložiště GitHub

{
    "author": "Microsoft",
    "dependencies": {
        "MyDependency": {
            "github": {
                "owner": "GitHubUser",
                "repo": "GitHubRepoName",
                "ref": "CommitHash",
                "path": "/path/to/dependency"
            }
        }
}

• V případě závislostí GitHubu odkazuje odkaz na odkaz GitHubu. Microsoft doporučuje vždy používat hodnotu hash potvrzení, takže můžete spoléhat na konkrétní verzi vaší závislosti.

Soubor manifestu externího projektu

Pokud je váš externí Q# projekt publikovaný ve veřejném úložišti GitHub, musíte přidat vlastnost souborů do souboru manifestu externího projektu, včetně všech souborů použitých v projektu.

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

Vlastnost "files" je volitelná pro externí projekt, který se importuje ( "path" to znamená import založený na místní cestě k souborům). Vyžaduje se jenom u projektů publikovaných na GitHubu.

Použití příkazu exportu

Pokud chcete, aby funkce a operace v externím projektu byly přístupné pro volání projektů, použijte tento export příkaz. V souboru můžete exportovat všechny volatelné nebo všechny volatelné. Syntaxe zástupných znaků není podporovaná, je nutné zadat každou volanou pro export.

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;             

Použití příkazu import

Z volajícího programu použijete import příkazy k zpřístupnění položek z externí závislosti. import příkazy používají obor názvů definovaný pro závislost v souboru manifestu. Například pro tuto závislost

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

importovat volatelné jako

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

Příkaz import také podporuje syntaxi a aliasy se zástupnými kartami.

// 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; 

Příklad externího projektu

V tomto příkladu použijete stejný teleportační program jako v předchozím příkladu, ale oddělíte volající program a volatelné do různých projektů.

1. Vytvořte dvě složky na místním disku, například "Project_A" a "Project_B".

2. V každé složce vytvořte Q# projekt podle kroků v krocích Q# pro vytvoření projektu.

3. V Project_A volající program zkopírujte následující kód do souboru manifestu a upravte cestu podle potřeby pro Project_B

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

4. V Project_A zkopírujte následující kód do souboru 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. V Project_B zkopírujte následující kód do Souboru 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
   

   Poznámka:

   Všimněte si, že PrepareBellPair operace nemusí být exportována, protože není volána přímo z programu v Project_A. Vzhledem k tomu, že je v místním rozsahu Project_B, je již přístupný Teleport operací.

6. Program spustíte tak, že v editoru VS Code otevřete soubor /Project_A/Main.qs a vyberete Spustit.

Projekty a implicitní obory názvů

Pokud Q# v projektech není v programu *.qs zadaný obor názvů, použije kompilátor název souboru jako obor názvů. Odkazování na volatelnou z externí závislosti pak použije syntaxi <dependencyName>.<obor názvů>.<volatelné>. Pokud se ale soubor jmenuje Main.qs, kompilátor předpokládá obor názvů a syntaxe volání je <dependencyName>.<volatelné>, jako v předchozím příkladu , import MyTeleportLib.Teleport.

Vzhledem k tomu, že není neobvyklé mít více souborů projektu, musíte při odkazování na volatelné soubory zohlednit správnou syntaxi. Například v projektu s následující strukturou souborů

• /Src
  • Main.qs
  • MathFunctions.qs

volání externí závislosti by byla

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

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

Další informace o chování oboru názvů naleznete v tématu Uživatelské obory názvů.