Creación y administración de Q# proyectos y bibliotecas personalizadas

En este artículo, aprenderá a crear, administrar y compartir Q# proyectos. Un Q# proyecto es una estructura de carpetas con varios Q# archivos que pueden acceder entre sí a las operaciones y funciones del otro. Los proyectos le ayudan a organizar lógicamente el código fuente. También puede usar proyectos como bibliotecas personalizadas a las que puede acceder desde orígenes externos.

Requisitos previos

• Un área de trabajo de Azure Quantum en la suscripción de Azure. Para crear un área de trabajo, consulte Create an Azure Quantum workspace.
• Visual Studio Code (VS Code) con las extensiones Microsoft Quantum Development Kit (QDK) y Python instalados.
• Para publicar el proyecto externo en un repositorio de GitHub público, debe tener una cuenta de GitHub.

Para ejecutar programas de Python, también necesita lo siguiente:

• Un entorno de Python con Python y Pip instalado.

• La biblioteca qdkPython con la azure adicional.

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

Cómo Q# funcionan los proyectos

Un Q# proyecto contiene un Q# archivo de manifiesto denominado qsharp.json, y uno o más .qs archivos y .qsc archivos en una estructura de carpetas especificada. Puede crear un Q# proyecto manualmente o directamente en VS Code.

Al abrir un .qs archivo o .qsc en VS Code, el compilador busca en la jerarquía de carpetas circundantes el archivo de manifiesto y determina el ámbito del proyecto. Si el compilador no encuentra un archivo de manifiesto, el compilador funciona en un modo de archivo único.

Al establecer el en un archivo /> , el compilador busca el archivo de manifiesto en la carpeta .

Un proyecto de Q# externo es un proyecto estándar Q# que se encuentra en otro directorio o en un repositorio de GitHub público y actúa como una biblioteca personalizada. Un proyecto externo usa export instrucciones para definir las funciones y las operaciones a las que pueden acceder los programas externos. Los programas definen el proyecto externo como una dependencia en su archivo de manifiesto y usan import instrucciones para tener acceso a los elementos del proyecto externo, como operaciones, funciones, estructuras y espacios de nombres. Para obtener más información, consulte Uso de proyectos como dependencias externas.

Definición de un Q# proyecto

Un Q# proyecto se define mediante la presencia de un qsharp.json archivo de manifiesto y una src carpeta, ambos deben estar en la carpeta raíz del proyecto. La src carpeta contiene los Q# archivos de origen. En el caso Q# de programas y proyectos externos, el Q# compilador detecta automáticamente la carpeta del proyecto. Para Python programas y Jupyter Notebook archivos, debe especificar la carpeta del proyecto Q# mediante una llamada qsharp.init. Sin embargo, la estructura de carpetas de un Q# proyecto es la misma para todos los tipos de programas.

from qdk import qsharp

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

Crear un archivo de manifiesto

Un archivo de manifiesto es un archivo JSON denominado qsharp.json que puede incluir campos opcionales author, licensey lints . El archivo de manifiesto mínimo viable es la cadena {}. Al crear un Q# proyecto en VS Code, se crea un archivo de manifiesto mínimo automáticamente.

{}

Ejemplos de archivos manifest

En los ejemplos siguientes se muestra cómo definen los archivos de manifiesto el ámbito del Q# proyecto.

• En este ejemplo, author es el único campo especificado, por lo que todos los .qs archivos de este directorio y sus subdirectorios se incluyen en el Q# proyecto.

  {
      "author":"Microsoft"
  }
  

• Dentro de un Q# proyecto, también puede usar el archivo de manifiesto para ajustar la VS CodeQ# configuración de Linter. De forma predeterminada, las tres reglas de Linter son:

  • needlessParens: valor predeterminado = allow

  • divisionByZero: valor predeterminado = warn

  • redundantSemicolons: valor predeterminado = warn

    Puede establecer cada regla en el archivo de manifiesto en allow, warn o error. Por ejemplo:

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

• También puede usar el archivo de manifiesto para definir un proyecto externo Q# como una dependencia y acceder de forma remota a las operaciones y funciones de ese proyecto externo. Para obtener más información, consulte Uso de proyectos como dependencias externas.

