Cloud and Quantum Hardware Execution

Cloud and Quantum Hardware Execution

Choose a remote execution path, configure account access, submit a circuit, recover its job identity, and interpret the returned result.

Scope: FlagQuantum 0.3.1, checked on October 20, 2026. The local baseline and synthetic Braket/Azure preflight scripts were executed with Python 3.12.14, PyTorch 2.13.0, and macOS ARM64. The two account-dependent scripts had their CLI and lifecycle control flow checked with local test doubles. No live provider login, remote simulation, paid job, or quantum-hardware submission was performed for this page. Live output examples below are explicitly marked as formats or ideal references, not measured results.

Use Installation and Compatibility, Circuit Compilation and Interoperability, and Qubit Ordering and Result Conventions alongside this guide.

1. Supported Integration Paths

Platform / integration	Entry points in this release	Execution meaning and boundary
Quafu current task API and legacy SQC compatibility	fq.run(target="quafu:..."), fq.submit, fq.restore_job, QuafuProvider	Remote ideal/device-noise simulators and actual QPU targets. Availability, account entitlement, and protocol requirements vary by target.
Jiuding QuantumAI Cloud	fq.submit / fq.restore_job for native jobs; fq.run(target="jiuding:...") for resident-workspace execution; JiudingClient for expert workflows	Remote classical CPU/GPU simulation, not a QPU hardware measurement. Requires compatible resources and runtime images.
Amazon Braket	AmazonBraketProvider, deployment packages, dry_run, submit, fetch_result	SDK-backed OpenQASM 3 route to a selected device. There is no generic Braket fq.submit receipt journey demonstrated here.
Azure Quantum	AzureQuantumProvider plus deployment packages; synchronous fq.run(target="azure:<target-id>")	OpenQASM 3 compiled to QIR with QDK. The root fq.run slice supports one full-register counts request. It is separate from the Quafu/Jiuding detached-job API.
Configured HTTP provider contracts	HttpQuantumProvider and provider-owned profiles/endpoints	An integration interface, not evidence that every cloud service or hardware vendor is supported.

Use discovery and the signed-in provider console to choose a currently accessible target. Device names in release examples are not a live inventory, and a provider SDK's device catalog is broader than the capabilities verified by a FlagQuantum adapter.

Quafu examples use names such as Baihua, Shenglian, and Dongling; their actual availability and capabilities must be queried. Braket needs an accessible device ARN. Azure needs a workspace and enabled target ID. Do not substitute invented device names, queue names, image references, or widths.

The repository also contains a separately scoped QBoson Kaiwu remote SDK layer whose provider contract is under review. It is not one of the gate-circuit/counts workflows demonstrated here and must not be assumed to work through the same fq.submit interface.

2. Environment and Credentials

Core FlagQuantum 0.3.1 requires Python 3.10–3.12 and PyTorch >=2.10,<2.15. A fresh CPU environment can run the offline examples with:

python -m pip install "flagquantum==0.3.1" numpy
python -m pip check

Retain a managed accelerator environment's vendor runtime when applicable. The remote runtime image must independently contain a compatible executor and dependencies; installing the client locally does not prepare a cloud image.

Integration	Dependency / environment	Credential source
Quafu direct task API	Core HTTP adapter; direct service compilation does not require quafusqc, local QuarkCircuit, or QSteed	QUAFU_API_KEY for the current task API. Legacy SQC requires QUAFU_API_TOKEN or an explicit legacy token. The two are not interchangeable.
Jiuding native jobs	Core remote client, project membership, active supported queue, compatible image	Explicit JiudingCredentials, or both JIUDING_AK and JIUDING_SK, or the platform-injected pair inside a workspace.
Braket	pip install "flagquantum[braket]==0.3.1"; extra declares amazon-braket-sdk>=1.117,<2 on Python 3.11+	The AWS SDK credential chain, a configured profile or role, provider access, and appropriate result-storage permissions.
Azure	pip install "flagquantum[azure]==0.3.1"; extra declares qdk[azure]>=1.32.3,<2	The configured Azure/QDK workspace identity and authorization. Workspace resource ID and target ID identify resources; they are not substitutes for authentication.

