Divi

https://github.com/qoroquantum/divi
Admin
Divi is a Python library for generating, parallelizing, and executing quantum programs at scale with...
Tokens:268,443
Snippets:1,839
Trust Score:7.8
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick Start: Train a 2-qubit QNN classifier

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/quantum_neural_networks.rst

Imports required libraries and sets up a 2-qubit QNN training example. Uses Qiskit gates (CXGate, RYGate, RZGate), Divi's QNN, AngleEmbedding, GenericLayerAnsatz, ScipyOptimizer, and MaestroSimulator. This snippet is the starting point for the quick start workflow.

```python
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

n_qubits = 2
```

--------------------------------

### Install and Run divi-ai

Source: https://github.com/qoroquantum/divi/blob/main/README.md

Install the qoro-divi[ai] package and run divi-ai in the terminal. No API keys or internet required after setup; uses a local LLM to answer questions about Divi APIs and generate code examples.

```bash
pip install qoro-divi[ai]
divi-ai
```

--------------------------------

### Install All Optional Extras

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Command to install the core package with all available optional extras.

```bash
pip install "qoro-divi[all]"
```

--------------------------------

### QNGOptimizer with VQE run

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/optimizers.rst

Shows how to use QNGOptimizer with a VQE instance. The optimizer preconditions the parameter-shift gradient with a regularized metric. The example includes the necessary imports and a VQE setup with the optimizer, backend, and max_iterations.

```python
from divi.qprog import VQE
from divi.qprog.optimizers import QNGOptimizer

vqe = VQE(
    problem,
    backend=backend,
    optimizer=QNGOptimizer(step_size=0.1, regularization=1e-3),
    max_iterations=10,
)
vqe.run()
```

--------------------------------

### Install dependencies with uv sync

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Installs the default dev, testing, and docs dependency groups.

```bash
uv sync
```

--------------------------------

### PartitioningProgramEnsemble Usage Example

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of setting up and running a partitioning program ensemble for portfolio allocation using MaestroSimulator, ScipyOptimizer, and PortfolioSelectionProblem.

```APIDOC
## PartitioningProgramEnsemble

### Description
PartitioningProgramEnsemble clusters assets by covariance and solves each cluster as its own portfolio problem. The budget is split across clusters by their weight in the problem's continuous relaxation. Covariance between clusters and extra constraints are considered when combining solutions.

### Usage Example
```python
import numpy as np

from divi.backends import MaestroSimulator
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import PortfolioSelectionProblem, QUBOPartitioningConfig
from divi.qprog.workflows import PartitioningProgramEnsemble

rng = np.random.default_rng(0)
mu = rng.uniform(0.05, 0.15, 8)
```

### Notes
- Requires `encoding="domain_wall"` for PortfolioAllocationProblem.
- `max_n_variables_per_cluster` counts assets, not qubits.
- `aggregate_results` repairs the combined portfolio, improves it by one-unit transfers, and returns `(decoded, objective)`.
```

--------------------------------

### Live reload documentation for development

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Starts a live-reload development server for the documentation.

```bash
cd docs
make dev
```

--------------------------------

### Run tutorials with backend flags

Source: https://github.com/qoroquantum/divi/blob/main/tutorials/README.md

Examples of executing tutorials with specific backend configurations and sampling options.

```bash
python tutorials/optimization/qaoa_graph_problems.py --local-maestro
python tutorials/optimization/qaoa_graph_problems.py --cloud-maestro
python tutorials/optimization/qaoa_graph_problems.py --local-qiskit --force-sampling
```

--------------------------------

### QDrift Configuration Example

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of configuring QDrift as a trotterization strategy for QAOA, showing the available parameters.

```APIDOC
## QDrift Configuration

### Description
Configure QDrift as a trotterization strategy for QAOA to sample Hamiltonian terms for shallower circuits.

### Parameters
- **keep_fraction** (float) - Required - Fraction of terms to deterministically keep by coefficient magnitude.
- **sampling_budget** (int) - Required - Number of terms to sample from the remaining Hamiltonian.
- **n_hamiltonians_per_iteration** (int) - Required - Number of samples per cost evaluation; losses are averaged.
- **sampling_strategy** (str) - Required - Either "uniform" or "weighted" (by coefficient magnitude).
- **seed** (int) - Optional - Seed for reproducibility.

### Example
```python
from divi.hamiltonians import QDrift

qdrift = QDrift(
    keep_fraction=0.2,
    sampling_budget=5,
    n_hamiltonians_per_iteration=3,
    sampling_strategy="weighted",
    seed=1997,
)
qaoa = QAOA(problem, trotterization_strategy=qdrift, ...)
```
```

--------------------------------

### Install uv

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Installs the uv dependency manager using the official installation script.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install documentation dependencies

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Synchronizes the docs dependency group using uv.

```bash
uv sync --group docs
```

--------------------------------

### Install Divi Core from Source

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Method for installing the core package directly from the GitHub repository using uv.

```bash
git clone https://github.com/QoroQuantum/divi.git
cd divi
uv sync
```

--------------------------------

### Setup Partitioned Workflow with BQM

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Initialize a large BQM and configure the PartitioningProgramEnsemble with a D-Wave EnergyImpactDecomposer, Scipy optimizer, and Maestro simulator.

```python
import dimod
import hybrid
from qiskit.circuit.library import RYGate, RZGate
from divi.qprog import InterpolationStrategy
from divi.qprog.problems import BinaryOptimizationProblem
from divi.qprog.workflows import PartitioningProgramEnsemble
from divi.qprog.algorithms import GenericLayerAnsatz
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

def run_partitioned(ensemble):
    ensemble.run()
    return ensemble.aggregate_results()

large_bqm = dimod.generators.gnp_random_bqm(25, 0.5, vartype="BINARY")
decomposer = hybrid.EnergyImpactDecomposer(size=5)
optimizer = ScipyOptimizer(method=ScipyMethod.COBYLA)
backend = MaestroSimulator()
```

--------------------------------

### Clone and set up the repository with uv and pre-commit

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/development/contributing.rst

Commands to clone the repository, install dependencies with uv (including dev, testing, and docs groups), and install pre-commit hooks. Run the test suite with 'uv run pytest -n auto'.

```bash
git clone https://github.com/QoroQuantum/divi.git
cd divi
uv sync                # installs dev, testing, and docs groups
pre-commit install
```

--------------------------------

### Install divi-ai

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/tools/divi_ai.rst

Install the divi-ai package using pip.

```bash
pip install qoro-divi[ai]
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Installs the pre-commit hooks to enforce formatting and license headers automatically.

```bash
pre-commit install
```

--------------------------------

### Initialize Portfolio Selection Problem with Partitioning

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Setup for a portfolio selection problem using the PartitioningProgramEnsemble, including necessary imports and random number generation for asset returns.

```python
import numpy as np

from divi.backends import MaestroSimulator
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import PortfolioSelectionProblem, QUBOPartitioningConfig
from divi.qprog.workflows import PartitioningProgramEnsemble

rng = np.random.default_rng(0)
mu = rng.uniform(0.05, 0.15, 8)
```

--------------------------------

### Install nightly development build

Source: https://github.com/qoroquantum/divi/blob/main/README.md

Install the latest development build published daily from the main branch. Use the `--pre` flag to include pre-release versions.

```bash
pip install qoro-divi --pre
```

--------------------------------

### Install Nightly Builds

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Commands to install the latest nightly development build or a specific version by date.

```bash
pip install qoro-divi --pre

pip install qoro-divi==0.8.0.dev20260305
```

--------------------------------

### Configure QNSPSAOptimizer

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/optimizers.rst

Examples for initializing the QNSPSA optimizer using either the default stochastic-fidelity metric or a specific FubiniStudyMetricEstimator.

```python
# Faithful stochastic-fidelity metric (default)
optimizer = QNSPSAOptimizer(c=0.2, regularization=1e-3)

# Or reuse an exact metric with the SPSA gradient
from divi.qprog.optimizers import FubiniStudyMetricEstimator

optimizer = QNSPSAOptimizer(
    metric_estimator=FubiniStudyMetricEstimator(),
)
```

--------------------------------

### Install Divi Core via uv

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Recommended method for installing the core package using the uv package manager.

```bash
uv add qoro-divi
```

--------------------------------

### Install Divi with chem extra

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/quickstart.rst

Install the qoro-divi package with the chem extra to enable molecule inputs for quantum chemistry problems.

```bash
pip install "qoro-divi[chem]"
```

--------------------------------

### Characterize and validate a binary optimization problem

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/tools/qubo_characterization.rst

This example demonstrates how to initialize a BinaryOptimizationProblem, run the characterization service with a deep preset, and display the resulting diagnostics and metrics.

```python
import numpy as np

from divi.backends import QoroService
from divi.backends.characterization import (
    CharacterizationOptions,
    characterize_and_validate,
)
from divi.qprog.problems import BinaryOptimizationProblem

problem = BinaryOptimizationProblem(np.array([[-1, 2], [0, -1]]))

result = characterize_and_validate(
    problem,
    reference_states=["01", "10"],
    service=QoroService(),
    options=CharacterizationOptions(preset="deep"),
)

result.display()
print(result.regime, result.confidence)
print(result.certificate)
print(result.classical_baseline)
print(result.approximation_ratio)
```

--------------------------------

### Install qoro-divi via pip

Source: https://github.com/qoroquantum/divi/blob/main/README.md

Install the core qoro-divi package. Optional extras are available for additional features like PennyLane, Qiskit Aer, QUBO decomposition, chemistry, AI, and Jupyter; use `pip install "qoro-divi[all]"` for everything.

```bash
pip install qoro-divi
```

--------------------------------

### Install Optional Extras

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Commands to install specific optional extras or combinations of extras using pip or uv.

```bash
pip install "qoro-divi[aer]"
pip install "qoro-divi[pennylane]"
pip install "qoro-divi[aer,chem,pennylane]"

