Contribuir a Qiskit¶

Qiskit es un proyecto de código abierto comprometido a llevar la computación cuántica a personas de cualquier perfil de conocimiento. Esta página describe cómo puedes unirte a la comunidad de Qiskit para lograr este objetivo.

Dónde Están las Cosas¶

El código Qiskit se ubica en el repositorio GitHub de Qiskit, donde puedes encontrar los proyectos individuales que conforman Qiskit, incluyendo

Primeros Pasos¶

Aprende cómo los miembros de la comunidad de Qiskit

Informar de Errores y Solicitar Mejoras¶

Cuando encuentres un problema, abre una propuesta en el rastreador de incidencias del elemento de Qiskit correspondiente:

Elemento	Rastreador de Incidencias
qiskit-terra	https://github.com/Qiskit/qiskit-terra/issues
qiskit-aer	https://github.com/Qiskit/qiskit-aer/issues
Documentación o Metapaquetes de Qiskit	https://github.com/Qiskit/qiskit/issues

Si se te ocurre una nueva funcionalidad, por favor, abre una incidencia de tipo Enhancement en el rastreador de incidencias del elemento apropiado. Al abrir una incidencia, se inicia una discusión con el equipo sobre tu idea, cómo encaja con el proyecto, cómo se puede implementar, etc.

Contribuir con el Código¶

Guía de Estilo¶

Para hacer cumplir un estilo de código consistente en el proyecto, usamos Pylint y pycodestyle para verificar que las contribuciones de código se ajusten y respeten la guía de estilo del proyecto. Para verificar que tus cambios se ajustan a la guía de estilo, ejecuta: tox -elint

Acuerdo de Licencia del Contribuidor¶

Antes de que puedas enviar cualquier código, todos los colaboradores deben firmar un acuerdo de licencia de contribuidor (contributor license agreement, CLA). Al firmar un CLA, atestiguas que eres el autor de la contribución y que estás contribuyendo libremente bajo los términos de la licencia Apache-2.0.

Cuando contribuyas al proyecto de Qiskit con un nuevo Pull Request, un bot evaluará si has firmado el CLA. Si es necesario, el bot comentará sobre el Pull Request, incluyendo un enlace para aceptar el acuerdo. El documento CLA individual está disponible para su revisión en formato PDF.

Nota

Si tu contribución es parte de tu empleo o tu contribución es propiedad de tu empleador, entonces seguramente necesitas firmar también un CLA corporativo y enviarlo al correo <qiskit@us.ibm.com>.

Pull Requests¶

Utilizamos pull requests de Github para aceptar las contribuciones.

Aunque no es obligatorio, abrir una nueva incidencia sobre el error que estás arreglando o la funcionalidad en la que estás trabajando antes de abrir un Pull Request, es un paso importante para iniciar una discusión con la comunidad sobre tu trabajo. La incidencia nos da un lugar para hablar sobre la idea y cómo podemos trabajar juntos para implementarla en el código. También le permite a la comunidad saber en qué estás trabajando y, si necesitas ayuda, puedes hacer referencia a la incidencia cuando lo discutas con otros miembros de la comunidad y del equipo.

Si has escrito algo de código, pero necesitas ayuda para terminarlo, o deseas obtener comentarios iniciales sobre él antes de finalizarlo, o deseas compartirlo y discutirlo antes de concluir la implementación, puedes abrir un Pull Request como Work in Progress (Trabajo en Progreso). Cuando crees el Pull Request, inicia el título con la etiqueta [WIP] (para Work In Progress). Esto indicará a los revisores que el código en el PR (Pull Request) no está en su estado final y cambiará. También significa que no se integrará el código hasta que esté finalizado. Tú o un revisor pueden eliminar la etiqueta [WIP] cuando el código esté listo para ser revisado por completo para su integración.

Revisión de Código¶

La revisión de código se hace de forma abierta y es visible para cualquier persona. Aunque solo los encargados tienen acceso para integrar código, es extremadamente importante que la comunidad dé su opinión sobre los Pull Requests. También es un buen mecanismo para aprender sobre el código base. Puedes ver una lista de todos los Pull Requests abiertos aquí:

Elemento	Pull Requests
qiskit-terra	https://github.com/Qiskit/qiskit-terra/pulls
qiskit-aer	https://github.com/Qiskit/qiskit-aer/pulls
Documentación o Metapaquetes de Qiskit	https://github.com/Qiskit/qiskit/pulls

Mensajes de commit¶

El contenido del mensaje de confirmación que describe un cambio es tan importante como el propio cambio. El mensaje proporciona el contexto no sólo para la revisión del código, sino también el historial de cambios en el registro de Git. Un mensaje detallado hará que sea más fácil revisar tu código, y también proporcionará contexto cuando alguien revise el cambio en el futuro. Cuando escribas un mensaje de confirmación, recuerda estos detalles importantes:

No supongas que quien revisa entiende cual era el problema original.

