Werken met Q# projecten

Met de release van Azure Quantum Development Kitkunt u projecten definiërenQ#. Dit zijn mapstructuren met meerdere Q# bestanden die toegang hebben tot elkaars resources. Projecten zijn handig voor het maken van herbruikbare bibliotheken en het logisch ordenen van uw broncode.

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

Vereisten

• Een Azure Quantum-werkruimte in uw Azure-abonnement. Zie een Azure Quantum-werkruimte Creatie als u een werkruimte wilt maken.
• Een Python-omgeving met Python en Pip geïnstalleerd.
• Visual Studio Code met de Azure Quantum Development Kit - en Python-extensie geïnstalleerd.
• De Azure Quantum qsharp en azure-quantum -pakketten.

Q# Een project definiëren

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

Q# Een programma gebruiken

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 qsharp.json manifestbestand. Als er een manifestbestand wordt gevonden, doorzoekt de compiler vervolgens alle submappen van de src-map naar *.qs-bestanden en slaat alle bewerkingen of functies in de cache op en maakt deze bewerkingen en functies beschikbaar voor alle *.qs-bestanden, volgens de uitsluitingsregels van het manifestbestand.

Bijvoorbeeld, gezien deze mapstructuur:

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

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

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

Python of een Jupyter Notebook gebruiken

De projectmap definiëren (Python en Jupyter Notebook-programma's)

Wanneer u een Python-programma of Jupyter Notebook cel gebruikt om toegang te krijgen tot Q# resources, moet u de hoofdmap van het project rechtstreeks instellen met een qsharp.init -instructie. Dezelfde mapstructuur gebruiken als in het vorige voorbeeld

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

U stelt de project_root voordat u aanroepen doet in op bewerkingen Q# .

Ervan uitgaande dat uw Python-programma zich in de Q# projectmap bevindt

import qsharp

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

Het pad van de hoofdmap is relatief ten opzichte van het bestand waarin het is ingesteld, wat betekent dat uw Q# projectmap zich overal kan bevinden en het aanroepende programma zich niet noodzakelijkerwijs in het project hoeft te bevinden. Een geldig pad kan ook , of ../../Teleportation_projectzijn'./MyProjects/Teleportation_project'.

De Q# compiler controleert of er een geldig qsharp.json-bestand is in de opgegeven hoofdmap en maakt *.qs-resources onder de map src beschikbaar voor referentie, volgens de uitsluitingsregels van het manifestbestand.

een manifestbestand Creatie

Een manifestbestand is een eenvoudig .json bestand met de naam qsharp.json dat desgewenst auteurs-, licentie- en .ints-velden 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"
}

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

Binnen een Q# project kunt u ook het manifestbestand gebruiken om de VS Code Q# Linter-instellingen aan te passen. De drie Linter-regels zijn standaard:

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

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

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

Q# projectvereisten en -eigenschappen

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

• Alle *.qs-bestanden die u in het project wilt opnemen, moeten zich in een map met de naam src bevinden, die zich onder de hoofdmap van het Q# project moet bevinden. Wanneer u een Q# project maakt in VS Code, wordt de /src map automatisch gemaakt.
• Het qsharp.json manifestbestand moet zich op hetzelfde niveau bevinden als de map src . Wanneer u een Q# project maakt in VS Code, wordt het qsharp.json-bestand automatisch gemaakt.
• Bewerkingen en functies in beschikbare bronbestanden zijn toegankelijk met behulp van open -instructies:

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

of verwijst naar de naamruimte:

MyMathLib.Multiply(x,y);

Alleen voor Q# programma's

• Er kan slechts een *.qs-bestand in een Q# project zijn @EntryPoint() gedefinieerd.
• Het bestand *.qs met de @EntryPoint() definitie kan zich op elk niveau onder het manifestbestand bevinden.
• Elke bewerking of functie die vanuit een *.qs-bestand ergens in het project in de Q# cache wordt opgeslagen, wordt weergegeven in voorspellende tekst in VS Code.
• Als de naamruimte voor een geselecteerde bewerking of functie nog niet is toegevoegd, voegt VS Code automatisch de benodigde open instructie toe.

Stappen voor het maken van een Q# project

1. Klik in de VS Code-verkenner met de rechtermuisknop op de map die u wilt gebruiken voor de hoofdmap van het Q# project en selecteer Creatie Q# project, of open de map en selecteer Opdrachtpalet >Q#weergeven>: Creatie een Q# project....

2. VS Code maakt een minimaal qsharp.json 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 dezelfde map bevindt als de hoofdmap van het Q# project:

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

6. Als u alleen Q# bestanden in VS Code gebruikt, zoekt de compiler bij het openen van een Q# bestand naar het qsharp.json manifestbestand, bepaalt de hoofdmap van het project en scant vervolgens de submap op *.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 eerder getoonde mapstructuur 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 voor het compileren van uw programma en het maken van verbinding met uw Azure-werkruimte.

In het voorbeeld wordt deze mapstructuur gebruikt:

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

Het qsharp.json manifestbestand bevat de velden auteur en licentie :

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

Q# bronbestanden

Met één klein verschil, de @EntryPoint() instructie, zijn de bronbestanden hetzelfde voor een Q# programma, een Python-programma of een Jupyter Notebook.

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

Het bestand PrepareState.qs bevat een standaard herbruikbare bewerking om een Bell-paar te maken.

namespace PrepareBell {    
    
    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 het programma uitvoert.

Q# Een programma uitvoeren

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

Een Jupyter Notebook uitvoeren

Voor een Jupyter Notebook-programma is het kenmerk niet vereist voor de @EntryPoint() bronbestanden. De bestanden fungeren alleen als bronbibliotheken.

Als u dit programma wilt uitvoeren in een Juptyer Notebook, opent u een nieuw notitieblok en voert u de volgende cellen uit:

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

Als uw pad geldig is, ziet u een bevestigingsbericht: Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Voer het programma uit door de hoofdbewerking aan te roepen met behulp van de %%qsharp magic-opdracht

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

of met behulp van de qsharp.eval() instructie

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

Een Python-programma uitvoeren

Voor een Python-programma is het kenmerk niet vereist voor de @EntryPoint() bronbestanden. De bestanden fungeren alleen als bronbibliotheken.

Voer de volgende opdrachten uit om dit programma uit te voeren:

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

Als uw pad geldig is, ziet u een bevestigingsbericht: Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Voer het programma uit door de hoofdbewerking aan te roepen met qsharp.eval()

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