Skapa och hantera Q# projekt och anpassade bibliotek

I den här artikeln får du lära dig hur du skapar, hanterar och delar Q# projekt. Ett Q# projekt är en mappstruktur med flera Q# filer som kan komma åt varandras åtgärder och funktioner. Projekt hjälper dig att logiskt organisera källkoden. Du kan också använda projekt som anpassade bibliotek som du kan komma åt från externa källor.

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.
• Visual Studio Code (VS Code) med Microsoft Quantum Development Kit (QDK) och Python tillägg installerade.
• Om du vill publicera ditt externa projekt på en offentlig GitHub lagringsplats måste du ha ett GitHub konto.

Om du vill köra Python-program behöver du också:

• En Python-miljö med Python och Pip installerat.

• biblioteket qdkPython med azure extra.

  python -m pip install --upgrade "qdk[azure]"
  

Så Q# här fungerar projekt

Ett Q# projekt innehåller en Q# manifestfil med namnet qsharp.json, och en eller flera .qs filer och .qsc filer i en angiven mappstruktur. Du kan skapa ett Q# projekt manuellt eller direkt i VS Code.

När du öppnar en .qs fil .qsc i VS Codesöker kompilatorn i den omgivande mapphierarkin efter manifestfilen och avgör projektets omfång. Om kompilatorn inte hittar någon manifestfil fungerar kompilatorn i ett enda filläge.

När du anger project_root-filen i en Jupyter Notebook eller Python-fil letar kompilatorn efter manifestfilen i mappen project_root.

Ett externt Q# projekt är ett standardprojekt Q# som finns i en annan katalog eller på en offentlig GitHub lagringsplats och fungerar som ett anpassat bibliotek. Ett externt projekt använder export instruktioner för att definiera de funktioner och åtgärder som är tillgängliga för externa program. Program definierar det externa projektet som ett beroende i manifestfilen och använder import instruktioner för att komma åt objekten i det externa projektet, till exempel åtgärder, funktioner, strukturer och namnområden. Mer information finns i Använda projekt som externa beroenden.

Definiera ett Q# projekt

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

from qdk import qsharp

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

Skapa en manifestfil

En manifestfil är en JSON-fil med namnet qsharp.json som kan innehålla valfria authorfält , licenseoch lints . Den minsta livskraftiga manifestfilen är strängen {}. När du skapar ett Q# projekt i VS Codeskapas en minimal manifestfil åt dig.

{}

Exempel på manifestfil

I följande exempel visas hur manifestfiler definierar projektets Q# omfattning.

• I det här exemplet author är det enda angivna fältet, så alla .qs filer i den här katalogen och dess underkataloger ingår i Q# projektet.

  {
      "author":"Microsoft"
  }
  

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

  • needlessParens: default = allow

  • divisionByZero: default = warn

  • redundantSemicolons: default = warn

    Du kan ange varje regel i manifestfilen till antingen allow, warneller error. Till exempel:

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

• Du kan också använda manifestfilen för att definiera ett externt Q# projekt som ett beroende och fjärråtkomst till åtgärder och funktioner i det externa projektet. Mer information finns i Använda projekt som externa beroenden.

Q# projektkrav och egenskaper

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

• Alla .qs filer som du vill inkludera i projektet måste vara under en mapp med namnet src, som måste finnas under rotmappen för Q# projektet. När du skapar ett Q# projekt i VS Code/src skapas mappen automatiskt.

• Manifestfilen ska vara på samma nivå som src mappen. När du skapar ett Q# projekt i VS Codeskapas automatiskt en minimal manifestfil.

• Använd import instruktioner för att referera till åtgärder och funktioner från andra filer i projektet.

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

  Eller referera till dem individuellt via namnrymden.

  MyMathLib.Multiply(x,y); 
  

Endast för Q# projekt

• Du kan definiera en startpunktsåtgärd i endast en .qs fil i ett Q# projekt, vilket är åtgärden Main() som standard.
• Du måste placera .qs filen med startpunktsdefinitionen på projektkatalognivå under manifestfilen.
• Alla operationer och funktioner i Q#-projektet som cachelagras från en .qs display som visas i prediktiv text i VS Code.
• Om namnområdet för en vald åtgärd eller funktion inte har importerats ännu lägger du VS Code automatiskt till den nödvändiga import instruktionen.

Så här skapar du ett Q# projekt

Följ dessa steg för att skapa ett Q# projekt:

1. I utforskaren VS Code går du till den mapp som du vill använda som rotmapp för Q# projektet.

2. Öppna menyn Visa och välj Kommandopalett.

3. Ange QDK: Skapa Q# projekt. VS Code skapar en minimal manifestfil i mappen och lägger till en /src mapp med en Main.qs mallfil.

4. Redigera manifestfilen för projektet. Se Exempel på manifestfil.

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

6. Om du kommer åt projektet Q# från ett Python-program eller Jupyter Notebook anger du mappsökvägen root med qsharp.init. Det här exemplet förutsätter att programmet finns i /src mappen för Q# projektet:

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

7. Om du endast använder Q# filer i VS Code, söker kompilatorn efter en manifestfil när du öppnar ett Q#-fil och fastställer rotmappen för projektet. Sedan genomsöker /src kompilatorn och dess underkataloger efter .qs och .qsc filer.

Exempelprojekt