Cuando leas una incidencia, después de intercambiar algunos comentarios, por lo general queda claro cuál es la causa del problema. El mensaje de commit debe expresar claramente cuál es el problema original. El error es simplemente interesante por antecedentes históricos sobre cómo se identificó el problema. Debería ser posible revisar la corrección de un parche propuesto a partir del mensaje de commit, sin tener que leer el ticket del error.

No supongas que el código es evidente/autodocumentado.

Lo que es evidente para una persona, podría no serlo para otra. Siempre documenta cuál era el problema original y cómo se está arreglando. Esto aplica para todos los cambios excepto errores de dedo o modificaciones de solo espacios en blanco.

Describe por qué se está realizando un cambio.

Un error común es solo documentar cómo se ha escrito el código, sin describir por qué el desarrollador eligió hacerlo de esa manera. Se debe describir la estructura general del código, particularmente para los cambios grandes, pero lo más importante es describir la intención/motivación detrás de los cambios.

Lee el mensaje de confirmación para ver si sugiere una estructura de código mejorada.

A veces, al revisar un mensaje de confirmación grande, resulta obvio que el cambio debería haberse dividido en dos o más partes. No tengas miedo de volver atrás y dividir el cambio en Pull Requests diferentes.

Asegúrate de que haya información suficiente para decidir si se debe revisar.

Cuando GitHub envía un correo electrónico alertando de una nueva solicitud de Pull Request, solamente se incluye un mínimo de información - usualmente sólo el mensaje de commit y la lista de cambios en los archivos. Debido al alto volumen de parches, un mensaje de commit debe contener suficiente información para que quien la revise pueda encontrar el parche a revisar.

La primera línea del mensaje de commit es la más importante.

En los commits de Git, la primera línea del mensaje del commit tiene particular importancia. Esta es usada por defecto como el título de la Pull Request, asunto de la notificación por correo electrónico, mensajes de anotación de git, anotación del visualizador gitk, mensajes de commit para merge y muchos otros lugares donde el espacio es limitado. Además de resumir el cambio, debe explicar detalladamente qué parte del código es afectada por este.

Además, la primera línea del mensaje de commit se convierte en una entrada en el registro de cambios si el PR está etiquetado para incluirse en el changelog. Es crítico que escribas un resumen claro y conciso.

Describe las limitaciones del código actual.

Si el código que está siendo modificado aún tiene potencial para mejoras posteriores, o alguna limitación, menciónalo en el mensaje de commit. Esto demuestra a quien revisa que se ha considerado un panorama más amplio, y qué compensaciones se han echo en cuanto a objetivos de corto plazo contra deseos de largo plazo.

Incluye referencias a los problemas.

Si las modificaciones del commit están relacionadas con algún problema, asegúrate de anotarlo en el mensaje del commit. Usa la sintaxis:

Fixes #1234

si soluciona el problema (GitHub cerrará el problema cuando se haga merge del Pull Request).

La principal regla a seguir es:

El mensaje de commit debe contener toda la información necesaria para entender en su totalidad y revisar si el parche es apropiado. Menos no es más.

Documentando Tu Código¶

Si modificas un elemento, asegúrate de actualizar las docstrings asociadas al igual que las partes de la documentación ubicadas en el folder docs/apidocs del repositorio correspondiente. Para compilar localmente la documentación específica de un elemento, ejecuta tox -edocs, para compilar localmente la documentación y guardar el resultado en docs/_build/html. Además, el trabajo de Docs CI en azure pipelines ejecutará esto y alojará un archivo zip con la salida que puedes descargar y ver localmente.

Si tienes algún problema con la documentación integrada que se encuentra en el repositorio Qiskit/qiskit, puedes abrir un documentation issue si encuentras algún error, tienes alguna nueva funcionalidad por documentar o crees que se puede agregar material a los documentos existentes.

Primeras Contribuciones Recomendadas¶

Si quieres contribuir a Qiskit, pero no estás seguro por dónde comenzar, la etiqueta good first issue en la lista de problemas de un proyecto destaca aquellos problemas apropiados para quienes se inician en el proyecto. Otros contribuidores han revisado y marcados estos problemas como algo en lo que un nuevo contribuidor debería poder trabajar. En otras palabras, conocimiento profundo de Qiskit no es un requisito para desarrollar una solución para el problema.

Política de Obsolescencia¶

Los usuarios de Qiskit necesitan saber si una funcionalidad o una API en la que confían continuará siendo compatible con el software el día de mañana. Es importante para el usuario saber en qué condiciones el proyecto puede eliminar (o cambiar de manera incompatible con versiones anteriores) una funcionalidad o API. Para gestionar las expectativas, la siguiente política es cómo Qiskit maneja la desactivación/eliminación de una API o funcionalidad:

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. La ruta de migración debe haber existido al menos en una liberación anterior antes de que la nueva función pueda quedar obsoleta. Por ejemplo, si tienes una función foo() que va a ser reemplazada por bar(), no puedes hacer obsoleta la función foo() en la misma versión que introduces bar(). La función bar() debe estar disponible en una versión antes de que foo() quede obsoleto. Esto es necesario para permitir que los consumidores intermedios (downstream) de Qiskit que mantienen sus propias librerías escriban código que funcione con más de 1 liberación a la vez, lo cual es importante para todo el ecosistema. Si deseas indicar que se producirá una obsolescencia en una versión futura, puedes usar la advertencia PendingDeprecationWarning para señalar esto. Sin embargo, el periodo de obsolescencia solo comienza después de que se emite una DeprecationWarning.

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.