For AWS account and storage permissions, follow Braket access management. For Azure workspace access, follow Microsoft's workspace authentication guide. Use provider instructions matching the installed SDK rather than upgrading outside FlagQuantum's dependency window.

Keep credential values outside committed scripts and notebooks. The environment examples below contain placeholders; replace them through your shell/session or credential manager. FlagQuantum does not load .env files automatically. A credential configured in a different process is not necessarily visible to the active notebook kernel.

Quafu Configuration

For the current task API:

export QUAFU_API_KEY="YOUR_CURRENT_TASK_API_KEY"

The optional QUAFU_TASK_SERVER_URL defaults to the production HTTPS task endpoint. Configure it only when your deployment requires a different verified service. Set QUAFU_API_TOKEN separately if you need the legacy SQC path. An API key alone does not authorize the legacy endpoint.

A wholly missing credential is rejected before submission. Single-circuit protocol fallback is bounded by the adapter's request/response rules; an ambiguous submission is not safe to blindly retry. Simulator-only targets and circuit collections have no equivalent legacy fallback.

The optional quafu extra supplies a separate SDK/calibration dependency with a Python 3.12 marker in this release; it does not install the local QSteed compiler plugin. Use the direct service-compilation path in this guide unless you explicitly need and configure a different compiler workflow.

Jiuding Configuration

For a trusted single-user shell, export both values:

export JIUDING_AK="YOUR_JIUDING_ACCESS_KEY"
export JIUDING_SK="YOUR_JIUDING_SECRET_KEY"

For a per-user application/notebook session, construct JiudingCredentials(access_key=..., secret_key=...) and pass credentials= to JiudingClient, fq.submit, and fq.restore_job. Explicit credentials bypass fallback discovery. A partial pair is rejected, and values are not combined across sources. Inside an appropriate workspace, the final fallback reads the platform's /etc/accesskey/user-ak and /etc/accesskey/user-sk files.

Shared kernels under one Unix account do not provide a hard credential boundary. Use per-user isolation or an appropriate credential broker for mutually untrusted users. Receipts omit credentials, but still contain private account/job context and should be kept in personal persistent storage.

3. Establish a Local Reference First

Save as cloud_local.py:

import torch
import flagquantum as fq
from flagquantum.deployment import expectation_z_from_counts

options = fq.ExecutionOptions(mode='statevector', backend='pytorch', device='cpu', seed=7)
asymmetric = fq.run(fq.Circuit(3).x(0), options=options, outputs=fq.counts(), shots=128)
assert asymmetric.counts == [{'100': 128}]
bell = fq.run(fq.Circuit(2).h(0).cx(0, 1), options=options, outputs=fq.probabilities())
assert torch.allclose(bell.probabilities, torch.tensor([[0.5, 0.0, 0.0, 0.5]]), atol=1e-6)
# Synthetic counts illustrate result analysis; they are not hardware data.
synthetic = {'00': 60, '11': 68}
z0 = expectation_z_from_counts(synthetic, qubits=0).item()
assert abs(z0 + 0.0625) < 1e-6
print('Local X(0) counts:', asymmetric.counts[0])
print('Local Bell probabilities:', [round(v, 6) for v in bell.probabilities[0].tolist()])
print('Synthetic count total:', sum(synthetic.values()))
print(f'Synthetic <Z0>: {z0:.6f}')
print('Local baseline and count-analysis checks passed.')

Run python cloud_local.py. Expected output:

Local X(0) counts: {'100': 128}
Local Bell probabilities: [0.5, 0.0, 0.0, 0.5]
Synthetic count total: 128
Synthetic <Z0>: -0.062500
Local baseline and count-analysis checks passed.

X(0) prepares |100> because qubit 0 is the most-significant bit. This asymmetric circuit exposes ordering mistakes that a symmetric Bell circuit can conceal. The synthetic counts demonstrate how <Z0> is estimated as (N0-N1)/shots; they are not hardware observations.

