Troubleshooting¶
This page covers common issues when running CASCAQit examples, including installation, validation, result interpretation and chart display.
Installation¶
Use a supported Python version from 3.9 through 3.13 and install from the repository root:
python3 -m pip install -e ".[dev]"
If imports fail after installation, first confirm that the command was run in the repository root and that the same Python interpreter is used to run the examples:
python3 -c "import cascaqit; print(cascaqit.__version__)"
Run The Learning Examples First¶
Use the learning examples as the first check:
python3 examples/learning/analog_first_run.py
python3 examples/learning/digital_first_run.py
python3 examples/learning/result_diagnostics_first_run.py
python3 examples/learning/visualization_metadata_first_run.py
If you only need a shorter package smoke check, run the release examples:
python3 examples/release/minimal_analog_quickstart.py
python3 examples/release/minimal_digital_quickstart.py
python3 examples/release/minimal_result_view.py
python3 examples/release/minimal_structured_error.py
Both sets are expected to run without hardware, cloud services, credentials, or network access.
I See hardware_execution: False Or cloud_execution: False¶
That is expected. The current release examples use local SDK paths. hardware_execution: False and cloud_execution: False are there to make the boundary visible.
The Analog Example Reports Validation Errors¶
The release analog example should print an empty validation_errors list. If a program you wrote reports validation errors, inspect:
- atom spacing and coordinate units;
- waveform duration and shape;
- target constraints from
MockNeutralAtomTarget.v0_1(); - shot settings passed to
program.validate(...).
Validation errors are meant to stop invalid programs before compilation or any backend handoff.
The Digital Example Has Unexpected Bitstrings¶
Check bit_order before interpreting bitstrings. The release digital example prints:
['q0', 'q1']
That means bitstrings are interpreted in q0, then q1 order. Keep this metadata with counts and probabilities when writing analysis code.
The Result View Does Not Render A Chart¶
That is expected. minimal_result_view.py builds a metadata-only result view and a histogram descriptor. It keeps the example runnable in a plain Python environment and does not render charts directly.
Use build_counts_histogram(result) when you need visualization-ready metadata. Render it later in your notebook, web UI, or report tooling.
A Structured Error Has A Suggestion¶
Treat suggestion as recovery guidance, not as an automatic fix. The stable fields for tooling are code, object_path, reason_category, and category.
Check How An Example Runs¶
These experiments use local simulators. When investigating different results, check the selected Backend and retain the execution configuration, shots, seed and SDK version so you can repeat the run in the same environment.
Where To Read Next¶
- Learning path:
docs/user-guide/learning-path.md - Quickstart smoke check:
docs/getting-started/quickstart.md - Analog walkthrough:
docs/user-guide/analog-walkthrough.md - Digital walkthrough:
docs/user-guide/digital-walkthrough.md - Results and diagnostics:
docs/user-guide/result-diagnostics-visualization.md - Limitations:
docs/limitations.md