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 auxquelles vous pouvez accéder à partir de sources externes.

Prérequis

• 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.
• Visual Studio Code (VS Code) avec les extensions Microsoft Quantum Development Kit (QDK) et Python installées.
• Pour publier votre projet externe dans un référentiel de GitHub public, vous devez disposer d’un compte GitHub.

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

• Environnement Python avec Python et Pip installés.

• Bibliothèque qdkPython avec l'option azure supplémentaire.

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

Fonctionnement des Q# projets

Un Q# projet contient un Q# fichier manifeste nommé qsharp.json, et un ou plusieurs .qs fichiers et .qsc 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 fichier .qs ou .qsc dans VS Code, le compilateur recherche dans la hiérarchie des dossiers environnants le fichier manifeste et détermine l’étendue du projet. Si le compilateur ne trouve pas de fichier manifeste, le compilateur fonctionne en mode fichier unique.

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

Un projet Q# externe est un projet standard Q# situé dans un autre répertoire ou sur un référentiel de 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 qsharp.json fichier manifeste et 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 les programmes Python et les fichiers Jupyter Notebook, vous devez specifier le dossier de projet Q# avec un appel qsharp.init. 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 inclure des champs , authoret license facultatifslints. 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 manifestes définissent l’étendue de votre Q# projet.

• Dans cet exemple, author 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"
  }
  

• 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 manifeste minimal est automatiquement créé.

• 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 un Q# projet. 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 projet Q# à partir d'un programme Python ou Jupyter Notebook, définissez le chemin du dossier root avec 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, alors le compilateur recherche un fichier manifeste lorsque vous ouvrez un fichier Q# et détermine le dossier racine du projet. Ensuite, le compilateur analyse /src et ses sous-répertoires pour .qs et .qsc fichiers.

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 matériel ou des simulateurs tiers, consultez Démarrer avec les programmes Q# et VS Code pour obtenir les étapes nécessaires pour compiler votre programme et vous connecter à votre espace de travail Azure Quantum.

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

• Projet_de_Téléportation
  • 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 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);
        }
    }

Le TeleportLib.qs fichier définit l’opération Teleport et appelle 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 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()"))

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

Vous pouvez configurer Q# des projets en tant que dépendance externe pour d’autres projets, similaires à une bibliothèque, pour rendre les fonctions et les opérations dans le projet externe Q# disponibles pour d’autres Q# projets. Une dépendance externe peut résider sur un partage de lecteur ou être publiée dans un référentiel de 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é files au fichier manifeste du projet externe.
• Ajoutez des export déclarations de code au projet externe.
• Ajoutez des import instructions au projet appelant.

Configurer les fichiers manifestes

Les projets Q# externes peuvent résider sur un partage de lecteur local ou réseau, ou vous pouvez les publier dans un référentiel de GitHub public.

Le 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 référentiel de 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 Q# externe est publié dans un référentiel de GitHub public, vous devez ajouter la propriété files au fichier manifeste du projet externe, y compris tous les fichiers utilisés par le projet.

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

La files propriété est facultative pour un projet externe que vous importez avec "path" une importation basée sur un chemin de fichier local. La propriété files est requise uniquement pour les projets publiés dans 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. Vous ne pouvez pas utiliser la syntaxe des caractères génériques, vous devez donc spécifier chaque élément 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 que vous définissez 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, utilisez le même programme de téléportation que l’exemple précédent, mais séparez le programme d'appel et les entités 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

   Vous n’avez pas besoin d’exporter l’opération PrepareBellPair si votre programme dans Project_A n’appelle pas directement cette opération. L’opération PrepareBellPair est déjà accessible par l’opération Teleport , car PrepareBellPair elle se trouve dans l’étendue locale de Project_B.

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

Projets et espaces de noms implicites

Dans Q# les projets, si vous ne spécifiez pas d’espace de noms 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>. Par exemple : 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.