Utiliser des Q# projets

Avec la version d’Azure Quantum Development Kit, vous pouvez définir des Q# projets, qui sont des structures de dossiers avec plusieurs Q# fichiers pouvant accéder aux ressources des uns des autres. Les projets sont utiles pour créer des bibliothèques réutilisables et organiser logiquement votre code source.

Un Q# projet contient un Q# fichier manifeste nommé qsharp.json et un ou plusieurs fichiers *.qs dans une structure de dossiers spécifiée. Lorsqu’un utilisateur ouvre un fichier *.qs dans VS Code ou définit le project_root fichier Jupyter Notebook ou Python, le compilateur recherche la hiérarchie de dossiers environnante pour le fichier manifeste et détermine l’étendue du projet. Si aucun fichier manifeste n’est trouvé, le compilateur fonctionne en mode fichier unique. Un Q# projet peut être créé manuellement ou directement dans VS Code.

Prérequis

• Un espace de travail Azure Quantum dans votre abonnement Azure. Pour créer un espace de travail, consultez Créer un espace de travail Azure Quantum.
• Un environnement Python avec Python et Pip installés.
• Visual Studio Code avec l’extension Azure Quantum Development Kit et Python installée.
• Azure Quantum qsharp et azure-quantum packages.

Définir un Q# projet

Un Q# projet est défini par la présence d’un fichier manifeste qsharp.json et d’un dossier src (qui contient les Q# fichiers sources), dont les deux doivent se trouver dans le dossier racine du projet. Pour Q# les programmes, le Q# compilateur détecte automatiquement le dossier du projet. Pour les programmes Python et les notebooks Jupyter, vous devez spécifier le dossier du Q# projet avec un qsharp.init appel. Toutefois, la structure de dossiers d’un Q# projet reste la même pour tous les types de programmes.

Utilisation d’un Q# programme