A local simulator reference verifies the circuit and result convention. It does not verify a provider credential, queue, physical mapping, or hardware accuracy.

4. Discover Resources and Manage Quafu/Jiuding Jobs

Save this complete account-dependent script as cloud_job.py:

import argparse
import os
from pathlib import Path
import flagquantum as fq

parser = argparse.ArgumentParser(description='Submit once or inspect a saved Quafu/Jiuding job. Submit creates real remote work.')
parser.add_argument('provider', choices=('quafu', 'jiuding'))
parser.add_argument('action', choices=('discover', 'submit', 'status', 'result', 'wait', 'cancel'))
parser.add_argument('--receipt', type=Path)
parser.add_argument('--target', help='Submit target; defaults to quafu:sim or jiuding:gpu')
parser.add_argument('--shots', type=int, default=128)
parser.add_argument('--timeout', type=float, default=300)
args = parser.parse_args()
if args.action == 'discover':
    if args.provider == 'quafu':
        from flagquantum.remote.qpu import QuafuProvider
        for device in QuafuProvider().list_devices():
            print(device.name, 'simulator=' + str(device.is_simulator), 'qubits=' + str(device.n_qubits))
    else:
        from flagquantum.remote.compute import JiudingClient
        for resource in JiudingClient().list_resources():
            print(resource)
    raise SystemExit(0)
if args.receipt is None:
    parser.error('--receipt is required for this action')
receipt = args.receipt.expanduser().resolve()
print('Receipt path:', receipt)

if args.action == 'submit':
    target = args.target or ('quafu:sim' if args.provider == 'quafu' else 'jiuding:gpu')
    if not target.startswith(args.provider + ':'):
        parser.error('Target prefix must match the selected provider')
    settings = {}
    if args.provider == 'jiuding':
        for field, variable in [('project', 'JIUDING_PROJECT'), ('queue', 'JIUDING_QUEUE'), ('image', 'JIUDING_IMAGE')]:
            value = os.environ.get(variable)
            if not value:
                parser.error(f'Set {variable} to a discovered, compatible platform value')
            settings[field] = value
    job = fq.submit(
        fq.Circuit(3).x(0), target=target, outputs=fq.counts(), shots=args.shots,
        receipt=receipt, name='wiki-asymmetric-readout', **settings,
    )
else:
    job = fq.restore_job(receipt)
    if not job.target.startswith(args.provider + ':'):
        parser.error('Receipt target does not match the selected provider')
print('Job ID:', job.id)

if args.action in ('submit', 'status'):
    print('Status:', job.status())
    print('Raw status:', job.raw_status)
elif args.action == 'cancel':
    job.cancel()
    print('Status after cancellation request:', job.status())
else:
    result = job.wait(timeout=args.timeout) if args.action == 'wait' else job.result()
    for index, counts in enumerate(result.counts):
        print(f'Circuit {index} counts:', counts)
        print('Count total:', sum(counts.values()))

python cloud_job.py --help works without cloud access. Other actions contact the selected platform and require the configuration above. submit creates real remote work on its first matching request; it can consume quota or incur charges according to the selected service. The script uses one counts output and the asymmetric three-qubit circuit from the local reference.

Quafu: Discover, Submit, and Read

List account-visible targets first:

python cloud_job.py quafu discover

Each returned row has the form <name> simulator=<True|False> qubits=<width>. The values are provider responses; this page does not assert a current target list.

Start with the remote ideal simulator:

python cloud_job.py quafu submit --target quafu:sim --shots 128 --receipt quafu-sim.receipt.json
python cloud_job.py quafu status --receipt quafu-sim.receipt.json
python cloud_job.py quafu wait --timeout 300 --receipt quafu-sim.receipt.json

Expected submission-output format:

Receipt path: <absolute path>/quafu-sim.receipt.json
Job ID: <provider-assigned id>
Status: <normalized status>
Raw status: <provider status>

For an ideal successful execution of this X-only circuit, the result should be:

