Getting Started with Marqov

This guide walks you through setting up Marqov and running your first hybrid workload. By the end, you’ll understand how to define jobs, submit them to quantum and classical backends, and monitor their execution.

What is Marqov?

Marqov is a hybrid orchestration platform that unifies quantum processors (QPUs), GPUs, and classical compute under a single control plane. Instead of managing separate APIs, credentials, and execution models for each provider, Marqov gives you:

• One interface for IBM Quantum, AWS Braket, Azure Quantum, IonQ, and classical cloud providers
• Intelligent routing that places workloads on the optimal backend based on cost, availability, and performance
• Full provenance so every job is reproducible and auditable
• Seamless hybrid workflows where classical pre-processing, quantum execution, and post-processing are coordinated automatically

Whether you’re running variational algorithms, quantum machine learning, or optimization workloads, Marqov handles the infrastructure complexity so you can focus on the science.

Prerequisites

Before you begin, you’ll need:

1. A Marqov Account

Sign up at marqov.com to get your account credentials. Early access is available for research teams and enterprises.

2. Backend Credentials (Optional)

Marqov can manage backend credentials for you, or you can bring your own:

• IBM Quantum: API token from quantum.ibm.com
• AWS Braket: AWS access key with Braket permissions
• Azure Quantum: Azure subscription with Quantum workspace
• IonQ: API key from IonQ Cloud

You can add these later through the Marqov dashboard or CLI.

3. Python 3.9+

The Marqov CLI and SDK require Python 3.9 or higher.

python --version
# Python 3.9.x or higher

Installing the CLI

Install the Marqov CLI using pip:

pip install marqov

Verify the installation:

marqov --version
# marqov 0.1.0

Authenticate

Log in to connect your CLI to your Marqov account:

marqov login

This opens a browser window for authentication. Once complete, your credentials are stored securely in ~/.marqov/config.

You can also authenticate with an API key for CI/CD environments:

export MARQOV_API_KEY=your-api-key

Creating Your First Workload

A workload in Marqov defines what to run, where to run it, and how to handle the results. Let’s create a simple hybrid workflow.

Define a Workload

Create a file called hello-quantum.yaml:

name: hello-quantum
version: 1

# Define the steps in your workflow
steps:
  - name: prepare
    type: classical
    runtime: python:3.11
    script: |
      import numpy as np
      # Generate random parameters for variational circuit
      params = np.random.uniform(0, 2*np.pi, size=4)
      print(f"Generated parameters: {params}")
      # Pass to next step
      output = {"parameters": params.tolist()}

  - name: execute
    type: quantum
    backend: auto  # Let Marqov choose the best available backend
    depends_on: prepare
    circuit: |
      OPENQASM 3.0;
      include "stdgates.inc";
      qubit[2] q;
      bit[2] c;
      ry(input.parameters[0]) q[0];
      ry(input.parameters[1]) q[1];
      cx q[0], q[1];
      ry(input.parameters[2]) q[0];
      ry(input.parameters[3]) q[1];
      c = measure q;
    shots: 1024

  - name: analyze
    type: classical
    runtime: python:3.11
    depends_on: execute
    script: |
      counts = input.counts
      total = sum(counts.values())
      probabilities = {k: v/total for k, v in counts.items()}
      print(f"Measurement probabilities: {probabilities}")

# Resource preferences (optional)
preferences:
  cost: optimize  # Options: optimize, balanced, performance
  region: us-east  # Preferred region for classical compute

Understanding the Workload

This workload has three steps:

1. prepare (classical): Generates random variational parameters
2. execute (quantum): Runs a parameterized 2-qubit circuit
3. analyze (classical): Processes the measurement results

The depends_on field creates the execution graph. Marqov handles data passing between steps automatically.

Submitting to a Backend

Submit the Workload

marqov submit hello-quantum.yaml

Output:

Submitting workload: hello-quantum
  - Step 'prepare': queued (classical/us-east)
  - Step 'execute': pending (quantum/auto)
  - Step 'analyze': pending (classical/us-east)

Workload submitted: wl-7f3a2b1c
View status: https://app.marqov.com/workloads/wl-7f3a2b1c

Specify a Backend

To target a specific quantum backend:

marqov submit hello-quantum.yaml --backend ibm_sherbrooke

Or modify your workload to specify backends explicitly:

- name: execute
  type: quantum
  backend: ibm_sherbrooke  # Specific IBM backend
  # Or use provider selection:
  # backend:
  #   provider: aws-braket
  #   device: ionq-aria

Available Backends

List available backends with:

marqov backends list

Output:

PROVIDER        BACKEND           TYPE      QUBITS    STATUS
ibm             ibm_sherbrooke    QPU       127       available
ibm             ibm_brisbane      QPU       127       available
aws-braket      ionq-aria         QPU       25        available
aws-braket      rigetti-ankaa     QPU       84        maintenance
azure           ionq-harmony      QPU       11        available
simulator       aer               SIM       32        available
simulator       braket-sv1        SIM       34        available

Monitoring Job Status

Check Status

Monitor your workload in real-time:

marqov status wl-7f3a2b1c

Output:

Workload: hello-quantum (wl-7f3a2b1c)
Status: running
Started: 2025-02-15 10:23:45 UTC

Steps:
  [done]    prepare     0.8s    classical/us-east-1
  [running] execute     --      ibm_sherbrooke (position 3 in queue)
  [pending] analyze     --      classical/us-east-1

Estimated completion: ~4 minutes

Stream Logs

Watch logs in real-time:

marqov logs wl-7f3a2b1c --follow

Wait for Completion

Block until the workload completes:

marqov wait wl-7f3a2b1c

Get Results

Retrieve the final output:

marqov results wl-7f3a2b1c

Output:

{
  "workload_id": "wl-7f3a2b1c",
  "status": "completed",
  "duration": "3m 42s",
  "steps": {
    "prepare": {
      "output": {"parameters": [1.23, 4.56, 2.78, 0.91]}
    },
    "execute": {
      "backend": "ibm_sherbrooke",
      "shots": 1024,
      "counts": {"00": 512, "01": 128, "10": 128, "11": 256}
    },
    "analyze": {
      "output": {"probabilities": {"00": 0.5, "01": 0.125, "10": 0.125, "11": 0.25}}
    }
  }
}

Next Steps

You’ve just run your first hybrid workload on Marqov. Here’s where to go next:

Learn More

• Workload Reference: Deep dive into workload definition, dependencies, and data flow
• Backend Configuration: Configure credentials, set preferences, and understand backend selection
• Error Handling: Handle failures, retries, and fallback backends

Build Real Workflows

• VQE Tutorial: Build a complete Variational Quantum Eigensolver
• QAOA Optimization: Solve combinatorial problems with quantum-classical optimization
• Batch Execution: Run parameter sweeps efficiently across backends

Join the Community

• Discord: Get help and share your projects
• GitHub: Contribute to open-source components
• Request a Demo: See advanced features with our team

---

Questions? Reach out to support@marqov.com or join our Discord community.