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.

Documentación del caso de uso#

Esta es la parte obligatoria de la plataforma: lo que toda organización del hub debe completar para cada uno de sus casos de uso. Se resume en tres elementos:

Business Information — la documentación del caso de uso.
Business Impact — las métricas de impacto.
Showcase — el seguimiento del progreso.

Con estos tres elementos, tu caso de uso queda listo para el reporting a Gaia y Red.es.

Fechas clave

Antes del 15 de julio — casos de uso dados de alta en la plataforma, con la información mínima de negocio cargada.
Antes del 20 de julio — métricas de impacto y seguimiento (KPIs) introducidas: la primera foto del estado de cada caso.

A partir de ahí, el seguimiento avanza por fases: evaluación inicial (julio), seguimiento intermedio (septiembre) y evaluación final (diciembre).

1. Business Information#

Es el primer paso y el imprescindible: documentar el caso de uso. Cada organización completa la plantilla de su caso directamente en la plataforma. Los campos guía están disponibles en español, así que te van orientando sobre qué escribir en cada apartado.

No hace falta rellenarlo todo de una vez; lo importante es tener la información mínima cargada para la fecha indicada.

Tu caso de uso ya está creado

No tienes que darlo de alta: al entrar en la plataforma encontrarás tu caso de uso ya creado y listo para rellenar. Ve a Use cases > My use cases en el menú lateral izquierdo, ábrelo y completa la pestaña Business information.

La plantilla de Business Information incluye:

Business description — descripción del problema de negocio: contexto, objetivo y valor esperado.
Limitations & Opportunities — restricciones del problema y oportunidades de mejora.
Input & Output Data — qué datos entran y qué resultados se esperan.
Best practices — benchmarks y referencias contra las que comparar.
Regulatory framework — marco regulatorio y consideraciones legales aplicables.

Empieza por la descripción de negocio

Si no sabes por dónde empezar, completa primero la Business description. Es la que da contexto al resto de apartados.

2. Business Impact#

El segundo paso es medir el impacto del caso de uso. Aquí se registran las métricas que constituyen la base del reporting a Gaia y Red.es, y que permiten evidenciar cómo evoluciona la madurez del caso a lo largo del proyecto.

Las métricas de impacto son:

Priority — prioridad de negocio del caso (valores más altos = mayor prioridad a corto plazo).
Business impact — impacto del caso de uso en el negocio de la organización.
Complexity — complejidad general del problema.
Time/Effort to implement — dificultad estimada de implementar una solución.
Data availability — si los datos de entrada necesarios ya están disponibles.
Quantum Feasibility — en qué horizonte las tecnologías cuánticas podrán resolver el problema (valores más altos = viable a más corto plazo).

Cómo introducirlas:

Abre tu caso de uso y ve a la pestaña Business impact.
Selecciona la subpestaña Impact metrics.
Ajusta cada métrica según tu caso.

Puntuación aproximada

Si tienes dudas sobre cómo puntuar alguna métrica, déjala en un valor aproximado y ajústala más adelante conforme avance el caso.

3. Showcase#

El tercer elemento es el seguimiento del progreso. En la pestaña Showcase se visualiza el avance de cada caso de uso a lo largo del proyecto, con los KPIs organizados por fases. Es el elemento que hace visible tu progreso ante el hub, y se actualiza conforme avanzas.

Qué muestra el Showcase:

Un resumen de indicadores con el estado de cada KPI (verde / amarillo / rojo / sin dato).
Un dashboard de KPIs GAIA con el seguimiento trimestral de los indicadores (generales y de soporte).
La evolución de indicadores como el Quantum Adjusted Project Value (QAPV), Q-TRL, Quantum Readiness Index (QRI), entre otros.

Cómo actualizar el avance:

Abre tu caso de uso y ve a la pestaña Showcase.
Haz clic en el botón Edit para habilitar la edición de los KPIs.
Introduce o actualiza los valores de los KPIs correspondientes al periodo.
Guarda los cambios: el progreso se refleja en el dashboard y en la fecha de última actualización.

Mantén el Showcase al día