Ten en cuenta que este retraso es mínimo. Para características importantes, se recomienda que la característica obsoleta aparezca al menos el doble de ese tiempo. Además, según la política de rama (branch) estable, las eliminaciones de obsolescencia solo pueden ocurrir durante las versiones menores; no son apropiadas para backporting (adaptación a versiones anteriores).

3a. Una característica obsoleta no se puede eliminar a menos que esté en desuso en más de una liberación, incluso si ha transcurrido el período mínimo de obsolescencia. Por ejemplo, si una función está obsoleta en 0.20.0 que se lanzó el 20 de enero de 2022 y la próxima versión secundaria 0.21.0 se lanzó el 16 de junio de 2022, la función obsoleta no se puede eliminar hasta la versión 0.22.0, a pesar de que 0.21.0 se generó a más de tres meses después del lanzamiento de 0.20.0. Esto es importante porque el objetivo de las advertencias de obsoletización es informar a los usuarios que se avecina un cambio de API potencialmente importante y darles la oportunidad de adaptar su código. Sin embargo, muchos usuarios se saltan las versiones (especialmente si hay una gran cantidad de cambios en cada versión) y no actualizan a cada versión, por lo que es posible que se pierda la advertencia si solo está presente en una versión menor.

Advertencias de Obsolescencia¶

La forma correcta de generar una advertencia de obsolescencia es usar la función warn del módulo de advertencias en la biblioteca estándar de Python. La clase de categoría de advertencia debe ser una DeprecationWarning. Un ejemplo sería:

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)

Una cosa a tener en cuenta aquí es el kwarg stack_level en la llamada a warn(). Este argumento se utiliza para especificar qué nivel de la pila de llamadas se utilizará como línea que inicia la advertencia. Por lo general, stack_level debe establecerse en 2, ya que esto mostrará la línea que llama al contexto donde se generó la advertencia. En el ejemplo anterior, sería el llamador de foo(). Si no configuraste esto, la advertencia mostraría que fue causada por la línea en la función foo(), lo cual no es útil para los usuarios que intentan determinar el origen de una llamada obsoleta. Sin embargo, este valor puede ajustarse, dependiendo de la pila de llamadas y de dónde se llama a warn(). Por ejemplo, si la advertencia siempre se genera mediante un método privado que solo se llama desde un solo lugar, stack_level=3 podría ser apropiado.

Política de Ramificación Estable¶

La rama estable está destinada a ser una fuente segura de correcciones para errores de alto impacto y problemas de seguridad que se han solucionado en master desde su lanzamiento. Al revisar un PR de rama estable, debemos equilibrar el riesgo de cualquier parche dado con el valor que proporcionará a los usuarios de la rama estable. Solo una clase limitada de cambios es apropiada para su inclusión en la rama estable. Un parche grande y arriesgado para un problema importante podría tener sentido, al igual que una solución trivial para un caso de manejo de errores bastante oscuro. Se deben tomar en cuenta varios factores al considerar un cambio:

El riesgo de regresión: incluso los cambios más pequeños conllevan algún riesgo de romper algo, y realmente queremos evitar regresiones en la rama estable.
El beneficio de visibilidad para el usuario: ¿estamos arreglando algo que los usuarios podrían notar? y, de ser así, ¿qué tan importante es?
Qué tan autónoma es la solución: si soluciona un problema importante, pero también refactoriza una gran cantidad de código, probablemente valga la pena pensar en cómo se vería una solución menos riesgosa.
Si la corrección ya está en master: un cambio debe ser un backport de un cambio ya fusionado en master, a menos que el cambio simplemente no tenga sentido en master.

Procedimiento de adaptación a versiones anteriores (backporting):¶

Al adaptar un parche de la rama master a una rama estable, queremos mantener una referencia del cambio en master. Cuando crees la rama para el PR estable, usa:

$ git cherry-pick -x $master_commit_id

Sin embargo, esto solo funciona para pequeños parches autónomos de master. Si necesitas exportar un subconjunto de un commit más grande (de un PR compactado, por ejemplo) de master, hazlo manualmente. En estos casos, agrega:

Backported from: #master pr number

para que podamos rastrear la fuente del subconjunto de cambios, incluso si una selección puntual (cherry-pick) no tiene sentido.

Si el parche que estás proponiendo no se puede seleccionar puntualmente (cherry-pick) de manera limpia, puedes ayudar resolviendo los conflictos tu mismo y proponiendo el parche resultante. Mantén las líneas de Conflictos en el mensaje de confirmación (commit) para ayudar a revisar el parche estable.

Etiquetas de backport¶

Los errores o PRs etiquetados con stable backport potential son errores que también se aplican a la versión estable y pueden ser adecuados para el backporting una vez que una corrección llega a master. Una vez que se ha propuesto el backport, se debe quitar la etiqueta.