Circuit 0 counts: {'100': 128}
Count total: 128

That is the ideal reference, not a live result recorded for this page. For a physical run, select an exact discovered QPU name and a new experiment receipt; for example, if your account exposes Baihua:

python cloud_job.py quafu submit --target quafu:Baihua --shots 1024 --receipt quafu-hardware.receipt.json
python cloud_job.py quafu wait --receipt quafu-hardware.receipt.json

Hardware counts are noisy and need not equal {'100': 1024}. In the documented direct route, hardware shots are multiples of 1024 from 1024 through 8192; ideal/device-noise simulator targets accept 1 through 8192. Check target admission before using another count.

Other documented Quafu selectors include <device>-sim when that physical device reports simulator availability, plus all-race and all-redispatch for their respective real-device scheduling semantics. A -sim target remains a remote service request; it does not download a noise model or silently execute locally. Racing targets can involve more than one physical resource, so read their quota semantics before choosing them.

Jiuding: Discover Resources, Then Choose Exact Values

python cloud_job.py jiuding discover

A submit-ready resource has the following shape:

{'project': '<project-set.project>', 'queue': '<queue>', 'accelerator_model': '<model>', 'images': ['<compatible-image>'], 'submission_supported': True}

Use a compatible returned image and supported queue. These values are resource identifiers, not credentials or resources created by FlagQuantum. An empty list does not grant membership or quota; a visible image is not proof it contains the required executor.

For this script, export the selected values explicitly:

export JIUDING_PROJECT="YOUR_PROJECT_SET.YOUR_PROJECT"
export JIUDING_QUEUE="YOUR_SUPPORTED_QUEUE"
export JIUDING_IMAGE="YOUR_COMPATIBLE_RUNTIME_IMAGE"
python cloud_job.py jiuding submit --target jiuding:gpu --shots 128 --receipt jiuding-gpu.receipt.json
python cloud_job.py jiuding status --receipt jiuding-gpu.receipt.json
python cloud_job.py jiuding wait --receipt jiuding-gpu.receipt.json

JIUDING_QUEUE and JIUDING_IMAGE are read and passed by this example script; do not assume arbitrary client functions automatically discover those environment variables. The native job route uses project/queue/image configuration without requiring a resident workspace or SSH. The ideal X-only result has the same {'100': 128} reference, but it is a classical simulated result from the selected cloud runtime.

Status, Results, Timeouts, and Cancellation

Normalized job states are queued, running, succeeded, failed, cancelled, and unknown. Transpiled maps to queued, not completed. Unknown or missing status never establishes success.

• status() queries once and retains the raw provider status.
• result() does not poll and requires a successful job with available results.
• wait(timeout=...) polls intentionally. A timeout leaves the task running; it is not cancellation or resubmission. In-flight network calls have their own timeout behavior.
• cancel() requests cancellation; query afterwards to see the actual state. Closing a notebook or interrupting a cell does not cancel a remote task.

For example:

python cloud_job.py quafu result --receipt quafu-sim.receipt.json
python cloud_job.py quafu cancel --receipt quafu-sim.receipt.json

Use result after success; use cancel only for an experiment you intend to stop. No background watcher is created by these methods.

Receipt Recovery and Duplicate-Submission Boundaries

The script passes receipt= to fq.submit. On the first call, the SDK reserves a request journal, submits, and saves the receipt. A later matching call restores the same job. Changing the circuit, target, shots, or other identity-relevant settings rejects reuse. Keep the receipt and its SDK-created <receipt>.request.json journal together at the same persistent path.

fq.restore_job retrieves an existing job and never resubmits. Provide current credentials again after a process restart. A receipt is local decoding/recovery context, not cryptographic proof of hardware execution.

If a request journal exists but the receipt is missing, or submission loses its response, reconcile the experiment with the platform before another submission. Do not delete the guard just to retry. The local journal is not provider-side exactly-once execution. Without receipt=, each submit can create new work.