El Showcase es lo que ve el hub para valorar el avance del proyecto. Actualizarlo en cada fase (julio, septiembre, diciembre) es lo que mantiene tu caso “vivo” de cara al reporting.

El avance de los KPIs se representa también en visualizaciones que facilitan seguir la evolución del caso a lo largo del proyecto:

Con estos tres elementos — Business Information, Business Impact y Showcase — tu caso de uso está listo para el reporting.

Opciones avanzadas#

Todo lo anterior es lo obligatorio. Esta sección es opcional: está disponible para las organizaciones que quieran ir más allá de la documentación y experimentar con la ejecución de algoritmos. Si por ahora solo necesitas documentar tu caso, puedes saltarte esta sección.

Uso opcional

Nada de lo que sigue es necesario para cumplir con el reporting del hub. Es para quien quiera aprovechar la plataforma como entorno de experimentación.

2.1 Registrar y ejecutar solvers#

La plataforma permite registrar tus propios solvers (algoritmos clásicos, cuánticos o híbridos) y ejecutarlos sobre tu caso de uso. Puedes ejecutar varios solvers sobre el mismo caso y compararlos en igualdad de condiciones: tiempo de ejecución, coste y calidad de la solución.

El flujo completo (registrar un solver, conectar tu repositorio de código, construirlo y lanzar un job) está detallado paso a paso en el Tutorial completo al final de esta página.

2.2 Backends, GPUs y benchmarking#

Al ejecutar un solver puedes elegir sobre qué backend de hardware se ejecuta:

Hardware clásico — recursos de CPU/RAM asignados al solver.
GPUs clásicas y cuánticas.
Dispositivos de proveedores cuánticos (QPU, simuladores) a través de los proveedores habilitados para tu equipo.

Ejecutar el mismo caso sobre distintos backends permite hacer benchmarking: comparar rendimiento, coste y calidad de resultado entre enfoques y proveedores, con datos objetivos en lugar de estimaciones.

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. Detectarás errores rápido y tendrás una estimación realista de coste y tiempo antes de escalar.

2.3 Cargar datos de ejecuciones externas#

Si prefieres ejecutar tus algoritmos en tu propio entorno, también puedes subir los resultados a la plataforma para tenerlo todo centralizado y comparable junto al resto de ejecuciones.

Cómo importar una ejecución externa:

Ve a Jobs y entra en el job correspondiente (o crea uno).
Abre la opción Import executor.
Indica el caso de uso, el solver utilizado, el coste y la duración de la ejecución.
Adjunta el archivo de datos de salida en formato JSON (debe cumplir el formato de salida del problema) y, opcionalmente, el log de ejecución.

2.4 Agentes IA para descubrir nuevos casos de uso#

La plataforma incluye agentes de IA que, a partir del contexto de negocio de tu organización, te ayudan a identificar nuevos casos de uso con potencial cuántico. Es útil cuando quieras ampliar tu cartera más allá de los casos que ya tienes documentados.

El asistente hace preguntas sobre tu sector y área de actividad, y genera una lista editable de casos candidatos que puedes guardar y priorizar.

2.5 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:

Haz clic en el menú de usuario (esquina superior derecha).
Selecciona la sección Credits.
Consulta el saldo total disponible y redistribuye créditos entre los miembros de tu equipo.

Revisa el saldo antes de ejecuciones intensivas

Si un job no tiene créditos suficientes asignados al usuario, la ejecución será rechazada.

Asignación de créditos de computación cuántica

Los créditos para computación cuántica se valoran caso por caso.

Referencia de conceptos#

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 finalizan, el job queda completado.
Crédito — unidad de facturación de la plataforma. Cada ejecución consume créditos según el proveedor de hardware y el tiempo de ejecución.

Tutorial completo: de cero a un job#

Este tutorial recorre el flujo técnico completo de la plataforma: crear un caso de uso, registrar un solver, implementarlo, conectar tu repositorio, construirlo y ejecutar tu primer job. Es un recorrido opcional y orientado a perfiles técnicos; no es necesario para cumplir con la documentación obligatoria del hub.

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 GAIA).
- 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, 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.