Incluye [Stable] en el título del PR hacia la rama estable, como una señal de que establecer la rama objetivo como estable no fue un error. Además, haz referencia al número del PR en master del que se está transfiriendo.

Contribuir a la Documentación¶

La documentación de Qiskit está conformada por la filosofía documentación como código, extraída principalmente de los comentarios del código de Qiskit que está en el estilo de documentación para APIs.

La documentación se construye desde la rama master de Qiskit/qiskit/docs usando Sphinx. La mayoría de la documentación, bajo Referencias de la API, se toma de los comentarios del código en los repositorios indicados en Dónde Están las Cosas.

Estructura de la Documentación¶

La forma en que la documentación está estructurada en Qiskit es buscar tener la mayor cantidad de la documentación en docstrings como sea posible. Esto facilita que se realicen adiciones y correcciones durante el desarrollo, porque la mayoría de la documentación se encuentra cerca del código que se cambia. Hay tres niveles en la estructura de documentación normal en Terra:

Los archivos .rst en docs/apidocs

Estos archivos se utilizan para decirle a Sphinx qué módulos incluir en la documentación renderizada. Esto contiene dos piezas de información: una referencia interna o una referencia cruzada al módulo, que se puede usar para enlaces internos dentro de la documentación, y una directiva automódulo que se utiliza para analizar las docstrings del módulo desde una ruta de importación especificada. Por ejemplo, el archivo dagcircuit.rst contiene:

.. _qiskit-dagcircuit:


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

El único archivo .rst fuera de este es qiskit.rst, que contiene la tabla de contenido. Si estás agregando un nuevo archivo .rst para la documentación de un nuevo módulo, asegúrate de agregarlo al toctree en ese archivo.

La docstring a nivel de módulo

Esta cadena de documentación (docstring) está a nivel de módulo para el módulo especificado en la directiva automodule en el primer archivo. Si el módulo especificado es un directorio/espacio de nombres (namespace), la docstring debe especificarse en el archivo __init__.py para ese directorio. Esta docstring a nivel de módulo contiene más detalles sobre el módulo que se está documentando. La estructura normal de esta docstring es describir todas las clases y funciones de la API pública contenidas en ese módulo. Esto se hace típicamente usando la directiva autosummary (o directivas autodoc directamente si el módulo es simple, como en el caso de qiskit.execute). La directiva autosummary se usa para autodocumentar (autodoc) una lista de diferentes elementos de Python (clases, funciones, etc.) directamente sin tener que llamar manualmente las directivas autodoc para cada uno. La cadena de documentación a nivel de módulo es donde se proporciona una descripción general de alto nivel de las funciones que proporciona el módulo. Esto se hace normalmente agrupando los diferentes componentes de la API pública en múltiples subsecciones.

Por ejemplo, como en el ejemplo anterior del módulo dagcircuit, los contenidos de la docstring del módulo para qiskit/dagcircuit/__init__.py serían:

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

Nota

Esto es solamente un ejemplo y la docstring real para el módulo dagcircuit podría diferir.

La docstring real para los elementos listados en la docstring del módulo

Deberías esforzarte por documentar a fondo todas las interfaces públicas expuestas utilizando ejemplos cuando sea necesario. Para las cadenas de documentación, se utilizan las Google Python Style Docstrings. Esto se analiza utilizando la extensión napoleon sphinx. La documentación de napoleon contiene un buen ejemplo de cómo deben formatearse las cadenas de documentación.

Nota

Puedes usar cualquier directiva de Sphinx o del formato rst en una docstring mientras sea razonable. Por ejemplo, una extensión comúnmente usada es la directiva jupyter-execute, que se utiliza para ejecutar un bloque de código en Jupyter y mostrar tanto el código como su salida. Esto es particularmente útil para las visualizaciones.

Integración de la Documentación¶

La documentación alojada en https://qiskit.org/documentation/ cubre todo el proyecto Qiskit; Terra es solo un componente de eso. Como tal, la documentación generada para la versión alojada está construida desde el repositorio de metapaquetes de Qiskit https://github.com/Qiskit/qiskit. Cuando los commits son mezclados con ese repositorio, la salida de las compilaciones de Sphinx se carga en el sitio web qiskit.org. Esas construcciones de Sphinx están configuradas para extraer la documentación de la versión de los elementos Qiskit instalados por el meta paquete en ese momento. Por ejemplo, si la versión del metapaquete es actualmente 0.13.0, entonces se copiará la documentación de la versión 0.10.0 de Terra. Cuando los requerimientos del metapaquete son incrementados, entonces comenzará a extraer documentación de la nueva versión. Esto significa que las correcciones para la documentación incorrecta de la API deberán incluirse en una nueva versión. Las correcciones de documentación son backports válidos para una versión de parche estable según la política de rama estable (consulta Política de Ramificación Estable).

