uniqc.visualization.timeline module

Circuit scheduling and timeline visualization.

This module computes a left-compacted schedule from a compiled circuit and can render both the existing table-style PDF timeline and static HTML/SVG views. Logical circuits require gate-duration data from backend metadata, chip-characterization data, or explicit gate_durations overrides. Pulse data that already carries start times remains supported without duration data.

class uniqc.visualization.timeline.TimelineGate(index, name, qubits, params=(), cbits=(), control_qubits=(), start=0.0, duration=0.0, end=0.0, layer=0, raw=None)[source]

Bases: object

One scheduled operation.

Parameters:
cbits: tuple[int, ...]
control_qubits: tuple[int, ...]
duration: float
end: float
index: int
property is_barrier: bool
property is_virtual: bool
layer: int
name: str
params: tuple[Any, ...]
qubits: tuple[int, ...]
raw: str | None
property resources: tuple[int, ...]

Return all quantum resources touched by this operation.

start: float
tooltip(*, unit='ns')[source]
Parameters:

unit (str)

Return type:

str

class uniqc.visualization.timeline.TimelineSchedule(gates, qubits, total_duration, unit='ns', gate_durations=None)[source]

Bases: object

Scheduled circuit timeline.

Parameters:
gate_durations: dict[str, float] | None
gates: tuple[TimelineGate, ...]
qubits: tuple[int, ...]
property time_points: tuple[int | float, ...]
total_duration: float
unit: str
uniqc.visualization.timeline.circuit_to_html(circuit, output_path=None, *, title='Quantum circuit')[source]

Render a static HTML/SVG circuit diagram without timing requirements.

Parameters:
Return type:

str

uniqc.visualization.timeline.create_time_line_table(layer_dict, qubit_list, time_line)[source]

Create a pandas DataFrame-like timeline table from legacy layer data.

uniqc.visualization.timeline.format_result(compiled_prog, *, backend_info=None, chip_characterization=None, gate_durations=None, compile_to_basis=True, basis_gates=None)[source]

Format a program into legacy (gate_layers, qubits, time_line) data.

Parameters:

  • compiled_prog (Any)

  • backend_info (Any | None)

  • chip_characterization (Any | None)

  • gate_durations (dict[str, float] | None)

  • compile_to_basis (bool)

  • basis_gates (list[str] | None)

uniqc.visualization.timeline.plot_time_line(compiled_prog, figure_save_path=PosixPath('/home/runner/work/UnifiedQuantum/UnifiedQuantum/docs/timeline_plot'), *, backend_info=None, chip_characterization=None, gate_durations=None, compile_to_basis=True, basis_gates=None)[source]

Plot the quantum circuit timeline as table-style PDF files.

Parameters:

  • figure_save_path (str | Path)

  • backend_info (Any | None)

  • chip_characterization (Any | None)

  • gate_durations (dict[str, float] | None)

  • compile_to_basis (bool)

  • basis_gates (list[str] | None)

uniqc.visualization.timeline.plot_time_line_html(compiled_prog, output_path=None, *, backend_info=None, chip_characterization=None, gate_durations=None, compile_to_basis=True, basis_gates=None, title='Quantum circuit timeline', unit='ns')[source]

Render a scheduled timeline as static HTML/SVG.

Each gate carries an SVG title tooltip with its qubits, parameters, start time, duration, and end time.

Parameters:

  • compiled_prog (Any)

  • output_path (str | Path | None)

  • backend_info (Any | None)

  • chip_characterization (Any | None)

  • gate_durations (dict[str, float] | None)

  • compile_to_basis (bool)

  • basis_gates (list[str] | None)

  • title (str)

  • unit (str)

Return type:

str

uniqc.visualization.timeline.schedule_circuit(compiled_prog, *, backend_info=None, chip_characterization=None, gate_durations=None, compile_to_basis=True, basis_gates=None, unit='ns')[source]

Schedule a compiled circuit by left-compacting gates on qubit resources.

Important

Whenever compile_to_basis=True (the default), this function calls uniqc.compile.compile(), which requires Qiskit. Qiskit is a core dependency installed by default with unified-quantum; if it fails to import, the install is broken (reinstall with pip install --upgrade unified-quantum). There is no native-only bypass: even if the input circuit already uses only chip-native gates (e.g. CZ/SX/RZ), schedule_circuit will still call compile() to collect timing data unless every entry already carries an explicit start time. To skip compile() entirely you must pass pulse / timeline data where every entry has start_time set, and pass compile_to_basis=False (otherwise TimelineDurationError is raised).

Parameters:

  • compiled_prog (Any) – A Circuit-like object, OriginIR text, JSON pulse data, or a list of gate dictionaries.

  • backend_info (Any | None) – Backend metadata used to resolve gate durations. BackendInfo.extra may contain gate_durations, single_qubit_gate_time, two_qubit_gate_time, and measure_time.

  • chip_characterization (Any | None) – Backend metadata used to resolve gate durations. BackendInfo.extra may contain gate_durations, single_qubit_gate_time, two_qubit_gate_time, and measure_time.

  • gate_durations (dict[str, float] | None) – Explicit duration overrides. Gate names are case-insensitive. Generic keys "1q", "2q", and "measure" are supported.

  • compile_to_basis (bool) – Logical circuits must be compiled to basis gates before scheduling. This flag defaults to True and may only be disabled for inputs that already carry explicit start times.

  • basis_gates (list[str] | None) – Basis gate override forwarded to compile() when compile_to_basis=True.

  • unit (str) – Display unit label for renderers. Numeric values are not converted.

Raises:

TimelineDurationError – If the circuit lacks explicit start times and a non-virtual operation cannot be assigned a duration from backend metadata or overrides.

Return type:

TimelineSchedule