Trabajar con Q# proyectos

  • Artículo

Con el lanzamiento de Azure Quantum Development Kit, puede definir Q# proyectos, que son estructuras de carpetas con varios Q# archivos que pueden acceder entre sí a los recursos. Los proyectos son útiles para crear bibliotecas reutilizables y organizar lógicamente el código fuente.

Un Q# proyecto contiene un Q# archivo de manifiesto, denominado qsharp.json, y uno o varios archivos *.qs en una estructura de carpetas especificada. Cuando un usuario abre un archivo *.qs en VS Code, o establece en project_root un archivo de Jupyter Notebook o Python, 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. Un Q# proyecto se puede crear manualmente o directamente en VS Code.

Requisitos previos

Definición de un Q# proyecto

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

Imagen que muestra la jerarquía de carpetas de un Q# proyecto.

Definición de la carpeta del proyecto (Q# programas)

Cuando se abre un archivo *.qs en VS Code, el Q# compilador busca hacia arriba en la estructura de carpetas un archivo de manifiesto de qsharp.json . Si encuentra un archivo de manifiesto, el compilador busca hacia abajo en todas las subcarpetas del directorio src para los archivos *.qs y almacena en caché todas las operaciones o funciones, y hace que esas operaciones y funciones estén disponibles para todos los archivos *.qs, según las reglas de exclusión del archivo de manifiesto.

Por ejemplo, dada esta estructura de carpetas:

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

al abrir el archivo /src/TeleportOperation/PrepareState/PrepareState.qs, el Q# compilador:

  1. Comprueba /src/TeleportOperation/PrepareState/ para un archivo qsharp.json .
  2. Comprueba /src/TeleportOperation para qsharp.json.
  3. Comprueba /src para qsharp.json.
  4. Comprueba /si hay qsharp.json.
  5. Establece / como el directorio raíz del proyecto e incluye todos los archivos *.qs en la raíz del proyecto, según la configuración del archivo de manifiesto.

Crear un archivo de manifiesto

Un archivo de manifiesto es un archivo de .json simple denominado qsharp.json que, opcionalmente, puede incluir campos de autor, licencia y .ints . El archivo de manifiesto mínimo viable es la cadena {}. Al crear un Q# proyecto en VS Code, se crea automáticamente un archivo de manifiesto mínimo.

{}

Ejemplos de archivos de manifiesto

A continuación se muestran algunos ejemplos de cómo los archivos de manifiesto pueden definir el ámbito del Q# proyecto.

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

{
    "author":"Microsoft"
}

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

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

  • needlessParens: valor predeterminado = allow
  • divisionByZero: valor predeterminado = warn
  • redundantSemicolons: valor predeterminado = warn

Con el archivo de manifiesto, puede establecer cada regla allowen , warno error, por ejemplo.

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

Q# requisitos y propiedades del proyecto

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

  • Todos los archivos *.qs 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 qsharp.json debe estar en el mismo nivel que la carpeta src . Al crear un Q# proyecto en VS Code, el archivo qsharp.json se crea automáticamente.
  • Se puede acceder a las operaciones y funciones de los archivos de origen disponibles mediante open instrucciones :
open MyMathLib;
...
    Multiply(x,y);

o haciendo referencia a ellos con el espacio de nombres :

MyMathLib.Multiply(x,y);

Solo para Q# programas

  • Solo un archivo *.qs de un Q# proyecto puede tener @EntryPoint() definido.
  • El archivo *.qs con la @EntryPoint() definición se puede encontrar en cualquier nivel por debajo del archivo de manifiesto.
  • Cualquier operación o función almacenada en caché desde un archivo *.qs en cualquier parte del Q# proyecto se muestra en texto predictivo en VS Code.
  • Si aún no se ha agregado el espacio de nombres de una operación o función seleccionada, VS Code agrega automáticamente la instrucción necesaria open .

Pasos para crear un Q# proyecto

  1. En el explorador de archivos de VS Code, haga clic con el botón derecho en la carpeta que desea usar para la carpeta raíz del Q# proyecto y seleccione Create Q# proyecto, o abra la carpeta y seleccione Ver > paleta >Q#de comandos: Create un Q# proyecto....

  2. VS Code crea un archivo de manifiesto mínimo qsharp.json en la carpeta y agrega una /src carpeta con un Main.qs archivo de plantilla.

  3. Edite el archivo de manifiesto según sea necesario. Consulte ejemplos de archivos de manifiesto.

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

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

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

  6. Si solo usa Q# archivos en VS Code, al abrir un Q# archivo, el compilador busca el archivo de manifiesto qsharp.json , determina la carpeta raíz del proyecto y, a continuación, examina la subcarpeta de los archivos *.qs.

Nota

También puede crear manualmente el archivo de manifiesto y la carpeta en el /src paso 2.

Proyecto de ejemplo

Este programa de teletransporte cuántico es un ejemplo de un Q# proyecto basado en la estructura de carpetas mostrada anteriormente y se ejecuta en el simulador local en VS Code. Para ejecutar el programa en hardware de Azure Quantum o simuladores de terceros, consulte Introducción a Q# los programas y VSCode para conocer los pasos para compilar el programa y conectarse a su área de trabajo de Azure.

En el ejemplo se usa esta estructura de directorios:

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

El archivo de manifiesto qsharp.json contiene los campos de autor y licencia :

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

Q# archivos de origen

Con una diferencia menor: la @EntryPoint() instrucción : los archivos de origen son los mismos para un Q# programa, un programa de Python o un Jupyter Notebook.

El archivo principal, RunTeleport.qs, contiene el punto de entrada y hace referencia al TeleportLib espacio de nombres en 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 define la Teleport() operación y llama a la PrepareBellPair() operación desde 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);
    }
}

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

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

Ejecución de los programas

Seleccione la pestaña del entorno en el que está ejecutando el programa.

Para ejecutar este programa, abra el archivo RunTeleport.qs en VS Code y seleccione Ejecutar.