Write your first Qiskit Serverless program

• Package versions

  The code on this page was developed using the following requirements. We recommend using these versions or newer.

  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 upload your program to IBM Quantum Platform to use as a reusable remote service.

Workflow overview

1. Create a local directory and empty program file (./source_files/transpile_remote.py)
2. Add code to your program that, when uploaded to Qiskit Serverless, will transpile a circuit
3. Use qiskit-ibm-catalog to authenticate to Qiskit Serverless
4. Upload the program to Qiskit Serverless

Once you have completed the workflow steps above, you can then run your uploaded program to transpile the circuit by following the Run your first Qiskit Serverless workload remotely guide.

Example: Remote transpilation with Qiskit Serverless

This example walks you through creating and adding to a program file that, when you upload it to Qiskit Serverless, will transpile a circuit against a given backend and target optimization_level.

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

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.

Create the directory and an empty program file

First, create a directory named source_files, then create a program file in the directory, so that its path is ./source_files/transpile_remote.py. This is the file you will upload to Qiskit Serverless.

Add code to your program file

Populate your program file with the following code, then save it.

# This cell is hidden from users, it just creates a new folder
from pathlib import Path
 
Path("./source_files").mkdir(exist_ok=True)

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

Add code to get program arguments

Now add the following code to your program file, which sets up 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.

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")

Add code that calls the backend

Add the following code to your program file, which calls your backend with QiskitRuntimeService.

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)

Add code to transpile

Finally, add the following code to your program file. This code runs 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
})

Authenticate to Qiskit Serverless

Use qiskit-ibm-catalog to authenticate to QiskitServerless with your API key (you can use your QiskitRuntimeService API key, or 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()

Run code to upload

Run the following code to 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)

Verify upload

To check if it successfully uploaded, use serverless.list(), as in the following code:

# 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