Marqov Architecture Overview

Marqov is a quantum-classical compute orchestration platform designed to abstract away the complexity of hybrid workloads. This document provides a technical overview of the system architecture, component interactions, and the design principles that guide our approach.

High-Level Architecture

Marqov consists of four core components that work together to provide seamless orchestration across heterogeneous compute backends:

┌─────────────────────────────────────────────────────────────────────┐
│                              Agent                                   │
│         AI-powered assistant for capsule generation & management     │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                             Capsule                                  │
│           Reproducible, portable compute workload specification      │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                            Platform                                  │
│              Registry and execution engine for capsules              │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                              Mesh                                    │
│     Distributed network connecting IBM Quantum, AWS Braket, GPUs     │
└─────────────────────────────────────────────────────────────────────┘

Agent

The Agent is an AI-powered assistant that helps users generate and manage compute capsules. Rather than requiring users to manually specify complex workflow configurations, the Agent provides a conversational interface for:

Capsule generation — Describe your computation in natural language, and the Agent produces a valid capsule specification
Workflow optimization — The Agent suggests resource allocations, batching strategies, and error mitigation techniques
Debugging assistance — When executions fail, the Agent helps diagnose issues and suggests fixes
Best practices — Guidance on structuring hybrid workflows for reproducibility and performance

The Agent reduces the cognitive load of working with heterogeneous compute resources, making sophisticated orchestration accessible to researchers who aren’t infrastructure experts.

Capsule

The Capsule is the fundamental unit of work in Marqov. Think of it as a container for hybrid compute—a reproducible, portable specification that captures everything needed to execute a quantum-classical workload:

# Example capsule structure
capsule:
  name: vqe-h2-optimization
  version: 1.0.0

  environment:
    python: "3.11"
    dependencies:
      - qiskit>=1.0
      - numpy>=1.24

  workflow:
    steps:
      - name: initialize
        resource: cpu
        script: prepare_hamiltonian.py

      - name: optimize
        resource: qpu
        depends_on: [initialize]
        circuit: ansatz.qasm
        shots: 8192

      - name: analyze
        resource: gpu
        depends_on: [optimize]
        script: process_results.py

  resources:
    qpu:
      providers: [ibm, ionq, rigetti]
      constraints:
        min_qubits: 8
        min_fidelity: 0.99

Capsules provide:

Reproducibility — Complete capture of code, dependencies, parameters, and execution context
Portability — Abstract resource requirements that can be satisfied by multiple backends
Versioning — Track changes to workflows over time
Shareability — Publish capsules for others to use or build upon

Platform

The Platform serves as the registry and execution engine for capsules. It handles:

Capsule registry — Store, version, and discover capsules
Validation — Verify capsule specifications before execution
Scheduling — Queue jobs and allocate resources across the mesh
Execution management — Monitor running jobs, handle failures, collect results
Cost tracking — Attribute resource usage to users, teams, and projects

The Platform exposes both a CLI and API:

# CLI usage
marqov capsule validate ./my-capsule.yaml
marqov capsule publish ./my-capsule.yaml
marqov run vqe-h2-optimization --backend auto

# API usage
POST /api/v1/capsules
POST /api/v1/runs
GET  /api/v1/runs/{run_id}/status

Mesh

The Mesh is the distributed network layer that connects Marqov to compute backends. It abstracts the differences between providers, presenting a unified interface to the Platform.

Supported backends include:

Category	Providers
Quantum	IBM Quantum, AWS Braket, Azure Quantum, IonQ, Rigetti
GPU	AWS EC2, GCP, Azure, CoreWeave, Lambda Labs
Classical	Any Kubernetes cluster, on-prem HPC

The Mesh handles:

Connection management — Maintain authenticated sessions with providers
Job submission — Translate abstract requests to provider-specific APIs
Result collection — Gather outputs and normalize formats
Health monitoring — Track backend availability and queue times
Intelligent routing — Direct jobs to optimal backends based on constraints

Component Interactions

Request Flow

When a user submits a capsule for execution, the components interact as follows:

User → Agent → Capsule → Platform → Mesh → Backends
  ↑                         ↓                    ↓
  └─────────────────────────┴────────────────────┘
                Results

User describes their computation (optionally via Agent)
Agent generates or refines the capsule specification
Capsule is submitted to the Platform
Platform validates the capsule and creates an execution plan
Mesh routes each step to the appropriate backend
Results flow back through the stack to the user

Inter-Component Communication

Components communicate through well-defined interfaces:

Agent ↔ Platform: REST API for capsule CRUD operations
Platform ↔ Mesh: gRPC for low-latency job scheduling
Mesh ↔ Backends: Provider-specific SDKs (Qiskit, Braket, etc.)

All communication is authenticated and encrypted. The Platform maintains a persistent connection to the Mesh for real-time job status updates.

The Capsule Lifecycle

A capsule moves through five distinct phases:

1. Create

Capsules are created via the Agent, CLI, or programmatically:

from marqov import Capsule

capsule = Capsule(
    name="my-experiment",
    workflow=[
        Step("preprocess", resource="cpu"),
        Step("execute", resource="qpu", depends_on=["preprocess"]),
        Step("analyze", resource="cpu", depends_on=["execute"]),
    ]
)

The Agent can assist by:

Converting natural language descriptions to capsule specs
Suggesting optimal resource allocations
Adding error handling and retry policies

2. Validate

Before execution or publishing, capsules are validated:

marqov capsule validate ./capsule.yaml

Validation checks:

Schema compliance — Does the capsule match the specification?
Dependency resolution — Can all required packages be installed?
Resource availability — Are the requested backends accessible?
Cost estimation — What will this execution cost?

