Skip to content

Dashboard

Ctrl-freeq includes a dashboard facility that consolidates all analysis figures from an optimization run into a single, self-contained HTML file. The dashboard is constructed using Panel and presents the figures in a responsive card grid with a dark theme. Matplotlib figures and Bloch-sphere videos are accepted without conversion; for single-qubit runs the Bloch sphere is a video rendered by nutate.

Features

The dashboard provides several capabilities that facilitate the review and dissemination of optimization results. All figures are exported to a single standalone HTML file, which can be opened in any web browser without the need for a running server. The responsive two-column card layout adapts to the available screen size, and a clean dark theme is applied for improved readability. Since the entire dashboard is contained in a single file, it may be readily shared with collaborators.

Usage

When the Save Results button in the GUI is used, a dashboard is automatically generated alongside the saved plots in the results/dashboards/ directory.

Programmatic Usage

from ctrl_freeq.api import load_single_qubit_config
from ctrl_freeq.visualisation.plotter import process_and_plot
from ctrl_freeq.visualisation.dashboard import create_dashboard
from datetime import datetime

# Run optimization
api = load_single_qubit_config()
solution = api.run_optimization()

# Generate plots and get figures
waveforms, figures = process_and_plot(solution, api.parameters, save_plots=False)

# Create dashboard (pass parameters for a richer sidebar with algorithm, fidelity, etc.)
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
dashboard_path = create_dashboard(figures, timestamp, parameters=api.parameters)
print(f"Dashboard saved to: {dashboard_path}")

create_dashboard Parameters

create_dashboard(figures, timestamp, parameters=None)
Parameter Type Description
figures list Matplotlib figures and Bloch-sphere videos (MP4 paths or nutate trajectories); anything else raises TypeError
timestamp str Timestamp string for the dashboard filename
parameters Initialise, optional Parameters object from the optimization run. When provided, the dashboard sidebar displays algorithm, fidelity target, pulse parameters, and state information.

Enriched Sidebar Information

When the parameters argument is omitted, the dashboard sidebar displays only the timestamp and figure count. Passing api.parameters populates the sidebar with a comprehensive summary of the optimization and system parameters, which is generally recommended for reproducibility.

Demo Function

A sample dashboard may be generated by running the dashboard module directly:

python -m ctrl_freeq.visualisation.dashboard

Example Dashboard

An example of the dashboard generated from a single-qubit optimization run is shown below. This is representative of the output produced by clicking Save Results in the GUI or by invoking create_dashboard through the API.

View Example Dashboard

The dashboard opens in a new tab as a standalone page. The run is a Hadamard gate from Z with the built-in single-qubit configuration (Δ = 10 MHz, sw = 5 MHz, newton-cg).

Bloch-Sphere Video

For single-qubit runs, the Bloch-sphere card is a video rendered by nutate. This is the one in the example dashboard:

  • What it shows. The optimised pulse replayed for 31 offsets evenly spaced across the band it was optimised for, Δ ± sw/2, at the nominal Rabi amplitude. Each arrow is one offset, coloured by its frequency (the colour bar is in Hz with an SI prefix); the inset traces the drive amplitude with a moving cursor.
  • The optimizer's physics. The states come from ctrl-freeq's own replay (control mapping, propagator and, for dissipative runs, the Lindblad channel), so relaxation shortens the arrows exactly as it did in the objective. nutate only draws them.
  • Installation. The video needs the video extra, pip install "ctrl-freeq[video]"; without it the card is omitted. See Installation → Bloch-Sphere Video.
  • Files. Save Results writes results/plots/bloch_sphere_<timestamp>_rho<i>.mp4, one per initial state. When create_dashboard receives a trajectory instead (the API path with save_plots=False), it renders results/dashboards/bloch_<timestamp>_<i>.mp4. Either way the dashboard embeds the MP4 (720p, dark theme).
  • Rendering failures. nutate renders off-screen in a separate process. If that fails, for example on a machine without a display, the card is skipped with a message and everything else is still saved.

To make or view the video from Python, see API → Bloch-sphere video.

Dashboard Contents

The dashboard typically includes visualizations from the following categories:

Category Visualizations
Pulse Waveforms IQ components, amplitude and phase
State Evolution State history, observable dynamics, leakage (models with levels above the qubit)
Quantum State Bloch-sphere video (single qubit, needs ctrl-freeq[video])
Analysis Excitation profiles (frequency response over 1.5 × sw)

File Structure

ctrl-freeq/
├── src/
│   └── ctrl_freeq/
│       └── visualisation/
│           ├── __init__.py
│           ├── dashboard.py          # Dashboard creation module
│           ├── plotter.py            # Plotting functions, Bloch-sphere trajectory
│           ├── plot_settings.py      # Plot configuration
│           └── _nutate_child.py      # Runs nutate in a separate process
└── results/
    ├── plots/                        # Save Results: PNGs and bloch_sphere_*.mp4
    └── dashboards/                   # Generated dashboard HTML files
        └── dashboard_YYYYMMDD_HHMMSS.html

Troubleshooting

Dashboard Not Generating

If the dashboard is not being produced, it is advisable to verify that figures are being captured correctly: 

waveforms, figures = process_and_plot(solution, parameters, save_plots=False)
print(f"Captured {len(figures)} figures")

Dashboard File Size

Figures and the Bloch-sphere video are embedded in the HTML file, so a single-qubit dashboard is typically 2–3 MB. The Panel and Bokeh libraries are loaded from a CDN rather than embedded, so viewing a dashboard needs an internet connection.

Bloch-Sphere Card Missing

For a single-qubit run, check the console. "install ctrl-freeq[video]" means nutate is not installed; "nutate failed" means rendering failed, usually because the machine has no display. See Installation → Bloch-Sphere Video for the off-screen setup.

Figure Rendering Issues

For Matplotlib figures, it is recommended to ensure that the tight=True parameter is used.

Next Steps