Delen via

Projecten en aangepaste bibliotheken maken en beheren Q#

  • Artikel

In dit artikel leert u hoe u projecten maakt, beheert en deelt.Q# Q# projecten zijn mapstructuren met meerdere Q# bestanden die toegang hebben tot elkaars bewerkingen en functies. Projecten zijn handig voor het logisch ordenen van uw broncode. U kunt projecten ook gebruiken als aangepaste bibliotheken die toegankelijk zijn vanuit externe bronnen.

Vereisten

Voor het uitvoeren van Python-programma's hebt u ook het volgende nodig:

  • Een Python-omgeving waarop Python en Pip zijn geïnstalleerd.
  • De Azure Quantum qsharp en azure-quantum pakketten.

Hoe Q# projecten werken

Een Q# project bevat een Q# manifestbestand met de naam qsharp.json en een of meer *.qs-bestanden in een opgegeven mapstructuur. Wanneer een gebruiker een *.qs-bestand opent in VS Code of het project_root in een Jupyter Notebook- of Python-bestand instelt, zoekt de compiler naar de omringende maphiërarchie voor het manifestbestand en bepaalt het bereik van het project. Als er geen manifestbestand wordt gevonden, werkt de compiler in één bestandsmodus. U kunt een Q# project handmatig of rechtstreeks in VS Code maken.

Een extern Q# project is een standaardproject Q# dat zich in een andere map of in een openbare GitHub-opslagplaats bevindt en fungeert als een aangepaste bibliotheek. Een extern project maakt gebruik van export instructies om te definiëren welke functies en bewerkingen toegankelijk zijn voor externe programma's. Programma's definiëren het externe project als een afhankelijkheid in hun manifestbestand en gebruiken import instructies voor toegang tot de items (bewerkingen, functies, structs en naamruimten) in het externe project. Zie Projecten gebruiken als externe afhankelijkheden voor meer informatie.

Q# Een project definiëren

Een Q# project wordt gedefinieerd door de aanwezigheid van een manifestbestand met de naam qsharp.json en een src-map (die de Q# bronbestanden bevat), die beide zich in de hoofdmap van het project moeten bevinden. Voor Q# programma's en externe projecten detecteert de Q# compiler de projectmap automatisch. Voor Python-programma's en Jupyter Notebooks moet u de Q# projectmap opgeven met een qsharp.init aanroep. De mapstructuur voor een Q# project blijft echter hetzelfde voor alle typen programma's.

De mapstructuur en -hiërarchie voor een Q# project.