Durante el proceso de generación, los contenidos de cada elemento de docs/apidocs/ son recursivamente duplicados en una copia compartida de doc/apidocs/ en el repositorio del metapaquete junto con todos los otros elementos. Esto significa que lo que haya en esta raíz docs/apidocs de cada elemento en una versión acabará estando en la raíz de https://qiskit.org/documentation/apidoc/.

Traducir la Documentación¶

La documentación de Qiskit se traduce (se localiza) utilizando Crowdin, un software y una plataforma de localización web que permite a las organizaciones coordinar proyectos de traducción y colaborar con las comunidades para traducir materiales. Crowdin permite que nuestra comunidad de traductores amplifique su impacto al reutilizar automáticamente el trabajo invertido en la traducción de una oración para traducir otras oraciones similares. Crowdin también hace que las traducciones sean resistentes a muchos tipos de cambios en el material original, como mover oraciones, incluso entre archivos.

Las solicitudes de localización de Qiskit se gestionan en el repositorio Qiskit Translations. Para contribuir a la localización de Qiskit, sigue estos pasos:

Añade tu nombre (o ID) al archivo LOCALIZATION_CONTRIBUTORS.
Crea un Pull Request (PR) para incluir el cambio. Asegúrate de seguir la plantilla para abrir un Pull Request.
Nota
- Cada colaborador debe crear su propio PR y firmar el acuerdo de licencia de colaborador (CLA).
- Por favor, indica en el resumen del PR el idioma al que deseas contribuir.
- Si tienes un issue abierto en el que se solicita un idioma, agrega el vínculo del issue al PR.
Se te pedirá que firmes el Acuerdo de Licencia de Contribuidor (CLA); por favor, házlo.
Un mínimo de tres contribuidores por idioma es necesario, para que el idioma sea agregado y reciba el soporte oficial de los administradores del proyecto de localización.
Entre el grupo de contribuyentes, se debe identificar un líder de traducción para que sirva de enlace con los administradores del proyecto de localización. El líder debe contactar a: Yuri Kobayashi (yurik@jp.ibm.com) por correo electrónico.
En el proyecto Qiskit-Docs Crowdin, elige el idioma al que deseas contribuir.

Nota

Como es mencionado en la publicación del post, “Qiskit in my language is Qiskit, debemos asegurarnos que los idiomas traducidos tienen la comunidad suficiente de soporte para construir un equipo de traducción, correctores, y líderes de traducción. Si deseas ser un líder de traducción o está interesado en unirse a un nuevo equipo de proyecto de traducción, puedes abrir un GitHub issue para empezar un debate con el equipo de Qiskit y reclutar miembros del proyecto de traducción.
Haz click en el botón Unirse (Join) y pega la URL de tu PR en el cuadro de diálogo en el que se te pregunta por qué quieres unirte al proyecto de Crowdin.

Los administradores del proyecto Crowdin revisarán tu solicitud y te darán acceso tan pronto como sea posible.

Construcción a partir del Código Fuente¶

Puedes construir una copia local de la documentación desde tu clonación local del repositorio Qiskit/qiskit de la siguiente manera:

Clona el repositorio de Qiskit.

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

La clonación crea un folder local llamado qiskit.
```
cd qiskit
```
Genera la documentación navegando a tu copia local de Qiskit/qiskit y ejecutando el siguiente comando en una ventana de terminal.
```
tox -edocs
```
Si todavía no tienes instalado el comando tox, instálalo ejecutando:
```
pip install tox
```

Mientras haces cambios a tus archivos RST locales, puedes actualizar tus archivos HTML navegando a /doc/ y ejecutando lo siguiente en una terminal:

tox -edocs

Esto construirá una nueva versión de HTML con estilos de tu documentación local en el subdirectorio /docs/_build/html/.

Instalación a partir del Código Fuente¶

Instalar los elementos usando el código fuente te permite acceder a la última versión de Qiskit en lugar de la versión del repositorio de Python Package Index (PyPl). Esto te da la capacidad de inspeccionar y extender la última versión del código de Qiskit más eficientemente.

Al instalar los elementos y componentes a partir del código fuente, por defecto se usará su versión marcada como development (que corresponde a la rama git master), y no la versión stable (que contiene la misma base de código que la publicada en los paquetes pip). Dado que las versiones development de cada elemento o componente normalmente incluyen nuevas características y cambios, generalmente será necesario también instalar las versiones development del resto de los elementos.

Nota

Los paquetes Terra y Aer requieren un compilador para construirlos desde el código fuente antes de que puedas instalarlos. Ignis, Aqua y el backend de IBM Quantum Provider no requieren un compilador.

La instalación de los elementos desde el código fuente requiere el siguiente orden de instalación para evitar la instalación de versiones de elementos que pueden ser inferiores a las deseadas si la versión de pip es inferior a la de las versiones del código fuente:

qiskit-terra
qiskit-aer
qiskit-ibmq-provider (si deseas conectarte a los dispositivos IBM Quantum o al simulador en línea)

Para trabajar en varios componentes y elementos simultáneamente, sigue los siguientes pasos para cada elemento.

Nota

