Trabalhar com Q# projetos

Com o lançamento do Azure Quantum Development Kit, você pode definir Q# projetos, que são estruturas de pastas com vários Q# arquivos que podem acessar os recursos uns dos outros. Os projetos são úteis para criar bibliotecas reutilizáveis e organizar logicamente seu código-fonte.

Um Q# projeto contém um Q# arquivo de manifesto, chamado qsharp.json, e um ou mais arquivos *.qs em uma estrutura de pastas especificada. Quando um usuário abre um arquivo *.qs no VS Code, ou define o project_root em um arquivo Jupyter Notebook ou Python, o compilador procura o arquivo de manifesto na hierarquia de pastas ao redor e determina o escopo do projeto. Se nenhum arquivo de manifesto for encontrado, o compilador opera em um único modo de arquivo. Um Q# projeto pode ser criado manualmente ou diretamente no VS Code.

Pré-requisitos

• Um espaço de trabalho do Azure Quantum em sua assinatura do Azure. Para criar um espaço de trabalho, consulte Criar um espaço de trabalho do Azure Quantum.
• Um ambiente Python com Python e Pip instalados.
• Visual Studio Code com a extensão Azure Quantum Development Kit e Python instalada.
• O Azure Quantum qsharp e azure-quantum pacotes.

Definir um Q# projeto

Um Q# projeto é definido pela presença de um arquivo de manifesto qsharp.json e uma pasta src (que contém os Q# arquivos de origem), ambos os quais devem estar na pasta raiz do projeto. Para Q# programas, o Q# compilador deteta a pasta do projeto automaticamente. Para programas Python e Jupyter Notebooks, você deve especificar a pasta do Q# projeto com uma qsharp.init chamada. A estrutura de pastas para um Q# projeto, no entanto, permanece a mesma para todos os tipos de programas.

Usando um Q# programa

