Guide pratique pour créer et gérer Q# des projets et des bibliothèques personnalisées

Dans cet article, vous allez apprendre à créer, gérer et partager Q# des projets. Un Q# projet est une structure de dossiers avec plusieurs Q# fichiers qui peuvent accéder aux opérations et fonctions des autres. Les projets vous aident à organiser logiquement votre code source. Vous pouvez également utiliser des projets en tant que bibliothèques personnalisées accessibles à partir de sources externes.

Prérequis

• Un Azure Quantum espace de travail dans votre abonnement Azure. Pour créer un espace de travail, consultez Créer un Azure Quantum espace de travail.
• Visual Studio Code (VS Code) avec l'extension Azure Quantum Development Kit et l'extension Python installées.
• Un compte GitHub, si vous envisagez de publier votre projet externe dans un dépôt GitHub public.

Pour exécuter des Python programmes, vous avez également besoin des éléments suivants :

• Un Python environnement avec Python et Pip installé.

• Bibliothèque qdkPython avec l'extension azure optionnelle.

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

Fonctionnement des Q# projets

Un Q# projet contient un Q# fichier manifeste, nommé qsharp.jsonet un ou plusieurs .qs fichiers dans une structure de dossiers spécifiée. Vous pouvez créer un Q# projet manuellement ou directement dans VS Code.

Lorsque vous ouvrez un .qs fichier dans VS Code, le compilateur recherche la hiérarchie des dossiers environnants 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.

Lorsque vous définissez le project_root dans un fichier Jupyter Notebook ou Python, le compilateur recherche le fichier manifeste dans le dossier project_root.

Un projet externe Q# est un projet standard Q# qui réside dans un autre répertoire ou sur un dépôt GitHub public et agit comme une bibliothèque personnalisée. Un projet externe utilise export des instructions pour définir les fonctions et les opérations accessibles par des programmes externes. Les programmes définissent le projet externe comme une dépendance dans leur fichier manifeste et utilisent import des instructions pour accéder aux éléments du projet externe, tels que les opérations, les fonctions, les structs et les espaces de noms. Pour plus d’informations, consultez Utilisation de projets en tant que dépendances externes.

Définir un Q# projet

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

from qdk import qsharp

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

Créer un fichier manifeste

Un fichier manifeste est un fichier JSON nommé qsharp.json qui peut éventuellement inclure des champs auteur, licence et lints . 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

Les exemples suivants montrent comment les fichiers manifeste peuvent définir l’étendue de votre Q# projet.

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

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

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

  • needlessParens: default = allow

  • divisionByZero: default = warn

  • redundantSemicolons: default = warn

    Vous pouvez définir chaque règle dans le fichier manifeste sur allow, warnou error. Par exemple:

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

• Vous pouvez également utiliser le fichier manifeste pour définir un projet externe Q# en tant que dépendance et accéder à distance aux opérations et fonctions dans ce projet externe. Pour plus d’informations, consultez Utilisation de projets en tant que dépendances externes.

Q# exigences et propriétés du projet

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

• Tous les .qs fichiers 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 automatiquement créé.

• Le fichier manifeste doit être au même niveau que le src dossier. Lorsque vous créez un Q# projet dans VS Code, un fichier minimal est créé automatiquement.

• Utilisez des import instructions pour référencer des opérations et des fonctions à partir d’autres fichiers du projet.

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

  Vous pouvez également les référencer individuellement avec l’espace de noms.

  MyMathLib.Multiply(x,y); 
  

Pour les projets Q# uniquement

• Vous pouvez définir une opération de point d’entrée dans un .qs seul fichier d’un Q# projet, qui est l’opération Main() par défaut.
• Vous devez placer le .qs fichier avec la définition du point d’entrée au niveau d’un répertoire de projet sous le fichier manifeste.
• Toutes les opérations et fonctions du projet Q# qui sont mises en cache et affichées en mode texte prédictif à partir d'un affichage .qs dans VS Code.
• Si l’espace de noms d’une opération ou d’une fonction sélectionnée n’est pas encore importé, VS Code ajoute automatiquement l’instruction nécessaire import .

Guide pratique pour créer un Q# projet

Pour créer un Q# projet, procédez comme suit :

1. Dans l’Explorateur VS Code de fichiers, accédez au dossier que vous souhaitez utiliser comme dossier racine pour le Q# projet.

2. Ouvrez le menu Affichage et choisissez Palette de commandes.

3. Entrée QDK: Créer le projet Q# et appuyer sur Entrée. VS Code crée un fichier manifeste minimal dans le dossier et ajoute un /src dossier avec un Main.qs fichier de modèle.

4. Modifiez le fichier manifeste de votre projet. Consultez les exemples de fichier manifeste.

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

6. Si vous accédez au Q# projet à partir d’un Python programme ou Jupyter Notebook, définissez le chemin du dossier racine à l’aide de qsharp.init. Cet exemple suppose que votre programme se trouve dans le /src dossier du Q# projet :

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

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

Exemple de projet

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

Cet exemple présente la structure de répertoires suivante :

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

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

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

Q# fichiers sources

Le fichier principal, nommé Main.qs, contient le point d’entrée et fait référence à l'espace de noms TeleportOperations.TeleportLib à partir de 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);
        }
    }