Debido al uso del empaquetado de espacios de nombres (namespace) en Python, se debe tener cuidado al instalar los paquetes. Si planeas instalar cualquier elemento desde el código fuente, no uses el metapaquete qiskit. Además, sigue esta guía y utiliza un entorno virtual independiente para el desarrollo. Si eliges mezclar una instalación existente con su desarrollo, consulta https://github.com/pypa/sample-namespace-packages/blob/master/table.md para ver el conjunto de combinaciones de métodos de instalación que funcionan juntos.

Configurar el Ambiente de Desarrollo Virtual¶

Los entornos virtuales (virtual environments) son usados en el desarrollo en Qiskit para aislar el ambiente de desarrollo de los paquetes del sistema en general. De esta manera podemos evitar ser dependientes de que nuestro sistema tenga una configuración específica. Para desarrolladores, esto también hace que sea fácil mantener múltiples entornos (por ejemplo, uno por cada versión compatible de Python, para versiones anteriores de Qiskit, etc.).

Python venv

All Python versions supported by Qiskit include built-in virtual environment module venv.

Start by creating a new virtual environment with venv. The resulting environment will use the same version of Python that created it and will not inherit installed system-wide packages by default. The specified folder will be created and is used to hold the environment’s installation. It can be placed anywhere. For more detail, see the official Python documentation, Creation of virtual environments.

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

Activate the environment by invoking the appropriate activation script for your system, which can be found within the environment folder. For example, for bash/zsh:

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

Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections can be located for your system.

pip install -U pip

Conda

For Conda users, a new environment can be created as follows.

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

Instalar Terra a partir del Código Fuente¶

La instalación desde el código fuente requiere que tengas el compilador de Rust en tu sistema. Para instalar el compilador de Rust, el camino recomendado es usar rustup, que es un instalador de Rust multiplataforma. Para usar rustup puedes ir a:

https://rustup.rs/

que proporcionará instrucciones sobre cómo instalar rust en tu plataforma. Además de rustup, también hay otros métodos de instalación disponibles.

Una vez que está instalado el compilador de Rust, estarás listo para instalar Qiskit Terra.

Clona el repositorio de Terra.

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

La clonación del repositorio crea una carpeta local llamada qiskit-terra.
```
cd qiskit-terra
```
Si deseas ejecutar pruebas o verificaciones de linting, instala los requerimientos del desarrollador.
```
pip install -r requirements-dev.txt
```
Instala qiskit-terra.
```
pip install .
```

Si deseas instalarlo en modo editable, lo que significa que los cambios de código en el proyecto no requieren una reinstalación para ser aplicados, puedes hacerlo con:

pip install -e .

La instalación en modo editable construirá las extensiones compiladas en modo de depuración sin optimizaciones. Esto afectará el rendimiento en tiempo de ejecución del código compilado. Si deseas utilizar el modo editable y construir el código compilado que está publicado, con las optimizaciones habilitadas, puedes ejecutar:

python setup.py build_rust --release --inplace

después de que ejecutas pip y eso reconstruirá el binario en modo de liberación.

Si estás trabajando en el código de Rust en Qiskit, necesitarás reconstruir el código de extensión cada vez que realices un cambio local. pip install -e . solo compilará la extensión de Rust cuando sea ejecutado, por lo que cualquier cambio local que hagas en el código de Rust después de ejecutar pip no se reflejará en el paquete instalado a menos que reconstruyas la extensión. Puedes aprovechar el comando anterior build_rust para hacer esto (con o sin --release en función de si deseas compilar en modo de depuración o modo de liberación).

Luego puedes ejecutar los ejemplos de código después de instalar Terra. Puedes ejecutar un script de ejemplo con el siguiente comando.

python examples/python/using_qiskit_terra_level_0.py

Instalar Aer a partir del Código Fuente¶

Clona el repositorio Aer.

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

Instala los requerimientos de construcción.
```
pip install cmake scikit-build
```

Después de esto, los pasos para instalar Aer dependen del sistema operativo que estés utilizando. Dado que Aer es un programa en C++ compilado con una interfaz en Python, existen dependencias externas a Python para construir el binario de Aer que no se pueden instalar universalmente dependiendo del sistema operativo.

Linux

Install compiler requirements.

Building Aer requires a C++ compiler and development headers.

If you’re using Fedora or an equivalent Linux distribution, install using:
```
dnf install @development-tools
```
For Ubuntu/Debian install it using:
```
apt-get install build-essential
```
Install OpenBLAS development headers.

If you’re using Fedora or an equivalent Linux distribution, install using:
```
dnf install openblas-devel
```
For Ubuntu/Debian install it using:
```
apt-get install libopenblas-dev
```

macOS

Install dependencies.

To use the Clang compiler on macOS, you need to install an extra library for supporting OpenMP. You can use brew to install this and other dependencies.
```
brew install libomp
```
Then install a BLAS implementation; OpenBLAS is the default choice.
```
brew install openblas
```
Next, install Xcode Command Line Tools.
```
xcode-select --install
```

Windows

On Windows you need to use Anaconda3 or Miniconda3 to install all the dependencies.

