import { FileTree } from 'nextra/components'
import { useConfig } from 'nextra-theme-docs'
import Author from '../../components/ui/author'

# Running Dynamiqs Workloads on Qubernetes

<Author author={useConfig().frontMatter.author} />

Published on October 25, 2025.

This week I have attended the [Munich Quantum Software Forum](https://www.cda.cit.tum.de/research/quantum/mqsf/). The program included a variety of interesting talks and presentations on the latest developments in quantum software. Among the software pitches, I found the one from [Alice and Bob](https://www.alice-bob.com/) particularly intriguing. [Dynamiqs](https://www.dynamiqs.org/) was advertised as a *high-performance quantum systems simulation* build on top of [JAX](https://jax.readthedocs.io/en/latest/), optimised for both CPUs, GPUs and TPUs.

This situation created the perfect opportunity to test how fast I can run a Dynamiqs workload on our Qubernetes cluster located in Finland, which happens to have the necessary GPU resources available.

```mermaid
---
config:
 sequence:
 mirrorActors: false
---
sequenceDiagram
 box Munich Quantum Software Forum (Germany)
 actor M as Me
 actor T as Dynamiqs Pitch
 participant L as Laptop
 end

 box Qubernetes Cluster (Finland)
 participant api as api-server
 participant job as Quantum Job
 participant node as GPU Node (RTX 4090)
 end

 M ->> T: watches
 M ->> M: what about running it on Qubernetes?
 M ->> L: codes demo.py
 L ->> api: run code
 api ->> job: schedule
 job ->> node: executes
 node -->> L: results
 M ->> M: celebrates
```

In this blog post, I will share my experience and the steps I took to successfully run a Dynamiqs workload on Qubernetes.

## Adapting the Dynamiqs Example

The Dynamiqs documentation provides a simple workflow [example](https://www.dynamiqs.org/stable/documentation/basics/workflow.html) of how to use the library for quantum simulations. We will adapt this example to run it on Qubernetes. First, we need to create a Python script `demo.py` that contains the Dynamiqs example code:

```python copy filename="demo.py"
import dynamiqs as dq
import jax.numpy as jnp

# initial state
psi0 = dq.fock(2, 0)

# Hamiltonian
delta = 0.3 # detuning
Omega = 1.0 # Rabi frequency
H = delta * dq.sigmaz() + Omega * dq.sigmax()

print(f"State of type {type(psi0)} and shape {psi0.shape}.")
print(f"Hamiltonian of type {type(H)} and shape {H.shape}.")

# define sampling times
sim_time = 10.0 # total time of evolution
num_save = 101 # number of time slots to save
tsave = jnp.linspace(0.0, sim_time, num_save) # can also be a list or a NumPy array

# define list of observables
exp_ops = [dq.sigmaz()] # expectation value of sigma_z

# define method (Dormand-Prince method of order 5)
method = dq.method.Dopri5(rtol=1e-6, atol=1e-8)

# run simulation
result = dq.sesolve(H, psi0, tsave, exp_ops=exp_ops, method=method)

# print some information
print(f"`result` is of type {type(result)}.")
print(f"`result` has the following attributes:")
print(f"{[attr for attr in dir(result) if not attr.startswith('__')]}\n")
print(result)
```

Next we need to create a project configuration file `Q8Sproject`. This file specifies the dependencies and settings required to run the Dynamiqs example on CPU and GPU targets in Qubernetes.

```yaml copy filename="Q8Sproject"
name: dynamiqs-example

python_env:
 dependencies:
 - dynamiqs

targets:
 cpu:
 python_env:
 dependencies:
 - jax

 gpu:
 python_env:
 dependencies:
 - jax[cuda12]

docker:
 username: your_dockerhub_username

kubeconfig: /path/to/your/kubeconfig
```

The resulting project structure is as follows:

<FileTree>
 <FileTree.Folder name="root" defaultOpen>
 <FileTree.File name="Q8Sproject" />
 <FileTree.File name="demo.py" />
 </FileTree.Folder>
</FileTree>

## Running the Dynamiqs Simulation

With the project set up, we can now proceed to run the Dynamiqs example on our Qubernetes cluster. The first step is to build the target `gpu` image and push it to Docker Hub:

```bash copy
q8sctl build --target gpu
```

Once the images are built, we can execute the demo by running the following command:

```bash copy
q8sctl execute --target gpu --kubeconfig kubeconfig demo.py
```

The command will initiate the execution of the `demo.py` script on the GPU target.

## Challenges and Solutions

I attend quite often conferences and workshops, and I usually travel light with just my ultra-portable laptop. However, I still need to run heavy quantum simulations during these events. This is where Qubernetes comes in handy, as it allows me to offload these computations to the cloud while I work on my laptop. Not to mention, my colleagues can use the hardware capabilities of the cluster as well.

## Conclusion

Running Dynamiqs workloads on Qubernetes was a straightforward process, thanks to the flexibility of the Qubernetes platform and the ease of setting up projects with `Q8Sproject` files. The ability to seamlessly switch between CPU and GPU targets allows for efficient utilization of available computational resources.

The code in this blog post can be found in this [GitHub repository](https://github.com/qubernetes-dev/q8s-examples/tree/main/dynamiqs). Feel free to explore and modify it for your own experiments with Dynamiqs on Qubernetes!

Happy coding! 😊

This guide explains how to run Dynamiqs workloads on Qubernetes.

Running Dynamiqs Workloads on Qubernetes

import { FileTree } from 'nextra/components'
import { useConfig } from 'nextra-theme-docs'
import Author from '../../components/ui/author'

# How to use Catalyst with Lightning-GPU on Qubernetes

<Author author={useConfig().frontMatter.author} />

Published on March 7, 2025.

[Lightning-GPU](https://docs.pennylane.ai/projects/lightning/en/latest/lightning_gpu/device.html) is a high-performance CUDA-backed state-vector simulator for [PennyLane](https://pennylane.ai/). This device enables fast quantum circuit simulations on NVIDIA GPUs and has been recently integrated with [Catalyst](https://docs.pennylane.ai/projects/catalyst/en/stable/index.html). 

In this guide, you will find out how to execute efficiently the quantum routines described in the PennyLane's blog post [How to use Catalyst with Lightning-GPU](https://pennylane.ai/qml/demos/how_to_catalyst_lightning_gpu) that introduced this capability.

You will learn how to start a Qubernetes project and adapt the PennyLane demo to execute the routines on a remote cluster with the necessary computational capabilities for Catalyst and Lightning-GPU. This allows you to perform the demo experiments without needing a local machine with compatible hardware or having to install the required software locally.

## Setting Up the Environment

Before we start, you need to have the following pre-requisites:

- Access to a Kubernetes cluster that has has nodes with NVIDIA GPU devices with CUDA 12.8 support. The configuration file `kubeconfig` that allows you to connect to the remote cluster should be placed in the project root directory. You can check the [CUDA compatibility](https://developer.nvidia.com/cuda-gpus) of your GPU on the NVIDIA website.
- A Docker Hub account to store the images built for the project.


```mermaid
---
config:
 look: handDrawn
---
flowchart LR
 
 subgraph laptop[Laptop]
 pf[Q8Sproject]
 qt[demo.py]
 end

 subgraph dh[Docker Hub]
 image[Image]
 end

 subgraph qubernetes[Qubernetes Cluster]
 subgraph gpu[CUDA Node]
 j[Job]
 end
 end

 pf -- q8sctl build --> image
 qt -- q8sctl execute --> j
 image -.-> j
```

Next, install the `q8s` package. It provides the Qubernetes CLI tool `q8sctl` that allows you to build and execute your projects on the cluster. You can install the package using the following command:

```bash copy
pip install q8s
```

## Adapting the PennyLane Demo

We start by adding the demo [script](https://pennylane.ai/_downloads/8fc5809931208b806e0091bfad6e808a/how_to_catalyst_lightning_gpu.py) to the project. The following is an extract of the script that we will run on the remote cluster.

```python copy filename="demo.py"
import pennylane as qml
import jax.numpy as jnp

import jax

# Set number of wires
num_wires = 28

# Set a random seed
key = jax.random.PRNGKey(0)

dev = qml.device("lightning.gpu", wires=num_wires)

@qml.qjit(autograph=True)
@qml.qnode(dev)
def circuit(params):

 # Apply layers of RZ and RY rotations
 for i in range(num_wires):
 qml.RZ(params[3*i], wires=[i])
 qml.RY(params[3*i+1], wires=[i])
 qml.RZ(params[3*i+2], wires=[i])

 return qml.expval(qml.PauliZ(0) + qml.PauliZ(num_wires-1))

# Initialize the weights
weights = jax.random.uniform(key, shape=(3 * num_wires,), dtype=jnp.float32)

circuit(weights)

>>> 1.7712995142661776
```

Next, we create the project configuration file `Q8Sproject`. The configuration file defines the project name, the Python dependencies common to all targets, and Docker registry username. The `targets` section defines the dependencies specific to the CUDA environment as `gpu`, and optionally for the local environment as `cpu`.

```yaml copy filename="Q8Sproject"
name: catalyst-lightning-gpu-demo

python_env:
 dependencies:
 - pennylane
 - pennylane-catalyst

targets:
 cpu:
 python_env:
 dependencies:
 - jax
 - pennylane-lightning
 gpu:
 python_env:
 dependencies:
 - jax[cuda12]
 - pennylane-lightning-gpu

docker:
 username: vstirbu
```

The resulting project structure is as follows:

<FileTree>
 <FileTree.Folder name="root" defaultOpen>
 <FileTree.File name="kubeconfig" />
 <FileTree.File name="Q8Sproject" />
 <FileTree.File name="demo.py" />
 </FileTree.Folder>
</FileTree>

## Running the Demo

Now that the project is set up, we are ready to run the demo on the remote cluster. The first step is to build the target `gpu` image, and push it to the Docker Hub:

```bash copy
q8sctl build --target gpu 
```

Once the images are built we can run the demo by executing the following command:

```bash copy
q8sctl execute --target gpu --kubeconfig kubeconfig demo.py
```

The command will start the execution of the `demo.py` script on the GPU target.

## Benefits of Using Qubernetes

Qubernetes offers scalability, allowing you to seamlessly expand workloads across various computational configurations such as CPUs, GPUs, and QPUs. In this example, we used PennyLane with Catalyst and Lightning-GPU, but Qubernetes is flexible to support other quantum libraries as well.

Another advantage is portability. By leveraging containerized deployments, Qubernetes guarantees that your projects will run consistently across different environments. You can easily share the Q8Sproject configuration with your team members.

Efficiency is also a key benefit of Qubernetes. Its design optimizes resource management for GPU workloads by utilizing computational resources only during execution. Once a job is complete, the resources are released and can be used immediately for other tasks.

## Challenges and Solutions

Running the quantum routines using Catalyst with Lightning-GPU requires CUDA 12.8 compatible hardware. If you have the necessary hardware, you can configure a self-hosted cluster using the [k3s](https://k3s.io/) Kubernetes distribution, with the required [updates](https://docs.k3s.io/advanced#alternative-container-runtime-support) for supporting CUDA workloads. Alternatively, you can use a cloud provider that offers managed Kubernetes environments that offer GPU instances with the required CUDA version.

## Conclusion

In this guide, we have shown how to run quantum programs with Catalyst compiler and Lightning-GPU simulator on Qubernetes. You have learned how to set up the environment, adapt the PennyLane demo, and run the demo on a remote cluster. By following these steps, you can efficiently experiment with demanding quantum routines even if your local machine does not have the necessary hardware.

The code used in the guide is available on the [q8s-examples](https://github.com/torqs-project/q8s-examples/tree/main/catalyst-lightning-gpu) repository. Feel free to explore the repository and adapt the examples to your needs.

Happy coding! 🚀

This guide explains how to use Catalyst with Lightning-GPU on Qubernetes.

Blog

Running Dynamiqs Workloads on Qubernetes

How to use Catalyst with Lightning-GPU on Qubernetes