Run your first experiment¶
After installing the environment, run one rotation and inspect the measurement. The experiment starts in 0, applies a Y-axis rotation of π/3 radians and measures the qubit 128 times. Its ideal probability of 1 is sin²(π/6) = 1/4.
Before running, predict whether all 128 shots must produce exactly 32 ones. The sampling lesson will explain why the answer is no.
"""Rotate one qubit, read the samples and save a report from the same result."""
from __future__ import annotations
import argparse
import json
from math import pi
from pathlib import Path
from typing import Literal
import cascaqit
from cascaqit import Circuit, visualize
def experiment(output: Path, language: Literal["en", "zh"] = "en") -> dict[str, object]:
"""Keep the raw result beside the HTML so the plot can be checked later."""
theta, shots, seed = pi / 3, 128, 17
circuit = Circuit(1).ry(theta, 0).measure_all(key="readout")
result = circuit.run(shots=shots, seed=seed, return_probabilities=True)
output.parent.mkdir(parents=True, exist_ok=True)
visualize(result, program=circuit, output=output, language=language)
raw = output.with_suffix(".json")
raw.write_text(json.dumps(result.to_dict(), indent=2) + "\n", encoding="utf-8")
return {
"sdk_version": cascaqit.__version__,
"theta_rad": theta,
"shots": shots,
"seed": seed,
"counts": result.counts,
"probabilities": result.probabilities,
"bit_order": result.metadata["bitstring_ordering"]["qubit_order"],
"diagnostic_codes": [item.code for item in result.diagnostics],
"report": output.as_posix(),
"raw_result": raw.as_posix(),
}
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--output", type=Path, default=Path("artifacts/first-experiment.html")
)
parser.add_argument("--language", choices=("en", "zh"), default="en")
args = parser.parse_args()
print(json.dumps(experiment(args.output, args.language), sort_keys=True))
if __name__ == "__main__":
main()
From the repository root:
python examples/learning/foundations/first_experiment.py --language en
Circuit(1) creates a one-qubit program. .ry(theta, 0) rotates qubit 0; .measure_all(key="readout") declares terminal measurement. circuit.run(...) executes locally and returns ResultIR. visualize() reads that result to make a report; it does not sample the circuit again.
{
"bit_order": [
"q0"
],
"counts": {
"0": 91,
"1": 37
},
"diagnostic_codes": [
"DIGITAL_SIMULATION_COMPLETED",
"DIGITAL_RESULT_ALIGNMENT_VALID"
],
"probabilities": {
"0": 0.7500000000000001,
"1": 0.24999999999999994
},
"raw_result": "artifacts/first-experiment.json",
"report": "artifacts/first-experiment.html",
"sdk_version": "1.0.8a",
"seed": 17,
"shots": 128,
"theta_rad": 1.0471975511965976
}
The counts sum to 128. The probabilities should be close to 0.75 for 0 and 0.25 for 1, within floating-point precision. Counts are integers from finite sampling and need not equal those probabilities multiplied by 128. The seed helps reproduce sampling in the same environment.
Open artifacts/first-experiment.html in a browser. The neighboring JSON file preserves the result used by the report. No upload is needed to view either file.
Change one number¶
In a local copy, change theta to pi. Predict the outcome, then run again with a different --output, such as artifacts/pi-rotation.html, so the first result remains available. Inspect both counts and probabilities.
Expected result
An ideal Y rotation by π takes 0 to 1, so the probability of 1 is one up to numerical precision. Do not infer the bit order of a two-qubit result from this one-qubit example; read that result's ordering metadata.
Continue with reading results and reports, or study complex state vectors if the probability calculation is unfamiliar.