Det här kvantteleporteringsprogrammet är ett exempel på ett Q# projekt som körs på den lokala simulatorn i VS Code. För att köra programmet på Azure Quantum-maskinvara eller simulatorer från tredje part, se Kom igång med Q#-program och VS Code för steg-för-steg-instruktioner om hur du kompilerar ditt program och ansluter till din Azure Quantum-arbetsmiljö.

Det här exemplet har följande katalogstruktur:

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

Manifestfilen innehåller fälten författare och licenser :

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

Q# källfiler

Huvudfilen Main.qs innehåller startpunkten och refererar till TeleportOperations.TeleportLib namnområdet från 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);
        }
    }

Filen TeleportLib.qs definierar åtgärden Teleport och anropar PrepareBellPair åtgärden från PrepareStateLib.qs filen.

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

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

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

Kör programmen

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

from qdk 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 that 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()"))

from qdk 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 that your program is in the same folder as the root folder
qsharp.init(project_root = '../Teleportation_project')

# To run the program, call the main operation
print (qsharp.eval("Main.Main()"))

Konfigurera Q# projekt som externa beroenden

Du kan konfigurera Q# projekt som ett externt beroende för andra projekt, som liknar ett bibliotek, för att göra funktioner och åtgärder i det externa Q# projektet tillgängliga för andra Q# projekt. Ett externt beroende kan finnas på en delad nätverksenhet eller publiceras i en offentlig GitHub-repository.

Om du vill använda ett Q# projekt som ett externt beroende måste du:

• Lägg till det externa projektet som ett beroende i manifestfilen för det anropande projektet.
• Om det externa projektet publiceras i GitHub lägger du till egenskapen files i manifestfilen för det externa projektet.
• Lägg till export uttalanden i det externa projektet.
• Lägg till import instruktioner i det anropande projektet.

Konfigurera manifestfilerna

Externa Q# projekt kan finnas på en lokal resurs eller nätverksenhetsresurs, eller så kan du publicera dem på en offentlig GitHub lagringsplats.

Manifestfilen för det anropande projektet

Om du vill lägga till ett beroende i ett externt projekt på en enhetsresurs definierar du beroendet i manifestfilen för det anropande projektet.

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

I föregående manifestfil MyDependency är en användardefinierad sträng som identifierar namnområdet när du anropar en åtgärd. Om du till exempel skapar ett beroende med namnet MyMathFunctionskan du anropa en funktion från det beroendet med MyMathFunctions.MyFunction().

Om du vill lägga till ett beroende till ett projekt som publiceras till en offentlig GitHub lagringsplats använder du följande exempelmanifestfil:

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

Manifestfilen för det externa projektet

Om ditt externa Q#-projekt publiceras till en offentlig GitHub lagringsplats måste du lägga till egenskapen files i manifestfilen för det externa projektet, inklusive alla filer som projektet använder.

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

Egenskapen files är valfri för ett externt projekt som du importerar via "path" med en lokal filsökvägsbaserad import. Egenskapen files krävs endast för projekt som publiceras till GitHub.

Använd export-instruktionen

Om du vill göra funktioner och åtgärder i ett externt projekt tillgängliga för anropande projekt använder du -instruktionen export . Du kan exportera valfria eller alla anropsbara objekt i filen. Du kan inte använda jokerteckensyntax, så du måste ange varje anropsbar som du vill exportera.

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;

Använd import-instruktionen

Om du vill göra objekt från ett externt beroende tillgängligt använder du import instruktioner från det anropande programmet. - import instruktionen använder det namnområde som du definierar för beroendet i manifestfilen.

Tänk till exempel på beroendet i följande manifestfil:

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

Importera anropsbara värden med följande kod:

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

...

Uttalandet import stöder även jokerteckensyntax och alias.

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

Exempel på externt projekt

I det här exemplet använder du samma teleporteringsprogram som i det tidigare exemplet, men separerar anropande program och anropsbara objekt i olika projekt.

1. Skapa två mappar på din lokala enhet, till exempel Project_A och Project_B.

2. Skapa ett Q# projekt i varje mapp. Mer information finns i stegen i Skapa ett Q# projekt.

3. I Project_A, det anropande programmet, kopiera följande kod till manifestfilen, men redigera sökvägen om det behövs för Project_B.

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

4. I Project_Akopierar du följande kod till 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. I Project_Bkopierar du följande kod till 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
   

   Kommentar

   Du behöver inte exportera åtgärden PrepareBellPair som programmet i Project_A inte direkt anropar. Åtgärden PrepareBellPair är redan tillgänglig för åtgärden Teleport eftersom PrepareBellPair finns i det lokala omfånget för Project_B.

6. Om du vill köra programmet öppnar /Project_A/Main.qs du i VS Code och väljer Kör.

Projekt och implicita namnområden

Om du inte anger ett namnområde i ett .qs-program i projekt Q#, använder kompilatorn filnamnet som namnområde. När du sedan refererar till ett anropsbart från ett externt beroende använder du syntaxen <dependencyName>.<namespace>.<callable>. Men om filen heter Main.qsförutsätter kompilatorn att namnområdet och den anropande syntaxen är <dependencyName>.<callable>. Till exempel import MyTeleportLib.Teleport.

Eftersom du kan ha flera projektfiler måste du ta hänsyn till rätt syntax när du refererar till anropsbara filer. Tänk dig till exempel ett projekt med följande filstruktur:

• /Src
  • Main.qs
  • MathFunctions.qs

Följande kod anropar det externa beroendet:

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

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

Mer information om namnområdesbeteende finns i Användarnamnrymder.