Définition du dossier de projet (Q# programmes)

Lorsqu’un fichier *.qs est ouvert dans VS Code, le Q# compilateur recherche dans la structure de dossiers un fichier manifeste qsharp.json . S’il trouve un fichier manifeste, le compilateur effectue ensuite une recherche vers le bas dans tous les sous-dossiers du répertoire src pour les fichiers *.qs et met en cache toutes les opérations ou fonctions, et met ces opérations et fonctions à la disposition de tous les fichiers *.qs, conformément aux règles d’exclusion du fichier manifeste.

Par exemple, étant donné cette structure de dossiers :

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

lorsque vous ouvrez le fichier /src/TeleportOperation/PrepareState/PrepareState.qs, le Q# compilateur :

1. Vérifie /src/TeleportOperation/PrepareState/ pour un fichier qsharp.json .
2. Vérifie /src/TeleportOperation pour qsharp.json.
3. Vérifie /src pour qsharp.json.
4. Recherche / qsharp.json.
5. Établit / comme répertoire racine du projet et inclut tous les fichiers *.qs sous la racine du projet, conformément aux paramètres du fichier manifeste.

Utilisation de Python ou d’un notebook Jupyter

Définition du dossier de projet (programmes Python et Jupyter Notebook)

Lorsque vous utilisez un programme Python ou une cellule Jupyter Notebook pour accéder Q# aux ressources, vous devez définir le répertoire racine du projet directement avec une qsharp.init instruction. Utilisation de la même structure de dossiers de l’exemple précédent

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

vous définissez l’avant project_root d’effectuer des appels à des Q# opérations.

En supposant que votre programme Python se trouve dans le dossier du Q# projet

import qsharp

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

Le chemin d’accès du dossier racine est relatif au fichier qui le définit, ce qui signifie que votre Q# dossier de projet peut être n’importe où et que le programme appelant n’a pas nécessairement besoin d’être dans le projet. Un chemin d’accès valide peut également être './MyProjects/Teleportation_project', ou ../../Teleportation_project.

Le Q# compilateur vérifie qu’il existe un fichier qsharp.json valide dans le dossier racine spécifié et rend toutes les ressources *.qs sous le dossier src disponibles pour référence, conformément aux règles d’exclusion du fichier manifeste.

Créer un fichier manifeste

Un fichier manifeste est un fichier de .json simple nommé qsharp.json qui peut éventuellement inclure des champs auteur, licence et .ints . Le fichier manifeste minimum viable est la chaîne {}. Lorsque vous créez un Q# projet dans VS Code, un fichier manifeste minimal est créé pour vous.

{}

Exemples de fichiers manifestes

Voici quelques exemples de la façon dont les fichiers manifeste peuvent définir l’étendue de votre Q# projet.

Dans cet exemple, l’auteur est le seul champ spécifié, et par conséquent tous les fichiers *.qs de ce répertoire et tous ses sous-répertoires sont inclus dans le Q# projet.

{
    "author":"Microsoft"
}

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

Dans un Q# projet, vous pouvez également utiliser le fichier manifeste pour affiner les paramètres vs Code Q# Linter. Par défaut, les trois règles Linter sont les suivantes :

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

À l’aide du fichier manifeste, vous pouvez définir chaque règle sur allow, warnou error, par exemple

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

Q# exigences et propriétés du projet

Les exigences et configurations suivantes s’appliquent à tous les Q# projets.

• Tous les fichiers *.qs que vous souhaitez inclure dans le projet doivent se trouver sous un dossier nommé src, qui doit se trouver sous le dossier racine du Q# projet. Lorsque vous créez un Q# projet dans VS Code, le /src dossier est créé automatiquement.
• Le fichier manifeste qsharp.json doit être au même niveau que le dossier src . Lorsque vous créez un Q# projet dans VS Code, le fichier qsharp.json est créé automatiquement.
• Les opérations et les fonctions dans les fichiers sources disponibles sont accessibles à l’aide open d’instructions :

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

ou référencez-les avec l’espace de noms :

MyMathLib.Multiply(x,y);

Pour Q# les programmes uniquement

• Un seul fichier *.qs dans un Q# projet peut avoir une @EntryPoint() définition.
• Le fichier *.qs avec la @EntryPoint() définition peut se trouver à n’importe quel niveau sous le fichier manifeste.
• Toute opération ou fonction mise en cache à partir d’un fichier *.qs n’importe où dans le Q# projet s’affiche en texte prédictif dans VS Code.
• Si l’espace de noms d’une opération ou d’une fonction sélectionnée n’a pas encore été ajouté, VS Code ajoute automatiquement l’instruction nécessaire open .

Étapes de création d’un Q# projet

1. Dans l’Explorateur de fichiers VS Code, cliquez avec le bouton droit sur le dossier racine du Q# projet et sélectionnez Créer Q# un projet, ou ouvrez le dossier et sélectionnez Afficher > la palette >Q#de commandes : Créer un Q# projet....

2. VS Code crée un fichier manifeste qsharp.json minimal dans le dossier et ajoute un /src dossier avec un Main.qs fichier de modèle.

3. Modifiez le fichier manifeste si nécessaire. Consultez les exemples de fichier manifeste.

4. Ajoutez et organisez vos Q# fichiers sources sous le /src dossier.

5. Si vous accédez au Q# projet à partir d’un programme Python ou d’un jupyter Notebook, définissez le chemin du dossier racine à l’aide qsharp.initde . Cet exemple suppose que votre programme se trouve dans le même dossier que le dossier racine du Q# projet :

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

6. Si vous utilisez uniquement Q# des fichiers dans VS Code, lorsque vous ouvrez un Q# fichier, le compilateur recherche le fichier manifeste qsharp.json , détermine le dossier racine du projet, puis analyse le sous-dossier pour les fichiers *.qs.

Remarque

Vous pouvez également créer manuellement le fichier manifeste et le dossier à l’étape /src 2.

Exemple de projet

Ce programme de téléportation quantique est un exemple de projet basé sur la structure de Q# dossiers indiquée précédemment et s’exécute sur le simulateur local dans VS Code. Pour exécuter le programme sur du matériel Azure Quantum ou des simulateurs tiers, consultez Prise en main des Q# programmes et VSCode pour connaître les étapes à suivre pour compiler votre programme et vous connecter à votre espace de travail Azure.

L’exemple utilise cette structure de répertoires :

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

Le fichier manifeste qsharp.json contient les champs d’auteur et de licence :

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

Q# fichiers sources

Avec une différence mineure - l’instruction - les @EntryPoint() fichiers sources sont identiques pour un programme, un Q# programme Python ou un jupyter Notebook.

Le fichier principal, RunTeleport.qs, contient le point d’entrée et fait référence à l’espace TeleportLib de noms dans 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 définit l’opération Teleport() et appelle l’opération PrepareBellPair() à partir de 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);
    }
}

Le fichier PrepareState.qs contient une opération réutilisable standard pour créer une paire Bell.

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

Exécution des programmes

Sélectionnez l’onglet de l’environnement dans lequel vous exécutez votre programme.

Exécution d’un Q# programme

Pour exécuter ce programme, ouvrez le fichier RunTeleport.qs dans VS Code, puis sélectionnez Exécuter.

Exécution d’un notebook Jupyter

Pour un programme Jupyter Notebook, les fichiers sources ne nécessitent pas l’attribut @EntryPoint() . Les fichiers fonctionnent uniquement en tant que bibliothèques sources.

Pour exécuter ce programme dans un bloc-notes Jupyter, ouvrez un nouveau notebook et exécutez les cellules suivantes :

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

Si votre chemin d’accès est valide, vous voyez un message de confirmation, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Exécutez le programme en appelant l’opération principale à l’aide de la %%qsharp commande magic

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

ou à l’aide de l’instruction qsharp.eval()

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

Exécution d’un programme Python

Pour un programme Python, les fichiers sources ne nécessitent pas l’attribut @EntryPoint() . Les fichiers fonctionnent uniquement en tant que bibliothèques sources.

Pour exécuter ce programme, exécutez les commandes suivantes :

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

Si votre chemin d’accès est valide, vous voyez un message de confirmation, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Exécutez le programme en appelant l’opération principale avec qsharp.eval()

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