Add qiboml integration for QAOA in QUBO

[jf-kong]

Summary

This PR integrates qiboml as an optional training engine for QUBO.train_QAOA, while keeping the existing qibo optimizer path as default (engine="legacy").

The goal is to enable gradient-based QAOA optimization through qiboml/torch with minimal API disruption and optional dependency installation.

What Changed

1. Added qiboml adapter integration

• New module: src/qiboopt/integrations/qiboml_adapter.py
• Implements optimize_qaoa_with_qiboml(...) using qiboml's PyTorch QuantumModel
• Supports differentiation backends (psr, jax, adjoint, default torch path)
• Supports qiboml optimizers: adam, sgd
• Applies QUBO/Ising constant energy shift so reported losses match QUBO objective scale

2. Extended QUBO.train_QAOA to support multi-engine training

• New args: engine, optimizer, lr, epochs, differentiation
• engine="legacy" remains default and preserves previous behavior
• engine="qiboml" uses qiboml adapter for regular-loss optimization
• CVaR (regular_loss=False) continues through legacy path

3. Added exact (no-shot) execution support

• nshots=None or nshots=0 now runs exact mode
• Return statistics are now:
  • sampled mode (nshots > 0): bitstring counts
  • exact mode (nshots is None or 0): bitstring probabilities

4. Refactored QAOA circuit construction utilities

• Added helpers for parameter splitting/rebuilding and callable circuit generation for qiboml tracing
• Added option to build circuits without measurements when needed by exact expectation paths

5. Dependency updates for optional qiboml usage

• pyproject.toml updated with optional qiboml and torch
• Added extras/group install path for qiboml runtime

Backward Compatibility

• Default behavior remains unchanged (engine="legacy").
• qiboml is fully optional and only required when engine="qiboml" is selected.

[shangtai]

Thanks for this. updated poetry.lock.

We will have to fix some bugs first :)

************* Module qiboopt.integrations.qiboml_adapter
src/qiboopt/integrations/qiboml_adapter.py:19:4: E0401: Unable to import 'qiboml.operations.differentiation' (import-error)
************* Module qiboopt.opt_class.opt_class
src/qiboopt/opt_class/opt_class.py:838:23: E0606: Possibly using variable 'params' before assignment (possibly-used-before-assignment)
src/qiboopt/opt_class/opt_class.py:857:16: E0606: Possibly using variable 'best' before assignment (possibly-used-before-assignment)
src/qiboopt/opt_class/opt_class.py:859:16: E0606: Possibly using variable 'extra' before assignment (possibly-used-before-assignment)
Error: Process completed with exit code 2.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (1fa474f) to head (ebf0682).
⚠️ Report is 16 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #80   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         4    +1     
  Lines          509       603   +94     
=========================================
+ Hits           509       603   +94     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/qiboopt/__init__.py	100.00% <100.00%> (ø)
src/qiboopt/integrations/qiboml_adapter.py	100.00% <100.00%> (ø)
src/qiboopt/opt_class/opt_class.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.