Q# requisitos y propiedades del proyecto

Los siguientes requisitos y configuraciones se aplican a todos los Q# proyectos.

• Todos los .qs archivos que desea incluir en el proyecto deben estar en una carpeta denominada src, que debe estar en la carpeta raíz del Q# proyecto. Al crear un Q# proyecto en VS Code, la /src carpeta se crea automáticamente.

• El archivo de manifiesto debe estar en el mismo nivel que la src carpeta. Al crear un Q# proyecto en VS Code, se crea automáticamente un archivo de manifiesto mínimo.

• Utilice declaraciones import para hacer referencia a operaciones y funciones de otros archivos del proyecto.

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

  O bien, haga referencia a ellos individualmente con el espacio de nombres .

  MyMathLib.Multiply(x,y); 
  

Solo para proyectos Q#

• Puede definir una operación de punto de entrada solo en un archivo .qs en un proyecto Q#, que es la operación Main() por defecto.
• Debe colocar el archivo .qs con la definición de punto de entrada en un nivel de directorio del proyecto por debajo del archivo de manifiesto.
• Todas las operaciones y funciones del proyecto Q# que se almacenan en caché a partir de una pantalla .qs se muestran como texto predictivo en VS Code.
• Si aún no se importa el espacio de nombres de una operación o función seleccionada, VS Code agrega automáticamente la instrucción necesaria import .

Creación de un Q# proyecto

Para crear un Q# proyecto, siga estos pasos:

1. En el VS Code explorador de archivos, vaya a la carpeta que desea usar como carpeta raíz del Q# proyecto.

2. Abra el menú Ver y elija Paleta de comandos.

3. Escriba QDK: Crear Q# proyecto. VS Code crea un archivo de manifiesto mínimo en la carpeta y agrega una /src carpeta con un Main.qs archivo de plantilla.

4. Edite el archivo de manifiesto del proyecto. Consulte Ejemplos de archivos de manifiesto.

5. Agregue y organice los Q# archivos de origen en la /src carpeta .

6. Si accede al proyecto desde un programa Q# o Python, establezca la ruta de acceso de la carpeta raíz Jupyter Notebook con . En este ejemplo se supone que el programa está en la /src carpeta del Q# proyecto:

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

7. Si solo usa Q# archivos en VS Code, el compilador busca un archivo de manifiesto al abrir un Q# archivo y determina la carpeta raíz del proyecto. A continuación, el compilador examina /src y sus subdirectorios en busca de archivos .qs y .qsc.

Proyecto de ejemplo

Este programa de teleportación cuántica es un ejemplo de proyecto que se ejecuta en el simulador local en Q#. Para ejecutar el programa en Azure Quantum hardware o simuladores de terceros, consulte Comience con los programas Q# y VS Code para obtener los pasos de compilación de su programa y de conexión a su espacio de trabajo Azure Quantum.

Este ejemplo tiene la siguiente estructura de directorios:

• Proyecto_de_Teleportación
  • qsharp.json
  • src
    • Main.qs
    • TeleportOperations
      • TeleportLib.qs
      • PrepareState
        • PrepareStateLib.qs

El archivo de manifiesto contiene los campos de autor y licencia :

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

Q# archivos de origen

El archivo Main.qs principal contiene el punto de entrada y hace referencia al TeleportOperations.TeleportLib espacio de nombres 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);
        }
    }

El TeleportLib.qs archivo define la Teleport operación y llama a la PrepareBellPair operación desde el PrepareStateLib.qs archivo .

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

El PrepareStateLib.qs archivo contiene una operación reutilizable estándar para crear un par bell.

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

Ejecución de los programas

Elija la pestaña del entorno en el que ejecuta el programa.

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

Configurar Q# proyectos como dependencias externas

Puede configurar Q# proyectos como una dependencia externa para otros proyectos, de forma similar a una biblioteca, para que las funciones y las operaciones del proyecto externo Q# estén disponibles para otros Q# proyectos. Una dependencia externa puede residir en un recurso compartido de disco o publicarse en un repositorio público de GitHub.

Para usar un Q# proyecto como dependencia externa, debe:

