Usar la Plataforma#

Acceso a la Plataforma#

La Plataforma QCentroid es accesible a través de esta URL: https://app.sandbox.qcentroid.com/

Usa tu dirección de correo electrónico y contraseña para acceder.

Conceptos clave#

Antes de empezar, estos son los conceptos que se usan habitualmente en la plataforma:

Caso de uso. El problema de optimización o simulación que se quiere resolver con un algoritmo.
Solver. El algoritmo que resuelve el caso de uso. Puede ser cuántico o clásico.
Repositorio. Referencia a un repositorio Git donde se almacena el código fuente del solver.
Job. Una ejecución concreta de uno o varios solvers sobre un caso de uso con unos datos de entrada.
Dataset. Archivo de datos de entrada en formato JSON que se proporciona al solver al ejecutar un job.
Executor. Por cada solver ejecutado en un job, se lanza un executor. Cuando todos los executors finalizan, el job queda completado.
Crédito. Unidad de facturación de la plataforma. Cada ejecución de un job consume créditos en función del proveedor de hardware y el tiempo de ejecución.

Créditos#

Tu organización tiene asignada una bolsa de créditos. Cada ejecución de un job descuenta créditos de esa bolsa según el coste estimado del solver utilizado.

Ver y reasignar créditos#

Para consultar el saldo de créditos o reasignarlos entre los usuarios de tu organización:

Haz clic en el menú de usuario (esquina superior derecha de la plataforma).
Selecciona la sección Credits.
Desde aquí podrás ver el saldo total disponible y redistribuir créditos entre los miembros de tu equipo.

Consejo

Revisa el saldo de créditos antes de lanzar ejecuciones intensivas. Si un job no tiene créditos suficientes asignados al usuario, la ejecución será rechazada.

Tutorial: Hello World#

Este tutorial te guía paso a paso por el flujo completo de la plataforma: crear un caso de uso, registrar un solver, conectar tu repositorio y ejecutar tu primer job.

Paso 1 — Crea tu primer caso de uso#

Ve a Use cases > My use cases en el menú lateral izquierdo.
Haz clic en Add new use case (esquina superior derecha).
Completa el formulario con la información obligatoria:
- Business sector: selecciona cualquier sector, por ejemplo Academic.
- Name: My first use case
- Description: Hello world use case used for learning purposes.
- URN: my-first-use-case (sin espacios ni caracteres especiales)
- Visibility: privado por defecto.
Haz clic en Add use case.

Serás redirigido a la página de detalle del caso de uso. Puedes completar las pestañas de Business information y Technical details más adelante; para este tutorial puedes dejarlas vacías.

Paso 2 — Registra tu primer solver#

Ve a Solvers > My solvers en el menú lateral izquierdo.
Haz clic en Add new solver y selecciona Code repository.
Sigue el asistente:
- Caso de uso: selecciona My first use case.
- Proveedor: selecciona No SDK y Classical CPU (o el proveedor asignado a tu equipo en BIQAIN).
- Nombre: My first solver
- Description: Hello world solver for learning purposes.
- URN: my-first-solver
- Branch/tag: main
- Programming language: Python
Haz clic en Add new solver.

Paso 3 — Implementa el solver#

Puedes implementar tu solver como prefieras: con VS Code en local, en el LaunchPad, con Jupyter Notebooks, o cualquier otro entorno. Puedes usar los SDKs de los proveedores de hardware, cualquier librería de Python, y estructurar el código en los módulos y archivos que necesites.

Para que tu solver funcione en la plataforma QCentroid, adicionalmente necesitas incluir estos dos archivos en la raíz del repositorio:

qcentroid.py#

Este archivo es el entrypoint de tu solver. Cuando se ejecuta un job, la plataforma busca este archivo en la raíz del repositorio, localiza la función run() y la ejecuta, pasándole los datos de entrada y los parámetros del job. Todo tu código debe poder invocarse desde esta función, ya sea directamente o llamando a otros módulos propios.

Copia el siguiente contenido, crea un archivo llamado qcentroid.py en la raíz de tu repositorio y pégalo:

qcentroid.py

import logging
logger = logging.getLogger("qcentroid-user-log")

def run(input_data: dict, solver_params: dict, extra_arguments: dict) -> dict:

    logger.info("Iniciando solver...")

    # Aquí va tu código

    output = {"message": "Hello world!"}

    logger.info("Solver finalizado.")
    return output

El objeto logger usa el sistema de logging estándar de Python y está preconfigurado para que la plataforma capture sus mensajes. Puedes llamar a logger.info(), logger.warning() o logger.error() en cualquier punto del código y los mensajes aparecerán en la pestaña Execution logs de la página de detalle del job tras cada ejecución.

Añade logs desde el primer momento

No esperes a que algo falle para añadir logs. Registra los valores de entrada, los pasos intermedios y los tiempos de ejecución desde el principio. En un entorno de experimentación como este, la visibilidad del comportamiento interno del solver vale más que unas líneas de código extra.

Sobre las excepciones

Evita capturar excepciones de forma global en tu solver (por ejemplo con un except Exception en el nivel raíz). Si una excepción se captura y no se relanza, la plataforma no puede detectar que el solver ha fallado y no mostrará la traza de error en la página de detalles del job. Deja escalar los errores bloqueantes para que la plataforma los capture y los muestre correctamente.

requirements.txt#

Si necesitas librerías adicionales, añádelas en un archivo requirements.txt en la raíz del repositorio siguiendo el formato de pip:

requirements.txt

ortools

Sobre el requirements.txt

Incluye solo las librerías que tu código importa directamente, con la versión lo más abierta posible (por ejemplo ortools en lugar de ortools==9.7.2996). Evita hacer un pip freeze y copiar el resultado: ese archivo incluye cientos de dependencias transitivas con versiones fijas que pueden entrar en conflicto en el entorno de la plataforma.

Crea un repositorio Git, sube estos archivos y anota la URL SSH del repositorio.

Paso 4 — Conecta el repositorio con la plataforma#

La plataforma QCentroid no almacena el código de tu solver: el código vive en tu propio repositorio Git y la plataforma lo descarga cada vez que lanzas un build. Esto significa que tienes control total sobre el código, puedes usar las herramientas de desarrollo que prefieras y el historial de versiones queda en tu servidor Git.

Para que la plataforma pueda acceder al repositorio, es necesario conectarlo explícitamente mediante una Deploy key — una clave SSH de solo lectura que autorizas en tu servidor Git. La plataforma genera este par de claves automáticamente durante el proceso de conexión.

La plataforma es compatible con cualquier servidor Git accesible por SSH o HTTPS, incluyendo GitHub, GitLab, Bitbucket y servidores Git propios (Gitea, Forgejo, GitLab self-hosted, etc.). Puedes usar tanto la URL SSH (del tipo git@github.com:usuario/repositorio.git) como la URL HTTPS (del tipo https://github.com/usuario/repositorio.git).

Importante

Sigue todos los pasos del asistente, especialmente el paso de añadir la Deploy Key en tu servidor Git. Sin este paso la plataforma no podrá acceder al código.

Ve a Solvers > Repositories en el menú lateral.
Haz clic en Connect a new repository.
Selecciona el solver My first solver e introduce la URL SSH de tu repositorio.
La plataforma generará un par de claves SSH automáticamente.
Copia la clave pública generada y añádela como Deploy key en tu servidor Git:

Permisos necesarios

Para añadir una Deploy key necesitas tener permisos de administrador sobre el repositorio. Si no los tienes, pide al propietario del repositorio que realice este paso.
- En GitHub: Settings > Deploy keys > Add deploy key
- En GitLab: Settings > Repository > Deploy keys
- En Bitbucket: Repository settings > Access keys > Add key
Vuelve a la plataforma y haz clic en Connect para completar el proceso.

Al conectar, se lanzará automáticamente el primer proceso de build del solver.

Durante este proceso la plataforma validará que el entrypoint existe — es decir, que el repositorio contiene el archivo qcentroid.py con la función run(). Si no lo encuentra, mostrará un error o aviso en el historial de builds que deberás resolver antes de poder ejecutar jobs.

Paso 5 — Construir el solver#

Cada vez que actualices el código del solver, deberás reconstruirlo en la plataforma.

Ve a la sección con el listado de repositorios (Solvers > Repositories), haz clic en tu repositorio y pulsa el botón Build junto al solver que quieres construir.

Espera a que el proceso aparezca como Finished y verifica que el commit descargado es el correcto.

Tu solver ya está listo para ejecutarse en jobs.

Paso 6 — Ejecuta tu primer job#

Ve a la sección Jobs en el menú principal.
Haz clic en Run job y sigue el asistente:
1. Selecciona el caso de uso My first use case.
2. Arrastra My first solver al panel de la derecha.
3. En la pestaña JSON input, introduce los datos de entrada:
```
{"my-input": "hello"}
```
4. Configura los parámetros del job:
  - Título: escribe un nombre para identificar esta ejecución.
  - Hardware clásico: selecciona los recursos de CPU/RAM que se asignarán al solver.
  - Device del proveedor cuántico: si tu solver utiliza hardware cuántico, selecciona aquí el dispositivo del proveedor (QPU, simulador, etc.). Para este tutorial puedes dejarlo por defecto.
5. Revisa el resumen y haz clic en Execute job.

Recibirás una notificación confirmando que el job se ha lanzado. Espera a que aparezca en estado Finished.

Job lanzado correctamente

Paso 7 — Explora los resultados#

Ve a la sección Jobs y haz clic sobre el job ejecutado.
En la página de detalle verás todas las secciones con la información del job.
En la pestaña Raw results verás la salida de tu solver:
```
{"message": "Hello world!"}
```

Las secciones disponibles en la página de detalle del job son:

Sección	Contenido
Benchmark results	Tiempo de ejecución, coste y métricas de comparación
Detailed results	Información detallada de los resultados del solver
Input data	Los datos de entrada usados en este job
Executors	Metadatos de cada solver ejecutado
Raw results	Salida en bruto del solver (descargable)
Assets	Archivos de salida adicionales generados por el solver
Execution logs	Logs de depuración emitidos por el solver

Buenas prácticas#

Ejecuta jobs en la plataforma cada vez que tengas una versión estable de tu algoritmo, no solo al final.
Añade logs en tu solver con logger.info(...) para facilitar la depuración desde la pestaña Execution logs.
Lanza el Build después de cada push de código para que la plataforma use la versión más reciente.
Empieza con simuladores y datasets pequeños. Antes de usar recursos cuánticos reales o hardware de mayor coste, valida tu solver con simuladores y datos reducidos. Esto te permitirá detectar errores rápidamente y tener una estimación realista del coste y el tiempo de ejecución antes de escalar a recursos más costosos.