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
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/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 ticket de Melhoria na ferramenta de ticket 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.

Contribuindo Código¶

Guia de Estilos¶

Para garantir um estilo de código consistente no projeto, nós usamos Pylint e pycodesytle 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
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/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 uma issue, 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 um histórico interessante 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.

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. Since releases do not occur at fixed time intervals, a deprecation warning may only occur in one release prior to removal.

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.

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 um cherry-pick estrito 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 na 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 é 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/ cobre 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 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 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-aqua
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¶

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

Instalando Terra a partir do Código Fonte¶

Instalar a partir do código fonte requer que você tenha um compilador C++ em seu sistema que suporte C++11.

Compilador para Linux

Na maioria das plataformas Linux, o compilador GCC necessário já está instalado.

Compilador para macOS

Se você usa macOS, você pode instalar o compilador Clang instalando o XCode. Verifique se você tem XCode e Clang instalados abrindo uma janela do terminal e entrando o seguinte comando.

clang --version

Instale o XCode e Clang usando o seguinte comando.

xcode-select --install

Compilador para Windows

No Windows, é mais fácil instalar o compilador Visual C ++ a partir de Build Tools for Visual Studio 2017. Você pode instalar também o Visual Studio versão 2015 ou 2017, certificando-se de selecionar as opções para instalar o compilador C++.

Quando os compiladores estiverem instalados, você estará pronto para instalar o 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
```
Instale as bibliotecas Python requeridas no seu diretório qiskit-terra.
```
pip install cython
```
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 .

Você pode então executar os código de exemplo após instalar o Terra. Você pode executar o código de exemplo com o seguinte comando.

python examples/python/using_qiskit_terra_level_0.py

Nota

Se você não pretende instalar outros componentes, qiskit-terra irá emitir um alerta de RuntimeWarning de que ambos qiskit-aer e qiskit-ibmq-provider não estão instalados. Isso é feito porque os usuários comumente pretendem usar os elementos adicionais, mas não percebem que eles não estão instalados, ou que a instalação da Aer ou do Provedor Quantum IBM falhou por alguma razão. Se você deseja suprimir estes avisos, adicione-os:

import warnings
warnings.filterwarnings('ignore', category=RuntimeWarning,
                        module='qiskit')

antes de importar qualquer qiskit ao seu código. Isto irá suprimir o aviso sobre o qiskit-aer e qiskit-ibmq-provider, mas irá continuar a exibir quaisquer outros avisos a partir do qiskit ou de outros pacotes.

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 cython
```

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 o Build 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.

Como alternativa, se você tiver um pip mais recente instalado ou tiver um requisito personalizado, você pode fazer o build do Python wheel manualmente.
```
cd qiskit-aer
python ./setup.py bdist_wheel
```
Se você precisar definir uma opção personalizada durante o build do wheel, consulte Opções personalizadas durante builds de wheel.

Depois que você construir o 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 personalizadas durante builds de wheel¶

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

Devido à complexidade de compilar os binários, você pode precisar passar opções para uma determinada parte do processo de construção. 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 construção subjacente (que neste caso é Automake), dizendo que você deseja construir em paralelo usando 8 processos.

Por exemplo, um caso de uso comum para essas flags no linux é para especificar 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 vai dizer ao CMake para usar o comando g++-7 em vez do g++ padrão quando compilar Aer.

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

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

Aqui --plat-name é uma flag para as ferramentas de configuração, para especificar o nome da plataforma a utilizar nos metadados do pacote, -DSTATIC_LINKING é uma flag para usar o CMake para desabilitar links estáticos, e -j8 é uma flag para usar o Automake 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 especificar um compilador C++ específico; isto é frequentemente necessário se seu g++ padrão for muito antigo.
OSX	setuptools	–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 utilizado um link estático.

Nota

Algumas dessas opções não são específicas de 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

Clonar o 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-ignis quando instalar do código fonte.
```
pip install -r requirements-dev.txt
```
Instale Ignis.
```
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 uma reinstalação para ser aplicada:

pip install -e .

Instalando Aqua a partir do Código Fonte¶

Clone o repositório Aqua.

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

Clonar o repositório cria uma pasta local chamada qiskit-aqua.
```
cd qiskit-aqua
```
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 instalar do código fonte.
```
pip install -r requirements-dev.txt
```
Instalar Aqua.
```
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 uma reinstalação para ser aplicada:

pip install -e .

Instalando o IBM Quantum Provider do Código Fonte¶

Clone o repositório qiskit-ibmq-provider.

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

Clonar o 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 instalar do código fonte.
```
pip install -r requirements-dev.txt
```
Instalar o qiskit-ibmq-provider.
```
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 uma reinstalação para ser aplicada:

pip install -e .