Contribuindo para o Qiskit¶

O Qiskit é um projeto de código aberto comprometido em introduzir a computação quântica para pessoas com qualquer tipo de experiência e conhecimento em TI. Esta página descreve como você pode se juntar à comunidade Qiskit neste objetivo.

Onde as coisas estão¶

O código fonte para o Qiskit está localizado no site Qiskit GitHub organization, onde você pode encontrar os projetos individuais que compõem o Qiskit, incluindo

Primeiros Passos¶

Aprenda com os membros da comunidade Qiskit

Reportar erros e solicitar melhorias¶

Ao encontrar um problema, por favor, abra um chamado na ferramenta de ticket:

Elemento	Rastreador de Issues
qiskit-terra	https://github.com/Qiskit/qiskit-terra/issues
qiskit-aer	https://github.com/Qiskit/qiskit-aer/issues
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/issues
Docs ou Qiskit Meta-package	https://github.com/Qiskit/qiskit/issues

Se você tiver uma ideia para um novo recurso, por favor, abra um issue de Melhoria na ferramenta de issue do elemento apropriado. Abrir um issue inicia uma discussão com a equipe sobre a sua ideia, como ela se encaixa no projeto, como ela pode ser implementada, etc.

Código Contribuinte¶

Guia de Estilos¶

Para garantir um estilo de código consistente no projeto, nós usamos Pylint e pycodestyle para verificar se as contribuições de código estão de acordo e respeitam o guia de estilos do projeto. Para verificar se suas mudanças estão de acordo com o guia de estilo, execute: tox -elint

Acordo de Licença do Contribuidor¶

Antes de poder enviar qualquer código, todos os colaboradores devem assinar o acordo de licença do contribuidor (contributor license agreement - CLA). Ao assinar um CLA, você está atestando que é o autor da contribuição, e que está contribuindo livremente nos termos da licença Apache-2.0.

Quando você contribuir para o projeto Qiskit com uma nova solicitação de pull, um bot irá avaliar se você assinou o CLA. Se necessário, o bot irá se pronunciar sobre a solicitação de pull, incluindo um link para aceite o acordo. O documento individual CLA está disponível para revisão como PDF.

Nota

Se a sua contribuição faz parte do seu emprego ou a sua contribuição é propriedade do seu empregador, então é muito provável que você precise assinar também um CLA corporativo e o envie para nós em <qiskit@us.ibm.com>.

Pull Requests¶

Utilizamos GitHub pull requests para aceitar contribuições.

Embora não seja obrigatório, é recomendável abrir uma nova issue sobre o bug que você está consertando, ou o recurso em que está trabalhando antes de abrir um pull request. A issue nos proporciona um espaço para iniciar uma discussão com a comunidade sobre o seu trabalho, falar sobre a ideia e como podemos trabalhar juntos para implementá-la no código. Também permite a comunidade saber no que você está trabalhando, e se precisar de ajuda, é possível referencia-lá ao discutir com outros membros da comunidade e da equipe.

Se você já escreveu algum código mas precisa de ajuda para finalizá-lo, se deseja obter feedback inicial sobre ele antes de terminá-lo, ou se deseja compartilhá-lo e discutir antes de finalizar a implementação, você pode abrir um pull request em Work in Progress. Ao criar a solicitação de pull, preceda o título com a tag [WIP] (para Work In Progress). Isso indicará para os revisores que o código no PR não está em seu estado final e vai mudar. Significa também que não vamos executar o commit até que ele esteja concluído. Você ou um revisor podem remover a tag [WIP] quando o código estiver pronto para ser totalmente revisado para o merge.

Revisão de Código¶

A revisão de código é feita de forma aberta e está aberta a qualquer pessoa. Enquanto apenas os mantenedores têm acesso para mesclar commits, o feedback da comunidade sobre os pull requests é extremamente valioso. É também um bom mecanismo para aprender sobre o código base. Você pode visualizar uma lista de todos os pedidos de pull abertos aqui:

Elemento	Pull Requests
qiskit-terra	https://github.com/Qiskit/qiskit-terra/pulls
qiskit-aer	https://github.com/Qiskit/qiskit-aer/pulls
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/pulls
Docs ou Qiskit Meta-package	https://github.com/Qiskit/qiskit/pulls

Mensagens de Commit¶

O conteúdo da mensagem de commit que descreve uma mudança é tão importante quanto a própria mudança. A mensagem de commit fornece o contexto não só para revisão de código mas também para o histórico de alterações no log do git. Uma mensagem detalhada do commit facilitará a revisão do seu código, e também fornecerá contexto para a mudança quando alguém olhar para ela no futuro. Ao escrever uma mensagem de commit, lembre-se destes detalhes importantes:

Não suponha que o revisor entenda qual era o problema original.

Ao ler um problema, depois de uma série de troca de comentários, muitas vezes é possível perceber qual a raiz do problema. A mensagem de commit deve ter uma declaração clara sobre qual é o problema original. O bug é apenas interessante para antecedentes históricos sobre como o problema foi identificado. Deve ser possível analisar uma atualização proposta para correção a partir da mensagem de commit, sem a necessidade de ler o ticket de bug.

Não suponha que o código seja auto-evidente/auto-documentado.

O que é óbvio para uma pessoa pode não ser para outra. Sempre documente qual foi o problema original e como ele está sendo corrigido. Para qualquer alteração, evite erros de digitação óbvios ou commits contendo apenas espaços em branco.