uv add "qoro-divi[aer,chem,pennylane]"
```

--------------------------------

### Install Divi Core via pip

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Standard method for installing the core package using pip.

```bash
pip install qoro-divi
```

--------------------------------

### Google-style docstring example for optimize_circuit

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/development/building_docs.rst

Example of a Google-style docstring for a public method. It includes type hints, an Args section, a Returns section, and a Raises section. This block is marked with .. skip: next because it is not runnable.

```python
def optimize_circuit(self, circuit: Circuit, method: str = "default") -> Circuit:
    """Optimize a quantum circuit using the specified method.

    Args:
        circuit: The quantum circuit to optimize
        method: Optimization method to use

    Returns:
        The optimized circuit

    Raises:
        ValueError: If the method is not supported
    """
    pass
```

--------------------------------

### Install qoro-divi with uv or pip

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/index.rst

Install the qoro-divi package using uv or pip. The comment shows the alternative pip command.

```bash
uv add qoro-divi     # or: pip install qoro-divi
```

--------------------------------

### Run all documentation snippets with make test-snippets

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/development/building_docs.rst

Runs all documentation snippet examples locally. By default, it runs all snippets without early exit.

```bash
cd docs
make test-snippets
```

--------------------------------

### Configure VQE with Qiskit Hamiltonian

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/ground_state_energy_estimation_vqe.rst

Example of wrapping a Qiskit SparsePauliOp in a HamiltonianProblem and running VQE with a GenericLayerAnsatz.

```python
from qiskit.circuit.library import RYGate, RZGate
from qiskit.quantum_info import SparsePauliOp
from divi.qprog import GenericLayerAnsatz, VQE
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import HamiltonianProblem
from divi.backends import MaestroSimulator

hamiltonian = SparsePauliOp.from_sparse_list(
    [("Z", [0], -1.0), ("ZZ", [0, 1], 0.5)], num_qubits=2
)
vqe = VQE(
    HamiltonianProblem(hamiltonian),
    ansatz=GenericLayerAnsatz([RYGate, RZGate]),
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(),
)
vqe.run()
```

--------------------------------

### PCE with get_top_solutions

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of using the PCE class to solve a QUBO problem and retrieve the top solution.

```APIDOC
## PCE

### Description
Solves a BinaryOptimizationProblem using compressed parity encoding. Supports dense and polynomial encoding types.

### Usage
```python
from divi.qprog import PCE
from divi.qprog.problems import BinaryOptimizationProblem
from divi.qprog.optimizers import MonteCarloOptimizer
from divi.backends import MaestroSimulator

qubo = np.array([[-1.0, 2.0], [0.0, 1.0]])
pce = PCE(
    problem=BinaryOptimizationProblem(qubo),
    encoding_type="dense",
    alpha=2.0,
    n_layers=2,
    optimizer=MonteCarloOptimizer(population_size=8),
    max_iterations=5,
    backend=MaestroSimulator(shots=2000),
    seed=42,
)
pce.run()

best = pce.get_top_solutions(
    n=1, include_decoded=True, sort_by="energy"
)[0]
print(f"Best solution: {best.decoded} (energy={best.energy})")
print(f"Qubits: {pce.n_qubits} for {pce.n_vars} variables")
```

### Parameters
- **problem** (BinaryOptimizationProblem) - Required - The optimization problem to solve.
- **encoding_type** (str) - Required - Either "dense" or "poly".
- **alpha** (float) - Required - Controls the objective used during optimization. Values below 5 use smooth parity relaxation; values at or above 5 use discrete CVaR-style objective.
- **n_layers** (int) - Required - Number of layers in the QAOA circuit.
- **optimizer** (Optimizer) - Required - Optimizer instance (e.g., MonteCarloOptimizer).
- **max_iterations** (int) - Required - Maximum number of optimization iterations.
- **backend** (Backend) - Required - Quantum backend (e.g., MaestroSimulator).
- **seed** (int) - Optional - Random seed for reproducibility.

### Methods
#### run()
Runs the optimization.

#### get_top_solutions(n, include_decoded, sort_by)
Returns the top n solutions.
- **n** (int) - Required - Number of top solutions to return.
- **include_decoded** (bool) - Required - Whether to include decoded solutions.
- **sort_by** (str) - Required - Sorting criterion (e.g., "energy").

### Attributes
- **n_qubits** (int) - Number of qubits used.
- **n_vars** (int) - Number of variables in the problem.
```

--------------------------------

### QAOA with Linear Constraints

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of adding linear constraints to a BinaryOptimizationProblem and checking feasibility.

```APIDOC
## QAOA with Linear Constraints

### Description
Pass LinearConstraint objects through constraints= to add constraints sum_i a_i x_i (=, <=, >=) b. Each becomes the squared penalty (sum_i a_i x_i +/- s - b)^2 in the constraint's own units, scaled by penalty_weight. Problems are minimised; negate an objective to maximise it.

