Key Concepts

Tasks

A task is a single unit of work — a Python function decorated with @task. Tasks are the building blocks of workflows. When called inside a workflow, tasks don’t execute immediately; instead, they register in a dependency graph and may run in parallel with other independent tasks.

@task(retries=3, timeout=600)
def measure(circuit, pauli_string):
    return device.run(circuit, shots=1000)

Workflows

A workflow is a composition of tasks, defined with @workflow. When you call a workflow function, Marqov analyzes which tasks depend on each other and builds an execution graph. Independent tasks run in parallel automatically.

@workflow(name="VQE-Step")
def vqe_step(theta):
    circuit = build_ansatz(theta)
    zz = measure(circuit, "ZZ")  # These three tasks
    zi = measure(circuit, "ZI")  # run in parallel
    iz = measure(circuit, "IZ")  # because they're independent
    return compute_energy(zz, zi, iz)

Execution Graph

The execution graph is the dependency tree Marqov builds from your workflow. Tasks are organized into execution levels — all tasks at the same level run in parallel, and the next level starts only when the previous completes.

Level 0: build_ansatz
Level 1: measure("ZZ"), measure("ZI"), measure("IZ")  ← parallel
Level 2: compute_energy

Backends

A backend is a quantum computer or simulator where your circuits execute. Marqov supports:

Switch backends by changing a single parameter — your algorithm code stays the same.

Jobs

A job is a single execution of a script on a backend. When you submit a script, Marqov creates a job, dispatches it to a worker, and tracks its status in real time (pending → running → completed/failed).

Each completed job stores:

• Result: Your algorithm’s output (counts, energies, etc.)
• Workflow metadata: Execution graph, per-task timing, Gantt chart data
• Temporal IDs: Links to the full Temporal execution history

Capsules

A capsule is a sealed, reproducible snapshot of a completed job. Capsules capture the script, parameters, backend configuration, and results — everything needed to reproduce or verify a quantum computation. Capsules progress through a lifecycle: draft → runnable → sealed → published.

Circuits

The Circuit class is Marqov’s backend-agnostic quantum circuit abstraction. Build circuits using a fluent API, then convert to any supported framework:

from marqov import Circuit
 
circuit = Circuit().h(0).cnot(0, 1).rz(0.5, 0)
 
braket_circuit = circuit.to_braket()
qiskit_circuit = circuit.to_qiskit()
qasm_string = circuit.to_openqasm()

Temporal

Temporal  is the workflow orchestration engine that powers Marqov’s execution. It provides:

• Durability: Workflows survive worker restarts
• Retries: Failed tasks automatically retry (configurable)
• Timeouts: Tasks that exceed their timeout are cancelled
• Observability: Full execution history in the Temporal UI

You don’t need to interact with Temporal directly — Marqov handles the integration. But you can inspect workflow executions in the Temporal UI for debugging.

Next steps

• Architecture — How these pieces fit together
• Quickstart — Build your first workflow