Install compiler requirements.

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

Install binary and build dependencies.

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

Construye e instala qiskit-aer directamente

Si tienes pip <19.0.0 instalado y tu entorno no requiere una compilación personalizada, ejecuta:
```
cd qiskit-aer
pip install .
```
Esto construirá los binarios e instalará Aer.

Alternativamente, si tienes instalado un pip más nuevo o tienes algún requerimiento personalizado, puedes construir una Python wheel manualmente.
```
cd qiskit-aer
python ./setup.py bdist_wheel
```
Si necesitas configurar una opción personalizada durante la construcción de la Python wheel, consulta Opciones personalizadas durante la construcción de la Python wheel.

Después de construir la Python wheel, se almacenará en el directorio dist/ en el repositorio de Aer. La versión exacta dependerá
```
cd dist
pip install qiskit_aer-*.whl
```
El nombre exacto del archivo de salida de la Python wheel depende de la versión actual de Aer en desarrollo.

Opciones personalizadas durante la construcción de la Python wheel¶

El sistema de construcción de Aer usa scikit-build para ejecutar la compilación cuando lo construye con la interfaz de Python. Actúa como una interfaz para setuptools para llamar a CMake y compilar los binarios para tu sistema local.

Debido a la complejidad de la compilación de binarios es posible que tengas que pasar opciones a ciertas partes del proceso de construcción. La forma de pasar variables es:

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

donde los elementos entre corchetes [] son opcionales, y skbuild_opts, cmake_opts, build_tool_opts deben ser reemplazados por banderas de tu elección. Una lista de opciones de CMake está disponible aquí: https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. Por ejemplo, podrías ejecutar algo como:

python setup.py bdist_wheel -- -- -j8

Esto es pasar la bandera -j8 al sistema de compilación subyacente (que en este caso es Automake), indicándole que deseas compilar en paralelo usando 8 procesos.

Por ejemplo, un caso de uso común para estas banderas (flags) en Linux es especificar una versión particular del compilador de C++ a ser usado (normalmente si el valor predeterminado es demasiado viejo):

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

el cuál comunicará a CMake que use el comando g++-7 en vez del predeterminado g++ al compilar Aer.

Otro caso de uso común para esto, dependiendo de tu entorno, es que es posible que debas especificar el nombre de tu plataforma y desactivar el enlazamiento estático.

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

Aquí --plat-name es una bandera para las setuptools para especificar el nombre de la plataforma a utilizar en los metadatos del paquete, -DSTATIC_LINKING es una bandera para hacer que CMake deshabilite el enlazamiento estático, y -j8 es una bandera para hacer que Automake utilice 8 procesos para la compilación.

Una lista de opciones comunes dependiendo de la plataforma es:

Plataforma	Herramienta	Opción	Caso de Uso
Todas	Automake	`-j`	Seguido de un número, establece el número de procesos que se utilizarán para la compilación.
Linux	CMake	`-DCMAKE_CXX_COMPILER`	Se utiliza para especificar un compilador de C++ específico; esto a menudo es necesario si tu g++ predeterminado es demasiado antiguo.
OSX	setuptools	`--plat-name`	Se usa para especificar el nombre de la plataforma en el paquete Python de salida.
OSX	CMake	`-DSTATIC_LINKING`	Se utiliza para especificar si se debe utilizar o no el enlazado estático.

Nota

Algunas de estas opciones no son específicas de la plataforma. Estas plataformas en particular se enumeran porque se usan comúnmente en un entorno local. Consulta la documentación de la herramienta para obtener más información.

Instalar IBM Quantum Provider a partir del Código Fuente¶

Clona el repositorio qiskit-ibmq-provider.

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

La clonación del repositorio crea un directorio local llamado qiskit-ibmq-provider.
```
cd qiskit-ibmq-provider
```
Si quieres ejecutar pruebas o verificaciones de linting, instala los requerimientos de desarrollador. Esto no es requerido para instalar o usar el paquete qiskit-ibmq-provider cuando se instala a partir del código fuente.
```
pip install -r requirements-dev.txt
```
Instala qiskit-ibmq-provider.
```
pip install .
```

Si deseas instalarlo en modo editable, es decir que los cambios en el código del proyecto no requieran una reinstalación para ser aplicados:

pip install -e .

Control de versiones de Qiskit¶

El proyecto Qiskit se compone de varios elementos, cada uno de los cuales realiza una funcionalidad diferente. Cada uno es útil de forma independiente y se puede utilizar por sí solo, pero para mayor comodidad proporcionamos este repositorio y metapaquete para proporcionar un único punto de entrada para instalar todos los elementos a la vez. Esto es para simplificar el proceso de instalación y proporcionar una interfaz unificada a los usuarios finales. Sin embargo, debido a que cada elemento de Qiskit tiene sus propias liberaciones y versiones, es necesario tener cuidado al tratar con versiones entre los diferentes repositorios. Este documento describe las pautas para tratar con versiones y liberaciones tanto de los elementos de Qiskit como del metapaquete.