### Code
```python
import numpy as np

from divi.qprog.problems import BinaryOptimizationProblem, LinearConstraint

objective = np.diag([-1.0, -2.0, -3.0])
problem = BinaryOptimizationProblem(
    objective,
    constraints=[
        LinearConstraint([1, 1, 1], "==", 2),     # exactly two variables set
        LinearConstraint([3, 1, 2], "<=", 4),     # a weighted cap
    ],
    penalty_weight=5.0,
)
print(problem.cost_hamiltonian.num_qubits)       # 3 decision + 3 slack (range 0-4) = 6
print(problem.is_feasible("011" + "000"))        # True: 1 + 2 <= 4
```
```

--------------------------------

### Run QAOA for MaxCliqueProblem

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of creating a bull graph, configuring the QAOA solver with a constrained mixer, and retrieving top solutions.

```python
# Create a graph
G = nx.bull_graph()

qaoa_problem = QAOA(
    MaxCliqueProblem(G, use_constrained_mixer=True),
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.NELDER_MEAD),
    max_iterations=10,
    backend=MaestroSimulator(),
)

qaoa_problem.run()

print(f"Quantum Solution: {set(qaoa_problem.solution)}")
print(f"Total circuits: {qaoa_problem.total_circuit_count}")

# Get top-N solutions by probability
top_solutions = qaoa_problem.get_top_solutions(n=5, include_decoded=True)
print("\nTop 5 solutions by probability:")
for i, sol in enumerate(top_solutions, 1):
    print(f"{i}. Nodes: {sol.decoded} (probability: {sol.prob:.2%})")
```

--------------------------------

### QAOA with random QUBO

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of creating a random QUBO, constructing a QAOA problem, running it, and retrieving top solutions.

```APIDOC
## QAOA with random QUBO

### Description
Generate a random QUBO, create a QAOA problem, run it, and print the solution and top solutions.

### Code
```python
import numpy as np
import dimod

from divi.backends import MaestroSimulator
from divi.qprog import QAOA
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import BinaryOptimizationProblem

# Generate a random QUBO
bqm = dimod.generators.randint(5, vartype="BINARY", low=-10, high=10, seed=1997)
qubo_array = bqm.to_numpy_matrix()

qaoa_problem = QAOA(
    BinaryOptimizationProblem(qubo_array),
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(),
)

qaoa_problem.run()

print(f"Solution: {qaoa_problem.solution}")
print(f"Best loss: {qaoa_problem.best_loss}")

# Get top-N solutions by probability
top_solutions = qaoa_problem.get_top_solutions(n=5)
print("\nTop 5 solutions by probability:")
for i, sol in enumerate(top_solutions, 1):
    solution_array = np.array([int(bit) for bit in sol.bitstring])
    energy = bqm.energy({var: int(val) for var, val in zip(bqm.variables, solution_array)})
    print(f"{i}. {sol.bitstring}: {sol.prob:.2%} (energy: {energy:.4f})")
```
```

--------------------------------

### QAOA with HUBO

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of using the QAOA class to solve a HUBO problem with a native Hamiltonian builder.

```APIDOC
## QAOA

### Description
Solves Higher-Order Binary Optimization (HUBO) problems using QAOA. Supports native and quadratized Hamiltonian builders.

### Usage
```python
from divi.qprog import QAOA
from divi.qprog.problems import BinaryOptimizationProblem
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

hubo = {
    ("a",): -2.0,
    ("b",): 1.0,
    ("c",): -3.0,
    ("a", "b"): 1.5,
    ("c", "d"): -1.0,
    ("a", "b", "c"): 2.0,
}

qaoa = QAOA(
    BinaryOptimizationProblem(hubo, hamiltonian_builder="native"),
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(shots=5000),
)

qaoa.run()
```

### Parameters
- **problem** (BinaryOptimizationProblem) - Required - The optimization problem, can be a HUBO.
- **n_layers** (int) - Required - Number of layers in the QAOA circuit.
- **optimizer** (Optimizer) - Required - Optimizer instance (e.g., ScipyOptimizer).
- **max_iterations** (int) - Required - Maximum number of optimization iterations.
- **backend** (Backend) - Required - Quantum backend (e.g., MaestroSimulator).

### Methods
#### run()
Runs the optimization.

### Hamiltonian Builders
- **"native"** (default) - Maps each polynomial term directly to a multi-Z Ising interaction. No ancilla qubits are added.
- **"quadratized"** - Reduces the polynomial to quadratic form by introducing ancilla qubits with a configurable penalty strength (quadratization_strength).
```

--------------------------------

### Launch divi-ai

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/tools/divi_ai.rst

Start the divi-ai TUI. On the first run, this will trigger the model selection process and cache the necessary models.

```bash
divi-ai
```

--------------------------------

### Solve HUBO with QAOA

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of configuring a QAOA solver for a HUBO problem using the native Hamiltonian builder.

```python
from divi.qprog import QAOA
from divi.qprog.problems import BinaryOptimizationProblem
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

