Quick Start Guide

Welcome to Divi! This guide will get you up and running with quantum program execution in minutes.

What is Divi?

Divi is a Python library that automates the orchestration around quantum programs: circuit generation, batching, error mitigation, parameter optimization, and result aggregation. Whether you’re studying molecular systems or solving combinatorial optimization problems, Divi handles the plumbing so you can focus on the problem.

Core capabilities:

  • Automated execution — run quantum programs with minimal boilerplate.

  • Parallel circuit execution — distribute circuits across available resources automatically.

  • Pluggable backends — swap between local simulators, noisy simulators, and cloud hardware without changing program code.

  • Integrated error mitigation — ZNE and QuEPP plug into the variational loop.

  • Progress tracking — real-time feedback during long-running computations.

Five-Minute Tutorial

Let’s solve a quantum chemistry problem - finding the ground state energy of a hydrogen molecule:

import numpy as np
import pennylane as qp
from divi.qprog import VQE, HartreeFockAnsatz
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

# Step 1: Define your molecule
h2_molecule = qp.qchem.Molecule(
   symbols=["H", "H"], coordinates=np.array([[0.0, 0.0, -0.6614], [0.0, 0.0, 0.6614]])
)

# Step 2: Choose your optimizer
optimizer = ScipyOptimizer(method=ScipyMethod.COBYLA)

# Step 3: Set up your quantum program
vqe = VQE(
   molecule=h2_molecule,
   ansatz=HartreeFockAnsatz(),
   n_layers=2,  # Circuit depth
   optimizer=optimizer,
   max_iterations=10,  # Optimization steps
   backend=MaestroSimulator(shots=1000),  # Local simulator
)

# Step 4: Run and get results!
vqe.run()

# Check your results
print(f"Ground state energy: {vqe.best_loss:.6f} Hartree")
print(f"Circuits executed: {vqe.total_circuit_count}")

That’s it — you just ran a variational quantum algorithm. The energy should be close to -1.137 Hartree (H₂’s true ground state energy).

Tip

Stuck? Try divi-ai — ask questions, get code examples, and explore APIs right in your terminal: pip install qoro-divi[ai] && divi-ai

Choosing the Right Algorithm

Divi offers specialized algorithms for different problem types:

VQE – Quantum Chemistry

Use VQE for molecular ground state calculations, dissociation curves, and electronic structure problems.

from divi.qprog import VQE, UCCSDAnsatz

vqe = VQE(
    molecule=h2_molecule,
    ansatz=UCCSDAnsatz(),  # More sophisticated than Hartree-Fock
    n_layers=2,
    backend=MaestroSimulator()
)
QAOA – Optimization Problems

Use QAOA for combinatorial optimization: Max-Cut, Max-Clique, traveling salesman, QUBO/HUBO, and similar NP-hard problems (graphs or binary polynomial formulations).

import networkx as nx
from divi.qprog import QAOA
from divi.qprog.problems import MaxCutProblem

# Create your problem graph
graph = nx.erdos_renyi_graph(10, 0.5)

qaoa = QAOA(
    MaxCutProblem(graph),
    n_layers=2,
    backend=MaestroSimulator()
)
PCE – QUBO/HUBO with Pauli Correlation Encoding

Use PCE for QUBO and higher-order (HUBO) binary optimization with parity-based encoding. PCE is a VQE variant that uses far fewer qubits than standard QAOA for the same problem size — see Combinatorial Optimization with QAOA and PCE for the encoding details and scaling trade-offs.

import numpy as np
from qiskit.circuit.library import CXGate, RYGate, RZGate
from divi.qprog import PCE, GenericLayerAnsatz
from divi.backends import MaestroSimulator

qubo_matrix = np.array([[-1.0, 2.0], [0.0, 1.0]])
pce = PCE(
    problem=qubo_matrix,
    ansatz=GenericLayerAnsatz(
        gate_sequence=[RYGate, RZGate],
        entangler=CXGate,
        entangling_layout="all-to-all",
    ),
    backend=MaestroSimulator(),
)
pce.run()
TimeEvolution – Hamiltonian Dynamics

Use TimeEvolution to simulate real-time quantum dynamics under a Hamiltonian (Trotter-Suzuki or QDrift). Supports probability or observable mode.

import math
import pennylane as qp
from divi.qprog import TimeEvolution
from divi.backends import MaestroSimulator

te = TimeEvolution(
    hamiltonian=qp.PauliX(0) + qp.PauliX(1),
    time=math.pi / 2,
    backend=MaestroSimulator(shots=5000),
)
te.run()
print(te.results)  # basis-state probabilities or expectation value
QNN – Quantum Machine Learning

Use QNN to train a variational classifier on a classical feature batch: a feature map encodes each sample, a trainable ansatz supplies the weights, and Divi composes and binds the circuit for you. See Quantum Neural Networks. To bring your own PennyLane or Qiskit circuit instead, use CustomVQA (PennyLane & Qiskit Integration).

import numpy as np
from qiskit.circuit.library import CXGate, RYGate, RZGate
from divi.qprog import QNN, AngleEmbedding, GenericLayerAnsatz
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

qnn = QNN(
    n_qubits=2,
    feature_map=AngleEmbedding(rotation="Y"),
    ansatz=GenericLayerAnsatz(
        gate_sequence=[RYGate, RZGate],
        entangler=CXGate,
        entangling_layout="linear",
    ),
    feature_batch=np.array([[0.1, 0.2], [2.0, 2.1]]),
    max_iterations=5,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    backend=MaestroSimulator(),
)
qnn.run(perform_final_computation=False)

Backend Options

Local development

Use MaestroSimulator (shown in all examples above) for fast iteration and testing. For noisy simulation, use QiskitSimulator with Qiskit noise models.

Cloud simulation & hardware

Access scalable cloud simulators (statevector, tensor-network, and more) through QoroService. Sign up at dash.qoroquantum.net to get started with free credits. For real quantum hardware access, contact us:

from divi.backends import QoroService, JobConfig

# Bell pair: H + CNOT, then measure both qubits (OpenQASM 2.0)
qasm = (
    'OPENQASM 2.0;\n'
    'include "qelib1.inc";\n'
    'qreg q[2];\n'
    'creg c[2];\n'
    'h q[0];\n'
    'cx q[0],q[1];\n'
    'measure q[0] -> c[0];\n'
    'measure q[1] -> c[1];\n'
)

service = QoroService()  # Uses QORO_API_KEY from .env file
result = service.submit_circuits(
    {"my_circuit": qasm},
    override_job_config=JobConfig(simulator_cluster="qoro_maestro"),
)