Descreva por que uma mudança está sendo feita.

Um erro comum é apenas documentar como o código foi escrito, sem descrever o por que o desenvolvedor escolheu fazer isso dessa maneira. Você deve descrever a estrutura geral do código, particularmente para grandes mudanças, porém, mais importante, certifique-se de descrever a intenção/motivação por trás das mudanças.

Leia a mensagem de commit para ver se ele mostra a estrutura de código melhorada.

Muitas vezes, ao descrever uma grande mensagem de commit, torna-se óbvio que o commit deveria ter sido dividido em duas ou mais partes. Não tenha medo de voltar e reestruturar a mudança para dividi-la em pull requests separados.

Garanta informações suficientes para decidir se deve revisar.

Quando o GitHub envia alertas de e-mail para novas submissões de pull request há informações mínimas incluídas - geralmente apenas a mensagem de commit e a lista de alterações de arquivos. Por causa do alto volume de patches, uma mensagem de commit deve conter informações suficientes para potenciais revisores conseguirem encontrar a atualização que eles precisam revisar.

A primeira linha do commit é a mais importante.

Nos commits do Git, a primeira linha da mensagem de submissão tem um significado especial. É usada como título padrão do pull request, título do assunto da notificação por e-mail, mensagem de anotação do Git, comentários de revisores gitk, merge de mensagens de commit, e muitos outros lugares. Além de resumir a alteração em si, deve especificar a parte do código que é afetada.

Além disso, a primeira linha da mensagem de commit se torna uma entrada no log de mudanças, caso o pull request seja marcado para ser incluído. É muito importante que as linhas sejam claras e sucintas.

Descreva quaisquer limitações do código atual.

Se o código a ser alterado ainda tiver oportunidades para melhorias futuras, ou quaisquer limitações conhecidas, mencione-as na mensagem de commit. Isto demonstra ao revisor que um escopo mais amplo foi considerado, e que alterações que foram escolhidas levam em conta objetivos conflitantes de curto e longo prazo.

Incluir referências para issues.

Se as correções do commit estiverem relacionadas a uma issue, certifique-se de anotá-la na mensagem de commit. Use a sintaxe:

Fixes #1234

se ele corrigir o problema (o GitHub irá fechar o problema quando o PR mesclar).

A regra principal a seguir é:

A mensagem de commit deve conter todas as informações necessárias para entender completamente e revisar o patch para correção. Menos não é mais.

Documentando Seu Código¶

Se você fizer uma alteração para um elemento, certifique-se de atualizar as docstrings associadas e partes da documentação em docs/apidocs no repositório correspondente. Para build local da documentação específica dos elementos, execute tox -edocs para compilar e fazer o build da documentação localmente e salve o destino para docs/_build/html. Adicionalmente, o trabalho Docs CI no azure pipelines será executado e hospedará um arquivo zip da saída que você poderá baixar e ver localmente.

Se você encontrar um problema com a documentação que é mantida no repositório Qiskit/qiskit, você pode abrir uma issue de documentação se você encontrar bugs na documentação, se houver um novo recurso que precisa ser documentado, ou acredita que adições podem ser feitas à documentação existente.

Boas Primeiras Contribuições¶

Se você quer contribuir com o Qiskit, mas não sabe por onde começar, a label good first issue em issues para um projeto destaca itens adequados para pessoas novas no projeto. Todos estes são issues que foram revisados e marcados pelos contribuidores como algo que um novo colaborador pode trabalhar. Em outras palavras, familiaridade com Qiskit não é uma exigência para desenvolver uma correção para um problema.

Política de Descontinuação¶

Os usuários do Qiskit precisam saber se um recurso ou uma API com a qual eles dependem continuarão a ser suportados pelo software amanhã. Saber em que condições o projeto pode remover (ou alterar versões anteriores incompatíveis) uma funcionalidade ou API é importante para o usuário. Para gerenciar isso, a seguinte política descreve como a API e a depreciação/remoção de funcionalidades são tratadas pelo Qiskit:

1. Features, APIs, or configuration options are marked deprecated in the code. Appropriate DeprecationWarning class warnings will be sent to the user. The deprecated code will be frozen and receive only minimal maintenance (just so that it continues to work as-is).

2. A migration path will be documented for current users of the feature. This will be outlined in the both the release notes adding the deprecation, and the release notes removing the feature at the completion of the deprecation cycle. If feasible, the warning message will also include the migration path. A migration path might be «stop using that feature», but in such cases it is necessary to first judge how widely used and/or important the feature is to users, in order to determine a reasonable obsolescence date.

2a. A rota de migração deve ter existido em pelo menos uma release anterior antes que a nova funcionalidade possa ser descontinuada. Por exemplo, se você tiver uma função foo()``que será substituída por ``bar(), você não pode depreciar a função foo() na mesma versão que introduz bar(). A função bar()``precisa estar disponível na versão anterior à descontinuação de ``foo(). Isso é necessário para permitir que os consumidores downstream do Qiskit que mantêm suas próprias bibliotecas escrevam código que funcione com > 1 versão por vez, o que é importante para todo o ecossistema. Se você gostaria de indicar que uma descontinuação virá em uma versão futura, você pode usar o aviso PendingDeprecationWarning para sinalizar isso. Mas, o período de depreciação só inicia após um DeprecationWarning ser emitido.