Validation errors are returned with actionable guidance:

ERROR: Capsule validation failed
  - Line 23: QPU constraint 'min_qubits: 127' cannot be satisfied
    Available backends: ibm_kyoto (127), ibm_osaka (127), ionq_forte (36)
    Suggestion: Reduce qubit requirement or specify ibm_* provider

3. Publish

Validated capsules can be published to the registry:

marqov capsule publish ./capsule.yaml

Publishing:

Assigns a unique identifier and version
Stores the capsule in the registry
Makes the capsule discoverable by team members
Optionally makes the capsule public

Published capsules are immutable—updates create new versions.

4. Execute

Execution is triggered via the CLI or API:

marqov run my-experiment@1.0.0 \
  --param shots=8192 \
  --backend auto \
  --priority high

The execution process:

Planning — Platform creates a DAG of workflow steps
Resource allocation — Mesh identifies available backends
Scheduling — Steps are queued based on dependencies and priority
Execution — Each step runs on its assigned backend
Data flow — Artifacts pass between steps as defined
Completion — Final results are stored and user is notified

During execution, users can monitor progress:

marqov run status abc123

Run: abc123
Capsule: my-experiment@1.0.0
Status: running
Progress: 2/3 steps complete

Steps:
  ✓ preprocess (cpu)     - 12s
  ✓ execute (qpu:ibm)    - 4m 32s
  ◐ analyze (gpu)        - running (1m 15s)

5. Analyze

After execution, results are available for analysis:

marqov run results abc123 --format json

The Platform provides:

Raw outputs — Direct results from each step
Execution metadata — Timing, resource usage, backend details
Provenance — Complete lineage from inputs to outputs
Cost breakdown — Per-step and total resource costs

Results can be downloaded, visualized in the web UI, or fed into downstream analysis pipelines.

Integration with Quantum Providers

Marqov integrates with quantum providers through the Mesh layer, providing a unified interface while preserving access to provider-specific features.

Connection Architecture

                    Mesh Controller
                          │
         ┌────────────────┼────────────────┐
         │                │                │
         ▼                ▼                ▼
   ┌──────────┐    ┌──────────┐    ┌──────────┐
   │ IBM      │    │ AWS      │    │ IonQ     │
   │ Adapter  │    │ Adapter  │    │ Adapter  │
   └────┬─────┘    └────┬─────┘    └────┬─────┘
        │               │               │
        ▼               ▼               ▼
   IBM Quantum      AWS Braket        IonQ

Each adapter handles:

Authentication — Managing API keys, tokens, and sessions
Circuit translation — Converting abstract circuits to provider formats
Job lifecycle — Submission, monitoring, cancellation
Result normalization — Converting provider outputs to standard format
Error mapping — Translating provider errors to Marqov error types

Provider-Specific Features

While Marqov abstracts common functionality, you can still access provider-specific features:

workflow:
  steps:
    - name: execute
      resource: qpu
      provider: ibm
      provider_options:
        optimization_level: 3
        resilience_level: 2
        dynamical_decoupling: true

Multi-Provider Workflows

A single workflow can span multiple quantum providers:

workflow:
  steps:
    - name: run-on-ibm
      resource: qpu
      provider: ibm
      circuit: circuit_a.qasm

    - name: run-on-ionq
      resource: qpu
      provider: ionq
      circuit: circuit_b.qasm

    - name: compare-results
      resource: cpu
      depends_on: [run-on-ibm, run-on-ionq]
      script: compare.py

This enables:

Benchmarking across hardware types
Exploiting hardware-specific advantages
Redundancy and verification

Key Design Principles

Marqov’s architecture is guided by three core principles:

Reproducibility

Every execution is fully reproducible. The Platform captures:

Code versions — Git commits, package versions, container digests
Parameters — All inputs and configuration
Environment — Runtime context, backend calibration data
Randomness — Seeds for any stochastic operations

Given a run ID, anyone can recreate the exact execution:

marqov run reproduce abc123

Reproducibility isn’t just about science—it’s about debugging. When something goes wrong, you need to recreate the failure to fix it.

Portability

Capsules are designed to be portable across:

Providers — Run on IBM today, IonQ tomorrow
Time — Execute now or schedule for later
Teams — Share capsules across organizations
Environments — Development, staging, production

Portability is achieved through:

Abstract resource requirements — Request “QPU with 20+ qubits” not “ibm_kyoto”
Standardized artifacts — Common formats for circuits, data, results
Environment isolation — Capsules carry their dependencies

Hardware Abstraction

The Mesh layer abstracts hardware differences, so workflows don’t need to know which specific backend they’ll run on:

# Algorithm code doesn't reference specific hardware
result = execute(
    circuit,
    resource="qpu",
    constraints={"min_qubits": 10, "min_fidelity": 0.98}
)

# Mesh routes to the best available backend
# Could be IBM, IonQ, Rigetti—the algorithm doesn't care

This abstraction enables:

Automatic failover — If one backend is unavailable, use another
Cost optimization — Route to the cheapest backend meeting constraints
Future-proofing — New backends work without code changes

Conclusion

Marqov’s architecture is designed to make quantum-classical orchestration accessible, reproducible, and portable. The Agent reduces complexity, Capsules capture intent, the Platform manages execution, and the Mesh abstracts infrastructure.

Whether you’re running variational algorithms, benchmarking quantum hardware, or building production hybrid systems, Marqov provides the orchestration layer you need.

Ready to explore the architecture yourself? Request a demo or read the docs to get started.