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.
{
"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>:
Example ( |
Feature |
Expected result or prerequisite |
|---|---|---|
|
Exact amplitude damping |
CPU expectations |
|
Amplitudes and mixed-state diagnostics |
Selected amplitudes |
|
Thermal gate/idle relaxation and detuning |
Density matrix; durations in seconds and detuning in Hz. |
|
Seeded correlated OU noise and MPS configuration |
128 realizations with reported standard errors. |
|
Noisy suffixes after an ideal prefix |
Both suffixes return |
|
Repeated exact Kraus steps |
Z expectations |
|
Local distributed statevector |
Two physical GPU ordinals and the matching plugin, runtime and license. |
|
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.