hubo = {
    ("a",): -2.0,
    ("b",): 1.0,
    ("c",): -3.0,
    ("a", "b"): 1.5,
    ("c", "d"): -1.0,
    ("a", "b", "c"): 2.0,
}

qaoa = QAOA(
    BinaryOptimizationProblem(hubo, hamiltonian_builder="native"),
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(shots=5000),
)

qaoa.run()
```

--------------------------------

### SQDConfig with carryover_cutoff

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/localized_active_space_sqd.rst

Example configuration for SQD with carryover enabled, showing how to set n_batches, batch_size, n_recovery_iterations, carryover_cutoff, and max_carryover.

```APIDOC
## SQDConfig

### Description
Configuration for SQD (Stochastic Quantum Dynamics) with support for carrying configurations between iterations and rounds.

### Parameters
- **n_batches** (int) - Required - Number of batches for sampling.
- **batch_size** (int) - Required - Size of each batch.
- **n_recovery_iterations** (int) - Required - Number of recovery iterations.
- **carryover_cutoff** (float) - Optional - Fraction of the largest coefficient that a determinant must exceed to be carried over. Defaults to 1e-5. Pass None for conventional SQD.
- **max_carryover** (int) - Optional - Maximum number of configurations to carry over.

### Example
```python
from divi.qprog import SQDConfig

sqd = SQDConfig(
    n_batches=2,
    batch_size=4,
    n_recovery_iterations=4,
    carryover_cutoff=1e-2,
    max_carryover=64,
)
```
```

--------------------------------

### Missing Extra Error Message

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/installation.rst

Example of the ImportError raised when a feature requiring an optional extra is accessed without that extra installed.

```text
ImportError: QiskitSimulator requires the 'aer' extra; install it with
`pip install qoro-divi[aer]`. Divi's default simulator, MaestroSimulator,
is included in the core install.
```

--------------------------------

### Configure LASSQD for a single fragment

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/localized_active_space_sqd.rst

This example demonstrates configuring LASSQD with the entire active space in a single fragment, making the result comparable to FCI. It uses the MaestroSimulator backend and specifies fragmentation and SQD configurations.

```python
from pyscf import gto
from divi.backends import MaestroSimulator
from divi.qprog import LASSQD, FragmentationConfig, FragmentSpec, SQDConfig
from divi.qprog.problems import MolecularProblem

mol = gto.M(atom="H 0 0 0; H 0 0 0.74", basis="sto-3g", verbose=0)

ensemble = LASSQD(
    MolecularProblem.from_molecule(mol),
    fragmentation=FragmentationConfig(
        active_spaces=[FragmentSpec(orbitals=(0, 1), n_alpha=1, n_beta=1)],
    ),
    sqd=SQDConfig(n_batches=4, batch_size=128, n_recovery_iterations=1),
    seed=0,
    backend=MaestroSimulator(shots=500),
)
print(type(ensemble.preparation).__name__)  # CCSDPreparation
ensemble.run(max_rounds=2)
print(f"Energy: {ensemble.energy:.6f} Ha")
```

--------------------------------

### Run a Divi tutorial

Source: https://github.com/qoroquantum/divi/blob/main/tutorials/README.md

Execute a specific tutorial file from the repository root using the Python interpreter.

```bash
python tutorials/optimization/qaoa_graph_problems.py
```

--------------------------------

### HierarchicalStrategy usage example

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/program_ensembles.rst

Shows how to use HierarchicalStrategy with group_size=4, k_per_partition=20, max_per_group=200, and merge_width=50. Unlike beam search, top_n does not widen the search for this strategy; it only sets how many final solutions are returned.

```python
from divi.qprog import HierarchicalStrategy

solution, energy = qaoa_partition.aggregate_results(
    strategy=HierarchicalStrategy(
        group_size=4, k_per_partition=20, max_per_group=200, merge_width=50
    )
)
```

--------------------------------

### PortfolioSelectionProblem with ESG constraint and QAOA

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of constructing a PortfolioSelectionProblem with expected returns, covariance matrix, cardinality constraint, risk tolerance, and an ESG linear constraint, then running QAOA with a constrained mixer and retrieving top feasible solutions.

```APIDOC
## PortfolioSelectionProblem with ESG constraint and QAOA

### Description
Constructs a portfolio selection problem that selects a fixed number of assets (n_holdings) with equal weight, subject to a weighted-mean ESG floor, and solves it using QAOA with a constrained mixer and a DickeState initial state.

### Class
PortfolioSelectionProblem

### Constructor Parameters
- **mu** (numpy.ndarray) - Required - Expected returns for each asset.
- **sigma** (numpy.ndarray) - Required - Covariance matrix of asset returns.
- **n_holdings** (int) - Required - Number of assets to hold (cardinality constraint).
- **risk_tolerance** (float) - Required - Weight on expected return in the objective; 0 minimises variance alone.
- **constraints** (list of LinearConstraint) - Optional - Additional linear constraints on asset weights.
- **use_constrained_mixer** (bool) - Optional - If True, uses a ring XY mixer on asset qubits and a DickeState of weight K as the recommended initial state.