For Quafu collections, fq.submit([circuit0, circuit1], ...) creates one parent job. The initial supported slice requires nonempty same-width logical circuits, shared target, service compilation, and full-register counts. Shots apply per circuit, and counts preserve input order. It does not support mixed widths, local compilers, explicit physical mappings, or Jiuding circuit lists. Partially failed collections are not returned as silently shortened success lists; see the release remote-job guide for target limits and quota rules.

5. Run Braket/Azure Preflight Entirely Offline

This complete script uses synthetic metadata objects, not real devices or SDK sessions. It exercises FlagQuantum deployment-package validation and provider preflight without credentials or network access.

Save as cloud_previews.py:

from types import SimpleNamespace
import flagquantum as fq
from flagquantum.deployment import create_deployment_package
from flagquantum.remote.qpu import AmazonBraketProvider, AzureQuantumProvider

# Synthetic metadata objects: no SDK session, credentials, or network.
class OfflineBraketDevice:
    arn = 'offline-example-braket-device'
    name = 'offline simulator'
    properties = SimpleNamespace(paradigm=SimpleNamespace(
        qubitCount=3, nativeGateSet=('h', 'cx', 'x'),
        connectivity=SimpleNamespace(connectivityGraph={'0': ['1'], '1': ['0', '2'], '2': ['1']}),
    ))
    def run(self, *args, **kwargs):
        raise AssertionError('The offline example must never submit a task')

class OfflineAzureTarget:
    name = 'offline.simulator'
    provider_id = 'offline-example'
    def submit(self, *args, **kwargs):
        raise AssertionError('The offline example must never submit a job')

providers = [
    AmazonBraketProvider(OfflineBraketDevice()),
    AzureQuantumProvider(object(), OfflineAzureTarget(), n_qubits=3, basis_gates=('h', 'cx', 'x')),
]
for provider in providers:
    package = create_deployment_package(
        fq.Circuit(2).h(0).cx(0, 1), backend=provider.backend,
        shots=128, qasm_version=3.0,
    )
    preview = provider.dry_run(package)
    assert preview.compatible and not preview.blockers
    assert preview.program == package.qasm
    assert preview.program.startswith('OPENQASM 3.0;')
    print(f'{provider.provider}: compatible={preview.compatible}, shots={preview.shots}, blockers={preview.blockers}')
print('Both offline preflights passed; no cloud task was submitted.')

Run python cloud_previews.py. Expected output:

amazon-braket: compatible=True, shots=128, blockers=()
azure-quantum: compatible=True, shots=128, blockers=()
Both offline preflights passed; no cloud task was submitted.

A compatible preview means the supplied package meets that adapter's local checks. Synthetic metadata cannot establish that the real target exists, accepts the program, has current quota, or behaves like the local simulator. Instantiating an adapter from a real ARN/resource ID may itself perform authenticated metadata lookup even when the later call is named dry_run.

6. Use SDK-Backed Braket/Azure Execution

Save as cloud_sdk.py:

import argparse
import os
import flagquantum as fq
from flagquantum.deployment import create_deployment_package
from flagquantum.remote.qpu import AmazonBraketProvider, AzureQuantumProvider, validate_deployment_result

parser = argparse.ArgumentParser(description='SDK-backed provider preview, or real submission with --submit.')
parser.add_argument('provider', choices=('braket', 'azure'))
parser.add_argument('--submit', action='store_true')
parser.add_argument('--shots', type=int, default=128)
args = parser.parse_args()
if args.provider == 'braket':
    provider = AmazonBraketProvider(os.environ['BRAKET_DEVICE_ARN'])
else:
    provider = AzureQuantumProvider(
        os.environ['AZURE_QUANTUM_RESOURCE_ID'], os.environ['AZURE_QUANTUM_TARGET_ID'],
        n_qubits=int(os.environ['AZURE_QUANTUM_TARGET_QUBITS']),
    )
package = create_deployment_package(
    fq.Circuit(2).h(0).cx(0, 1), backend=provider.backend,
    shots=args.shots, qasm_version=3.0,
)
preview = provider.dry_run(package)
print('Preflight:', preview.summary())
if not preview.compatible:
    raise SystemExit('Target/package preflight failed')
