Arbeta med Q# projekt

Med versionen av Azure Quantum Development Kitkan du definiera Q# projekt, som är mappstrukturer med flera Q# filer som kan komma åt varandras resurser. Projekt är användbara för att skapa återanvändbara bibliotek och logiskt organisera källkoden.

Ett Q# projekt innehåller en Q# manifestfil med namnet qsharp.json och en eller flera *.qs-filer i en angiven mappstruktur. När en användare öppnar en *.qs-fil i VS Code, eller anger project_root i en Jupyter Notebook- eller Python-fil, söker kompilatorn i den omgivande mapphierarkin efter manifestfilen och fastställer projektets omfång. Om ingen manifestfil hittas fungerar kompilatorn i ett enda filläge. Ett Q# projekt kan skapas manuellt eller direkt i VS Code.

Förutsättningar

• En Azure Quantum-arbetsyta i din Azure-prenumeration. Information om hur du skapar en arbetsyta finns i Skapa en Azure Quantum-arbetsyta.
• En Python-miljö med Python och Pip installerade.
• Visual Studio Code med Azure Quantum Development Kit - och Python-tillägget installerat.
• Azure Quantum qsharp och azure-quantum paket.

Definiera ett Q# projekt

Ett Q# projekt definieras av förekomsten av en qsharp.json manifestfil och en src-mapp (som innehåller källfilerna Q# ), som båda måste finnas i projektets rotmapp. För Q# program Q# identifierar kompilatorn projektmappen automatiskt. För Python-program och Jupyter Notebooks måste du ange projektmappen Q# med ett qsharp.init anrop. Mappstrukturen för ett Q# projekt är dock densamma för alla typer av program.

Använda ett Q# program