### QAOA Configuration
- **problem** (BinaryOptimizationProblem) - Required - The portfolio problem instance.
- **n_layers** (int) - Required - Number of QAOA layers.
- **optimizer** (ScipyOptimizer) - Required - Classical optimizer (e.g., COBYLA).
- **max_iterations** (int) - Required - Maximum number of optimizer iterations.
- **backend** (Backend) - Required - Quantum simulator backend (e.g., MaestroSimulator).

### Methods
- **run()** - Executes the QAOA optimization.
- **get_top_solutions(n, include_decoded, feasibility)** - Returns top solutions; feasibility='repair' returns only feasible portfolios ranked by objective without penalties, empty list if none can be repaired.
- **metrics(bitstring)** - Returns expected return, volatility, and Sharpe ratio for a feasible bitstring.

### Example Code
```python
import numpy as np

from divi.backends import MaestroSimulator
from divi.qprog import QAOA
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import LinearConstraint, PortfolioSelectionProblem

mu = np.array([0.10, 0.12, 0.08, 0.15, 0.09])
sigma = np.array(
    [
        [0.040, 0.006, 0.004, 0.010, 0.002],
        [0.006, 0.050, 0.005, 0.012, 0.003],
        [0.004, 0.005, 0.030, 0.006, 0.004],
        [0.010, 0.012, 0.006, 0.090, 0.005],
        [0.002, 0.003, 0.004, 0.005, 0.035],
    ]
)
esg = np.array([70.0, 55.0, 80.0, 60.0, 75.0])

problem = PortfolioSelectionProblem(
    mu,
    sigma,
    n_holdings=2,
    risk_tolerance=0.5,
    constraints=[LinearConstraint(esg, ">=", 65)],   # mean ESG >= 65
    use_constrained_mixer=True,
)
qaoa = QAOA(
    problem,
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(),
)
qaoa.run()

best = qaoa.get_top_solutions(n=1, include_decoded=True, feasibility="repair")[0]
print(f"Holdings: {best.decoded}, objective: {best.energy:.5f}")
print(problem.metrics(best.bitstring))
```

### Notes
- The objective minimises x^T Sigma x / K^2 - tau * mu^T x / K with sum x_i = K.
- Each inequality constraint adds slack qubits.
- With use_constrained_mixer=True, leave initial_state unset to use the recommended DickeState.
- get_top_solutions with feasibility='repair' returns an empty list when no sample can be repaired.
- .solution returns a dict mapping variable names to binary values for non-integer labels; for QUBO matrices it remains a NumPy array.
```

--------------------------------

### MaxCliqueProblem Example

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Example of finding the max-clique of a graph using MaxCliqueProblem with QAOA.

```APIDOC
## MaxCliqueProblem Example

### Description
Find the largest complete subgraph of a graph using MaxCliqueProblem.

### Parameters
- **graph** (networkx or rustworkx graph) - Required - The input graph.
- **use_constrained_mixer** (bool) - Optional - Default True. Selects the problem's constrained mixer and initial state. False uses the X mixer with penalty terms.

### Example
```python
import networkx as nx
from divi.qprog import QAOA
from divi.qprog.problems import MaxCliqueProblem
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.backends import MaestroSimulator

# Assuming graph is defined
problem = MaxCliqueProblem(graph)
qaoa = QAOA(problem, ...)
```
```

--------------------------------

### Serve built documentation

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Serves the already-built documentation site locally.

```bash
cd docs
make serve
```

--------------------------------

### Run and Resume QAOA Optimization

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/resuming_long_runs.rst

Demonstrates initializing a QAOA run with checkpointing, loading from a checkpoint, and continuing the optimization process.

```python
# Create problem
G = nx.bull_graph()
checkpoint_dir = Path("qaoa_checkpoints")

# Initial run - first half
qaoa1 = QAOA(
    MaxCliqueProblem(G),
    n_layers=2,
    optimizer=PymooOptimizer(method=PymooMethod.CMAES, population_size=10),
    max_iterations=10,
    backend=MaestroSimulator(),
)

# Run with checkpointing
qaoa1.run(checkpoint_config=CheckpointConfig(checkpoint_dir=checkpoint_dir))

# Later: Resume from checkpoint
qaoa2 = QAOA.load_state(
    checkpoint_dir=checkpoint_dir,
    backend=MaestroSimulator(),
    problem=MaxCliqueProblem(G),  # Must provide original problem
    n_layers=2,
)

# Continue optimization
qaoa2.max_iterations = 20  # Raise the cumulative target beyond the saved run
qaoa2.run()

