qlinks.visualizer

class qlinks.visualizer.BasisConfigurationVisualizer(lattice, layout=None, style=<factory>, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

Bases: object

Geometry-detached basis-configuration visualizer.

Parameters:

• lattice (qlinks.lattice.graph.LatticeGraph) – A LatticeGraph, e.g. ChainLattice or SquareLattice.

• layout (qlinks.variables.layout.VariableLayout | None) – VariableLayout mapping site/link ids to positions in the raw config array. If None, the visualizer assumes link variable index == link id for link plotting.

• periodic_image_mode (Literal['none', 'positive_patch']) –

  How to draw links that wrap periodic boundaries.

  ”none”: Don’t draw wrapped links.

  ”positive”: Draw wrapped links with the target site shifted by +1 period so they appear next to the source site. This is usually more intuitive for small lattices.

  ”both”: Draw both the original wrapped link and the complementary image link. This is more complete but can be visually cluttered.

• style (LinkVisualStyle)

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ndarray[tuple[Any, ...], dtype[float64]] | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

lattice: LatticeGraph

layout: VariableLayout | None = None

style: LinkVisualStyle

periodic_image_mode: Literal['none', 'positive_patch'] = 'positive_patch'

collapse_duplicate_visual_links: bool = True

coordinate_scale: float = 1.0

coordinate_transform: ndarray[tuple[Any, ...], dtype[float64]] | None = None

site_label_style: Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'] = 'cell_sublattice'

link_value(config, link_id)

Parameters:

• config (ArrayLike)

• link_id (int)

Return type:

int

site_value(config, site_id)

Parameters:

• config (ArrayLike)

• site_id (int)

Return type:

int | None

has_link_variables()

Return type:

bool

plot(config, *, ax=None, show=True, backend='matplotlib', mode='auto', with_site_labels=True, with_site_values=False, with_link_values=False, with_link_ids=False, with_plaquette_symbols=True, plaquette_symbol_style='auto', plaquette_symbol_values=None, title=None)

Plot one basis configuration.

Parameters:

• mode="arrows" – QLM-like style. Positive / 1 values point along the stored link orientation. Negative / 0 values point opposite.

• mode="dimers" – QDM-like style. Value 1 links are drawn thick; value 0 links are faint.

• mode="values" – Draw the lattice and place link values at link centers.

• plaquette_symbol_style (Literal['auto', 'none', 'circulation', 'resonance'])

• "circulation" –

  QLM-like signed-flux circulation marker. Draws circular arrows only when all nonzero signed link variables circulate

  consistently around a plaquette.

• "resonance" – QDM-like binary resonance marker.

• plaquette. (Draws a marker when binary dimer occupations alternate around an even-length)

• config (ArrayLike)

• show (bool)

• backend (Literal['matplotlib', 'networkx'])

• mode (Literal['auto', 'arrows', 'dimers', 'values'])

• with_site_labels (bool)

• with_site_values (bool)

• with_link_values (bool)

• with_link_ids (bool)

• with_plaquette_symbols (bool)

• plaquette_symbol_values (Mapping[int, tuple[str, str]] | None)

• title (str | None)

save(config, path, *, dpi=200, show=False, **plot_kwargs)

Save a visualization to disk.

Parameters:

• config (ArrayLike)

• path (str | Path)

• dpi (int)

• show (bool)

Return type:

None

__init__(lattice, layout=None, style=<factory>, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout | None)

• style (LinkVisualStyle)

• periodic_image_mode (Literal['none', 'positive_patch'])

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ndarray[tuple[Any, ...], dtype[float64]] | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

Return type:

None

class qlinks.visualizer.BasisGridVisualizer(lattice, layout=None, style=<factory>, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

Bases: object

Plot many basis configurations as an n by m grid.

Parameters:

• lattice (qlinks.lattice.graph.LatticeGraph) – Geometry/topology object.

• layout (qlinks.variables.layout.VariableLayout | None) – Variable layout used to interpret each config array.

• single_visualizer – Optional custom single-state visualizer. If omitted, this class creates BasisConfigurationVisualizer(lattice, layout).

• style (LinkVisualStyle)

• periodic_image_mode (Literal['none', 'positive_patch'])

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ArrayLike | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

lattice: LatticeGraph

layout: VariableLayout | None = None

style: LinkVisualStyle

periodic_image_mode: Literal['none', 'positive_patch'] = 'positive_patch'

collapse_duplicate_visual_links: bool = True

coordinate_scale: float = 1.0

coordinate_transform: ArrayLike | None = None

site_label_style: Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'] = 'cell_sublattice'

plot(states, *, nrows=None, ncols=None, start_index=0, labels=None, show_config_label=False, config_label_style='compact', config_label_max_length=48, mode='auto', plaquette_symbols='auto', figsize=None, show=True, backend='matplotlib', suptitle=None, suptitle_y=0.995, tight_layout_rect=None, single_plot_kwargs=None)

Plot a batch of basis states.

Parameters:

• states (ArrayLike) – Either a single config with shape (n_variables,) or a batch with shape (n_states, n_variables). Slices like basis.states[:12] work.

• nrows (int | None) – Optional grid shape. If not provided, a near-square shape is chosen.

• ncols (int | None) – Optional grid shape. If not provided, a near-square shape is chosen.

• start_index (int) – Index offset used in automatic labels. For example, if plotting basis.states[20:30], pass start_index=20.

• labels (Sequence[str] | None) – Optional explicit labels for each subplot.

• show_config_label (bool) – Whether to include the raw config/binary string below the state index label.

• mode (str) – Passed to BasisConfigurationVisualizer.plot. Common values: “arrows”, “dimers”, “values”.

• plaquette_symbols (Literal['auto', 'none', 'circulation', 'resonance']) –

  “none”:

  draw no plaquette symbols.

  ”circulation”:

  generic QLM-like circulation marker. Draws circular arrows when all link variables circulate consistently around a plaquette.

• config_label_style (Literal['none', 'compact', 'array'])

• config_label_max_length (int)

• figsize (tuple[float, float] | None)

• show (bool)

• backend (Literal['matplotlib', 'networkx'])

• suptitle (str | None)

• suptitle_y (float)

• tight_layout_rect (tuple[float, float, float, float] | None)

• single_plot_kwargs (dict | None)

plot_cage_support(result_or_record, *, basis_configs, signature=None, record_index=0, max_states=None, show_amplitudes=True, amplitude_digits=3, labels=None, suptitle=None, **plot_kwargs)

Plot the support basis states of one cage record.

Parameters:

• result_or_record – Either a CageSearchResult or a CageRecord.

• basis_configs (ArrayLike) – Basis configuration array with shape (hilbert_size, n_variables).

• signature (tuple[int, int] | None) – Optional cage signature (kappa, Z). If provided, select result_or_record[signature, record_index].

• record_index (int) – Record index among all records, or among records with the given signature.

• max_states (int | None) – Optional cap on the number of support states to plot.

• show_amplitudes (bool) – Whether subplot labels include local-state amplitudes.

• amplitude_digits (int)

• labels (Sequence[str] | None)

• suptitle (str | None)

plot_interference_zeros(classification_report, *, basis_configs, mechanism='all', max_states=None, labels=None, suptitle=None, **plot_kwargs)

Plot basis states corresponding to nontrivial interference zeros.

Parameters:

• classification_report – CageClassificationReport returned by classify_cage_state or classify_full_state.

• basis_configs (ArrayLike) – Basis configuration array with shape (hilbert_size, n_variables).

• mechanism (str) –

  One of:

  ”all”, “q_empty”, “closed_by_known_zeros”, “projector_like”, “unexplained_leakage”, “regional”, “extended”, “failure”.

• max_states (int | None) – Optional cap on the number of zero states to plot.

• labels (Sequence[str] | None)

• suptitle (str | None)

__init__(lattice, layout=None, style=<factory>, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout | None)

• style (LinkVisualStyle)

• periodic_image_mode (Literal['none', 'positive_patch'])

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ArrayLike | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

Return type:

None

class qlinks.visualizer.HamiltonianGraphData(adjacency, self_loop_values, original_indices=None, state_vector=None, vertex_labels=None, directed=False)

Bases: object

Graph data extracted from a sparse Hamiltonian matrix.

Parameters:

• adjacency (csr_array)

• self_loop_values (ndarray[tuple[Any, ...], dtype[complex128]])

• original_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• state_vector (ndarray[tuple[Any, ...], dtype[complex128]] | None)

• vertex_labels (Sequence[str] | None)

• directed (bool)

adjacency: csr_array

self_loop_values: ndarray[tuple[Any, ...], dtype[complex128]]

original_indices: ndarray[tuple[Any, ...], dtype[int64]] | None = None

state_vector: ndarray[tuple[Any, ...], dtype[complex128]] | None = None

vertex_labels: Sequence[str] | None = None

directed: bool = False

property n_vertices: int

property degrees: ndarray[tuple[Any, ...], dtype[int64]]

__init__(adjacency, self_loop_values, original_indices=None, state_vector=None, vertex_labels=None, directed=False)

Parameters:

• adjacency (csr_array)

• self_loop_values (ndarray[tuple[Any, ...], dtype[complex128]])

• original_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• state_vector (ndarray[tuple[Any, ...], dtype[complex128]] | None)

• vertex_labels (Sequence[str] | None)

• directed (bool)

Return type:

None

class qlinks.visualizer.HamiltonianGraphStyle(figure_size=(7.0, 7.0), vertex_size=14.0, default_vertex_color='lightgray', edge_width=0.8, edge_alpha=0.45, edge_color='gray', label_vertices=False, vertex_label_size=8.0, cmap='viridis', colorbar=True, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15)

Bases: object

Style options for drawing Hamiltonian/Fock-space graphs.

Parameters:

• figure_size (tuple[float, float])

• vertex_size (float)

• default_vertex_color (str)

• edge_width (float)

• edge_alpha (float)

• edge_color (str)

• label_vertices (bool)

• vertex_label_size (float)

• cmap (str)

• colorbar (bool)

• edge_cmap (str)

• edge_phase_cmap (str)

• edge_colorbar (bool)

• edge_complex_min_alpha (float)

• edge_complex_max_alpha (float)

• orbit_alpha (float)

• orbit_lightness_boost (float)

figure_size: tuple[float, float]

vertex_size: float

default_vertex_color: str

edge_width: float

edge_alpha: float

edge_color: str

label_vertices: bool

vertex_label_size: float

cmap: str

colorbar: bool

edge_cmap: str

edge_phase_cmap: str

edge_colorbar: bool

edge_complex_min_alpha: float

edge_complex_max_alpha: float

orbit_alpha: float

orbit_lightness_boost: float

__init__(figure_size=(7.0, 7.0), vertex_size=14.0, default_vertex_color='lightgray', edge_width=0.8, edge_alpha=0.45, edge_color='gray', label_vertices=False, vertex_label_size=8.0, cmap='viridis', colorbar=True, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15)

Parameters:

• figure_size (tuple[float, float])

• vertex_size (float)

• default_vertex_color (str)

• edge_width (float)

• edge_alpha (float)

• edge_color (str)

• label_vertices (bool)

• vertex_label_size (float)

• cmap (str)

• colorbar (bool)

• edge_cmap (str)

• edge_phase_cmap (str)

• edge_colorbar (bool)

• edge_complex_min_alpha (float)

• edge_complex_max_alpha (float)

• orbit_alpha (float)

• orbit_lightness_boost (float)

Return type:

None

class qlinks.visualizer.HamiltonianGraphVisualizer(graph_data, style=HamiltonianGraphStyle(figure_size=(7.0, 7.0), vertex_size=14.0, default_vertex_color='lightgray', edge_width=0.8, edge_alpha=0.45, edge_color='gray', label_vertices=False, vertex_label_size=8.0, cmap='viridis', colorbar=True, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15))

Bases: object

Visualizer for Fock-space graphs induced by Hamiltonian matrices.

Parameters:

• graph_data (HamiltonianGraphData)

• style (HamiltonianGraphStyle)

graph_data: HamiltonianGraphData

style: HamiltonianGraphStyle = HamiltonianGraphStyle(figure_size=(7.0, 7.0), vertex_size=14.0, default_vertex_color='lightgray', edge_width=0.8, edge_alpha=0.45, edge_color='gray', label_vertices=False, vertex_label_size=8.0, cmap='viridis', colorbar=True, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15)

classmethod from_sparse_matrix(matrix, *, include_self_loops=False, weight_tolerance=0.0, directed=False, style=None)

Construct a visualizer from a sparse or dense Hamiltonian matrix.

Parameters:

• matrix – Hamiltonian or kinetic matrix. Nonzero off-diagonal entries define graph edges. Diagonal entries are stored as self-loop values.

• include_self_loops (bool) – Whether to keep diagonal graph edges. Usually False for drawing.

• weight_tolerance (float) – Entries with absolute value <= this threshold are removed.

• directed (bool) – Whether to treat the matrix as directed (asymmetric) or undirected (symmetrized). For an undirected graph, the adjacency is symmetrized by A + A^T, which preserves edge weights but may introduce new edges if the input matrix is asymmetric.

• style (HamiltonianGraphStyle | None) – Optional drawing style.

Return type:

HamiltonianGraphVisualizer

classmethod from_directed_sparse_matrix(matrix, *, include_self_loops=False, weight_tolerance=0.0, style=None)

Construct a directed graph visualizer from a sparse matrix.

Parameters:

• include_self_loops (bool)

• weight_tolerance (float)

• style (HamiltonianGraphStyle | None)

Return type:

HamiltonianGraphVisualizer

bipartition_labels()

Return bipartition labels for the graph.

Raises:

ValueError – If the graph is not bipartite.

Return type:

ndarray[tuple[Any, …], dtype[int64]]

node_values(*, color_by, self_loop_values=None, state_vector=None, automorphism_backend='auto')

Return scalar node values used for coloring.

Parameters:

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• automorphism_backend (Literal['auto', 'pynauty', 'igraph'])

Return type:

ndarray[tuple[Any, …], dtype[float64]]

edge_values(*, color_by)

Return edge values in the same order as plotted graph edges.

Parameters:

color_by (Literal['constant', 'weight_abs', 'weight_real', 'weight_imag', 'weight_phase', 'weight_complex'])

Return type:

ndarray[tuple[Any, …], dtype[float64]] | ndarray[tuple[Any, …], dtype[complex128]]

plot(*, backend='igraph', color_by='constant', edge_color_by='constant', layout='auto', self_loop_values=None, state_vector=None, title=None, ax=None, show=True, save_path=None, target=None, bbox=(800, 800), margin=40, **layout_kwargs)

Draw the graph.

Parameters:

• backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• edge_color_by (Literal['constant', 'weight_abs', 'weight_real', 'weight_imag', 'weight_phase', 'weight_complex'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• title (str | None)

• show (bool)

• save_path (str | Path | None)

• target (str | Path | None)

• bbox (tuple[int, int])

• margin (int)

vertex_display_labels()

Return vertex labels for plotting.

For a full graph, these are 0, 1, 2, … For a subgraph, these are the original parent-graph basis indices.

Return type:

list[str]

to_igraph()

Convert to an igraph.Graph.

to_networkx()

Convert to a networkx.Graph.

save_graph(path, *, layout_backend='networkx', layout='auto', color_by='constant', self_loop_values=None, state_vector=None, **layout_kwargs)

Save graph with computed layout coordinates.

The graph is always exported through NetworkX writers.

Supported formats:

.graphml .gexf

The layout may be computed with either NetworkX or igraph.

Parameters:

• path (str | Path)

• layout_backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

Return type:

None

to_networkx_with_layout(*, layout_backend='networkx', layout='auto', color_by='constant', self_loop_values=None, state_vector=None, automorphism_backend='auto', **layout_kwargs)

Convert to NetworkX graph and attach computed layout coordinates.

The graph is always returned as NetworkX, but the layout can be computed using either NetworkX or igraph.

Parameters:

• layout_backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• automorphism_backend (Literal['auto', 'pynauty', 'igraph'])

to_igraph_with_layout(*, layout='auto', color_by='constant', self_loop_values=None, state_vector=None, automorphism_backend='auto', **layout_kwargs)

Convert to an igraph graph and attach computed layout coordinates.

Parameters:

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• automorphism_backend (Literal['auto', 'pynauty', 'igraph'])

save_plot(path, *, backend='igraph-cairo', color_by='constant', layout='auto', self_loop_values=None, state_vector=None, title=None, bbox=(800, 800), margin=40, **layout_kwargs)

Save a graph visualization to disk.

For backend='igraph-cairo', the plot is rendered directly by igraph/Cairo to path.

For Matplotlib-based backends, the plot is drawn on a Matplotlib figure and saved with fig.savefig(path).

Parameters:

• path (str | Path)

• backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• title (str | None)

• bbox (tuple[int, int])

• margin (int)

Return type:

Path

save(path, *, backend='igraph-cairo', color_by='constant', layout='auto', self_loop_values=None, state_vector=None, title=None, bbox=(800, 800), margin=40, **layout_kwargs)

Alias for save_plot().

Parameters:

• path (str | Path)

• backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• self_loop_values (ArrayLike | None)

• state_vector (ArrayLike | None)

• title (str | None)

• bbox (tuple[int, int])

• margin (int)

Return type:

Path

automorphism_orbits(*, backend='auto')

Return dense vertex-orbit labels under graph automorphisms.

The returned array has shape (n_vertices,) and integer labels 0, 1, ..., n_orbits - 1.

Parameters:

backend (Literal['auto', 'pynauty', 'igraph'])

Return type:

ndarray

edge_weights()

Return edge weights in plotting edge order.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

edge_pairs()

Return edge pairs in plotting edge order.

Return type:

list[tuple[int, int]]

n_edges()

Return type:

int

classmethod cage_subgraph_from_sparse_matrix(matrix, state_vector, *, zero_indices=None, classification_report=None, support_tolerance=1e-10, include_zero_edges=True, include_self_loops=False, weight_tolerance=0.0, style=None)

Build a cage-support-plus-zero subgraph visualizer from a sparse matrix.

Parameters:

• state_vector (ArrayLike)

• zero_indices (Sequence[int] | None)

• support_tolerance (float)

• include_zero_edges (bool)

• include_self_loops (bool)

• weight_tolerance (float)

• style (HamiltonianGraphStyle | None)

Return type:

HamiltonianGraphVisualizer

subgraph_for_cage_state(state_vector, *, zero_indices=None, classification_report=None, support_tolerance=1e-10, include_zero_edges=True)

Return the graph induced by a cage support plus nontrivial zeros.

Parameters:

• state_vector (ArrayLike) – Full Hilbert-space vector in the same basis as this graph.

• zero_indices (Sequence[int] | None) – Optional explicit nontrivial-zero node indices.

• classification_report – Optional caging classification report. If supplied, this method tries to extract zero indices from common report fields.

• support_tolerance (float) – Nodes with |psi_i| > support_tolerance are included as cage support.

• include_zero_edges (bool) – If True, keep all induced edges among support and zero nodes. If False, keep only edges incident to at least one support node.

Return type:

HamiltonianGraphVisualizer

__init__(graph_data, style=HamiltonianGraphStyle(figure_size=(7.0, 7.0), vertex_size=14.0, default_vertex_color='lightgray', edge_width=0.8, edge_alpha=0.45, edge_color='gray', label_vertices=False, vertex_label_size=8.0, cmap='viridis', colorbar=True, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15))

Parameters:

• graph_data (HamiltonianGraphData)

• style (HamiltonianGraphStyle)

Return type:

None

class qlinks.visualizer.LinkVisualStyle(node_size=180.0, node_color='tab:orange', edge_color='black', empty_edge_color='lightgray', arrow_linewidth=1.1, arrow_alpha=0.85, arrow_mutation_scale=None, arrow_shrink_points=None, occupied_width=2.0, empty_width=0.8, occupied_alpha=0.9, empty_alpha=0.5, site_label_fontsize=None, link_label_fontsize=None, plaquette_symbol_fontsize=22.0, vulnerable_link_arrow_length_fraction=1.1, plaquette_symbol_offset=(0.0, 0.0))

Bases: object

Basic visual style for link drawing.

Parameters:

• node_size (float)

• node_color (str)

• edge_color (str)

• empty_edge_color (str)

• arrow_linewidth (float)

• arrow_alpha (float)

• arrow_mutation_scale (float | None)

• arrow_shrink_points (float | None)

• occupied_width (float)

• empty_width (float)

• occupied_alpha (float)

• empty_alpha (float)

• site_label_fontsize (float | None)

• link_label_fontsize (float | None)

• plaquette_symbol_fontsize (float)

• vulnerable_link_arrow_length_fraction (float)

• plaquette_symbol_offset (tuple[float, float])

node_size: float

node_color: str

edge_color: str

empty_edge_color: str

arrow_linewidth: float

arrow_alpha: float

arrow_mutation_scale: float | None

arrow_shrink_points: float | None

occupied_width: float

empty_width: float

occupied_alpha: float

empty_alpha: float

site_label_fontsize: float | None

link_label_fontsize: float | None

plaquette_symbol_fontsize: float

vulnerable_link_arrow_length_fraction: float

plaquette_symbol_offset: tuple[float, float]

__init__(node_size=180.0, node_color='tab:orange', edge_color='black', empty_edge_color='lightgray', arrow_linewidth=1.1, arrow_alpha=0.85, arrow_mutation_scale=None, arrow_shrink_points=None, occupied_width=2.0, empty_width=0.8, occupied_alpha=0.9, empty_alpha=0.5, site_label_fontsize=None, link_label_fontsize=None, plaquette_symbol_fontsize=22.0, vulnerable_link_arrow_length_fraction=1.1, plaquette_symbol_offset=(0.0, 0.0))

Parameters:

• node_size (float)

• node_color (str)

• edge_color (str)

• empty_edge_color (str)

• arrow_linewidth (float)

• arrow_alpha (float)

• arrow_mutation_scale (float | None)

• arrow_shrink_points (float | None)

• occupied_width (float)

• empty_width (float)

• occupied_alpha (float)

• empty_alpha (float)

• site_label_fontsize (float | None)

• link_label_fontsize (float | None)

• plaquette_symbol_fontsize (float)

• vulnerable_link_arrow_length_fraction (float)

• plaquette_symbol_offset (tuple[float, float])

Return type:

None

qlinks.visualizer.automatic_grid_shape(n_items, *, ncols=None, nrows=None)

Decide a reasonable grid shape.

If both nrows and ncols are given, they must fit n_items. If only one is given, the other is inferred. If neither is given, use a near-square grid.

Parameters:

• n_items (int)

• ncols (int | None)

• nrows (int | None)

Return type:

tuple[int, int]

qlinks.visualizer.bipartition_labels(adjacency_matrix)

Compute bipartition labels for an undirected graph.

Disconnected components are handled independently. Isolated vertices are assigned label 0.

Return type:

ndarray[tuple[Any, …], dtype[int64]]

qlinks.visualizer.format_basis_config(config, *, style='compact', max_length=48)

Format one basis configuration for subplot labels.

style=”compact”:

binary configs are printed like 010101. other configs are printed like 1,-1,1,-1.

style=”array”:

use numpy array formatting.

style=”none”:

return an empty string.

Parameters:

• config (ArrayLike)

• style (Literal['none', 'compact', 'array'])

• max_length (int)

Return type:

str

qlinks.visualizer.plot_basis_config(lattice, config, *, layout=None, ax=None, show=True, backend='matplotlib', mode='auto', with_site_labels=True, with_site_values=False, with_link_values=False, with_link_ids=False, with_plaquette_symbols=True, plaquette_symbol_style='auto', title=None, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice', style=None)

Functional convenience wrapper around BasisConfigurationVisualizer.

Parameters:

• lattice (LatticeGraph)

• config (ArrayLike)

• layout (VariableLayout | None)

• show (bool)

• backend (Literal['matplotlib', 'networkx'])

• mode (Literal['auto', 'arrows', 'dimers', 'values'])

• with_site_labels (bool)

• with_site_values (bool)

• with_link_values (bool)

• with_link_ids (bool)

• with_plaquette_symbols (bool)

• plaquette_symbol_style (Literal['auto', 'none', 'circulation', 'resonance'])

• title (str | None)

• periodic_image_mode (Literal['none', 'positive_patch'])

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ArrayLike | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

• style (LinkVisualStyle | None)

qlinks.visualizer.plot_basis_grid(lattice, states, *, layout=None, nrows=None, ncols=None, start_index=0, labels=None, show_config_label=False, config_label_style='compact', config_label_max_length=48, backend='matplotlib', mode='auto', plaquette_symbols='auto', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice', style=None, figsize=None, show=True, suptitle=None, single_plot_kwargs=None)

Functional wrapper around BasisGridVisualizer.

Parameters:

• lattice (LatticeGraph)

• states (ArrayLike)

• layout (VariableLayout | None)

• nrows (int | None)

• ncols (int | None)

• start_index (int)

• labels (Sequence[str] | None)

• show_config_label (bool)

• config_label_style (Literal['none', 'compact', 'array'])

• config_label_max_length (int)

• backend (Literal['matplotlib', 'networkx'])

• mode (Literal['auto', 'arrows', 'dimers', 'values'])

• plaquette_symbols (Literal['auto', 'none', 'circulation', 'resonance'])

• periodic_image_mode (Literal['none', 'positive_patch'])

• collapse_duplicate_visual_links (bool)

• coordinate_scale (float)

• coordinate_transform (ArrayLike | None)

• site_label_style (Literal['cell', 'cell_sublattice', 'sublattice_cell', 'site_id'])

• style (LinkVisualStyle | None)

• figsize (tuple[float, float] | None)

• show (bool)

• suptitle (str | None)

• single_plot_kwargs (dict | None)

class qlinks.visualizer.LiouvillianGraphVisualizer(graph_visualizer, hilbert_dim, vectorization='column_major')

Bases: object

Directed graph visualizer for Liouvillian superoperators.

Nodes are operator-space basis elements |i><j|. Directed edges are nonzero off-diagonal Liouvillian matrix elements.

Parameters:

• graph_visualizer (HamiltonianGraphVisualizer)

• hilbert_dim (int)

• vectorization (Literal['column_major', 'row_major'])

graph_visualizer: HamiltonianGraphVisualizer

hilbert_dim: int

vectorization: Literal['column_major', 'row_major'] = 'column_major'

classmethod from_liouvillian(liouvillian, *, hilbert_dim, density_matrix=None, vectorization='column_major', include_self_loops=False, weight_tolerance=0.0, style=None)

Construct a Liouvillian graph visualizer.

Parameters:

• hilbert_dim (int)

• density_matrix (ArrayLike | None)

• vectorization (Literal['column_major', 'row_major'])

• include_self_loops (bool)

• weight_tolerance (float)

• style (HamiltonianGraphStyle | None)

Return type:

LiouvillianGraphVisualizer

property graph_data: HamiltonianGraphData

Return the underlying graph data.

plot(*, backend='networkx', color_by='state_amplitude_abs', edge_color_by='weight_complex', layout='auto', **kwargs)

Draw the Liouvillian graph.

Parameters:

• backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• color_by (Literal['constant', 'bipartition', 'self_loop', 'degree', 'automorphism_orbit', 'state_weight', 'state_amplitude_real', 'state_amplitude_imag', 'state_amplitude_abs', 'state_phase'])

• edge_color_by (Literal['constant', 'weight_abs', 'weight_real', 'weight_imag', 'weight_phase', 'weight_complex'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

to_networkx()

Convert to a directed NetworkX graph.

to_igraph()

Convert to a directed igraph graph.

save_graph(*args, **kwargs)

Save the graph through the underlying visualizer.

Return type:

None

__init__(graph_visualizer, hilbert_dim, vectorization='column_major')

Parameters:

• graph_visualizer (HamiltonianGraphVisualizer)

• hilbert_dim (int)

• vectorization (Literal['column_major', 'row_major'])

Return type:

None

qlinks.visualizer.flatten_density_matrix(density_matrix, *, convention='column_major')

Flatten a density matrix using the requested vectorization convention.

Parameters:

• density_matrix (ArrayLike)

• convention (Literal['column_major', 'row_major'])

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.visualizer.operator_space_labels(*, hilbert_dim, convention='column_major', indices=None)

Return labels |i><j| for Liouville-space nodes.

Parameters:

• hilbert_dim (int)

• convention (Literal['column_major', 'row_major'])

• indices (ArrayLike | None)

Return type:

list[str]

qlinks.visualizer.unflatten_operator_index(index, *, hilbert_dim, convention='column_major')

Map a vectorized Liouville-space index to an operator basis pair.

Returns:

The pair (ket_index, bra_index) corresponding to |ket><bra|.

Return type:

tuple[int, int]

Parameters:

• index (int)

• hilbert_dim (int)

• convention (Literal['column_major', 'row_major'])

class qlinks.visualizer.StochasticSchrodingerGraphVisualizer(graph_visualizer, trajectory, jump_visualizers=())

Bases: object

Graph visualizer for stochastic Schrödinger trajectories.

Nodes are Hilbert-space basis states. Node colors are taken from a time-dependent stochastic state vector psi(t).

Parameters:

• graph_visualizer (HamiltonianGraphVisualizer)

• trajectory (StochasticSchrodingerTrajectory)

• jump_visualizers (tuple[HamiltonianGraphVisualizer, ...])

graph_visualizer: HamiltonianGraphVisualizer

trajectory: StochasticSchrodingerTrajectory

jump_visualizers: tuple[HamiltonianGraphVisualizer, ...] = ()

classmethod from_trajectory(*, times, states, hamiltonian=None, jump_operators=None, basis_labels=None, weight_tolerance=0.0, style=None)

Construct a stochastic Schrödinger trajectory visualizer.

Parameters:

• times (ArrayLike)

• states (ArrayLike)

• jump_operators (Sequence | None)

• basis_labels (Sequence[str] | None)

• weight_tolerance (float)

• style (HamiltonianGraphStyle | None)

Return type:

StochasticSchrodingerGraphVisualizer

plot_frame(frame, *, backend='networkx', layout='auto', color_by='probability', edge_color_by='constant', title=None, show=True, ax=None, **layout_kwargs)

Plot one trajectory frame.

Parameters:

• frame (int)

• backend (Literal['igraph', 'igraph-mpl', 'igraph-cairo', 'networkx'])

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• color_by (Literal['probability', 'amplitude_abs', 'amplitude_real', 'amplitude_imag', 'phase'])

• edge_color_by (Literal['constant', 'weight_abs', 'weight_real', 'weight_imag', 'weight_phase', 'weight_complex'])

• title (str | None)

• show (bool)

animate(*, layout='auto', color_by='probability', edge_color_by='constant', interval=100, repeat=True, save_path=None, colorbar=False, redraw_each_frame=False, **layout_kwargs)

Animate the trajectory on a fixed graph layout.

Parameters:

• layout (Literal['auto', 'fr', 'kk', 'circle', 'grid_fr', 'kamada_kawai', 'spring'])

• color_by (Literal['probability', 'amplitude_abs', 'amplitude_real', 'amplitude_imag', 'phase'])

• edge_color_by (Literal['constant', 'weight_abs', 'weight_real', 'weight_imag', 'weight_phase', 'weight_complex'])

• interval (int)

• repeat (bool)

• save_path (str | Path | None)

• colorbar (bool)

• redraw_each_frame (bool)

__init__(graph_visualizer, trajectory, jump_visualizers=())

Parameters:

• graph_visualizer (HamiltonianGraphVisualizer)

• trajectory (StochasticSchrodingerTrajectory)

• jump_visualizers (tuple[HamiltonianGraphVisualizer, ...])

Return type:

None

class qlinks.visualizer.StochasticSchrodingerTrajectory(times, states)

Bases: object

One stochastic Schrödinger / quantum trajectory.

Parameters:

• times (ndarray[tuple[Any, ...], dtype[float64]])

• states (ndarray[tuple[Any, ...], dtype[complex128]])

times: ndarray[tuple[Any, ...], dtype[float64]]

states: ndarray[tuple[Any, ...], dtype[complex128]]

property n_times: int

property hilbert_dim: int

state_at(frame)

Parameters:

frame (int)

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

__init__(times, states)

Parameters:

• times (ndarray[tuple[Any, ...], dtype[float64]])

• states (ndarray[tuple[Any, ...], dtype[complex128]])

Return type:

None

qlinks.visualizer.as_stochastic_trajectory(*, times, states)

Validate and normalize trajectory arrays.

Parameters:

• times (ArrayLike)

• states (ArrayLike)

Return type:

StochasticSchrodingerTrajectory