Para el resto de esta guía, se utilizará la nomenclatura estándar de versiones semánticas de: Major.Minor.Patch para hacer referencia a los diferentes componentes de un número de versión. Por ejemplo, si el número de versión es 0.7.1, entonces la versión principal es 0, la versión secundaria 7 y la versión del parche 1.

Versión del Metapaquete¶

La versión del metapaquete de Qiskit es un valor independiente que está determinado por las versiones de cada uno de los elementos que está siendo rastreado. Cada vez que enviamos una versión a un componente rastreado (o agregamos un elemento), los requisitos del metapaquete y la versión deberán actualizarse y publicarse una nueva versión. El tiempo debe coordinarse con el lanzamiento de elementos para garantizar que los lanzamientos de metapaquetes se realicen con los lanzamientos de elementos.

Adición de Nuevos Elementos Rastreados¶

Cuando se agrega un nuevo elemento Qiskit a los requisitos del metapaquete, necesitamos aumentar la versión Minor del metapaquete.

Por ejemplo, si el metapaquete está rastreando los 2 elementos qiskit-aer y qiskit-terra y su versión es 0.7.4. Luego liberamos un nuevo elemento qiskit-ignis que pretendemos incluir también en el metapaquete. Entonces cuando agregamos el nuevo elemento al metapaquete, aumentamos la versión a 0.8.0.

Incremento de la Versión del Parche¶

Cuando cualquier elemento de Qiskit que ya está siendo rastreado por el metapaquete lanza una versión de parche para corregir errores en una liberación, también necesitamos aumentar el requerimiento en setup.py y luego aumentar la versión del parche del metapaquete.

Por ejemplo, si el metapaquete está rastreando los 3 elementos qiskit-terra==0.8.1, qiskit-aer==0.2.1, y qiskit-ignis==0.1.4 con la versión actual 0.9.6. Cuando qiskit-terra lance una nueva versión de parche para corregir un error 0.8.2, el metapaquete también deberá aumentar su versión de parche y su liberación, convirtiéndose en 0.9.7.

Además, ocasionalmente hay empaquetados u otros errores en el metapaquete en sí que deben corregirse provocando nuevas versiones. Cuando se encuentren, deberíamos aumentar la versión del parche para diferenciarla de la liberación rota. No elimines las versiones rotas o antiguas de pypi en cualquier situación, en su lugar, simplemente aumenta la versión del parche y carga una nueva versión.

Incrementos de la Versión Menor¶

Además, cuando se agrega un nuevo elemento al metapaquete, la versión menor del metapaquete también debe aumentarse cada vez que se aumente una versión menor en un elemento rastreado.

Por ejemplo, si el metapaquete está rastreando los 2 elementos qiskit-terra==0.7.0 y qiskit-aer==0.1.1 y la versión actual es 0.7.5. Cuando el elemento qiskit-aer libere 0.2.0, entonces necesitamos aumentar la versión del metapaquete para que sea 0.8.0 para que corresponda con la nueva versión.

Incrementos de la Versión Mayor¶

La versión principal (o mayor) es diferente del número de versión de los demás componentes. A diferencia de los números de versión de los otros componentes, que son actualizados al mismo tiempo con cada elemento rastreado, la versión principal solo aumenta cuando se modifican todas las versiones rastreadas (al menos antes de 1.0.0). En este momento, todos los elementos todavía tienen un número de versión principal de componente 0 y hasta que cada elemento rastreado en el meta-repositorio sea marcado como estable, al hacer que la versión principal sea >=1, entonces la versión del metapaquete no debería aumentar la versión principal (o mayor).

Aún no se ha decidido el comportamiento del seguimiento del componente del número de versión principal después de que todos los elementos sean >=1.0.0.

Extras Opcionales¶

Además de los elementos rastreados, hay paquetes adicionales construidos sobre Qiskit que se desarrollan en conjunto con Qiskit, por ejemplo, los repositorios de aplicaciones como qiskit-optimization. Para mayor comodidad, el metapaquete Qiskit realiza un seguimiento de estos paquetes como extras opcionales que se pueden instalar con Qiskit. Las versiones de estos proyectos downstream opcionales no provocan una liberación del metapaquete, ya que no están fijadas y no afectan a la versión del metapaquete. Si hay un problema de compatibilidad entre Qiskit y estas dependencias downstream opcionales, la versión mínima debe ajustarse en una liberación independiente, esto solo se hará como una liberación de parche, ya que es una corrección de errores de empaquetamiento.

Seguimiento de Requerimientos de Elementos de Qiskit¶

Si bien no está estrictamente relacionado con el metapaquete y el control de versiones de Qiskit, la forma en que rastreamos las versiones de los elementos en la lista de requerimientos del metapaquete es importante. Cada elemento enumerado en el archivo setup.py debe estar fijado a una única versión. Esto significa que cada versión de Qiskit solo debe instalar una única versión para cada elemento rastreado. Por ejemplo, la lista de requerimientos en un punto dado debería tener un aspecto similar a:

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

Esto es para ayudar en la depuración, pero también hace que el seguimiento de las versiones en varios elementos sea más transparente.