3. An obsolescence date for the feature will be set. The feature must remain intact and working (although with the proper warning being emitted) in all releases pushed until after that obsolescence date. At the very minimum, the feature (or API, or configuration option) should be marked as deprecated (and continue to be supported) for at least three months of linear time from the release date of the first release to include the deprecation warning. For example, if a feature were deprecated in the 0.9.0 release of Terra, which was released on August 22, 2019, then that feature should still appear in all releases until at least November 22, 2019.

Note que este atraso é um mínimo. Para features significativas, é recomendado que o recurso depreciado esteja presente por pelo menos o dobro desse tempo. Além disso, de acordo com a política da ramificação estável, as remoções de depreciação só podem ocorrer durante releases de versão menor; elas não são apropriadas para backporting.

3a. Uma funcionalidade descontinuada não pode ser removida, a menos que esteja depreciada em mais de uma release, mesmo que o período de depreciação mínimo tenha decorrido. Por exemplo, se uma funcionalidade é descontinuada na 0.20.0, que foi lançada em 20 de janeiro de 2022, e a próxima versão menor 0.21.0 é lançada em 16 de junho de 2022, a funcionalidade depreciada não pode ser removida até a versão 0.22.0, ainda que a 0.21.0 tenha sido lançada mais de três meses após a versão 0.20.0. Isso é importante porque o propósito dos avisos de descontinuação são de informar os usuários que uma possível mudança incompatível na API está vindo e dar a eles uma chance de adaptar seus códigos. No entanto, muitos usuários pulam versões (especialmente se houver uma grande quantidade de mudanças em cada release) e não atualizam para cada versão, então podem perder o aviso se ele estiver presente apenas para uma única versão menor.

Avisos de Descontinuação¶

A maneira adequada de gerar um aviso de descontinuação é usar a função warn do warnings module na biblioteca padrão do Python. A classe de advertência deve ser um DeprecationWarning. Um exemplo seria:

import warnings

def foo(input):
    warnings.warn('The qiskit.foo() function is deprecated as of 0.9.0, and '
                  'will be removed no earlier than 3 months after that '
                  'release date. You should use the qiskit.bar() function '
                  'instead.', DeprecationWarning, stacklevel=2)

Uma coisa a observar aqui é a chamada stack_level kwarg on the warn(). Esse argumento é usado para especificar qual nível na pilha de chamadas será usado como a linha que inicia o aviso. Normalmente, stack_level deve ser definido como 2, pois isto irá mostrar a linha que chama o contexto em que o aviso foi gerado. No exemplo acima, seria o autor da chamada de foo(). Se você não definir isso, o aviso mostrará que ele foi causado pela função na linha foo(), o que não é útil para usuários que tentam determinar a origem de uma chamada obsoleta. No entanto, este valor pode ser ajustado, dependendo da pilha de chamadas e de onde o warn() é chamado. Por exemplo, se o aviso é sempre criado por um método privado que tem apenas um chamador, pode ser apropriado usar stack_level=3.

Política de Branch Estável¶

O branch estável se destina a ser uma fonte segura de correções para bugs de alto impacto e problemas de segurança que foram corrigidos no master desde um lançamento. Ao revisar uma PR de branch estável, temos que balancear o risco de qualquer correção com o valor que ela proporcionará aos usuários da branch estável. Apenas uma classe de alterações limitada é apropriada para a inclusão na branch estável. Uma atualização grande e arriscada para um problema importante pode fazer sentido, assim como uma correção trivial para um caso de de erros obscuros. Vários fatores devem ser ponderados ao considerar uma mudança:

O risco de regressão: mesmo as menores alterações correm o risco de quebrar algo, e queremos realmente evitar regressões na branch estável.
O benefício da visibilidade do usuário: estamos corrigindo algo que os usuários podem notar, nesse caso, o quão importante é essa modificação?
O quão auto-contida a correção é: se ela corrige um problema significativo, mas também refatora muitos códigos, provavelmente vale a pena pensar sobre como um conserto menos arriscado poderia ser escrito.
Se a correção já está na master: uma mudança deve ser uma backport de uma mudança já combinada com a master, a não ser que a mudança simplesmente não faça sentido na master.

Processo de Backport:¶

Ao realizar uma backporting de um patch de master para estável, queremos manter uma referência às mudanças na master. Ao criar a branch para a versão PR, use:

$ git cherry-pick -x $master_commit_id

No entanto, isto só funciona para pequenos patches da master. Se você precisar enviar um subconjunto de um commit maior (de um PR, por exemplo) da master, faça isso manualmente. Nestes casos, adicione:

Backported from: #master pr number

para que possamos rastrear a fonte do subconjunto da mudança, mesmo que uma rigorosa escolha a dedo não faça sentido.

Se a atualização que você está propondo não faz cherry-pick corretamente, você pode ajudar resolvendo os conflitos por conta própria e propondo a atualização resultante. Por favor, mantenha linhas de conflito na mensagem do commit para ajudar a rever a atualização estável.

Rótulos de backport¶

Bugs ou PRs marcados com estável potencial de backport são bugs que se aplicam ao lançamento estável também e podem ser adequados para backporting uma vez que uma correção chegue na master. Depois que o backport for proposto, a tag deverá ser removida.