• Agregue el proyecto externo como dependencia en el archivo de manifiesto del proyecto que llama.
• Si el proyecto externo se publica en GitHub, agregue la propiedad files al archivo de manifiesto del proyecto externo.
• Agregue declaraciones export al proyecto externo.
• Agregue instrucciones import al proyecto que llama.

Configurar los archivos de manifiesto

Los proyectos Q# externos pueden ubicarse en una unidad local o en un recurso compartido de red, o puede publicarlos en un repositorio público de GitHub.

El archivo de manifiesto del proyecto que realiza la llamada

Para agregar una dependencia a un proyecto externo en una unidad compartida, defina la dependencia en el archivo de manifiesto del proyecto que hace la llamada.

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

En el archivo de manifiesto anterior, MyDependency es una cadena definida por el usuario que identifica el espacio de nombres al llamar a una operación. Por ejemplo, si crea una dependencia denominada MyMathFunctions, puede llamar a una función desde esa dependencia con MyMathFunctions.MyFunction().

Para agregar una dependencia a un proyecto publicado en un repositorio de GitHub público, use el siguiente archivo de manifiesto de ejemplo:

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

El archivo de manifiesto del proyecto externo

Si el proyecto externo Q# se publica en un repositorio de GitHub público, debe agregar la propiedad files al archivo de manifiesto del proyecto externo, incluidos todos los archivos que usa el proyecto.

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

La files propiedad es opcional para un proyecto externo que se importa mediante "path" con una importación basada en filepath local. La propiedad files solo es necesaria para los proyectos que se publican en GitHub.

Use la export instrucción

Para que las funciones y las operaciones de un proyecto externo sean accesibles para los proyectos que llaman, use la instrucción export. Puede exportar cualquiera o todos los elementos invocables en el archivo. No puede usar la sintaxis de caracteres comodín, por lo que debe especificar cada invocable que quiera exportar.

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;

Use la import instrucción

Para que los elementos de una dependencia externa estén disponibles, use instrucciones import del programa de llamada. La import instrucción usa el espacio de nombres que defines para la dependencia en el archivo de manifiesto.

Por ejemplo, considere la dependencia en el siguiente archivo de manifiesto:

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

Importe los invocables con el código siguiente:

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

...

La import instrucción también admite la sintaxis y los alias de comodín.

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

Proyecto externo de ejemplo

En este ejemplo, use el mismo programa de teletransportación que el ejemplo anterior, pero separe el programa de llamada y los invocables en proyectos diferentes.

1. Cree dos carpetas en la unidad local, por ejemplo Project_A , y Project_B.

2. Cree un Q# proyecto en cada carpeta. Para obtener más información, consulte los pasos descritos en Creación de un Q# proyecto.

3. En Project_A, el programa que realiza la llamada, copie en el archivo de manifiesto el código siguiente, pero edite la ruta según sea necesario para Project_B.

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

4. En Project_A, copie el código siguiente en 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. En Project_B, copie el código siguiente en 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
   

   Nota:

   No es necesario exportar la operación si tu programa en Project_A no llama directamente a esa operación. La PrepareBellPair operación ya es accesible por la Teleport operación porque PrepareBellPair está en el ámbito local de Project_B.

6. Para ejecutar el programa, abra /Project_A/Main.qs en VS Code y elija Ejecutar.

Proyectos y espacios de nombres implícitos

En proyectos Q#, si no se especifica un espacio de nombres en .qs programas, el compilador usa el nombre de archivo como su espacio de nombres. A continuación, cuando se hace referencia a un invocable desde una dependencia externa, se usa la sintaxis <dependencyName>.<namespace>.<callable>. Sin embargo, si el archivo se denomina Main.qs, el compilador asume que el espacio de nombres y la sintaxis que realiza la llamada es <dependencyName>.<callable>. Por ejemplo: import MyTeleportLib.Teleport.

Dado que es posible que tenga varios archivos de proyecto, debe tener en cuenta la sintaxis correcta al hacer referencia a los invocables. Por ejemplo, considere un proyecto con la siguiente estructura de archivos:

• /src
  • Main.qs
  • MathFunctions.qs

El código siguiente realiza llamadas a la dependencia externa:

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

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

Para obtener más información sobre el comportamiento del espacio de nombres, consulte Espacios de nombres de usuario.