Analysis And Io

---
name: "analysis-and-io"
description: "QuTiP visualization, phase-space analysis, tomography, file I/O,
  and reporting workflows."
metadata:
  disco-role: operating
disable-model-invocation: true
license: BSD 3-Clause
---

# Analysis and I/O

Use this subskill when the task is about turning QuTiP objects or solver results into plots, saved artifacts, process tomography, environment summaries, or citation output.

## Read this subskill when the prompt mentions

- `Bloch`, Bloch sphere plots, vectors, arcs, points, or qubit-state visualization
- `hinton`, `matrix_histogram`, `plot_wigner`, `plot_qfunc`, `plot_fock_distribution`, `plot_expectation_values`
- `wigner`, `qfunc`, spin Wigner functions, quasi-probability distributions, or harmonic-oscillator probability functions
- `qpt`, process tomography, `qpt_plot`, or `qpt_plot_combined`
- `qsave`, `qload`, `file_data_store`, `file_data_read`
- `about()`, `cite()`, `ipynbtools.version_table`, or notebook/reporting helpers

## What to decide first

1. Is the user trying to visualize a state, an operator, a process, or solver result data?
2. Does the environment have Matplotlib, and is a headless backend needed?
3. Is the task about a saved QuTiP object (`.qu`) or plain numeric data?
4. Does the task need a reusable artifact or only a quick diagnostic plot?

## Core workflow

- Set a non-interactive Matplotlib backend before plotting in headless runs.
- Build or receive a valid `Qobj` first; plotting helpers do not fix object dimensions.
- Pass explicit `fig` and `ax` objects when embedding plots into a larger script.
- Use `qsave` / `qload` for QuTiP objects and `file_data_store` / `file_data_read` for raw numeric arrays.
- Use `about()` for environment summaries and `cite()` for publication reminders.

## Typical success signals

- Plot helpers return a Matplotlib `Figure` and `Axes` or an animation object.
- Saved `Qobj` objects round-trip through `qsave` and `qload`.
- Basis labels have the same length as the plotted matrix axes.
- `about()` reports the package and dependency versions from the active interpreter.

## Boundaries

Use this subskill for analysis artifacts after a valid object or result exists. Do not use it as the main route for:

- Building the Hamiltonian, state, or measurement operators; use `core-objects` first.
- Choosing a solver or fixing time-dependent coefficient logic; use `dynamics-and-solvers`.
- PIQS, HEOM, or bath-model construction; use `specialized-open-systems` before plotting or saving outputs.

## Answer shape

When responding from this subskill, give:

1. The correct plotting, phase-space, file I/O, or reporting API.
2. The minimal object/result shape expected by that API.
3. A headless-safe code snippet if figures are created.
4. The artifact path, file suffix, or return-object type to expect.
5. A cleanup step such as closing Matplotlib figures or using a temporary directory.

## Validation hints

- Use `matplotlib.use('Agg')` for non-interactive smoke checks.
- Use qubit states for Bloch examples unless the prompt explicitly requires another representation.
- Verify `qsave` / `qload` round trips in a scratch directory before relying on saved data.

## Reference files

- `references/api-reference.md` for plotting, phase-space, file I/O, and reporting entry points.
- `references/workflows.md` for compact plotting and save/load recipes.
- `references/troubleshooting.md` for Matplotlib, basis-label, Bloch-geometry, and `.qu` suffix issues.

## Helper script

- `scripts/visual_io_smoke.py` verifies Matplotlib plotting, Bloch rendering, Wigner calculation, and `qsave`/`qload` round-tripping.