Inclua [Stable] no título do PR contra a branch estável, como sinal de que a definição da branch alvo como estável não foi um erro. Além disso, referêncie o número do PR na master que você está portando.

Contribuindo para a Documentação¶

A documentação do Qiskit é moldada pela filosofia do docs as code desenhada principalmente a partir de comentários de código Qiskit na style of API documentation.

A documentação é construída a partir da master branch Qiskit/qiskit/docs usando Sphinx. A maioria da documentação, em API Reference, é desenhada a partir de comentários de código nos repositórios listados em Onde as coisas estão.

Estrutura de Documentação¶

A forma como a documentação é estruturada no Qiskit é para disponibilizar a maior parte da documentação atual possível para as docstrings. Isto facilita a introdução de adições e correções durante o desenvolvimento, uma vez que a maior parte da documentação está próxima ao código sendo alterado. Existem três níveis na estrutura normal de documentação no Terra:

Os arquivos .rst na pasta docs/apidocs

Estes arquivos são utilizados para dizer ao Sphinx quais módulos incluir na documentação renderizada. Isto contém dois elementos de informação: uma referência interna ou referência cruzada para o módulo, que pode ser usado para links internos dentro da documentação, e uma diretiva automodule usada para analisar as docstrings do módulo de um path de importação especificado. Por exemplo, o arquivo dagcircuit.rst contém:

.. _qiskit-dagcircuit:


.. automodule:: qiskit.dagcircuit
   :no-members:
   :no-inherited-members:
   :no-special-members:

O único arquivo .rst fora deste é qiskit.rst, que contém a tabela de conteúdo. Se você está adicionando um novo arquivo .srt para a documentação de um novo módulo, não deixe de adicioná-lo ao toctree desse arquivo.

A docstring a nível de módulo

Esta docstring está no nível de módulo para o módulo especificado na diretiva automodule no arquivo rst. Se o módulo especificado é um diretório/namespace, a docstring deve ser especificada no arquivo __init__.py para esse diretório. Esta docstring de nível de módulo contém mais detalhes sobre o módulo sendo documentado. A estrutura normal para esta docstring é definir todas as classes e funções da API pública que estão contidas nesse módulo. Isso é normalmente feito usando a autosummary directive (ou autodoc directiva diretamente se o módulo for simples, tal como no caso de qiskit.execute). A diretiva de autosummary é usada para auto-documentar uma lista de diferentes elementos Python (classes, funções, etc.) diretamente sem precisar chamar manualmente as diretivas autodoc para cada uma delas. A docstring do módulo é o local para fornecer uma visão de alto nível de qual funcionalidade o módulo fornece. Isso normalmente é feito agrupando os diferentes componentes da API pública em múltiplas subseções.

Por exemplo, como no módulo-exemplo anterior, o conteúdo do módulo docstring para qiskit/dagcircuit/__init__.py seria:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================
.. currentmodule:: qiskit.dagcircuit
DAG Circuits
============
.. autosummary::
   :toctree: ../stubs/
   DAGCircuit
   DAGNode
Exceptions
==========
.. autosummary::
   :toctree: ../stubs/
   DAGCircuitError