if not args.submit:
    print('No task submitted. Provider metadata lookup may have used the network.')
else:
    handle = provider.submit(package)
    print('Task ID:', handle.task_id, flush=True)
    # These SDK result calls may wait for provider completion.
    result = validate_deployment_result(provider.fetch_result(handle))
    print('Counts:', dict(result.counts))
    print('Shots represented:', result.shots)

python cloud_sdk.py --help works without a provider SDK session. Actual provider preview/submission requires the corresponding extra, authorized resources, and SDK authentication. The code's lifecycle was checked with local test doubles, not with a live AWS or Azure account.

Amazon Braket Setup and Execution

Use Python 3.11 or 3.12 for the release's Braket extra:

python -m pip install "flagquantum[braket]==0.3.1"
export AWS_PROFILE="YOUR_CONFIGURED_PROFILE"
export AWS_DEFAULT_REGION="YOUR_DEVICE_REGION"
export BRAKET_DEVICE_ARN="YOUR_ACCESSIBLE_DEVICE_ARN"
python cloud_sdk.py braket

Use the provider console/SDK to obtain the ARN and confirm service enablement, device access, execution window, and result-storage permissions. The adapter reads an AwsDevice profile; it does not certify every device the SDK can list.

The preview prints a dictionary including provider/backend identity, shots, compatibility, and blockers, followed by the no-submission message. To intentionally submit the selected task:

python cloud_sdk.py braket --submit --shots 128

Azure Setup and Execution

Configure an authorized Azure Quantum workspace and the QDK identity using Microsoft's guidance, then:

python -m pip install "flagquantum[azure]==0.3.1"
export AZURE_QUANTUM_RESOURCE_ID="YOUR_WORKSPACE_RESOURCE_ID"
export AZURE_QUANTUM_TARGET_ID="YOUR_ENABLED_TARGET_ID"
export AZURE_QUANTUM_TARGET_QUBITS="AUTHORITATIVE_POSITIVE_INTEGER_WIDTH"
python cloud_sdk.py azure

Replace the width placeholder with the target's documented positive integer width; it is not inferred from the test circuit. The target must accept the adapter's QIR submission workflow. A QPU/emulator name alone does not establish this compatibility.

To intentionally submit:

python cloud_sdk.py azure --submit --shots 128

After successful completion, the SDK script prints this format:

Task ID: <provider-assigned task/job id>
Counts: <returned count dictionary>
Shots represented: <sum of returned counts>

A Bell circuit's ideal outcomes are 00 and 11, but finite-shot splits are random and actual hardware can add other outcomes. Do not publish an invented fixed histogram as hardware evidence. Inspect requested shots versus the represented result, package identity, and target metadata.

Azure's Short Synchronous Entry Point

With the same resource ID and authoritative width configured, the release also supports:

import os
import flagquantum as fq

result = fq.run(
    fq.Circuit(2).x(0),
    target='azure:' + os.environ['AZURE_QUANTUM_TARGET_ID'],
    outputs=fq.counts(), shots=128,
)
print(result.counts[0])

This is an account-dependent call, not an offline test. The ideal result is {'10': 128}. Its initial slice accepts one full-register counts output and rejects local execution options, a noise model, compiler=, and explicit target_qubits=. QDK performs the OpenQASM-to-QIR compilation and the target compiler owns physical mapping.

Provider-Adapter Limits

Braket and Azure return DeploymentResult through the expert provider interface, whereas fq.run and detached jobs expose ExecutionResult. The SDK example validates deployment identity and count accounting using the provider contract; it does not create a Quafu/Jiuding RemoteJob receipt. Retain the printed provider task ID and use the corresponding provider recovery workflow if the process exits. Do not feed an arbitrary adapter handle to fq.restore_job.

Azure's adapter declares dynamic circuits unsupported. Braket's IQM dynamic dialect is separately bounded and requires explicit compatible qubit groups; a static preview does not validate general feedback or all dynamic devices. Its documented result handling does not return IQM mid-circuit measurement records. Follow the release dynamic-deployment contract before attempting that workflow.

