Saltar al contenido principal

Empieza con Qiskit Functions

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime
# This cell is hidden from users
# It gets these details programmatically so we can test this notebook
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.circuit.random import random_circuit
from qiskit_ibm_catalog import QiskitFunctionsCatalog

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name
catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")
qesem_function = catalog.load("qedma/qesem")
circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

Los usuarios de los planes Premium, Flex y On-Prem (a través de la API de IBM Quantum Platform) pueden empezar a usar Qiskit Functions de IBM gratuitamente, o pueden adquirir una licencia de uno de los socios que han contribuido con una función al catálogo.

Solicita una prueba gratuita para Qiskit Functions de terceros​

Para solicitar una prueba gratuita, ve al Catálogo de Qiskit Functions y explora el panel de detalles. Haz clic en Request a free trial y completa la información requerida por el socio de Functions, incluido el AccessGroupId de IBM Cloud:

  1. Ve a IBM Cloud IAM.

  2. Verifica la elegibilidad.

    • Cambia tu cuenta en el menú de la cabecera a una con el siguiente formato: XXXXXXX - [Organization Name]

    • Asegúrate de que la organización sea la misma que la asociada a tu cuenta Premium.

    • Si ves "[Your Name]'s Account", estás usando tu cuenta personal, que no es elegible para el acceso premium.

  3. Encuentra el ID de tu grupo de acceso.

    • Haz clic en un nombre de grupo.

    • Haz clic en Details.

    • Copia el ID del grupo de acceso. Debe comenzar con AccessGroup-.

Instala el cliente del Catálogo de Qiskit Functions​

  1. Para empezar a usar Qiskit Functions, instala el cliente del Catálogo de Qiskit Functions de IBM:

    pip install qiskit-ibm-catalog

  2. Obtén tu clave de API desde el panel de IBM Quantum Platform, y activa tu entorno virtual de Python. Consulta las instrucciones de instalación si aún no tienes un entorno virtual configurado.

    If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the save_account() method to save your credentials locally. (Skip to the next step if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)

    La instancia con la que te autentiques debe tener habilitado el acceso a Qiskit Functions. Para configurarlo en una instancia existente, consulta Configurar el acceso a Qiskit Functions en una instancia.

    Para usar save_account(), ejecuta python en tu shell y luego introduce lo siguiente:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

    QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

    Escribe exit(). A partir de ahora, cada vez que necesites autenticarte en el servicio, puedes cargar tus credenciales con lo siguiente:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()

    Por ejemplo:

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks. If you must use an untrusted environment (on, for example, a public computer), change your API key after each use by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic. To initialize the service in this situation, use this code:

from qiskit_ibm_catalog import QiskitFunctionsCatalog

# After using the following code, delete your API key on the
# IBM Quantum Platform home dashboard
catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character
# API_KEY you created and saved from the IBM Quantum Platform Home dashboard
Protege tu clave de API

Nunca incluyas tu clave en el código fuente, scripts de Python o archivos de notebook. Al compartir código con otras personas, asegúrate de que tu clave de API no esté incrustada directamente en el script de Python. En su lugar, comparte el script sin la clave y proporciona instrucciones para configurarla de forma segura.

Si compartes accidentalmente tu clave con alguien o la incluyes en un sistema de control de versiones como Git, revoca inmediatamente tu clave eliminándola en la página de claves de API de IBM Cloud para reducir el riesgo. Aprende más en el tema Gestión de claves de API de usuario.

Lista las funciones a las que puedes acceder​

Después de autenticarte, puedes listar las funciones del Catálogo de Qiskit Functions a las que tienes acceso:

catalog.list()
[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

Ejecuta funciones habilitadas​

Después de instanciar un objeto de catálogo, puedes seleccionar una función usando catalog.load("<provider/function-name>"):

qesem_function = catalog.load("qedma/qesem")

Cada Qiskit Function tiene entradas, opciones y salidas personalizadas. Consulta las páginas de documentación específicas de la función que quieres ejecutar para obtener más información. Por defecto, todos los usuarios solo pueden ejecutar un trabajo de función a la vez:

from qiskit.quantum_info import SparsePauliOp

avg_magnetization = SparsePauliOp.from_sparse_list(
    [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5
)

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)
job.job_id
'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'
consejo

run() comprueba tu capacidad restante y el acceso al backend antes de enviar el trabajo. Si tu instancia se ha quedado sin capacidad, o el backend que has indicado no es accesible, run() genera un error de inmediato en lugar de dejar que el trabajo falle en la cola. Cuando la capacidad es baja, run() emite una advertencia. Pasa suppress_low_usage_warning=True para silenciarla.

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    suppress_low_usage_warning=True,
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)

Comprueba el estado del trabajo​