"""

Nota

Este é apenas um exemplo e o verdadeiro módulo docstring para o módulo dagcircuit pode divergir disto.

O docstring real para os elementos listados no módulo docstring

Você deve se esforçar para documentar minuciosamente todas as interfaces públicas expostas usando exemplos quando necessário. Para docstrings, o Google Python Style Docstrings é utilizado. Isto é analisado usando a extensão napoleon sphinx. A documentação napoleon contém um bom exemplo de como os docstrings devem ser formatados.

Nota

Você pode usar qualquer diretiva Sphinx ou a formatação rst em uma docstring desde que faça sentido. Por exemplo, uma extensão comum utilizada é a directiva jupyter-execute. que é usada para executar um bloco de código no Jupyter e exibir o código e a saída. Isso é particularmente útil para visualizações.

Integração da Documentação¶

A documentação hospedada em https://qiskit.org/documentation/ abrange todo o projeto Qiskit; Terra é apenas um componente. Como tal, as compilações de documentação para a versão hospedada são criadas pelo repositório Qiskit meta-package https://github.com/Qiskit/qiskit. Quando submissões (commits) são mesclados no repositório, a saída das compilações Sphinx são enviadas para o site qiskit.org. Essas compilações Sphinx estão configuradas para puxar a documentação da versão dos elementos Qiskit instalados pelo meta-package nesse ponto. Por exemplo, se a versão do meta-package é atualmente 0.13.0, então isso irá copiar a documentação da versão 0.10.0 do Terra. Quando os requisitos do meta-package são preenchidos, então ele vai começar a puxar a documentação a partir da nova versão. Isto significa que as correções para documentação de API incorretas terão de ser incluídas em uma nova versão. Correções de documentação são backports válidas para um lançamento de patch estável por uma política de ramificação (branch) estável (veja esta seção abaixo).

Durante o processo de construção, o conteúdo de docs/apidocs/ de cada elemento são recursivamente copiados em uma cópia compartilhada de doc/apidocs/ no repositório meta-package, juntamente com todos os outros elementos. Isso significa que o que estiver na raiz de docs/apidocs em cada elemento em um lançamento terminará na raiz de https://qiskit.org/documentation/apidoc/.

Traduzindo a Documentação¶

A documentação do Qiskit é traduzida (localizada) usando Crowdin, uma plataforma de tradução de software e web que permite às organizações coordenar projetos de tradução e colaborar com as comunidades para traduzir materiais. O Crowdin permite que nossa comunidade de tradutores amplie seu impacto reutilizando automaticamente o trabalho investido traduzindo uma frase para traduzir outras frases similares. Também permite flexibilizar as traduções diante de mudanças nos arquivos do projeto, como mover frases de uma parte para outra ou até mesmo entre arquivos.

Os pedidos de localização do Qiskit são tratados no repositório Qiskit Translations. Para contribuir com a localização do Qiskit, por favor, siga estas etapas:

Inclua seu nome (ou ID) no arquivo LOCALIZATION_CONTRIBUTORS.
Crie um pull request (PR) para fazer merge da sua alteração. Certifique-se de seguir o modelo para abrir um Pull Request.
Nota
- Cada contribuinte deve criar o seu próprio PR e assinar o CLA.
- Por favor, mencione o idioma para o qual você gostaria de contribuir no sumário da PR.
- Se você tem uma issue aberta para uma solicitação de idioma, adicione o link da issue ao PR.
Você será solicitado a assinar o Contrato de Licença dos Colaboradores de Qiskit (CLA); por favor, faça.
Um mínimo de três contribuidores por idioma são necessários para que quaisquer novos idiomas sejam adicionados e para receber o apoio oficial dos administradores do projeto de localização.
Entre o grupo de contribuidores, um líder de tradução deve ser identificado para servir como uma ligação com os administradores do projeto de localização. O líder deve contatar: Yuri Kobayashi (yurik@jp.ibm.com) por e-mail.
No projeto Qiskit-Docs <https://crowdin.com/project/qiskit-docs> __ Crowdin, escolha o idioma para qual você deseja contribuir.

Nota

Como mencionado no post do blog, Qiskit no meu idioma é Qiskit, queremos ter certeza de que os idiomas traduzidos têm suporte comunitário suficiente para construir uma equipe de tradução com tradutores, revisores e líderes de tradução. Se você quiser ser um líder de tradução ou estiver disposto a se juntar a uma nova equipe de projeto de tradução, você pode abrir uma Issue GitHub para começar uma discussão com a equipe do Qiskit e recrutar membros do projeto de tradução.
Clique no botão Join e cole a URL do seu PR na caixa de diálogo em que você é perguntado por que você quer se juntar ao projeto Crowdin.

Os administradores do projeto Crowdin revisarão sua solicitação e concederão acesso o mais rápido possível.

Build a partir do código-fonte¶

Você pode fazer o build de uma cópia local da documentação a partir do seu clone local do repositório Qiskit/qiskit da seguinte forma:

Clone o repositório Qiskit.

git clone https://github.com/Qiskit/qiskit.git

Clonar o repositório cria uma pasta local chamada qiskit.
```
cd qiskit
```
Faça o build da documentação navegando até seu clone local Qiskit/qiskit e executando o seguinte comando em uma janela do terminal.
```
tox -edocs
```
Se você ainda não tiver o comando tox instalado, instale-o executando:
```
pip install tox
```

À medida que você faz alterações nos seus arquivos RST locais você pode atualizar seus arquivos HTML navegando até /doc/ e executando o seguinte comando em uma janela do terminal:

tox -edocs

Isto irá fazer o build de uma versão HTML estilizada do seu repositório de documentação local no subdiretório /docs/_build/html/.

Instalando da Fonte¶

A instalação dos elementos do código fonte permite que você acesse a versão mais recente do Qiskit em vez de usar a versão do repositório Python Package Index (PyPI). Isso lhe dará a capacidade de inspecionar e estender a versão mais recente do código Qiskit de forma mais eficiente.

Ao instalar os elementos e componentes da fonte, por padrão sua versão development (que corresponde a master git branch) será usada, ao contrário da versão stable (que contém a mesma base de código que os pacotes pip publicados). Uma vez que as versões development de um elemento ou componente geralmente incluem novas características e mudanças, geralmente eles exigem usar a versão development ao resto dos itens também.

Nota

Ambos os pacotes Terra e Aer requerem um compilador para construir a partir da fonte antes da instalação. Ignis, Aqua e o provedor IBM Quantum não exigem um compilador.

Instalar elementos da fonte requer a seguinte ordem de instalação para evitar a instalação de versões de elementos que podem ser menores do que as desejadas se a versão pip estiver atrás das versões fonte:

qiskit-terra
qiskit-aer
qiskit-ignis
qiskit-ibmq-provider (se você quiser conectar aos dispositivos IBM Quantum ou o simulador online)

Para trabalhar com vários componentes e elementos simultaneamente, use as seguintes etapas para cada elemento.

Nota

Devido ao uso de pacotes de namespace em Python, é preciso ter cuidado com a forma como você instala os pacotes. Se você está planejando instalar algum elemento desde a fonte, não use o meta-package qiskit. Além disso, siga este guia e use um ambiente virtual separado para desenvolvimento. Se você optar por misturar uma instalação existente com o seu desenvolvimento, consulte https://github.com/pypa/sample-namespace-packages/blob/master/table.md para o conjunto de combinações de métodos de instalação que funcionam juntos.

Configurar o Ambiente de Desenvolvimento Virtual¶

Os ambientes virtuais são usados para desenvolvimento com o Qiskit para isolar o ambiente de desenvolvimento dos pacotes de todo o sistema. Desta forma, evitamos nos tornar inadvertidamente dependentes de uma configuração de sistema específica. Para desenvolvedores, isso também facilita a manutenção de vários ambientes (por exemplo, um por versão do Python suportada, para versões mais antigas do Qiskit, etc.).

Python venv

Todas as versões do Python suportadas pelo Qiskit incluem o módulo de ambiente virtual integrado venv.

Inicie criando um novo ambiente virtual com o venv. O ambiente resultante usará a mesma versão do Python que o criou e não herdará pacotes instalados em todo o sistema por padrão. A pasta especificada será criada e é usada para manter a instalação do ambiente. Ela pode ser colocada em qualquer lugar. Para obter mais detalhes, consulte a documentação oficial do Python, Criação de ambientes virtuais.

python3 -m venv ~/.venvs/qiskit-dev

Ative o ambiente invocando o script de ativação apropriado para o seu sistema, que pode ser encontrado na pasta do ambiente. Por exemplo, para bash/zsh:

source ~/.venvs/qiskit-dev/bin/activate

Atualize o pip dentro do ambiente para garantir que as dependências do Qiskit instaladas nas seções subsequentes possam ser localizadas para o seu sistema.

pip install -U pip

Conda

Para usuários do Conda, um novo ambiente pode ser criado da seguinte forma.

conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv

Instalando Terra a partir do Código Fonte¶

Installing from source requires that you have the Rust compiler on your system. To install the Rust compiler the recommended path is to use rustup, which is a cross-platform Rust installer. To use rustup you can go to:

https://rustup.rs/

which will provide instructions for how to install rust on your platform. Besides rustup there are other installation methods available too.

Once the Rust compiler is installed, you are ready to install Qiskit Terra.

Clone o repositório Terra.

git clone https://github.com/Qiskit/qiskit-terra.git

Clonar o repositório criará uma pasta local chamada qiskit-terra.
```
cd qiskit-terra
```
Se você quiser executar testes ou análise de código, instale os requisitos de desenvolvedor.
```
pip install -r requirements-dev.txt
```
Instale o qiskit-terra.
```
pip install .
```

Se você quiser instalá-lo em modo editável, o que significa que as alterações de código no projeto não requerem que uma reinstalação seja aplicada, você pode fazer isso com:

pip install -e .

Installing in editable mode will build the compiled extensions in debug mode without optimizations. This will affect the runtime performance of the compiled code. If you’d like to use editable mode and build the compiled code in release with optimizations enabled you can run:

python setup.py build_rust --release --inplace

after you run pip and that will rebuild the binary in release mode.

If you are working on Rust code in Qiskit you will need to rebuild the extension code every time you make a local change. pip install -e . will only build the Rust extension when it’s called, so any local changes you make to the Rust code after running pip will not be reflected in the installed package unless you rebuild the extension. You can leverage the above build_rust command to do this (with or without --release based on whether you want to build in debug mode or release mode).

You can then run the code examples after installing Terra. You can run an example script with the following command.

python examples/python/using_qiskit_terra_level_0.py

Instalando Aer do Código Fonte¶

Clone o repositório Aer.

git clone https://github.com/Qiskit/qiskit-aer

Instalar requisitos de build.
```
pip install cmake scikit-build
```

Depois disso, os passos para instalar Aer dependem de qual sistema operacional você está usando. Uma vez que Aer é um programa compilado em C++ com uma interface em Python, existem dependências não-Python para construir o binário Aer, que não podem ser instaladas universalmente, dependendo do sistema operacional.

Linux

Instalar requisitos do compilador.

Fazer o build do Aer requer cabeçalhos de desenvolvimento e compilador C++.

Se você estiver usando o Fedora ou uma distribuição Linux equivalente, instale usando:
```
dnf install @development-tools
```
Para o Ubuntu/Debian instale usando:
```
apt-get install build-essential
```
Instale cabeçalhos de desenvolvimento OpenBLAS.

Se você estiver usando o Fedora ou uma distribuição Linux equivalente, instale usando:
```
dnf install openblas-devel
```
Para o Ubuntu/Debian instale usando:
```
apt-get install libopenblas-dev
```

macOS

Instalar dependências.

Para usar o compilador Clang no macOS, você precisa instalar uma biblioteca extra para ter suporte a OpenMP. Você pode usar o brew para instalar esta e outras dependências.
```
brew install libomp
```
Em seguida, instale uma implementação do BLAS; OpenBLAS é a escolha padrão.
```
brew install openblas
```
Em seguida, instalar Xcode Command Line Tools.
```
xcode-select --install
```

Windows

No Windows você precisa usar o Anaconda3 ou o Miniconda3 para instalar todas as dependências.

Instalar requisitos do compilador.

conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime

Instalar as dependências dos binários e do build.

conda install --update-deps -c conda-forge -y openblas cmake

Faça a criação dos pacotes e instale o qiskit-aer diretamente

Se você tiver o pip <19.0.0 instalado e seu ambiente não requer um build personalizado, execute:
```
cd qiskit-aer
pip install .
```
Isto irá fazer o build dos binários e instalar o Aer.

Alternativamente, se você tiver uma versão do pip mais recente instalado ou tiver um requisito personalizado, você pode fazer a criação dos pacotes do Python wheel manualmente.
```
cd qiskit-aer
python ./setup.py bdist_wheel
```
Se você precisar definir uma opção personalizada durante a criação dos pacotes da wheel, consulte Opções customizadas durante os builds da wheel.

Depois de feito a criação dos pacotes do Python wheel, ela será armazenada no diretório dist/ no repositório Aer. A versão exata dependerá
```
cd dist
pip install qiskit_aer-*.whl
```
O nome exato do arquivo da wheel de saída depende da versão atual do Aer em desenvolvimento.

Opções customizadas durante os builds da wheel¶

O sistema do Aer build usa scikit-build para executar a compilação ao construí-la com a interface Python. Ele atua como uma interface de setuptools para chamar CMake e compilar os binários no seu sistema local.

Devido à complexidade de compilar os binários, você pode precisar passar opções para uma determinada parte do processo de build. A maneira de passar variáveis é:

python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]]

onde os elementos dentro de colchetes [] são opcionais, e skbuild_opts, cmake_opts, build_tool_opts serão substituídos por flags de sua escolha. Uma lista das opções CMake está disponível aqui: https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. Por exemplo, você pode executar algo como:

python setup.py bdist_wheel -- -- -j8

Isso está passando a flag -j8 para o sistema de empacotamento subjacente (que neste caso é Automake), dizendo que você deseja fazer o empacotamento em paralelo usando 8 processos.

Por exemplo, um caso de uso comum para essas flags no Linux é definir uma versão específica do compilador C++ para usar (normalmente se o padrão for muito antigo):

python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7

que dirá ao CMake para usar o comando g++-7 em vez do g++ padrão ao compilar o Aer.

Outro caso de uso comum para isso, dependendo do seu ambiente, é que você pode precisar especificar o nome da sua plataforma e desativar a linkagem estática.

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \
-- -DSTATIC_LINKING=False -- -j8

Aqui --plat-name é uma flag de ferramentas de configuração, para especificar o nome da plataforma a utilizar nos metadados do pacote; -DSTATIC_LINKING é uma flag para usar o CMake e desabilitar links estáticos, e -j8 é uma flag para fazer o Automake usar 8 processos para a compilação.

Uma lista de opções comuns dependendo da plataforma é:

Plataforma	Ferramenta	Opção	Caso de Uso
Todos	Automake	`-j`	Seguido por um número, define o número de processos a serem usados para compilação.
Linux	CMake	`-DCMAKE_CXX_COMPILER`	Usado para definir um compilador C++ específico; isso é geralmente necessário se seu g++ padrão for muito antigo.
OSX	Ferramentas de configuração	`--plat-name`	Usado para especificar o nome da plataforma no pacote de saída Python.
OSX	CMake	`-DSTATIC_LINKING`	Usado para especificar se deve ou não ser utilizada a linkagem estática.

Nota

Algumas dessas opções não são específicas da plataforma. Essas plataformas em particular são listadas porque são comumente usadas no ambiente. Consulte a documentação da ferramenta para obter mais informações.

Instalando Ignis a partir do Código Fonte¶

Clone o repositório Ignis.

git clone https://github.com/Qiskit/qiskit-ignis.git

O clone do repositório cria uma pasta local chamada qiskit-ignis.
```
cd qiskit-ignis
```
Se você quiser executar testes ou análise de código, instale os requisitos de desenvolvedor. Isso não é necessário para instalar ou usar o pacote qiskit-aqua quando efetuado a instalação a partir do código fonte.
```
pip install -r requirements-dev.txt
```
Instale o Ignis.
```
pip install .
```

Se você quiser, pode instalá-lo em modo editável, o que significa que as alterações no código do projeto não requerem uma reinstalação para serem aplicadas:

pip install -e .

Instalando o IBM Quantum Provider a partir do Código Fonte¶

Clone o repositório qiskit-ibmq-provider.

git clone https://github.com/Qiskit/qiskit-ibmq-provider.git

O clone do repositório cria um diretório local chamado qiskit-ibmq-provider.
```
cd qiskit-ibmq-provider
```
Se você quiser executar testes ou análise de código, instale os requisitos de desenvolvedor. Isso não é necessário para instalar ou usar o pacote qiskit-ibmq-provider quando efetuado a instalação a partir do código fonte.
```
pip install -r requirements-dev.txt
```
Instalar o qiskit-ibmq-provider.
```
pip install .
```

Se você quiser, pode instalá-lo em modo editável, o que significa que as alterações no código do projeto não requerem uma reinstalação para serem aplicadas:

pip install -e .

Versionamento do Qiskit¶

O projeto Qiskit é composto de vários elementos, onde cada um executa uma funcionalidade diferente. Cada elemento é independentemente útil e pode ser usado por conta própria, mas por conveniência nós fornecemos este repositório e um meta-pacote, de modo a proporcionar um único ponto de entrada para a instalação de todos os elementos, em uma só vez. Isto simplifica o processo de instalação e fornece uma interface unificada aos usuários finais. No entanto, como cada elemento no Qiskit tem seus próprios releases e versões, alguns cuidados são necessários ao lidar com as versões dentre os diferentes repositórios. Este documento descreve as diretrizes para lidar com versões e releases para ambos os elementos Qiskit e meta-pacote.

Para o restante deste guia, o padrão de nomenclatura do Controle de Versionamento Semântico a ser utilizado será: Major.Minor.Patch` para se referir aos diferentes componentes de um número de versão. Por exemplo, se o número da versão era 0.7.1, então a versão principal é 0, a versão secundária é 7 e a versão da correção é 1.

Versão do pacote-Meta¶

A versão do meta-pacote no Qiskit tem um valor independente, que é determinado pelos releases de cada um dos elementos que estão sendo rastreados. A cada vez que lançamos uma versão para um componente rastreado (ou adicionamos um elemento), os requisitos e a versão do meta-pacote precisam ser atualizados, e uma nova versão publicada. Este tempo deve ser coordenado juntamente com o release dos elementos para garantir que o release do meta-pacote os acompanhem.

Adicionando Novos Elementos Rastreados¶

Quando um novo elemento do Qiskit está sendo adicionado aos requisitos de um meta-pacote, nós precisamos incrementar a versão Secundária do meta-pacote.

Neste exemplo, o meta-pacote está rastreando os dois elementos `` qiskit-aer`` e `` qiskit-terra``, na versão `` 0.7.4``. Então em seguida lançamos um novo elemento, o `` qiskit-ignis``, que também pretendemos incluir neste meta-pacote. Assim, quando adicionamos este novo elemento ao meta-pacote, incrementamos a versão para `` 0.8.0``.

Incremento de Versão¶

Quando qualquer elemento Qiskit, que já está sendo rastreado pelo meta-pacote, lança uma versão de patch para corrigir bugs em uma versão, nós também precisamos eliminar o requisito no setup.py e, em seguida, incrementar a versão de patch do meta-pacote.

Por exemplo, um meta-pacote está rastreando três elementos: `` qiskit-terra == 0.8.1``, `` qiskit-aer == 0.2.1``, e `` qiskit-ignis == 0.1.4 , na versão atual `` 0.9.6,. Quando o qiskit-terra lançar uma nova versão de patch para corrigir o bug `` 0.8.2``, o meta-pacote também precisará incrementar a sua versão de patch e de release, subindo para `` 0.9.7``.

Além disso, ocasionalmente pode ocorrer um enpacotamento ou outros bugs dentro do próprio meta-pacote que precisam ser corrigidos por meio de novas releases. Quando encontrados, nós precisamos aumentar a versão do patch para diferenciá-lo da versão problemática. ** Não ** exclua as versões com problemas ou antigas do pypi sob nenhuma circunstância; ao invés disso, apenas aumente a versão do patch e carregue uma nova release.

Incremento da Versão Secundária¶

Além disso, ao adicionar um novo elemento ao meta-pacote, a sua versão secundária também deve ser incrementada toda vez que uma versão secundária aumenta em um elemento rastreado.

Neste exemplo o meta-pacote está rastreando dois elementos: `` qiskit-terra == 0.7.0`` e `` qiskit-aer == 0.1.1``, onde a versão atual é `` 0.7.5``. Quando o elemento `` qiskit-aer`` for lançado na versão `` 0.2.0``, então nós precisamos aumentar a versão do meta-pacote para `` 0.8.0``, de forma a corresponder com a nova release.

Incremento da Versão Principal¶

A versão principal é diferente do versionamento de outros componentes. Ao contrário da versão dos outros componentes, que são atualizados em sintonia com cada elemento rastreado, a versão principal só é incrementada quando todas as versões rastreadas são alteradas (ao menos antes de `` 1.0.0``). Até aqui, todos os elementos ainda têm um componente de número da versão principal em 0, até que cada elemento rastreado no meta-repositório seja marcado como estável alterando a versão principal para > = 1, então a versão do meta-pacote não deve incrementar o valor da versão principal.

O comportamento do rastreamento de componente no número de versão principal após todos os elementos atingirem > = 1.0.0 ainda não foi decidido.

Extras Opcionais¶

Além dos elementos rastreados, existem pacotes adicionais criados sobre o Qiskit que são desenvolvidos em conjunto com este, tais como os repositórios de aplicativo - por exemplo, o qiskit-optimization. Por conveniência, esses pacotes são rastreados pelo meta-pacote Qiskit como extras opcionais, que podem ser instalados juntamente com o Qiskit. Os lançamentos mais recentes desses projetos opcionais não geram uma release nova de meta-pacote, uma vez que são independentes e não afetam a sua versão. Se houver um problema de compatibilidade entre o Qiskit e essas dependências opcionais mais recentes e a versão mínima precisar ser ajustada em uma release separada, isto somente será feito em uma release de versão de patch, já que é um pacote de correção de bug.

Rastreamento de Requisito de Elemento do Qiskit¶

Embora não esteja estritamente relacionado ao versionamento do meta-pacote e do Qiskit, a maneira como rastreamos as versões do elemento na lista de requisitos do meta-pacote é importante. Cada elemento listado no setup.py deve estar atrelado a uma única versão. Isso significa que cada versão do Qiskit deve instalar uma versão única para cada elemento rastreado. Por exemplo, a lista de requisitos em determinado momento deve se parecer como algo assim:

requirements = [
    "qiskit_terra==0.7.0",
    "qiskit-aer==0.1.1",
]

Isso é para ajudar na depuração e também para tornar o rastreamento sobre as múltiplas versões de elementos mais transparente.