Some Azure targets return probabilities rather than integer histograms; the adapter can convert them into shot-accounted integer counts. Such reconstructed counts are not evidence that the target supplied raw per-shot measurement records. Preserve provider provenance when interpreting them.

7. Jiuding Workspace and Capacity Boundaries

The synchronous fq.run(..., target="jiuding:gpu") path reuses a resident development workspace and differs from the native job script above. Inside a supported workspace the name can be discovered; from outside, set JIUDING_WORKSPACE to an already running workspace. It requires a compatible image and the documented workspace/SSH access path. The first call can initialize the worker; later calls reuse the process/channel.

Advanced shared-storage jobs require source/result paths already mounted into the workspace and job. That route does not upload arbitrary source or build an image for you. A successful native job does not validate a different workspace or storage configuration.

Native jobs carry a circuit command bounded to 64 KiB and results through authenticated chunked logs bounded to 8 MiB, with completeness and checksum checks. Prefer compact counts/expectations over large statevectors. Retention and account permissions limit recovery; a checksum detects transport corruption rather than proving hardware execution.

The documented multi-device native slice is single-node GPU execution with a power-of-two device count and a suitable image/queue. devices reserves accelerators and launches ranks. General outputs currently gather the state before materialization, so inspect both distributed-evolution and result-materialization evidence. This page does not exercise multi-device jobs or establish scaling. See Distributed Simulation and Training and the provider-specific runbook before extending the single-device example.

8. Result Interpretation and Troubleshooting

Problem	Check or limitation
Missing or rejected credential	Check the active process and exact source. Quafu API key and legacy token differ; Jiuding requires a complete credential pair.
Empty resources or rejected queue/image	Confirm membership, active capacity, supported queue configuration, and executor compatibility; a client cannot grant access.
Simulation mistaken for hardware	Check target type and provenance. Jiuding CPU/GPU and Quafu simulator targets produce simulated results.
Hardware rejects the circuit	Check target width, native gates, physical mapping/compiler path, supported operations, and shot constraints.
Wrong bitstrings	Quafu direct counts are already normalized to logical order with qubit 0 on the left. Use an asymmetric test before applying any extra reversal. Check expert-adapter result conventions independently.
Unsupported output on submit	Quafu detached jobs support full-register counts; grouped expectation requests through synchronous fq.run can require multiple basis-measurement tasks and additional shots.
Job timed out locally	Query or restore the same job; timeout and notebook interruption do not cancel it.
Missing receipt after an uncertain POST	Reconcile with the provider using the journal/context; blindly resubmitting can duplicate work.
Provider says complete but results are unavailable	Result publication/retention may differ from task state. The documented Jiuding wait path retries incomplete results until its deadline.
A local preview passes but cloud execution fails	Preview does not establish authentication, target admission, quota, availability, network access, or live SDK compatibility.

Remote measurement counts are nondifferentiable data. Local PyTorch training does not automatically become hardware training by changing a target string. Hardware optimization needs an explicitly supported gradient-estimation/measurement workflow, repeated submissions, and appropriate shot/queue accounting.

For a report, record the client release, remote runtime/SDK versions, target and provider, simulation-versus-hardware classification, source circuit, compiler/mapping settings, requested/received shots, receipt/task ID, timestamps, count convention, and provenance. Keep credentials out of the report. Adapter tests and synthetic output are separate from live provider acceptance and physical-device characterization.

Sources and Related Guides

FlagQuantum sources are pinned to v0.3.1:

• Remote task lifecycle, receipts, collections, and Jiuding native jobs
• Quafu authentication, targets, protocols, and hardware limits
• Jiuding account, workspace, image, storage, and execution requirements
• Braket adapter · Azure adapter
• Root execution routes · Azure/Quafu output validation and execution
• Provider result contracts · Release dependency declarations
• Capability catalog
• Accelerator Setup · Circuit Compilation and Interoperability · Troubleshooting and FAQ