Definiera projektmappen (Q# program)

När en *.qs-fil öppnas i VS Code Q# söker kompilatorn uppåt i mappstrukturen efter en qsharp.json manifestfil. Om den hittar en manifestfil söker kompilatorn nedåt genom alla undermappar i src-katalogen efter *.qs-filer och cachelagrar alla åtgärder eller funktioner, och gör dessa åtgärder och funktioner tillgängliga för alla *.qs-filer enligt manifestfilens undantagsregler.

Till exempel, med tanke på den här mappstrukturen:

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

när du öppnar filen /src/TeleportOperation/PrepareState/PrepareState.qs, Q# kompilatorn:

1. Kontrollerar /src/TeleportOperation/PrepareState/ efter en qsharp.json fil.
2. Kontrollerar /src/TeleportOperation för qsharp.json.
3. Kontrollerar /src för qsharp.json.
4. Söker efter /qsharp.json.
5. Etablerar / som projektets rotkatalog och innehåller alla *.qs-filer under roten i projektet enligt manifestfilens inställningar.

Använda Python eller en Jupyter Notebook

Definiera projektmappen (Python och Jupyter Notebook program)

När du använder ett Python-program eller Jupyter Notebook cell för att komma åt Q# resurser måste du ange rotkatalogen för projektet direkt med en qsharp.init instruktion. Använda samma mappstruktur från föregående exempel

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

du ställer in project_root innan du gör anrop till åtgärder Q# .

Förutsatt att Python-programmet finns i projektmappen Q#

import qsharp

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

Sökvägen till rotmappen är relativ till den fil som ställer in den, vilket innebär att projektmappen Q# kan finnas var som helst och att det anropande programmet inte nödvändigtvis behöver finnas i projektet. En giltig sökväg kan också vara './MyProjects/Teleportation_project', eller ../../Teleportation_project.

Kompilatorn Q# verifierar att det finns en giltig qsharp.json fil i den angivna rotmappen och gör alla *.qs-resurser under src-mappen tillgängliga som referens, enligt manifestfilens undantagsregler.

Skapa en manifestfil

En manifestfil är en enkel .json fil med namnet qsharp.json som kan innehålla fälten författare, licens och .ints . Den minsta livskraftiga manifestfilen är strängen {}. När du skapar ett Q# projekt i VS Code skapas en minimal manifestfil åt dig.

{}

Exempel på manifestfiler

Följande är några exempel på hur manifestfiler kan definiera projektets Q# omfattning.

I det här exemplet är författare det enda angivna fältet, och därför ingår alla *.qs-filer i den här katalogen och alla dess underkataloger i Q# projektet.

{
    "author":"Microsoft"
}

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

I ett Q# projekt kan du också använda manifestfilen för att finjustera VS Code Q# Linter-inställningarna. Som standard är de tre Linter-reglerna:

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

Med hjälp av manifestfilen kan du ställa in varje regel på antingen allow, warneller error, till exempel

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

Q# projektkrav och egenskaper

Följande krav och konfigurationer gäller för alla Q# projekt.

• Alla *.qs-filer som du vill ska ingå i projektet måste finnas under en mapp med namnet src, som måste finnas under projektrotmappen Q# . När du skapar ett Q# projekt i VS Code /src skapas mappen automatiskt.
• Qsharp.json manifestfilen ska vara på samma nivå som src-mappen. När du skapar ett Q# projekt i VS Code skapas qsharp.json-filen automatiskt.
• Åtgärder och funktioner i tillgängliga källfiler kan nås med hjälp av open instruktioner:

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

eller refererar till dem med namnområdet:

MyMathLib.Multiply(x,y);

Endast för Q# program

• Endast en *.qs-fil i ett Q# projekt kan ha en @EntryPoint() definierad.
• Filen *.qs med @EntryPoint() definitionen kan finnas på valfri nivå under manifestfilen.
• Alla åtgärder eller funktioner som cachelagras från en *.qs-fil var som helst i Q# projektet visas i förutsägelsetext i VS Code.
• Om namnområdet för en vald åtgärd eller funktion inte har lagts till ännu lägger VS Code automatiskt till den nödvändiga open instruktionen.

Steg för att skapa ett Q# projekt

1. I VS Code-utforskaren högerklickar du på den mapp som du vill använda för projektrotmappen Q# och väljer Skapa Q# projekt, eller öppnar mappen och väljer Visa > kommandopalett>Q#: Skapa ett Q# projekt....

2. VS Code skapar en minimal qsharp.json manifestfil i mappen och lägger till en /src mapp med en Main.qs mallfil.

3. Redigera manifestfilen efter behov. Se Exempel på manifestfil.

4. Lägg till och organisera källfilerna Q#/src under mappen.

5. Om du kommer åt Q# projektet från ett Python-program eller Jupyter Notebook anger du sökvägen till rotmappen med hjälp av qsharp.init. Det här exemplet förutsätter att programmet finns i samma mapp som rotmappen i Q# projektet:

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

6. Om du bara Q# använder filer i VS Code Q# söker kompilatorn efter qsharp.json manifestfil, fastställer projektrotmappen och söker sedan igenom undermappen efter *.qs-filer.

Anteckning

Du kan också skapa manifestfilen och /src mappen manuellt i steg 2.

Exempelprojekt

Det här kvantteleporteringsprogrammet är ett exempel på ett Q# projekt baserat på mappstrukturen som visades tidigare och körs på den lokala simulatorn i VS Code. Information om hur du kör programmet på Azure Quantum-maskinvara eller simulatorer från tredje part finns i Komma igång med Q# program och VSCode för steg för att kompilera ditt program och ansluta till din Azure-arbetsyta.

I exemplet används den här katalogstrukturen:

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

Qsharp.json-manifestfilen innehåller fälten författare och licens:

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

Q# källfiler

Med en mindre skillnad – instruktionen @EntryPoint() – är källfilerna samma för ett Q# program, ett Python-program eller en Jupyter Notebook.

Huvudfilen RunTeleport.qs innehåller startpunkten och refererar till TeleportLib namnområdet i 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 definierar Teleport() åtgärden och anropar åtgärden PrepareBellPair() från 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);
    }
}

Filen PrepareState.qs innehåller en standardåtgärd som kan återanvändas för att skapa ett Bell-par.

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

Köra programmen

Välj fliken för den miljö där du kör programmet.

Köra ett Q# program

Om du vill köra det här programmet öppnar du filen RunTeleport.qs i VS Code och väljer Kör.

Köra en Jupyter Notebook

För ett Jupyter Notebook program kräver inte källfilerna attributet @EntryPoint() . Filerna fungerar endast som källbibliotek.

Om du vill köra det här programmet i en Juptyer Notebook öppnar du en ny notebook-fil och kör följande celler:

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

Om din sökväg är giltig visas ett bekräftelsemeddelande, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Kör programmet genom att anropa huvudåtgärden med hjälp av det %%qsharp magiska kommandot

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

eller med hjälp av -instruktionen qsharp.eval()

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

Köra ett Python-program

För ett Python-program kräver inte källfilerna attributet @EntryPoint() . Filerna fungerar endast som källbibliotek.

Kör det här programmet genom att köra följande kommandon:

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

Om din sökväg är giltig visas ett bekräftelsemeddelande, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Kör programmet genom att anropa huvudåtgärden med qsharp.eval()

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