# Access results
print(f"Best loss: {qaoa2.best_loss}")
print(f"Solution: {qaoa2.solution}")
```

--------------------------------

### Install AI extra dependencies

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Installs additional divi-ai dependencies by adding the 'ai' extra.

```bash
uv sync --extra ai            # divi-ai dependencies
```

--------------------------------

### Configure and run PCE partitioning

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Sets up a BinaryOptimizationProblem and executes the partitioning program using the PCE quantum routine with a custom GenericLayerAnsatz.

```python
problem = BinaryOptimizationProblem(large_bqm, decomposer=decomposer)
ensemble = PartitioningProgramEnsemble(
    problem=problem,
    quantum_routine="pce",
    ansatz=GenericLayerAnsatz([RYGate, RZGate]),
    n_layers=2,
    encoding_type="dense",
    alpha=2.0,
    optimizer=optimizer,
    max_iterations=10,
    backend=backend,
)
sol_pce, energy_pce = run_partitioned(ensemble)
```

--------------------------------

### Configure and run QAOA partitioning

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Sets up a BinaryOptimizationProblem with a SplatComposer and executes the partitioning program using the default QAOA quantum routine.

```python
problem = BinaryOptimizationProblem(
    large_bqm,
    decomposer=decomposer,
    composer=hybrid.SplatComposer(),
)
ensemble = PartitioningProgramEnsemble(
    problem=problem,
    n_layers=2,
    optimizer=optimizer,
    max_iterations=10,
    backend=backend,
)
sol_qaoa, energy_qaoa = run_partitioned(ensemble)
```

--------------------------------

### Install Divi AI dependencies

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/tools/divi_ai.rst

Command to install the AI-enabled version of Divi with specific binary constraints for llama-cpp-python.

```bash
pip install "qoro-divi[ai]" \
    --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu \
    --only-binary=llama-cpp-python
```

--------------------------------

### Build documentation

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Builds the documentation site from the docs directory.

```bash
cd docs
make build
```

--------------------------------

### Conventional Commits examples

Source: https://github.com/qoroquantum/divi/blob/main/CONTRIBUTING.md

Example commit messages following the Conventional Commits specification, enforced by a commit-msg hook.

```text
feat: add beam search aggregation strategy
fix: resolve duplicate object warnings in docs
docs: update backend execution guide with job configuration
test: add auth token resolution tests
```

--------------------------------

### Configure CharacterizationOptions for Warm-start and Subspaces

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/tools/qubo_characterization.rst

Demonstrates setting up automatic and manual characterization options. Use automatic for deep presets and manual for specific bitstring and variable qubit configurations.

```python
from divi.backends.characterization import CharacterizationOptions

automatic = CharacterizationOptions(
    preset="deep",
    subspace={
        "auto_warmstart": True,
        "solver": "greedy",
        "max_variable_qubits": 12,
        "restarts": 5,
    },
)

manual = CharacterizationOptions(
    n_qubits=6,
    subspace={
        "auto_warmstart": False,
        "base_bitstring": "001010",
        "variable_qubits": [0, 2, 5],
    },
)
```

--------------------------------

### Solve Binary Optimization with PCE

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Demonstrates initializing a PCE solver with a QUBO matrix, configuring encoding and optimization parameters, and retrieving the top solution.

```python
import numpy as np

from divi.backends import MaestroSimulator
from divi.qprog import PCE
from divi.qprog.optimizers import MonteCarloOptimizer
from divi.qprog.problems import BinaryOptimizationProblem

qubo = np.array([[-1.0, 2.0], [0.0, 1.0]])
pce = PCE(
    problem=BinaryOptimizationProblem(qubo),
    encoding_type="dense",
    alpha=2.0,
    n_layers=2,
    optimizer=MonteCarloOptimizer(population_size=8),
    max_iterations=5,
    backend=MaestroSimulator(shots=2000),
    seed=42,
)
pce.run()

best = pce.get_top_solutions(
    n=1, include_decoded=True, sort_by="energy"
)[0]
print(f"Best solution: {best.decoded} (energy={best.energy})")
print(f"Qubits: {pce.n_qubits} for {pce.n_vars} variables")
```

--------------------------------

### VQE example for hydrogen molecule

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/quickstart.rst

Python example using Divi to set up a VQE calculation for a hydrogen molecule, including imports for PySCF, VQE, HartreeFockAnsatz, ScipyOptimizer, MolecularProblem, and MaestroSimulator.

```python
from pyscf import gto
from divi.qprog import VQE, HartreeFockAnsatz
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import MolecularProblem
from divi.backends import MaestroSimulator
```

--------------------------------

### Example ExecutionResult structure

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/backends.rst

Shows the expected structure of the results attribute: a list of dictionaries with label, results, and metadata (for MaestroSimulator). The example displays two circuit results with bitstring counts.

```python
[
    {"label": "circuit_0", "results": {"00": 500, "11": 500}},
    {"label": "circuit_1", "results": {"01": 1000}}
]
```

--------------------------------

### Configure ensemble with sampling backend

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/program_ensembles.rst

Initializes a PartitioningProgramEnsemble with distinct optimization and sampling backends.

```python
ensemble = PartitioningProgramEnsemble(
    ...,
    backend=optimisation_backend,
    sampling_backend=sampling_backend,
)
ensemble.run()
```

--------------------------------

### Example test with fixtures and API key marker

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/development/testing.rst

Example test using the dummy_simulator fixture (defined in tests/conftest.py) to avoid real backend execution. The second test is marked with @pytest.mark.requires_api_key and only runs with --run-api-tests.

```python
import pytest
from pyscf import gto
from divi.qprog import VQE
from divi.qprog.algorithms import HartreeFockAnsatz
from divi.qprog.problems import MolecularProblem