Les TeleportLib.qs fichiers définissent l’opération Teleport et appellent l’opération PrepareBellPair à partir du PrepareStateLib.qs fichier.

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

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

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

Exécuter les programmes

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

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 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()"))

Configurer des Q# projets en tant que dépendances externes

Vous pouvez configurer Q# des projets en tant que dépendances externes pour d’autres projets, similaires à une bibliothèque. Les fonctions et les opérations du projet externe Q# sont mises à la disposition de plusieurs Q# projets. Une dépendance externe peut résider sur un partage de lecteur ou être publiée dans un dépôt GitHub public.

Pour utiliser un Q# projet comme dépendance externe, vous devez :

• Ajoutez le projet externe en tant que dépendance dans le fichier manifeste du projet appelant.
• Si le projet externe est publié sur GitHub, ajoutez la propriété fichiers au fichier manifeste du projet externe.
• Ajoutez des export instructions au projet externe.
• Ajoutez des import instructions au projet appelant.

Configurer les fichiers manifestes

Les projets externes Q# peuvent résider sur un partage de lecteur local ou réseau, ou être publiés dans un dépôt GitHub public.

Fichier manifeste du projet appelant

Pour ajouter une dépendance à un projet externe sur un partage de lecteurs, définissez la dépendance dans le fichier manifeste du projet appelant.

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

Dans le fichier manifeste précédent, MyDependency est une chaîne définie par l’utilisateur qui identifie l’espace de noms lorsque vous appelez une opération. Par exemple, si vous créez une dépendance nommée MyMathFunctions, vous pouvez appeler une fonction à partir de cette dépendance avec MyMathFunctions.MyFunction().

Pour ajouter une dépendance à un projet publié dans un dépôt GitHub public, utilisez l’exemple de fichier manifeste suivant :

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

Fichier manifeste du projet externe

Si votre projet externe Q# est publié dans un dépôt GitHub public, vous devez ajouter la propriété fichiers au fichier manifeste du projet externe, y compris tous les fichiers utilisés dans le projet.

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

La propriété fichiers est facultative pour un projet externe importé via "path" (autrement dit, une importation basée sur un chemin de fichier local). La propriété fichiers est requise uniquement pour les projets publiés sur GitHub.

Utiliser l’instruction export

Pour rendre les fonctions et les opérations dans un projet externe accessibles aux projets appelants, utilisez l’instruction export . Vous pouvez exporter l’un ou l’ensemble des callables dans le fichier. La syntaxe des caractères génériques n’est pas prise en charge, vous devez donc spécifier chaque appelable que vous souhaitez exporter.

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;

Utiliser l’instruction import

Pour rendre les éléments d’une dépendance externe disponibles, utilisez les déclarations import du programme appelant. L’instruction import utilise l’espace de noms défini pour la dépendance dans le fichier manifeste.

Par exemple, considérez la dépendance dans le fichier manifeste suivant :

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

Importez les fonctions appelables avec le code suivant :

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

...

L’instruction import prend également en charge la syntaxe de génériques de caractères et les 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; 

Exemple de projet externe

Pour cet exemple, vous utilisez le même programme de téléportation que l’exemple précédent, en séparant le programme appelant et les éléments appelables dans différents projets.

1. Créez deux dossiers sur votre lecteur local, par exemple Project_A et Project_B.

2. Créez un Q# projet dans chaque dossier. Pour plus d’informations, consultez les étapes de création d’un Q# projet.

3. Dans Project_A, le programme appelant, collez le code suivant dans le fichier manifeste, mais modifiez le chemin si nécessaire pour Project_B:

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

4. Dans Project_A, copiez le code suivant dans 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. Dans Project_B, copiez le code suivant dans 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
   

   Remarque

   Notez que l’opération PrepareBellPair n’a pas besoin d’être exportée, car elle n’est pas appelée directement à partir de votre programme dans Project_A. Étant donné que PrepareBellPair se trouve dans l’étendue locale de Project_B, il est déjà accessible par l’opération Teleport.

6. Pour exécuter le programme, ouvrez /Project_A/Main.qsVS Code et choisissez Exécuter.

Projets et espaces de noms implicites

Dans les Q# projets, si un espace de noms n’est pas spécifié dans un .qs programme, le compilateur utilise le nom de fichier comme espace de noms. Ensuite, lorsque vous référencez un appelant à partir d’une dépendance externe, vous utilisez la syntaxe <dependencyName>.<namespace>.<callable>. Toutefois, si le fichier est nomméMain.qs, le compilateur part du principe que l’espace de noms et la syntaxe appelante sont <dependencyName>.<callable>, comme dans l’exemple précédent. import MyTeleportLib.Teleport

Étant donné que vous avez peut-être plusieurs fichiers projet, vous devez prendre en compte la syntaxe correcte lorsque vous référencez des fonctions appelables. Par exemple, considérez un projet avec la structure de fichiers suivante :

• /src
  • Main.qs
  • MathFunctions.qs

Le code suivant effectue des appels à la dépendance externe :

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

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

Pour plus d’informations sur le comportement de l’espace de noms, consultez Espaces de noms utilisateur.