Cómo añadir un solver#
Introducción#
En este artículo veremos el proceso para añadir un nuevo solver a QCentroid Platform.
El proceso de creación de un nuevo solver implica seis pasos principales:
- Elegir el caso de uso
- Registrar el solver en la plataforma
- Implementar el solver usando la plantilla de solver y almacenarlo en un repositorio Git
- Conectar tu repositorio con la plataforma
- Pull & build del nuevo código del solver en la plataforma
- Ejecutar un job en la plataforma con tu solver
Requisitos previos#
Antes de crear un solver, asegúrate de tener preparados estos requisitos previos:
- Algunas herramientas de desarrollo instaladas:
- Python
- Pip
- Git
- virtualenv
- Entorno de desarrollo (IDE), como Visual Studio Code
- Habilitar los SDKs que quieras usar desde la sección SDKs.
- Habilitar los proveedores de hardware que quieras usar desde la sección Providers.
- Elegir un caso de uso o crear tu propio caso de uso y familiarizarte con los formatos de entrada y salida (JSON) del caso de uso, porque tu solver debe cumplirlos.
Instalar Python#
Asegúrate de que Python está instalado en tu sistema. Puedes descargarlo desde el sitio web oficial de Python.
Para comprobar si Python está instalado, ejecuta:
python --version
o
python3 --version
Instalar Pip#
El instalador de paquetes de Python, pip, normalmente viene incluido con las instalaciones de Python. Verifica si pip está instalado ejecutando:
pip --version
o
python3 -m pip --version
Si pip no está instalado, sigue las instrucciones de la página de instalación de pip.
Instalar Git#
Necesitas git para clonar repositorios desde GitHub. Descarga e instala git desde git-scm.com si aún no lo tienes instalado.
Instalar virtualenv#
Instala virtualenv usando pip:
pip install virtualenv
Instalar Visual Studio Code#
Necesitas Visual Studio Code o tu IDE favorito para desarrollar tu solver. Descarga e instala Visual Studio Code desde code.visualstudio.com/docs si aún no lo tienes instalado.
Habilitar SDKs#
Ve al dashboard de la plataforma y a la sección SDKs. Recorre la lista de SDKs disponibles y habilita los que vayas a usar en tus solvers.
Habilitar proveedores de hardware#
Ve al dashboard de la plataforma y a la sección Providers. Recorre la lista de proveedores disponibles y habilita los que vayas a usar en tus solvers.
En este paso, se te preguntará si tienes tu propio access token para cada proveedor y si quieres usarlo, o si prefieres usar tokens de QCentroid.
Elegir el caso de uso y familiarizarte con el formato de entrada/salida#
Navega por la sección Use Cases para ver los casos de uso ya creados en tu organización y por el Use Cases catalog para ver otros casos de uso públicos disponibles para desarrollar solvers.
Una vez elegido el caso de uso, o creado tu propio caso de uso, visítalo y revisa la sección Technical details.
Este es un ejemplo de la especificación de entrada y salida del caso de uso Max Cut en formato JSON:
Este sería un ejemplo de archivo de datos de entrada para el caso de uso Max Cut, siguiendo el formato de entrada:
{
"adj_matrix": [ [0, 9, 5, 2, 4, 1],
[9, 0, 3, 8, 7, 6],
[5, 3, 0, 2, 8, 4],
[2, 8, 2, 0, 9, 3],
[4, 7, 8, 9, 0, 2],
[1, 6, 4, 3, 2, 0] ],
"num_nodes": 6
}
Y este sería un ejemplo de datos de salida generados por un solver:
{
"partitions": [1, 0, 1, 0, 1, 1, 0, 1, 0, 0],
"cut_value": 147
}
1. Elegir el caso de uso#
El primer paso es elegir el caso de uso que se va a resolver.
En la sección Use cases puedes encontrar todos los casos de uso disponibles en la plataforma.
También puedes crear tu propio caso de uso si no encuentras uno adecuado ya creado. Consulta Crear un caso de uso para ver las instrucciones.
Para este tutorial asumiremos que queremos resolver el problema Max Cut, un problema clásico de optimización.
2. Registrar el solver en la plataforma#
Ahora puedes registrar tu solver en la plataforma.
Para registrar un nuevo solver en la plataforma:
- Ve a la sección My solvers desde el menú lateral izquierdo.
- Después, en la esquina superior derecha, haz clic en el botón Add new solver.
- Verás el asistente de creación de solver, donde puedes completar toda la información:
- Selecciona el caso de uso que vas a resolver.
- Completa los detalles de tu solver, como nombre y descripción.
- Completa la branch que usarás en tu repositorio, normalmente
mainodevelop. Puedes cambiarla más adelante.
- Haz clic en el botón Add new solver al final del asistente para guardar el solver.
Cuando este paso esté completo, puedes empezar a implementar el código fuente del solver.
3. Implementar el solver usando la plantilla de solver#
Una vez elegido el caso de uso y registrado el solver en la plataforma, puedes empezar a implementar el código fuente real de tu solver.
Veamos cómo implementar el solver para que pueda ejecutarse en la plataforma QCentroid.
La forma más sencilla de programar tus solvers es usar Python.
Configurar un entorno limpio#
Cuando trabajas en local, es muy útil crear un entorno nuevo con VirtualEnv o Conda para asegurarte de que no mezclas dependencias ni te falta nada. Empieza con un entorno Python3.11 completamente nuevo y añade todos los módulos necesarios en tu archivo requirements.txt.
Crear un entorno virtual#
Los entornos virtuales permiten gestionar dependencias de distintos proyectos por separado. Para crear un entorno virtual, navega al directorio deseado del proyecto y ejecuta:
python -m venv myenv
Sustituye myenv por el nombre de tu entorno virtual.
Activar el entorno virtual#
Después de crear el entorno virtual, actívalo:
.\myenv\Scripts\activate
source myenv/bin/activate
El prompt de la terminal cambiará para indicar que el entorno virtual está activo. Verás (myenv) al inicio del prompt.
Puedes comprobar que estás en un entorno limpio listando los paquetes instalados:
pip list
Deberías ver que no hay paquetes instalados, solo algo como esto antes de instalar los requisitos del solver:
Package Version
---------- -------
pip 23.0.1
setuptools 65.5.0
Para salir del entorno virtual y volver a la configuración normal del sistema, usa el comando deactivate:
deactivate
Después de ejecutar este comando, verás que el prompt vuelve a la normalidad.
Puedes activar el entorno de nuevo en cualquier momento y estará en el mismo estado y con los mismos paquetes instalados que la última vez que lo dejaste.
Descargar la plantilla de solver#
La plantilla de solver contiene los siguientes archivos:
README.md(archivo de documentación del solver)qcentroid.pyrequirements.txt
README.md (archivo de documentación del solver)#
Es necesario tener en la raíz del repositorio un archivo README.md que contenga la documentación que quieres incluir sobre tu solver, explicando, si existen, los parámetros que puede introducir el usuario final.
## MyFirstSolver
Test documentation associated with my solver.
I don't have auxiliary parameters but I could define them like this:
- "parameter1": (int) This is what my first parameter does.
qcentroid.py#
Este archivo contendrá únicamente una función run a la que se pasarán los parámetros input_data, solver_params y extra_arguments:
import logging
logger = logging.getLogger("qcentroid-user-log")
from qiskit import QuantumCircuit, Aer, execute, IBMQ
def run(input_data:dict, solver_params:dict, extra_arguments:dict) -> dict:
logger.info("Starting Solver...")
# This is your solver's code
size = int(input_data['size'])
backend = Aer.get_backend('qasm_simulator')
qc = QuantumCircuit(1)
qc.h(0)
qc.measure_all()
job = execute(qc, backend=backend, shots=size, memory=True)
individual_shots = job.result().get_memory()
logger.info("Ending Solver...")
shots = ''
for i in individual_shots:
shots += i
output = {'shots': shots}
# And this is the output it returns, which is a dictionary
return output
requirements.txt#
Por último, tenemos el archivo requirements.txt, que contiene los paquetes usados en el solver junto con sus versiones:
qiskit==0.17.0
En tu entorno, puedes instalar todos los paquetes listados en el archivo requirements.txt usando pip:
pip install -r requirements.txt
Se instalarán las librerías aprobadas estándar disponibles en pip. Asegúrate de añadir todas las dependencias de tu código, excepto las librerías estándar de Python, como json, logging o time.
Por otro lado, si tu proyecto usa pyproject.toml, Pipfile u otro gestor de dependencias, sigue sus instrucciones correspondientes.
Modificar el código fuente del solver#
Lo normal es empezar modificando la plantilla para crear tu propio solver en el archivo qcentroid.py:
Este archivo contiene la función run(), que es el punto de entrada.
Si tu solver se ejecuta en un proveedor cuántico de terceros, usa QCentroid Loaders para resolver el objetivo del proveedor seleccionado para cada job sin hardcodear credenciales, nombres de backend, dispositivos o configuración de workspace en tu repositorio.
Aprende más sobre QCentroid Loaders
Generar assets de salida#
Además del diccionario devuelto por la función run(), tu solver puede generar archivos de salida adicionales. Estos archivos aparecen en la sección Assets de la página de resultados del job. Para que estén disponibles ahí, crea una carpeta llamada additional_output en la ruta raíz del solver y escribe ahí los archivos durante la ejecución.
Se admite casi cualquier formato de archivo autocontenido, incluidas imágenes, archivos HTML, TXT, CSV, Markdown, JSON u otros archivos que ayuden a explicar o inspeccionar los resultados del solver.
Por ejemplo:
from pathlib import Path
import logging
logger = logging.getLogger("qcentroid-user-log")
def run(input_data:dict, solver_params:dict, extra_arguments:dict) -> dict:
logger.info("Starting Solver...")
# This is your solver's code
output = {"status": "completed"}
additional_output_path = Path("additional_output")
additional_output_path.mkdir(exist_ok=True)
logger.info("Generating asset file: summary.txt")
(additional_output_path / "summary.txt").write_text(
"Solver execution completed successfully.",
encoding="utf-8",
)
logger.info("Generating asset file: results.csv")
(additional_output_path / "results.csv").write_text(
"metric,value\nstatus,completed\n",
encoding="utf-8",
)
logger.info("Solver ended.")
return output
Si generas archivos HTML, haz que sean autocontenidos para que puedan abrirse sin dependencias externas.
Instalar requisitos adicionales#
Si necesitas añadir nuevos paquetes a tu solver durante el proceso de desarrollo, recomendamos añadir el nuevo paquete a tu archivo requirements.txt y después volver a ejecutar la instalación del archivo completo:
pip install -r requirements.txt
Así, tu archivo requirements.txt estará actualizado y listo para cuando ejecutes tu solver en la plataforma.
Gestionar excepciones#
Importante
No captures excepciones de forma global en tu solver. Deja que las excepciones bloqueantes se lancen y sean gestionadas por la plataforma, para que la ejecución se detenga y el mensaje de excepción se muestre en el dashboard.
Puedes añadir gestión de excepciones con alcance limitado en el código de tu solver, pero asegúrate de lanzar los errores bloqueantes como excepciones para que la plataforma pueda capturarlos y detener la ejecución.
Puedes revisar estas excepciones en el dashboard, en la página de detalles del job, después de la ejecución.
Añadir logs a tu solver#
Puedes añadir logs en tu solver y verlos en el dashboard web de la plataforma después de cada ejecución.
Tip
Añade tantos logs como quieras, especialmente durante las fases de desarrollo, pruebas y experimentación, para recopilar tanta información como sea posible sobre el rendimiento de tu solver.
Para hacerlo, realiza lo siguiente en cualquiera de los archivos de tu solver:
Primero, importa la librería nativa de Python para logging e inicialízala:
import logging
logger = logging.getLogger("qcentroid-user-log")
Después, añade tantos registros de log como quieras a lo largo del código:
logger.info("Starting solver execution...")
Este es un ejemplo de archivo qcentroid.py que incluye registros de log:
import logging
logger = logging.getLogger("qcentroid-user-log")
def run(input_data, solver_params, extra_arguments):
logger.info("Starting solver execution...")
# This is your solver's code:
input_param_1 = int(input_data['param_1'])
logger.info(f"Input param_1: { input_param_1 }")
output = {"output_param": "This is an output parameter"}
# And this is the output it returns
logger.info("End of solver execution.")
return output
Todos estos registros de log se almacenan y se muestran en el dashboard web, en la página de detalles del job, en la sección Execution logs.
Medir el tiempo de ejecución#
Puedes usar esta funcionalidad de logging para medir el tiempo efectivo de ejecución de tu solver usando la librería time.
Tip
Puedes medir el tiempo de ejecución de tu solver o de cualquier subproceso dentro de tu solver.
Importa la librería nativa de Python time:
import time
Registra el tiempo de inicio y fin, réstalos y envía el resultado al log de ejecución:
start_time = time.time() # Start timing
# The process you want to measure
end_time = time.time() # End timing
elapsed_time = end_time - start_time
logger.info(f"Elapsed time (in seconds): { elapsed_time }")
Ejecutar el solver localmente#
Para ejecutar tu solver localmente durante el proceso de desarrollo y antes de subirlo a la plataforma, ejecuta el script Python app del solver:
python app.py
Subir el código al repositorio#
Cuando tengas una versión funcional de tu solver, haz push del código al repositorio Git.
git commit -a -m "The commit description."
git push
4. Conectar tu repositorio Git con la plataforma#
Ahora que tienes el código fuente de tu solver gestionado en un repositorio, puedes conectar este repositorio con la plataforma. Esto es necesario para permitir que la plataforma acceda al código fuente y pueda ejecutarlo.
Importante
Asegúrate de seguir todos los pasos del proceso siguiente, especialmente el paso 3.d, donde tienes que ir a tu servidor Git (GitHub, por ejemplo) y añadir la Deploy Key proporcionada por la plataforma.
Para conectar un repositorio con la plataforma:
- Ve a la sección Solvers > Repositories desde el menú lateral izquierdo.
- Después, en la esquina superior derecha, haz clic en el botón Connect a new repository.
- Verás el asistente de conexión del repositorio, donde puedes realizar todos los pasos necesarios:
- Selecciona el solver alojado en este repositorio.
- Completa la información del repositorio: nombre y URL SSH (una URL SSH válida en tu servidor Git).
- Genera un par de claves SSH para garantizar un acceso controlado y seguro a tu código.
- Ve a tu servidor Git: Your repository > Settings > Deploy keys y añade la clave generada.
- Haz clic en el botón Connect al final del asistente para completar el proceso.
En este momento, tu repositorio está conectado y solo tienes que esperar a que el proceso finalice.
Verás tu nuevo repositorio marcado como Connected cuando termine.
5. Pull del nuevo código del solver#
Ahora que tienes el código fuente de tu solver gestionado en un repositorio, puedes hacer Pull and build en la plataforma para poder ejecutar jobs con él.
Ve a la página de detalle del Repository desde el menú lateral izquierdo y haz clic en el botón Pull junto a tu solver.
Debajo puedes consultar el historial de pulls. Espera hasta que este proceso aparezca como Finished y asegúrate de que el commit descargado sea el que acabas de subir al servidor Git.
Ahora, tu solver está listo para ejecutar jobs en la plataforma.
6. Ejecutar tu solver en la plataforma#
El último paso será ejecutar en la plataforma el solver que acabas de crear.
Ve al siguiente artículo para ver cómo hacerlo: