quantum-serverless/client
Goyo 28fcf0db24
fix pretty error bug (#1668)
2025-06-27 07:54:26 -04:00
..
qiskit_serverless fix pretty error bug (#1668) 2025-06-27 07:54:26 -04:00
tests Prettify error message on jobs (#1662) 2025-06-24 12:42:11 +02:00
.pylintrc Rename function.get_jobs to function.jobs and make it return Job objects (#1480) 2024-09-11 11:09:10 -04:00
README.md Extend Python version support in serverless client (#1638) 2025-05-23 09:40:30 -04:00
mypy.ini Quantum Serverless initial implementation (#1) 2022-09-19 09:31:56 -04:00
pyproject.toml Extend Python version support in serverless client (#1638) 2025-05-23 09:40:30 -04:00
requirements-dev.txt Update nbsphinx package (#1629) 2025-05-06 10:43:36 +02:00
requirements.txt Include qpy-compat option from Qsikit 2.1.0 (#1663) 2025-06-23 13:23:38 -04:00
setup.cfg Update README.md (#43) 2022-10-31 14:35:41 -04:00
setup.py Extend Python version support in serverless client (#1638) 2025-05-23 09:40:30 -04:00
tox.ini Extend Python version support in serverless client (#1638) 2025-05-23 09:40:30 -04:00

README.md

Stability Client verify process License Code style: Black Python Qiskit

Qiskit Serverless client

diagram

Installation

To install the latest release of the client, run:

pip install qiskit-serverless

To install an editable package from source, run:

pip install -r requirements.txt -r requirements-dev.txt
pip install -e .

Documentation

Full docs can be found at https://qiskit.github.io/qiskit-serverless/

Usage

Step 1: write funtion in ./src/function.py

from qiskit_serverless import distribute_task, get, get_arguments, save_result

from qiskit import QuantumCircuit
from qiskit.circuit.random import random_circuit
from qiskit.primitives import StatevectorSampler as Sampler
from qiskit.quantum_info import SparsePauliOp

# 1. let's annotate out function to convert it
# to distributed async function
# using `distribute_task` decorator
@distribute_task()
def distributed_sample(circuit: QuantumCircuit):
    """Calculates quasi dists as a distributed function."""
    return Sampler().run([(circuit)]).result()[0].data.meas.get_counts()

# 2. our program will have one arguments
# `circuits` which will store list of circuits
# we want to sample in parallel.
# Let's use `get_arguments` funciton
# to access all program arguments
arguments = get_arguments()
circuits = arguments.get("circuits", [])

# 3. run our functions in a loop
# and get execution references back
function_references = [
    distributed_sample(circuit)
    for circuit in circuits
]

# 4. `get` function will collect all
# results from distributed functions
collected_results = get(function_references)

# 5. `save_result` will save results of program execution
# so we can access it later
save_result({
    "quasi_dists": collected_results
})

Step 2: run function

from qiskit_serverless import ServerlessClient, QiskitFunction
from qiskit.circuit.random import random_circuit

client = ServerlessClient(
    token="<TOKEN>",
    host="<GATEWAY_ADDRESS>",
)

# create function
function = QiskitFunction(
    title="Quickstart",
    entrypoint="program.py",
    working_dir="./src"
)
client.upload(function)

# create inputs to our program
circuits = []
for _ in range(3):
    circuit = random_circuit(3, 2)
    circuit.measure_all()
    circuits.append(circuit)

# run program
my_function = client.get("Quickstart")
job = my_function.run(circuits=circuits)

Step 3: monitor job status

job.status()
# 'DONE'

# or get logs
job.logs()

Step 4: get results

job.result()
# {'quasi_dists': [
# {'101': 902, '011': 66, '110': 2, '111': 37, '100': 17},
# {'100': 626, '101': 267, '001': 49, '000': 82},
# {'010': 145, '100': 126, '011': 127, '001': 89, '110': 173, '111': 166, '000': 94, '101': 104}
# ]}