De projectmap definiëren (Q# programma's)

Wanneer een *.qs-bestand wordt geopend in VS Code, zoekt de Q# compiler omhoog in de mapstructuur naar een manifestbestand. Als er een manifestbestand wordt gevonden, bevat de compiler vervolgens alle Q# bestanden in de map /src of een van de bijbehorende submappen. De items van elk bestand worden beschikbaar gesteld voor alle andere bestanden in het project.

Bijvoorbeeld, op grond van deze mapstructuur:

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

wanneer u het bestand /src/TeleportOperation/PrepareState/PrepareStateLib.qs opent, is de Q# compiler:

  1. Controleert /src/TeleportOperation/PrepareState/ op qsharp.json.
  2. Controleert /src/TeleportOperation op qsharp.json.
  3. Controleert /src op qsharp.json.
  4. Controleert / op qsharp.json.
  5. / Wordt ingesteld als de hoofdmap van het project en bevat alle *.qs-bestanden onder de hoofdmap in het project, volgens de instellingen van het manifestbestand.

Een manifestbestand maken

Een manifestbestand is een eenvoudig .json-bestand met de naam qsharp.json dat desgewenst auteurs-, licentie- en lintvelden kan bevatten. Het minimaal levensvatbare manifestbestand is de tekenreeks {}. Wanneer u een Q# project maakt in VS Code, wordt er een minimaal manifestbestand voor u gemaakt.

{}

Voorbeelden van manifestbestanden

Hier volgen enkele voorbeelden van hoe manifestbestanden het bereik van uw Q# project kunnen definiëren.

  • In dit voorbeeld is auteur het enige veld dat is opgegeven en daarom zijn alle *.qs-bestanden in deze map en alle bijbehorende submappen opgenomen in het Q# project.

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

  • Binnen een Q# project kunt u ook het manifestbestand gebruiken om de VS Code Q# Linter-instellingen af te stemmen. Standaard zijn de drie Linter-regels:

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

    Met behulp van het manifestbestand kunt u elke regel instellen op allow, warnof errorbijvoorbeeld

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

  • U kunt het manifestbestand ook gebruiken om een extern Q# project te definiëren als een afhankelijkheid en externe toegang tot bewerkingen en functies in dat externe project. Zie Projecten gebruiken als externe afhankelijkheden voor meer informatie.

Q# projectvereisten en -eigenschappen

De volgende vereisten en configuraties zijn van toepassing op alle Q# projecten.

  • Alle *.qs-bestanden die u wilt opnemen in het project, moeten zich onder een map met de naam src bevinden, die zich onder de hoofdmap van de map van het Q#project bevinden. Wanneer u een Q# project maakt in VS Code, wordt de /src map automatisch gemaakt.

  • Het manifestbestand moet zich op hetzelfde niveau bevinden als de src-map . Wanneer u een Q# project maakt in VS Code, wordt er automatisch een minimaal bestand gemaakt.

  • Gebruik import instructies om te verwijzen naar bewerkingen en functies van andere bestanden in het project.

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

    of deze afzonderlijk verwijzen naar de naamruimte

    MyMathLib.Multiply(x,y);

Alleen voor Q# projecten

  • Slechts één *.qs-bestand in een Q# project kan een invoerpunt hebben dat is gedefinieerd door één Main() bewerking.
  • Het bestand *.qs met de definitie van het toegangspunt kan zich op elk niveau onder het manifestbestand bevinden.
  • Elke bewerking of functie die vanuit een *.qs-bestand in de cache wordt opgeslagen, wordt overal in het Q# project weergegeven in voorspellende tekst in VS Code.
  • Als de naamruimte voor een geselecteerde bewerking of functie nog niet is geïmporteerd, voegt VS Code automatisch de benodigde import instructie toe.

Stappen voor het maken van een Q# project

Deze stappen zijn van toepassing op alle Q# projecten.

  1. Klik in de Verkenner van VS Code met de rechtermuisknop op de map die u wilt gebruiken voor de hoofdmap van het Q# project en selecteer Project makenQ#, of open de map en selecteer Opdrachtpalet >Q#weergeven>: Een Q# project maken....

  2. VS Code maakt een minimaal manifestbestand in de map en voegt een /src map toe met een Main.qs sjabloonbestand.

  3. Bewerk het manifestbestand indien nodig. Zie voorbeelden van manifestbestanden.

  4. Voeg uw Q# bronbestanden toe en organiseer deze onder de /src map.

  5. Als u het Q# project opent vanuit een Python-programma of Jupyter Notebook, stelt u het pad naar de hoofdmap in met behulp van qsharp.init. In dit voorbeeld wordt ervan uitgegaan dat uw programma zich in de map /src van het Q# project bevindt:

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

  6. Als u alleen Q# bestanden in VS Code gebruikt, zoekt de compiler naar Q# een manifestbestand, bepaalt de hoofdmap van het project en scant de submap naar *.qs-bestanden.

Notitie

U kunt het manifestbestand en de /src map in stap 2 ook handmatig maken.

Voorbeeldproject

Dit kwantumteleportatieprogramma is een voorbeeld van een Q# project op basis van de structuur met één map die eerder wordt weergegeven en wordt uitgevoerd op de lokale simulator in VS Code. Als u het programma wilt uitvoeren op Azure Quantum-hardware of simulators van derden, raadpleegt u Aan de slag met Q# programma's en VSCode voor stappen om uw programma te compileren en verbinding te maken met uw Azure-werkruimte.

In het voorbeeld wordt deze mapstructuur gebruikt:

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

Het manifestbestand bevat de auteurs - en licentievelden :

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

Q# bronbestanden

Het hoofdbestand Main.qs bevat het toegangspunt en verwijst naar de TeleportOperations.TeleportLib naamruimte van 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 definieert de Teleport() bewerking en roept de PrepareBellPair() bewerking aan vanuit 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);
    }

Het bestand PrepareStateLib.qs bevat een standaard herbruikbare bewerking om een belpaar te maken.

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

De programma's uitvoeren

Selecteer het tabblad voor de omgeving waarin u uw programma uitvoert.

Als u dit programma wilt uitvoeren, opent u het bestand Main.qs in VS Code en selecteert u Uitvoeren.

Q# Projecten configureren als externe afhankelijkheden

Een Q# project kan ook worden geconfigureerd als een externe afhankelijkheid voor andere projecten, zoals een bibliotheek, waarbij de functies en bewerkingen in het externe Q# project beschikbaar worden gesteld aan meerdere Q# projecten. Een externe afhankelijkheid kan zich bevinden op een stationshare of gepubliceerd naar een openbare GitHub-opslagplaats.

Als u een Q# project als een externe afhankelijkheid wilt gebruiken, moet u het volgende doen:

  • Voeg het externe project toe als een afhankelijkheid in het manifestbestand van het aanroepende project.
  • Als het externe project wordt gepubliceerd naar GitHub, voegt u de eigenschap 'bestanden' toe aan het manifestbestand van het externe project.
  • Voeg instructies toe export aan het externe project.
  • Voeg instructies toe import aan het aanroepende project.

De manifestbestanden configureren

Externe Q# projecten kunnen zich op een lokale of netwerkstationshare bevinden of worden gepubliceerd naar een openbare GitHub-opslagplaats.

Het aanroepende projectmanifestbestand

Als u een afhankelijkheid wilt toevoegen aan een extern project op een stationshare, definieert u de afhankelijkheid in het manifestbestand van het aanroepende project.

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