Definição da pasta do projeto (Q# programas)

Quando um arquivo *.qs é aberto no VS Code, o compilador procura um arquivo de manifesto Q# qsharp.json para cima na estrutura de pastas. Se encontrar um arquivo de manifesto, o compilador procurará arquivos *.qs em todas as subpastas do diretório src e armazenará em cache quaisquer operações ou funções, e disponibilizará essas operações e funções para todos os arquivos *.qs, de acordo com as regras de exclusão do arquivo de manifesto.

Por exemplo, dada esta estrutura de pastas:

• Teleportation_project
  • qsharp.json
  • SRC
    • RunTeleport.qs
    • Operações de Teletransporte
      • Teleport.qs
      • PrepareState
        • PrepareState.qs

quando você abre o arquivo /src/TeleportOperation/PrepareState/PrepareState.qs, o Q# compilador:

1. Verifica /src/TeleportOperation/PrepareState/ para um arquivo qsharp.json .
2. Verifica /src/TeleportOperation para qsharp.json.
3. Verifica /src para qsharp.json.
4. Verifica / se há qsharp.json.
5. Estabelece / como o diretório raiz do projeto e inclui todos os arquivos *.qs sob a raiz no projeto, de acordo com as configurações do arquivo de manifesto.

Usando Python ou um Jupyter Notebook

Definição da pasta do projeto (programas Python e Jupyter Notebook)

Quando você estiver usando um programa Python ou célula do Jupyter Notebook para acessar Q# recursos, você precisa definir o diretório raiz do projeto diretamente com uma qsharp.init instrução. Usando a mesma estrutura de pastas do exemplo anterior

• Teleportation_project
  • qsharp.json
  • SRC
  • MyPythonProgram.py
    • RunTeleport.qs
    • Operações de Teletransporte
      • Teleport.qs
      • PrepareState
        • PrepareState.qs

você definiria o project_root antes de fazer chamadas para qualquer Q# operação.

Supondo que seu programa Python esteja na pasta do Q# projeto

import qsharp

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

O caminho da pasta raiz é relativo ao arquivo que está definindo-o, o que significa que a Q# pasta do projeto pode estar em qualquer lugar e o programa de chamada não precisa necessariamente estar no projeto. Um caminho válido também pode ser './MyProjects/Teleportation_project', ou ../../Teleportation_project.

O Q# compilador verifica se há um arquivo qsharp.json válido na pasta raiz especificada e disponibiliza quaisquer recursos *.qs na pasta src para referência, de acordo com as regras de exclusão do arquivo de manifesto.

Criar um arquivo de manifesto

Um arquivo de manifesto é um arquivo de .json simples chamado qsharp.json que pode opcionalmente incluir campos autor, licença e .ints . O arquivo de manifesto mínimo viável é a cadeia de caracteres {}. Quando você cria um Q# projeto no VS Code, um arquivo de manifesto mínimo é criado para você.

{}

Exemplos de arquivo de manifesto

A seguir estão alguns exemplos de como os arquivos de manifesto podem definir o escopo do seu Q# projeto.

Neste exemplo, autor é o único campo especificado e, portanto, todos os arquivos *.qs neste diretório e todos os seus subdiretórios são incluídos no Q# projeto.

{
    "author":"Microsoft"
}

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

Dentro de um Q# projeto, você também pode usar o arquivo de manifesto para ajustar as configurações do VS Code Q# Linter. Por padrão, as três regras do Linter são:

• needlessParens: padrão = allow
• divisionByZero: padrão = warn
• redundantSemicolons: padrão = warn

Usando o arquivo de manifesto, você pode definir cada regra como allow, warnou , por errorexemplo

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

Q# Requisitos e propriedades do projeto

Os seguintes requisitos e configurações aplicam-se a todos os Q# projetos.

• Todos os arquivos *.qs que você deseja incluir no projeto devem estar sob uma pasta chamada src, que deve estar sob a pasta raiz do Q# projeto. Quando você cria um Q# projeto no VS Code, a /src pasta é criada automaticamente.
• O arquivo de manifesto qsharp.json deve estar no mesmo nível da pasta src . Quando você cria um Q# projeto no VS Code, o arquivo qsharp.json é criado automaticamente.
• Operações e funções em arquivos de origem disponíveis podem ser acessadas usando open instruções:

open MyMathLib;
...
    Multiply(x,y);

ou fazendo referência a eles com o namespace:

MyMathLib.Multiply(x,y);

Apenas para Q# programas

• Apenas um arquivo *.qs em um Q# projeto pode ter um @EntryPoint() definido.
• O arquivo *.qs com a @EntryPoint() definição pode ser localizado em qualquer nível abaixo do arquivo de manifesto.
• Qualquer operação ou função armazenada em cache a partir de um arquivo *.qs em qualquer lugar do Q# projeto é exibida em texto preditivo no VS Code.
• Se o namespace de uma operação ou função selecionada ainda não tiver sido adicionado, o VS Code adicionará automaticamente a instrução necessária open .

Etapas para criar um Q# projeto

1. No explorador de ficheiros VS Code, clique com o botão direito do rato na pasta que pretende utilizar para a pasta raiz do Q# projeto e selecione Criar Q# projeto, ou abra a pasta e selecione Ver > Paleta >Q#de Comandos: Criar um Q# projeto....

2. O VS Code cria um arquivo de manifesto de qsharp.json mínimo na pasta e adiciona uma /src pasta com um arquivo de Main.qs modelo.

3. Edite o arquivo de manifesto conforme necessário. Consulte Exemplos de arquivo de manifesto.

4. Adicione e organize seus Q# arquivos de /src origem na pasta.

5. Se você estiver acessando o Q# projeto a partir de um programa Python ou Jupyter Notebook, defina o caminho da pasta raiz usando qsharp.init. Este exemplo pressupõe que seu programa esteja na mesma pasta que a pasta raiz do Q# projeto:

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

6. Se você estiver usando apenas Q# arquivos no VS Code, quando você abrir um Q# arquivo, o compilador procura o arquivo de manifesto qsharp.json , determina a pasta raiz do projeto e, em seguida, verifica a subpasta em busca de arquivos *.qs.

Nota

Você também pode criar manualmente o arquivo de manifesto e a /src pasta na etapa 2.

Exemplo de projeto

Este programa de teletransporte quântico é um exemplo de um Q# projeto baseado na estrutura de pastas mostrada anteriormente e é executado no simulador local no VS Code. Para executar o programa no hardware do Azure Quantum ou em simuladores de terceiros, consulte Introdução Q# a programas e VSCode para obter etapas para compilar seu programa e conectar-se ao seu espaço de trabalho do Azure.

O exemplo usa esta estrutura de diretório:

• Teleportation_project
  • qsharp.json
  • SRC
    • RunTeleport.qs
    • Operações de Teletransporte
      • Teleport.qs
      • PrepareState
        • PrepareState.qs

O arquivo de manifesto qsharp.json contém os campos autor e licença :

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

Q# arquivos de origem

Com uma pequena diferença - a @EntryPoint() instrução - os arquivos de origem são os mesmos para um Q# programa, um programa Python ou um Jupyter Notebook.

O arquivo principal, RunTeleport.qs, contém o ponto de entrada e faz referência ao TeleportLib namespace em 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 a Teleport() operação e chama a PrepareBellPair() operação de 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);
    }
}

O arquivo PrepareState.qs contém uma operação reutilizável padrão para criar um par Bell.

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

Executando os programas

Selecione a guia para o ambiente no qual você está executando o programa.

Executando um Q# programa

Para executar este programa, abra o arquivo RunTeleport.qs no VS Code e selecione Executar.

Executando um Notebook Jupyter

Para um programa Jupyter Notebook, os arquivos de origem não exigem o @EntryPoint() atributo. Os arquivos funcionam apenas como bibliotecas de código-fonte.

Para executar este programa em um Jupyter Notebook, abra um novo bloco de anotações e execute as seguintes células:

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 same folder as the root folder
qsharp.init(project_root = './Teleportation_project')

Se o seu caminho for válido, você verá uma mensagem de confirmação, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Execute o programa chamando a operação principal usando o %%qsharp comando magic

%%qsharp
// call the main operation
RunTeleport.RunTeleportationExample();

ou utilizando a qsharp.eval() declaração

print (qsharp.eval("RunTeleport.RunTeleportationExample()"));

Executando um programa Python

Para um programa Python, os arquivos de origem não exigem o @EntryPoint() atributo. Os arquivos funcionam apenas como bibliotecas de código-fonte.

Para executar este programa, execute os seguintes comandos:

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 same folder as the root folder
qsharp.init(project_root = '/.Teleportation_project')

Se o seu caminho for válido, você verá uma mensagem de confirmação, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Execute o programa chamando a operação principal com qsharp.eval()

print (qsharp.eval("RunTeleport.RunTeleportationExample()"));