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 se puede acceder desde orígenes externos.

Requisitos previos

• Un Azure Quantum espacio de trabajo en tu suscripción de Azure. Para crear un área de trabajo, consulte Creación de un Azure Quantum área de trabajo.
• Visual Studio Code (VS Code) con las extensiones Azure Quantum Development Kit y Python instaladas.
• Una cuenta de GitHub, si planea publicar el proyecto externo en un repositorio público de GitHub.

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

• Un entorno Python con Python y Pip instalado.

• La qdkPython biblioteca con el complemento opcional azure.

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

Cómo Q# funcionan los proyectos

Un Q# proyecto contiene un Q# archivo de manifiesto, denominado qsharp.jsony uno o varios .qs archivos en una estructura de carpetas especificada. Puede crear un Q# proyecto manualmente o directamente en VS Code.

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

Cuando se establece project_root en un archivo Jupyter Notebook o Python, el compilador busca el archivo de manifiesto en la carpeta project_root.

Un proyecto externo Q# es un proyecto estándar Q# que reside en otro directorio o en un repositorio público de GitHub 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 archivo de manifiesto, denominado qsharp.jsony 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 Q# proyecto con una qsharp.init invocación. 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 opcionalmente campos de autor, licencia y 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 de manifiesto

En los ejemplos siguientes se muestra cómo los archivos de manifiesto pueden definir 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",
      "license": "MIT"
  }
  

• 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 mínimo.

• Use import instrucciones 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 proyecto Q# y pulse Intro. 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 Q# proyecto a través de un Python programa o Jupyter Notebook, establezca la ruta de acceso de la carpeta raíz utilizando qsharp.init. 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 está utilizando archivos Q# en VS Code, el compilador busca un archivo de manifiesto al abrir un archivo Q#, determina la carpeta raíz del proyecto y luego examina la subcarpeta para archivos .qs.

Proyecto de ejemplo

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

Este ejemplo tiene la siguiente estructura de directorios:

• Teleportation_project
  • 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 principal, denominado Main.qs, 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 operación Teleport y llama a la operación PrepareBellPair desde el archivo PrepareStateLib.qs.

    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 se 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 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 dependencias externas para otros proyectos, de forma similar a una biblioteca. Las funciones y operaciones del proyecto externo Q# están disponibles para varios Q# proyectos. Una dependencia externa puede residir en una unidad compartida 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 instrucciones export al proyecto externo.
• Agregue instrucciones import al proyecto que llama.

Configurar los archivos de manifiesto

Los proyectos externos Q# pueden residir en un recurso compartido de unidad de red o local, o publicarse en un repositorio público de GitHub.

El archivo de manifiesto del proyecto que llama

Para agregar una dependencia a un proyecto externo en un recurso compartido de unidad, defina la dependencia en el archivo de manifiesto del proyecto que llama.

{
    "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 público de GitHub, 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 público de GitHub, debe agregar la propiedad files al archivo de manifiesto del proyecto externo, incluidos todos los archivos usados en el proyecto.

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

La propiedad files es opcional para un proyecto externo que se importa a través de "path" (es decir, una importación basada en ruta de archivo 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 se admite 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 definido 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, se usa el mismo programa de teletransportación que el ejemplo anterior, pero se separa 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:

   Tenga en cuenta que no es necesario exportar la operación PrepareBellPair ya que no se llama directamente desde su programa en Project_A. Dado que PrepareBellPair está en el ámbito local de Project_B, ya es accesible por la operación Teleport.

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

Proyectos y espacios de nombres implícitos

En Q# los proyectos, si no se especifica un espacio de nombres en un .qs programa, el compilador usa el nombre del archivo como 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 de llamada es <dependencyName>.<callable>, como en el ejemplo anterior, 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:

• /Fuente
  • 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.