Con el job_id de tu Qiskit Function, puedes comprobar el estado de los trabajos en ejecución. Esto incluye los siguientes estados:

  • QUEUED: El programa remoto está en la cola de Qiskit Functions. La prioridad de la cola se basa en cuánto has usado Qiskit Functions.

  • INITIALIZING: El programa remoto se está iniciando; esto incluye configurar el entorno remoto e instalar dependencias.

  • RUNNING: El programa se está ejecutando. Esto también incluye varios estados más detallados si son compatibles con funciones específicas.

    • RUNNING: MAPPING: La función está mapeando actualmente tus entradas clásicas a entradas cuánticas.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: La función se está optimizando para la QPU seleccionada. Esto puede incluir transpilación de circuitos, caracterización de la QPU, retropropagación de observables, etc.

    • RUNNING: WAITING_FOR_QPU: La función ha enviado un trabajo al Servicio de Cómputo Cuántico de IBM, y está esperando en la cola.

    • RUNNING: EXECUTING_QPU: La función tiene un trabajo activo de Cómputo Cuántico.

    • RUNNING: POST_PROCESSING: La función está postprocesando resultados, lo que puede incluir mitigación de errores, mapeo de resultados cuánticos a clásicos, etc.

  • DONE: El programa se ha completado, y puedes obtener los datos de resultado con job.result().

  • ERROR: El programa dejó de ejecutarse debido a un problema. Usa job.result() para obtener el mensaje de error.

  • CANCELED: El programa fue cancelado por un usuario, el servicio o el servidor.

job.status()
'QUEUED'

Recupera resultados​

Después de que un programa esté DONE, puedes usar job.result() para obtener el resultado. Este formato de salida varía según cada función, así que asegúrate de seguir la documentación específica:

result = job.result()
print(result)
PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': True, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

También puedes cancelar un trabajo en cualquier momento:

job.cancel()
'Job has been stopped.'

Accede a los trabajos de Cómputo Cuántico asociados​

Una Qiskit Function puede enviar uno o más trabajos de Cómputo Cuántico a una QPU mientras se ejecuta. Para obtener los ID de esos trabajos de tiempo de ejecución, usa job.runtime_jobs(). Puedes usar estos ID para obtener los objetos de trabajo de tiempo de ejecución desde una instancia de QiskitRuntimeService, o para encontrar las cargas de trabajo en el panel de IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Si una función agrupa sus trabajos de tiempo de ejecución en sesiones o lotes, usa job.runtime_sessions() para listar los ID de sesión. Pasa un ID de sesión a job.runtime_jobs() para devolver solo los trabajos de tiempo de ejecución de esa sesión:

sessions = job.runtime_sessions()
if sessions:
    session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])
    print(session_runtime_jobs)
else:
    print("No runtime sessions for this job.")
nota

La lista devuelta puede estar vacía. Una función informa de sus trabajos de runtime solo cuando los envía a través del servicio de runtime que la función recibe en tiempo de ejecución, y algunas funciones no envían trabajos de runtime directamente.

Ver registros del trabajo​

Usa job.logs() para obtener el registro de salida que produce una función mientras se ejecuta. Los registros son útiles para hacer seguimiento del progreso y para depurar un trabajo que termina en un estado ERROR.

print(job.logs().splitlines())

Para un trabajo de larga duración que produce muchas líneas de registro, usa job.filtered_logs() para devolver solo las líneas que quieres. Pasa una expresión regular a include para mantener las líneas coincidentes, o a exclude para descartar las líneas coincidentes:

print(job.filtered_logs(include="iteration"))

Lista los trabajos de Qiskit Functions ejecutados previamente​

Puedes usar jobs() para listar todos los trabajos enviados a Qiskit Functions:

old_jobs = catalog.jobs()
old_jobs
[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

Para acotar los resultados, pasa filtros. Filtra por función con function, por estado con status, y por fecha de envío con created_after. Recorre los resultados con limit y offset:

recent_errors = catalog.jobs(
    function=qesem_function,
    status="ERROR",
    created_after="2024-01-01T00:00:00Z",
    limit=5,
)
recent_errors

Si ya tienes el ID de trabajo de un trabajo determinado, puedes obtenerlo con catalog.job():

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with `catalog.job`
job_by_id = catalog.job(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)
f6c29f49-4d5f-4fff-aca6-2e9a115b9763

Obtén mensajes de error​

Si el estado de un programa es ERROR, usa job.error_message() para obtener el mensaje de error de la siguiente manera:

job.error_message()
qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

Próximos pasos​

Recomendaciones
Fuente: IBM Quantum docs — actualizado el 3 sept 2026
Versión en inglés en doQumentation — actualizado el 3 sept 2026
¿Problema con el sitio o la traducción?¿Problema de contenido? Editar en IBM Quantum docs