Documentation version

Check the plan before enlarging an experiment¶

Run a six-site Digital–Analog–Digital program and compare requested settings with the settings actually applied. Complete physical noise first and use the installed environment. This lesson uses a small local CPU simulation so that resource estimates can be inspected without attempting a large allocation.

Estimate the state, then include the workspace¶

For six two-level sites, the full Hilbert dimension is 2⁶ = 64. A complex64 amplitude takes eight bytes, so one state vector takes 64 × 8 = 512 bytes. A full density matrix has 64² entries and takes 32768 bytes at the same precision.

Neither number is the peak memory required to run an experiment. Operators, solver workspace, sampling and result buffers also consume memory. Concurrent jobs or trajectories can add copies. The planner estimates these components before large state-array allocation; its estimate is not a measurement of total process memory.

"""Audit resource planning and execution evidence for a Hybrid workload.

The planner evaluates method candidates before large-array allocation. The
accepted plan records state representation, Hilbert dimension, memory estimate,
workers, tolerances, and rejection reasons; execution records what was applied.
"""

from __future__ import annotations

import json

from cascaqit import (
    AHSProgram,
    AtomRegister,
    Circuit,
    HybridProgram,
    LocalBackend,
    Waveform,
)
from cascaqit.simulators import SimulationOptions


def main() -> None:
    """Run a six-site D-A-D workload and compare planned versus applied settings."""
    sites = 6
    analog = AHSProgram(
        AtomRegister.line(count=sites, spacing=7.0),
        program_id="lesson.hybrid.resource.analog",
    ).drive(
        rabi=Waveform.linear(0.1, 0.6, duration=0.1),
        detuning=Waveform.constant(-0.1, duration=0.1),
        phase=0.0,
    )
    program = (
        HybridProgram("lesson.hybrid.resource")
        .digital("prepare", Circuit(sites).h(0).cx(0, 1))
        .analog("evolve", analog)
        .digital("correct", Circuit(sites).rz(0.2, sites - 1))
        .measure_all()
    )
    result = (
        LocalBackend(analog_time_steps=4)
        .run(
            program,
            shots=16,
            seed=105,
            options=SimulationOptions(
                integrator="fixed_step_krylov",
                dtype="complex64",
                max_steps=4,
                workers=2,
            ),
        )
        .result()
    )
    plan = result.metadata["simulation_plan"]
    execution = result.metadata["simulation_execution_config"]

    payload = {
        "track": "hybrid_researcher",
        "level": "expert",
        "lesson": "resource_planning",
        "facts": {
            "logical_sites": plan["logical_sites"],
            "method_selected": plan["method_selected"],
            "candidate_statuses": {
                item["method"]: item["status"] for item in plan["candidates"]
            },
            "hilbert_dimension": plan["hilbert_dimension"],
            "state_bytes": plan["estimate"]["state_bytes"],
            "estimated_peak_bytes": plan["estimate"]["estimated_peak_bytes"],
            "workers_requested": plan["metadata"]["workers_requested"],
            "workers_applied": execution["workers"],
            "estimated_peak_positive": plan["estimate"]["estimated_peak_bytes"] > 0,
            "execution_dtype": execution["dtype"],
            "tolerance_applied": execution["tolerance_applied"],
            "state_bytes_returned": result.metadata["state_bytes_returned"],
        },
        "boundaries": {
            "hardware_execution": False,
            "cloud_execution": False,
            "network_accessed": False,
            "credentials_loaded": False,
        },
    }
    print(json.dumps(payload, sort_keys=True))


if __name__ == "__main__":
    main()

Download the full script

python3 examples/user/tracks/hybrid_researcher/05_expert_resource_planning_en.py

The Digital preparation entangles the first two sites. The Analog interval uses a global drive and detuning, and a final Digital RZ acts on the last site. No two-body interaction is declared. Six sites alone do not make this an interacting Rydberg-array model.

Read what was selected and what was applied¶

{
  "boundaries": {
    "cloud_execution": false,
    "credentials_loaded": false,
    "hardware_execution": false,
    "network_accessed": false
  },
  "facts": {
    "candidate_statuses": {
      "density_matrix": "rejected",
      "state_vector": "selected",
      "subspace": "rejected",
      "trajectory": "rejected"
    },
    "estimated_peak_bytes": 20992,
    "estimated_peak_positive": true,
    "execution_dtype": "complex64",
    "hilbert_dimension": 64,
    "logical_sites": 6,
    "method_selected": "state_vector",
    "state_bytes": 512,
    "state_bytes_returned": false,
    "tolerance_applied": false,
    "workers_applied": 1,
    "workers_requested": 2
  },
  "lesson": "resource_planning",
  "level": "expert",
  "track": "hybrid_researcher"
}

Output	How to read it
`method_selected`	The accepted representation is `state_vector` for this noiseless workload.
`candidate_statuses`	The other methods were evaluated; rejection is not evidence that they are generally unavailable.
`state_bytes`, `estimated_peak_bytes`	One state array versus the planner's combined allocation estimate.
`workers_requested`, `workers_applied`	Two were requested; this selected state-vector path uses one kernel worker.
`execution_dtype`	`complex64` was applied during execution.
`tolerance_applied`	False for the explicitly selected fixed-step integration.
`state_bytes_returned`	False means amplitudes were not returned, not that no state was allocated.

For details, inspect plan["candidates"]: each candidate includes reason_codes. Here the subspace candidate lacks a supplied basis; density-matrix and trajectory candidates require a noise model. The planner does not silently invent a noise model or a blockade approximation to make a method eligible.

The example requests fixed_step_krylov with four time slices. Its tolerance fields are recorded, but they do not control adaptive step selection. Raising shots only changes sampling. To assess evolution error, compare results at increasing time resolution, and use the supported adaptive method when appropriate. A dtype choice is not an accuracy guarantee.

Make one resource change at a time¶

Change complex64 to complex128. Predict the state-array bytes and check the reported value.
Increase the sites from six to seven. Predict the state-vector and density-matrix sizes at complex64.
Add max_memory_bytes=1024 to SimulationOptions. Read the resource error. Why is 1024 bytes insufficient even though the state vector takes only 512?

Check your reasoning

At six sites, complex128 uses 64 × 16 = 1024 bytes for one vector. Seven sites at complex64 use 128 × 8 = 1024 bytes for a vector and 128² × 8 = 131072 bytes for a density matrix. The restricted budget cannot hold the required workspace and buffers; the planner rejects the workload. Reducing result output does not remove the state needed for evolution.

Keep the accepted plan, applied execution settings and program with your results. Host memory budgets may differ across machines, so do not use a printed host budget as a portable minimum requirement. See simulation planning for the planner's rules and experiment design for reproducibility records.

中文版

SDK 1.0.8a · `8b227bff`