waarbij MyDependency een door de gebruiker gedefinieerde tekenreeks is die de naamruimte identificeert bij het aanroepen van een bewerking. Als u bijvoorbeeld een afhankelijkheid met de naam 'MyMathFunctions' maakt, roept u een functie aan van die afhankelijkheid met MyMathFunctions.MyFunction().

Een afhankelijkheid toevoegen aan een project dat wordt gepubliceerd naar een openbare GitHub-opslagplaats

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

Notitie

Voor GitHub-afhankelijkheden verwijst 'ref' naar een GitHub-refspec. Microsoft raadt aan altijd een commit-hash te gebruiken, zodat u kunt vertrouwen op een specifieke versie van uw afhankelijkheid.

Het manifestbestand van het externe project

Als uw externe Q# project wordt gepubliceerd naar een openbare GitHub-opslagplaats, moet u de bestandseigenschap toevoegen aan het manifestbestand van het externe project, inclusief alle bestanden die in het project worden gebruikt.

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

De eigenschap 'bestanden' is optioneel voor een extern project dat wordt geïmporteerd via "path" (dat wil gezegd een lokaal importbestandspad). Dit is alleen vereist voor projecten die zijn gepubliceerd naar GitHub.

De exportinstructie gebruiken

Als u functies en bewerkingen in een extern project toegankelijk wilt maken voor het aanroepen van projecten, gebruikt u de export instructie. U kunt alle aanroepbare items in het bestand exporteren. Syntaxis van jokertekens wordt niet ondersteund. U moet elke aanroepbare opgeven die u wilt exporteren.

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;

De importinstructie gebruiken

Vanuit het aanroepende programma gebruikt import u instructies om items van een externe afhankelijkheid beschikbaar te maken. import instructies gebruiken de naamruimte die is gedefinieerd voor de afhankelijkheid in het manifestbestand. Bijvoorbeeld voor deze afhankelijkheid

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

u aanroepbare items importeert als

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

De import instructie ondersteunt ook syntaxis en aliassen van jokertekens

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

Notitie

De momenteel gebruikte open instructie , Q#die wordt gebruikt om te verwijzen naar bibliotheken en naamruimten, wordt nog steeds ondersteund, maar wordt uiteindelijk afgeschaft. Ondertussen kunt u eventueel uw huidige bestanden bijwerken om de import instructie te gebruiken. Kan bijvoorbeeld open Microsoft.Quantum.Diagnostics; worden vervangen door import Microsoft.Quantum.Diagnostics.*;. Houd er ook rekening mee dat wanneer u de import instructie met de standaardbibliotheken Q# gebruikt, u de hoofdnaamruimte kunt inkorten tot Std. Kan bijvoorbeeld import Microsoft.Quantum.Diagnostics.*; worden geschreven als import Std.Diagnostics.*;.

Voorbeeld van extern project

In dit voorbeeld gebruikt u hetzelfde teleportatieprogramma als in het vorige voorbeeld, maar scheidt u het oproepprogramma en de aanroepbare bestanden in verschillende projecten.

  1. Maak twee mappen op uw lokale station, bijvoorbeeld 'Project_A' en 'Project_B'.

  2. Maak een Q# project in elke map volgens de stappen in Stappen voor het maken van een Q# project.

  3. Kopieer in Project_A het aanroepende programma de volgende code naar het manifestbestand en bewerk het pad indien nodig voor Project_B

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

  4. Kopieer in Project_A de volgende code naar 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. Kopieer in Project_B de volgende code naar 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

    Notitie

    Houd er rekening mee dat de bewerking niet hoeft te worden geëxporteerd omdat deze PrepareBellPair niet rechtstreeks vanuit uw programma in Project_A wordt aangeroepen. Omdat deze zich in het lokale bereik van Project_B bevindt, is deze al toegankelijk voor de Teleport bewerking.

  6. Als u het programma wilt uitvoeren, opent u /Project_A/Main.qs in VS Code en selecteert u Uitvoeren.

Projecten en impliciete naamruimten

Als Q# in projecten geen naamruimte is opgegeven in een *.qs-programma, gebruikt de compiler de bestandsnaam als de naamruimte. Als u verwijst naar een aanroepbare van een externe afhankelijkheid, wordt vervolgens de syntaxis <dependencyName> gebruikt.<naamruimte>.<aanroepbaar>. Als het bestand echter de naam Main.qs heeft, gaat de compiler ervan uit dat de naamruimte en de aanroepende syntaxis dependencyName> is<.<aanroepbaar>, zoals in het vorige voorbeeld. import MyTeleportLib.Teleport

Omdat het niet ongebruikelijk is om meerdere projectbestanden te hebben, moet u rekening houden met de juiste syntaxis bij het verwijzen naar aanroepbare bestanden. Bijvoorbeeld in een project met de volgende bestandsstructuur

  • /Src
    • Main.qs
    • MathFunctions.qs

aanroepen naar de externe afhankelijkheid zijn

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

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

Zie Gebruikersnaamruimten voor meer informatie over het gedrag van de naamruimte.