def test_vqe_initialization(dummy_simulator):
    """Test that VQE initializes correctly with mock backend."""
    # Minimal H2 molecule for testing (or use a fixture from conftest)
    mol = gto.M(
        atom="H 0 0 -0.6614; H 0 0 0.6614", basis="sto-3g", unit="Bohr"
    )
    vqe = VQE(
        MolecularProblem.from_molecule(mol),
        ansatz=HartreeFockAnsatz(),
        backend=dummy_simulator,
    )
    assert vqe.n_params_per_layer is not None
    assert vqe.n_layers is not None

@pytest.mark.requires_api_key
def test_cloud_backend_integration(api_key):
    """Test integration with cloud backend."""
    # This test only runs with --run-api-tests
    pass
```

--------------------------------

### Submitting and Monitoring Jobs with QoroService

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/backends.rst

Initializes the QoroService client to access advanced simulators, tensor-network backends, and real QPUs.

```python
from divi.backends import QoroService

service = QoroService()
```

--------------------------------

### Initialize and Run VQE with Checkpointing

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/resuming_long_runs.rst

Sets up a molecular problem and VQE program, then executes it with checkpointing enabled to a specified directory.

```python
# Create a molecule
mol = gto.M(atom="H 0 0 -0.6614; H 0 0 0.6614", basis="sto-3g", unit="Bohr")
problem = MolecularProblem.from_molecule(mol)

# Create VQE program
vqe = VQE(
    problem,
    ansatz=HartreeFockAnsatz(),
    n_layers=2,
    max_iterations=10,
    optimizer=MonteCarloOptimizer(),
    backend=MaestroSimulator(),
)

# Run with checkpointing enabled
checkpoint_dir = Path("my_checkpoints")
vqe.run(checkpoint_config=CheckpointConfig(checkpoint_dir=checkpoint_dir))
```

--------------------------------

### Portfolio Selection Problem with QAOA

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/combinatorial_optimization_qaoa_pce.rst

Demonstrates setting up a PortfolioSelectionProblem with expected returns, covariance, ESG constraints, and a constrained mixer, followed by running the QAOA optimizer.

```python
import numpy as np

from divi.backends import MaestroSimulator
from divi.qprog import QAOA
from divi.qprog.optimizers import ScipyMethod, ScipyOptimizer
from divi.qprog.problems import LinearConstraint, PortfolioSelectionProblem

mu = np.array([0.10, 0.12, 0.08, 0.15, 0.09])
sigma = np.array(
    [
        [0.040, 0.006, 0.004, 0.010, 0.002],
        [0.006, 0.050, 0.005, 0.012, 0.003],
        [0.004, 0.005, 0.030, 0.006, 0.004],
        [0.010, 0.012, 0.006, 0.090, 0.005],
        [0.002, 0.003, 0.004, 0.005, 0.035],
    ]
)
esg = np.array([70.0, 55.0, 80.0, 60.0, 75.0])

problem = PortfolioSelectionProblem(
    mu,
    sigma,
    n_holdings=2,
    risk_tolerance=0.5,
    constraints=[LinearConstraint(esg, ">=", 65)],   # mean ESG >= 65
    use_constrained_mixer=True,
)
qaoa = QAOA(
    problem,
    n_layers=2,
    optimizer=ScipyOptimizer(method=ScipyMethod.COBYLA),
    max_iterations=10,
    backend=MaestroSimulator(),
)
qaoa.run()

best = qaoa.get_top_solutions(n=1, include_decoded=True, feasibility="repair")[0]
print(f"Holdings: {best.decoded}, objective: {best.energy:.5f}")
print(problem.metrics(best.bitstring))
```

--------------------------------

### Initialize QNSPSAOptimizer

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/execution_workflows/optimizers.rst

Basic initialization of the QNSPSAOptimizer, which preconditions SPSA with a pluggable metric.

```python
from divi.qprog.optimizers import QNSPSAOptimizer
```

--------------------------------

### Basic ZNE usage with VQE

Source: https://github.com/qoroquantum/divi/blob/main/docs/source/algorithms/improving_results_qem.rst

Shows how to set up ZNE with a Richardson extrapolator and pass it to a VQE program. Requires importing ZNE, RichardsonExtrapolator, VQE, MonteCarloOptimizer, MolecularProblem, QiskitSimulator, and pyscf.gto.

```python
from divi.circuits.zne import ZNE, RichardsonExtrapolator
from divi.qprog import VQE
from divi.qprog.optimizers import MonteCarloOptimizer
from divi.qprog.problems import MolecularProblem
from divi.backends import QiskitSimulator
from pyscf import gto
```
Tokens:
Raw