Skip to content

feat(executors): add IonQ Direct API executor#42

Open
Adithyaphani wants to merge 1 commit into
marqov-dev:mainfrom
Adithyaphani:ionq-direct-executor
Open

feat(executors): add IonQ Direct API executor#42
Adithyaphani wants to merge 1 commit into
marqov-dev:mainfrom
Adithyaphani:ionq-direct-executor

Conversation

@Adithyaphani

@Adithyaphani Adithyaphani commented Jun 12, 2026

Copy link
Copy Markdown

Closes #1.

Summary

  • Add IonQExecutor / IonQExecutorConfig for direct IonQ v0.3 REST API
    submission (no AWS Braket routing required).
  • Convert circuits via circuit.to_qiskit() -> OpenQASM 2.0 -> IonQ "qasm"
    input format.
  • Poll job status; map IonQ probability results to ExecutionResult.counts
    (bitstring counts, matching BraketExecutor's output shape).
  • Map IonQ job failures (failure.error / failure.code) to a descriptive
    RuntimeError.
  • Map IonQ backend status (available/running/calibrating/unavailable/
    reserved/offline) to DeviceStatus per CONTRIBUTING.md §2 (device-level,
    not job-level).
  • Register "IonQ Direct" in ExecutorFactory, export from
    marqov/executors/__init__.py.
  • Update README's "Supported Backends" table to mark IonQ Direct as
    available.
  • Unit tests with a mocked IonQ client (15 tests) covering: successful
    execution, polling to completion, job failure handling, cancel
    (success/failure), backend status mapping for all documented states,
    probability->counts bit-ordering, factory registration, and missing-API-key
    error handling.

Here's the architecture, in two diagrams, IonQExecutor sits in the codebase:

ionq_executor_architecture

Now the request/data flow inside execute():

ionq_execute_flow

Design note

The issue references the ionq PyPI package, which is currently pre-release
(0.0.0a15) and doesn't yet cover job polling, results retrieval, cancellation,
or backend status -- all required by the acceptance criteria. Rather than
depend on an unstable alpha SDK, this implements a small injectable REST
client (_IonQRestClient) against IonQ's documented v0.3 API
(https://docs.ionq.com/guides/direct-api-submission). No new dependency is
required -- requests is already a transitive dependency (via azure-core,
ibm-cloud-sdk-core, qiskit-ibm-runtime). The client is a thin, swappable
layer if the official SDK matures.

Verification

  • ruff check marqov/executors/ionq.py marqov/executors/factory.py marqov/executors/__init__.py tests/test_ionq_executor.py -- all checks passed
  • pytest tests/test_ionq_executor.py -v -- 15 passed
  • pytest tests/ -q -- 283 passed, 13 skipped, 0 failed (after excluding 3
    pre-existing failures, see note below)
  • Submitted a real request to https://api.ionq.co/v0.3/jobs (with an
    invalid placeholder key) and confirmed the client correctly surfaces IonQ's
    401 Unauthorized via requests.HTTPError -- the request/auth/error-
    propagation path is exercised against the live API, not just mocks.

Pre-existing test failures (unrelated)

tests/test_activity_heartbeat.py, tests/test_decorators.py, and
tests/test_temporal_activities.py fail with RecursionError: Stack overflow
(cloudpickle serialization) on Python 3.14 in this environment. Confirmed via
git stash that these fail identically on main without this change -- a
pre-existing environment issue unrelated to this PR.

AI disclosure

Claude helped draft the initial IonQExecutor implementation and tests. I reviewed every method, ran the full suite, debugged and isolated three pre-existing environment failures unrelated to this change (confirmed via git stash), verified the dependency claims, checked the live API's error response, and updated the README.

@Adithyaphani

Copy link
Copy Markdown
Author

@ddri looking forward to your review and response on the opened PR , happy to make further changes if needed.

@Adithyaphani

Copy link
Copy Markdown
Author

@ddri looking forward to your review & response, and happy to make further changes if needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(executors): IonQ native API executor

1 participant