Quickstart

Below are minimal examples to get you running digital circuits and analog evolutions.

Digital Circuit Example

Build a 2-qubit circuit, sample it using CUDA backend, and inspect measurement counts:

import numpy as np
from qilisdk.digital import Circuit, H, RX, CNOT
from qilisdk.backends import CudaBackend, CudaSamplingMethod
from qilisdk.functionals import Sampling

# 1. Define a simple 2‑qubit circuit
circuit = Circuit(2)
circuit.add(H(0))
circuit.add(RX(1, theta=np.pi / 2))
circuit.add(CNOT(0, 1))

# 2. Wrap it in a Sampling functional
sampling = Sampling(circuit=circuit, nshots=500)

# 3. Execute on GPU
backend = CudaBackend(sampling_method=CudaSamplingMethod.STATE_VECTOR)
results = backend.execute(sampling)

print("Counts:", results.probabilities)

Note

This example requires CUDA backend which can be installed using pip install qilisdk[cuda] if you have the proper drivers installed. for more details check the information on the official CUDA documentation: https://nvidia.github.io/cuda-quantum/latest/using/quick_start.html#install-cuda-q

Analog Time Evolution Example

Define two Hamiltonians, build an interval-based interpolation schedule, and run using Qutip backend:

from qilisdk.analog import Schedule, X, Z
from qilisdk.core import ket, tensor_prod
from qilisdk.functionals import TimeEvolution
from qilisdk.backends import QutipBackend

# Total time and step
T, dt = 5.0, 0.1

# Hamiltonians H1 = ∑ X, H2 = ∑ Z
n = 1
H1 = sum(X(i) for i in range(n))
H2 = sum(Z(i) for i in range(n))

# Define coefficients over the full interval with automatic sampling
schedule = Schedule(
    hamiltonians={"h1": H1, "h2": H2},
    coefficients={
        "h1": {(0.0, T): lambda t: 1 - t / T},
        "h2": {(0.0, T): lambda t: t / T},
    },
    dt=dt,
)

# Initial state |+⟩
psi0 = tensor_prod([(ket(0) - ket(1)).unit() for _ in range(n)]).unit()

# TimeEvolution functional
tevo = TimeEvolution(
    schedule=schedule,
    initial_state=psi0,
    observables=[Z(0)],
    nshots=100,
    store_intermediate_results=True,
)

# Execute on CPU
results = QutipBackend().execute(tevo)
print(results)

Note

This example requires QuTiP backend which can be installed using pip install qilisdk[qutip].

Next Steps

Once you’ve confirmed everything works, explore:

  • Core primitives (Core) for state vectors, operators, and shared abstractions.

  • Digital workflows (Digital) covering circuit construction, parameter sweeps, and QASM export.

  • Analog workflows (Analog) for Hamiltonian builders, schedules, and time-evolution utilities.

  • Functionals (Functionals) to see how experiments connect models with execution backends.

  • Execution targets (Backends) to compare Qutip (CPU) and CUDA (CPU/GPU) runtimes.

  • SpeQtrum cloud (SpeQtrum) for account setup, calibration-aware jobs, and result retrieval.

  • Example gallery (Code Examples) for end-to-end notebooks you can adapt to your workflow.

Happy quantum coding!