Maestro Local examples#

Maestro Local supports legacy QASM execute/estimate payloads and native schema-2 requests. Native requests expose symbolic simulator selection, noise models, state queries, incremental evolution, checkpoint batches and GPU distribution. The native request guide describes configuration, results, diagnostics and supported operations.

Setup and execution#

Build and install QRMI. Install maestro-local-server and the Maestro library it uses by following the server’s installation guide, which uses a prebuilt Maestro release. QRMI needs no optional Python extra for native requests. Python is an optional client; the server and workers use Rust/C/C++.

From the QRMI checkout, with an already acquired Maestro session:

export QRMI_JOB_QPU_RESOURCES=MAESTRO_LOCAL
export QRMI_JOB_QPU_TYPES=maestro-local
export MAESTRO_LOCAL_QRMI_JOB_ACQUISITION_TOKEN=<existing-session-id>
# Set QRMI_MAESTRO_SOCKET if the daemon does not use /run/maestro.sock.
python examples/task_runner/maestro_local/gen_native_input.py --example noise -o native-noise.json
task_runner MAESTRO_LOCAL native-noise.json

Both the Rust and Python task runners accept these files directly. The runner uses the supplied session; its owner should release that session after the workload finishes.

Exact amplitude damping#

This CPU example estimates X and Z after exact T1 damping, giving expectation values [0.8, 0.36]. It needs the QCSim density-matrix backend.

native-noise.json#
{
  "schema_version": 2,
  "operation": "estimate",
  "circuit": {
    "format": "openqasm",
    "num_qubits": 1,
    "source": "OPENQASM 2.0;\nqreg q[1]; h q[0];"
  },
  "simulator": {
    "backend": "qcsim",
    "method": "density_matrix"
  },
  "observables": [
    "X",
    "Z"
  ],
  "execution": {
    "seed": 123
  },
  "noise": {
    "evaluation": "exact",
    "channels": [
      {
        "kind": "t1",
        "targets": [
          0
        ],
        "gamma": 0.36
      }
    ]
  }
}

Native request templates#

Generate any of the native request templates with gen_native_input.py --example <name>:

Native examples#

Example (--example)

Feature

Expected result or prerequisite

noise

Exact amplitude damping

CPU expectations [0.8, 0.36].

query

Amplitudes and mixed-state diagnostics

Selected amplitudes [1, 0] and purity 0.8848.

thermal-idle

Thermal gate/idle relaxation and detuning

Density matrix; durations in seconds and detuning in Hz.

correlated-noise

Seeded correlated OU noise and MPS configuration

128 realizations with reported standard errors.

checkpoint

Noisy suffixes after an ideal prefix

Both suffixes return {"1": 32}.

incremental

Repeated exact Kraus steps

Z expectations [-1, -0.5, -0.125, 0.3671875] at steps [0, 1, 2, 4].

distributed-gpu

Local distributed statevector

Two physical GPU ordinals and the matching plugin, runtime and license.

mpi-gpu

MPI distributed GPU statevector

An administrator-defined server profile, rank-local GPU binding, MPI GPU plugin/license and CUDA-aware MPI.

Estimators and queries omit execution.shots; only execute and checkpoint_batch accept it. Checkpoint noise applies to suffixes after an ideal prefix. Seeds describe the complete ordered checkpoint request, so changing earlier suffixes can change later samples. The incremental example applies its Kraus channel at every step, including unobserved intermediate steps.

For MPI requests, adapt the launch profile name to the server configuration. launch is server routing metadata and is rejected by the standalone maestro-request validator. See the native guide for validation and execution tests, including the separate opt-ins for local GPU and MPI GPU tests.

Other Maestro examples#

Legacy QASM generator scripts and their requirements are in the task runner example directory. Legacy numeric simulator IDs depend on the Maestro build; consult target() for the installed catalog or use symbolic names in native requests.

The repository also includes Rust, Python, C, Lua and Qiskit primitive examples. The Qiskit examples require Qiskit to construct circuits.