Write your first Qiskit Serverless program

qiskit[all]~=1.3.1
qiskit-ibm-runtime~=0.34.0
qiskit-aer~=0.15.1
qiskit-serverless~=0.18.1
qiskit-ibm-catalog~=0.2
qiskit-addon-sqd~=0.8.1
qiskit-addon-utils~=0.1.0
qiskit-addon-mpf~=0.2.0
qiskit-addon-aqc-tensor~=0.1.2
qiskit-addon-obp~=0.1.0
scipy~=1.15.0
pyscf~=2.8.0

This example demonstrates how to use qiskit-serverless tools to create a parallel transpilation program, and then implement qiskit-ibm-catalog to deploy your program to IBM Quantum Platform to use as a reusable remote service.

Workflow overview:

1. Create local program file that transpiles a circuit
2. Add code to your program to receive inputs (circuits, backend_name, and optimization_level)
3. Authenticate to the Qiskit Runtime service and load a backend
4. Use qiskit-ibm-catalog to authenticate to Qiskit Serverless
5. Upload the program result
6. Run the program

Example: remote transpilation with Qiskit Serverless

Start with the following example that transpiles a circuit against a given backend and target optimization_level, and gradually add more elements to deploy your workload to Qiskit Serverless.

Serverless uploads the contents of a specific directory (in this example, the source_files directory) to run remotely. Once these are set up, you can adjust transpile_remote.py to fetch inputs and return outputs.

serverless_program
├── program_uploader.ipynb
└── source_files
    ├── transpile_remote.py
    └── *.py

First, run the following code cell to create a program file, ./source_files/transpile_remote.py, which you will upload to Qiskit Serverless.

from qiskit.transpiler import generate_preset_pass_manager
 
def transpile_remote(circuit, optimization_level, backend):
    """Transpiles an abstract circuit into an ISA circuit for a given backend."""
    pass_manager = generate_preset_pass_manager(
        optimization_level=optimization_level,
		backend=backend
    )
    isa_circuit = pass_manager.run(circuit)
    return isa_circuit

Get program arguments

Your initial transpile_remote.py has three inputs: circuits, backend_name, and optimization_level. Serverless is currently limited to only accept serializable inputs and outputs. For this reason, you cannot pass in backend directly, so use backend_name as a string instead.

The following cell appends code to your transpile_remote.py file.

from qiskit_serverless import get_arguments, save_result, distribute_task, get
 
# Get program arguments
arguments = get_arguments()
circuits = arguments.get("circuits")
backend_name = arguments.get("backend_name")
optimization_level = arguments.get("optimization_level")

At this point, you can get your backend with QiskitRuntimeService and add your existing program with the following code.

The following code assumes that you have already followed the process to save your credentials by using QiskitRuntimeService.save_account, and will load your default saved account unless you specify otherwise. See Save your login credentials and Initialize your Qiskit Runtime service account for more information.

from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService()
backend = service.backend(backend_name)

Finally, you can run transpile_remote() across all circuits passed in, and return the transpiled_circuits as a result:

# Each circuit is being transpiled and will populate the array
%%writefile --append ./source_files/transpile_remote.py
 
results = [
    transpile_remote(circuit, 1, backend)
    for circuit in circuits
]
 
save_result({
    "transpiled_circuits": results
})

Output:

Appending to ./source_files/transpile_remote.py

Upload to Qiskit Serverless

The previous section created a program to be run remotely. The following code cells upload that program to Qiskit Serverless, before running the workload (which is demonstrated in the Run your first Qiskit Serverless workload remotely guide).

Use qiskit-ibm-catalog to authenticate to QiskitServerless with your API key (use your same key as before, or you can create a new API key on the IBM Quantum Platform dashboard).

from qiskit_ibm_catalog import QiskitServerless, QiskitFunction
 
# Authenticate to the remote cluster and submit the pattern for remote execution
serverless = QiskitServerless()

Now you can upload the program. Qiskit Serverless compresses the contents of working_dir (in this case, source_files) into a tar, which is uploaded and cleaned up after. The entrypoint identifies the main program executable for Qiskit Serverless to run.

transpile_remote_demo = QiskitFunction(
    title="transpile_remote_serverless",
    entrypoint="transpile_remote.py",
    working_dir="./source_files/",
)

serverless.upload(transpile_remote_demo)

Output:

QiskitFunction(transpile_remote_serverless)

To check if it successfully uploaded, use serverless.list():

# Get program from serverless.list() that matches the title of the one we uploaded
next(
    program
    for program in serverless.list()
    if program.title == "transpile_remote_serverless"
)

Output:

QiskitFunction(transpile_remote_serverless)

Next steps