Como trabalhar com Q# projetos

Com o Azure Quantum Development Kit, você pode definir Q# projetos, que são estruturas de pasta com vários Q# arquivos que podem acessar as operações e funções uns dos outros. Os projetos são úteis para organizar logicamente seu código-fonte. Você também pode usar projetos como dependências externas ou bibliotecas personalizadas, que podem ser acessadas de fontes externas.

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.

Um projeto externo Q# é um projeto padrão Q# que reside em outro diretório ou em um repositório público do GitHub e usa export instruções para definir quais funções e operações podem ser acessadas por programas externos. Os programas definem o projeto externo como uma dependência em seu arquivo de manifesto e usam import instruções para acessar os itens (operações, funções, estruturas e namespaces) no projeto externo. Para obter mais informações, consulte Usando projetos como dependências externas.

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.
• Visual Studio Code com a extensão Azure Quantum Development Kit e Python instalada.
• Uma conta do GitHub, se você estiver planejando publicar seu projeto externo em um repositório público do GitHub.

Para executar programas Python, você também precisará:

• Um ambiente Python com Python e Pip instalados.
• O Azure Quantum qsharp e azure-quantum pacotes.

Definir um Q# projeto

Um Q# projeto é definido pela presença de um arquivo de manifesto, chamado 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 e projetos externos, 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.

import qsharp

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

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 fiapos . 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",
      "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"
          }
        ]
  }
  

• Você também pode usar o arquivo de manifesto para definir um projeto externo Q# como uma dependência e acessar remotamente operações e funções nesse projeto externo. Para obter mais informações, consulte Usando projetos como dependências externas.

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 deve estar no mesmo nível da pasta src . Quando você cria um Q# projeto no VS Code, um arquivo mínimo é criado automaticamente.

• Operações e funções de arquivos de origem no projeto podem ser acessados por outros arquivos no projeto usando import instruções

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

  ou referenciando-os individualmente com o namespace

  MyMathLib.Multiply(x,y);  
  

Apenas para Q# projetos

• Apenas um arquivo *.qs em um Q# projeto pode ter um ponto de entrada definido, definido por uma única Main() operação.
• O arquivo *.qs com a definição do ponto de entrada 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 para uma operação ou função selecionada ainda não tiver sido adicionado explicitamente, o VS Code adicionará automaticamente a instrução necessária import .

Etapas para criar um Q# projeto

Estas etapas aplicam-se a todos os Q# projetos.

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 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 pasta /src do Q# projeto:

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

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

Exemplo de projeto

Este programa de teletransporte quântico é um exemplo de um Q# projeto baseado na estrutura de pasta única 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
    • Main.qs
    • Operações de Teletransporte
      • TeleportLib.qs
      • PrepareState
        • PrepareStateLib.qs

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

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

Q# arquivos de origem

O arquivo principal, Main.qs, contém o ponto de entrada e faz referência ao TeleportOperations.TeleportLib namespace 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);
        }
    }

TeleportLib.qs define a Teleport() operação e chama a PrepareBellPair() operação de 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);
    }

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

    
    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.

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

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')

print (qsharp.eval("Main.Main()"))

Configurando Q# projetos como dependências externas

Um Q# projeto também pode ser configurado como uma dependência externa para outros projetos, agindo como uma biblioteca, onde as funções e operações no projeto externo Q# são disponibilizadas para vários Q# projetos. Uma dependência externa pode residir em um compartilhamento de unidade ou publicada em um repositório público do GitHub.

Para usar um Q# projeto como uma dependência externa, você precisa:

• Adicione o projeto externo como uma dependência no arquivo de manifesto do projeto chamador.
• Se o projeto externo for publicado no GitHub, adicione a propriedade "files" ao arquivo de manifesto do projeto externo.
• Adicione export instruções ao projeto externo.
• Adicione import instruções ao projeto de chamada.

Configurando os arquivos de manifesto

Projetos externos Q# podem residir em um compartilhamento de unidade local ou de rede ou publicados em um repositório público do GitHub.

O arquivo de manifesto do projeto chamando

Para adicionar uma dependência a um projeto externo em um compartilhamento de unidade, defina a dependência no arquivo de manifesto do projeto chamador.

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

onde "MyDependency" é uma cadeia de caracteres definida pelo usuário que identifica o namespace ao chamar uma operação. Por exemplo, se você criar uma dependência chamada "MyMathFunctions", chamaria uma função dessa dependência com MyMathFunctions.MyFunction().

Para adicionar uma dependência a um projeto publicado em um repositório público do GitHub

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

• Para dependências do GitHub, "ref" refere-se a uma refspec do GitHub. A Microsoft recomenda sempre usar um hash de confirmação, para que você possa confiar em uma versão específica de sua dependência.

O arquivo de manifesto do projeto externo

Se seu projeto externo Q# for publicado em um repositório público do GitHub, você deverá adicionar a propriedade files ao arquivo de manifesto do projeto externo, incluindo todos os arquivos usados no projeto.

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

A propriedade "files" é opcional para um projeto externo que está sendo importado via "path" (ou seja, uma importação local baseada em caminho de arquivo). Ele só é necessário para projetos publicados no GitHub.

Usando a instrução de exportação

Para tornar funções e operações em um projeto externo acessíveis para chamar projetos, use a export instrução. Você pode exportar qualquer um ou todos os chamáveis no arquivo. Não há suporte para sintaxe curinga, você deve especificar cada chamável para exportação.

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;             

Usando a instrução import

A partir do programa de chamada, você usa import instruções para disponibilizar itens de uma dependência externa. import As instruções usam o namespace definido para a dependência no arquivo de manifesto. Por exemplo, para esta dependência

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

você importa callables como

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

A import instrução também suporta sintaxe curinga e aliases

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

Exemplo de projeto externo

Neste exemplo, você usará o mesmo programa de teletransporte do exemplo anterior, mas separará o programa de chamada e os chamáveis em projetos diferentes.

1. Crie duas pastas na sua unidade local, por exemplo "Project_A" e "Project_B".

2. Crie um Q# projeto em cada pasta seguindo as etapas em Etapas para criar um Q# projeto.

3. No Project_A, o programa de chamada, copie o código a seguir para o arquivo de manifesto, editando o caminho conforme necessário para Project_B

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

4. No Project_A, copie o seguinte código para 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. No Project_B, copie o seguinte código para 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

   Observe que a PrepareBellPair operação não precisa ser exportada porque não é chamada diretamente do seu programa no Project_A. Por estar no âmbito local da Project_B, já está acessível pela Teleport operação.

6. Para executar o programa, abra /Project_A/Main.qs no VS Code e selecione Executar.

Projetos e namespaces implícitos

Em Q# projetos, se um namespace não for especificado em um programa *.qs, o compilador usará o nome do arquivo como namespace. A referência a um chamável de uma dependência externa usa a sintaxe <dependencyName>.<espaço para nomes>.<exigível>. No entanto, se o arquivo for chamado "Main.qs", o compilador assumirá o namespace e a sintaxe de chamada será <dependencyName>.<chamável>, como no exemplo anterior, import MyTeleportLib.Teleport.

Como não é incomum ter vários arquivos de projeto, você precisa levar em conta a sintaxe correta ao fazer referência a chamáveis. Por exemplo, em um projeto com a seguinte estrutura de arquivos

• /src
  • Main.qs
  • MathFunctions.qs

os apelos à dependência externa seriam

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

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

Para obter mais informações sobre o comportamento do namespace, consulte Namespaces de usuário.