qlinks.visualizer

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

Bases: object

Draw one basis configuration on a lattice geometry.

The visualizer is model-agnostic: it reads variable values from a VariableLayout and renders them as QLM arrows, QDM dimers, or generic values.

lattice

Lattice graph, such as ChainLattice or SquareLattice.

Type:

qlinks.lattice.graph.LatticeGraph

layout

Optional variable layout. If omitted, link plotting assumes link_variable_index == link_id.

Type:

qlinks.variables.layout.VariableLayout | None

theme

Named presentation theme. "research" preserves the historical qlinks styling; "paper" uses compact publication defaults.

Type:

Literal[‘research’, ‘paper’]

style

Optional explicit visual style. When provided, it overrides the link/site style supplied by theme while retaining the theme’s presentation defaults.

Type:

qlinks.visualizer.basis.LinkVisualStyle | None

periodic_image_mode

How to draw links that wrap periodic boundaries. "none" omits wrapped links; "positive_patch" draws the positive image patch; "both" draws both images.

Type:

Literal[‘none’, ‘positive_patch’]

collapse_duplicate_visual_links

Whether to collapse duplicate periodic visual links.

Type:

bool

coordinate_scale

Uniform coordinate scaling.

Type:

float

coordinate_transform

Optional 2x2 coordinate transform.

Type:

numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.float64]] | None

site_label_style

How to label lattice sites.

Type:

Literal[‘cell’, ‘cell_sublattice’, ‘sublattice_cell’, ‘site_id’]

lattice: LatticeGraph

layout: VariableLayout | None = None

style: LinkVisualStyle | None = None

theme: Literal['research', 'paper'] = 'research'

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)

site_value(config, site_id)

has_link_variables()

build_grid_render_cache(*, reference_config, mode='auto', plaquette_symbols='auto')

Build a reusable cache for fast repeated grid plotting.

The cache resolves the plotting mode once, precomputes visual geometry, and converts physical site/link ids to raw configuration indices. The resulting object is specific to this visualizer’s lattice/layout/style options and to the resolved mode/plaquette_symbols pair.

plot(config, *, ax=None, show=True, backend='matplotlib', mode='auto', with_site_labels=None, with_coordinate_labels=None, 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)

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

Save a visualization to disk.

__init__(lattice, layout=None, style=None, theme='research', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

class qlinks.visualizer.BasisGridVisualizer(lattice, layout=None, style=None, theme='research', 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 a grid of lattice panels.

The grid visualizer reuses the same drawing primitives as BasisConfigurationVisualizer and can build an internal render cache for repeated plotting on the same geometry.

lattice

Geometry/topology object.

Type:

qlinks.lattice.graph.LatticeGraph

layout

Variable layout used to interpret each configuration array.

Type:

qlinks.variables.layout.VariableLayout | None

theme

Named presentation theme. "research" preserves the historical qlinks styling; "paper" uses compact publication defaults.

Type:

Literal[‘research’, ‘paper’]

style

Optional explicit visual style. When provided, it overrides the link/site style supplied by theme.

Type:

qlinks.visualizer.basis.LinkVisualStyle | None

periodic_image_mode

How to draw periodic links.

Type:

Literal[‘none’, ‘positive_patch’]

collapse_duplicate_visual_links

Whether duplicate periodic visual links are collapsed.

Type:

bool

coordinate_scale

Uniform coordinate scaling.

Type:

float

coordinate_transform

Optional 2x2 coordinate transform.

Type:

collections.abc.Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str] | None

site_label_style

How to label lattice sites.

Type:

Literal[‘cell’, ‘cell_sublattice’, ‘sublattice_cell’, ‘site_id’]

lattice: LatticeGraph

layout: VariableLayout | None = None

style: LinkVisualStyle | None = None

theme: Literal['research', 'paper'] = 'research'

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

collapse_duplicate_visual_links: bool = True

coordinate_scale: float = 1.0

coordinate_transform: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None

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

build_render_cache(*, reference_config, mode='auto', plaquette_symbols='auto')

Build a reusable render cache for this grid visualizer.

Pass the returned cache to plot() when plotting several batches with the same lattice/layout/style and plotting mode.

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, render_cache=None)

Plot a batch of basis states.

Parameters

states:

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

nrows, ncols:

Optional grid shape. If not provided, a near-square shape is chosen.

start_index:

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

labels:

Optional explicit labels for each subplot.

show_config_label:

Whether to include the raw config/binary string below the state index label.

mode:

Passed to BasisConfigurationVisualizer.plot. Common values: “arrows”, “dimers”, “values”.

plaquette_symbols:

“none”:

draw no plaquette symbols.

“circulation”:

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

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:

Basis configuration array with shape (hilbert_size, n_variables).

signature:

Optional cage signature (kappa, Z). If provided, select result_or_record[signature, record_index].

record_index:

Record index among all records, or among records with the given signature.

max_states:

Optional cap on the number of support states to plot.

show_amplitudes:

Whether subplot labels include local-state amplitudes.

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:

Basis configuration array with shape (hilbert_size, n_variables).

mechanism:

One of:

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

max_states:

Optional cap on the number of zero states to plot.

__init__(lattice, layout=None, style=None, theme='research', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='cell_sublattice')

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

Bases: object

Graph data extracted from a sparse Hamiltonian matrix.

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

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

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, basis_configurations=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, vertex_label_source='auto', vertex_label_offset_points=(6.0, 0.0), configuration_symbol_map=((-1, '-'), (0, '0'), (1, '+')), font_style='default', latex_math_fontfamily='cm', cmap='viridis', colorbar=True, colorbar_label=None, colorbar_label_size=9.0, colorbar_tick_size=8.0, colorbar_include_endpoints=True, colorbar_max_ticks=7, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_colorbar_label=None, 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.

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

vertex_label_source: Literal['auto', 'configuration']

vertex_label_offset_points: tuple[float, float]

configuration_symbol_map: tuple[tuple[int, str], ...]

font_style: Literal['default', 'latex']

latex_math_fontfamily: str

cmap: str

colorbar: bool

colorbar_label: str | None

colorbar_label_size: float

colorbar_tick_size: float

colorbar_include_endpoints: bool

colorbar_max_ticks: int

edge_cmap: str

edge_phase_cmap: str

edge_colorbar: bool

edge_colorbar_label: str | None

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, vertex_label_source='auto', vertex_label_offset_points=(6.0, 0.0), configuration_symbol_map=((-1, '-'), (0, '0'), (1, '+')), font_style='default', latex_math_fontfamily='cm', cmap='viridis', colorbar=True, colorbar_label=None, colorbar_label_size=9.0, colorbar_tick_size=8.0, colorbar_include_endpoints=True, colorbar_max_ticks=7, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_colorbar_label=None, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15)

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, vertex_label_source='auto', vertex_label_offset_points=(6.0, 0.0), configuration_symbol_map=((-1, '-'), (0, '0'), (1, '+')), font_style='default', latex_math_fontfamily='cm', cmap='viridis', colorbar=True, colorbar_label=None, colorbar_label_size=9.0, colorbar_tick_size=8.0, colorbar_include_endpoints=True, colorbar_max_ticks=7, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_colorbar_label=None, 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.

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, vertex_label_source='auto', vertex_label_offset_points=(6.0, 0.0), configuration_symbol_map=((-1, '-'), (0, '0'), (1, '+')), font_style='default', latex_math_fontfamily='cm', cmap='viridis', colorbar=True, colorbar_label=None, colorbar_label_size=9.0, colorbar_tick_size=8.0, colorbar_include_endpoints=True, colorbar_max_ticks=7, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_colorbar_label=None, 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, basis_configurations=None, 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:

Whether to keep diagonal graph edges. Usually False for drawing.

weight_tolerance:

Entries with absolute value <= this threshold are removed.

directed:

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:

Optional drawing style.

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

Construct a directed graph visualizer from a sparse matrix.

bipartition_labels()

Return bipartition labels for the graph.

Raises

ValueError

If the graph is not bipartite.

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

Return scalar node values used for coloring.

edge_values(*, color_by)

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

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.

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.

vertex_configuration_labels(*, matplotlib_mathtext=False)

Return basis configurations formatted as ket labels.

The default symbol map is suitable for spin-1 / spin-chain basis values: -1 -> -, 0 -> 0, and +1 -> +. Matplotlib backends may request mathtext labels, yielding e.g. $\left|+-00\right\rangle$ without invoking external LaTeX.

vertex_plot_labels(*, matplotlib_mathtext)

Resolve the labels requested by HamiltonianGraphStyle.

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.

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.

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.

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).

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().

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.

edge_weights()

Return edge weights in plotting edge order.

edge_pairs()

Return edge pairs in plotting edge order.

n_edges()

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.

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:

Full Hilbert-space vector in the same basis as this graph.

zero_indices:

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:

Nodes with |psi_i| > support_tolerance are included as cage support.

include_zero_edges:

If True, keep all induced edges among support and zero nodes. If False, keep only edges incident to at least one support node.

__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, vertex_label_source='auto', vertex_label_offset_points=(6.0, 0.0), configuration_symbol_map=((-1, '-'), (0, '0'), (1, '+')), font_style='default', latex_math_fontfamily='cm', cmap='viridis', colorbar=True, colorbar_label=None, colorbar_label_size=9.0, colorbar_tick_size=8.0, colorbar_include_endpoints=True, colorbar_max_ticks=7, edge_cmap='coolwarm', edge_phase_cmap='twilight', edge_colorbar=True, edge_colorbar_label=None, edge_complex_min_alpha=0.2, edge_complex_max_alpha=0.95, orbit_alpha=0.65, orbit_lightness_boost=0.15))

class qlinks.visualizer.LinkVisualStyle(node_size=180.0, node_color='tab:orange', node_face_color=None, node_edge_color=None, node_linewidth=None, 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.

node_size: float

node_color: str

node_face_color: str | None

node_edge_color: str | None

node_linewidth: float | None

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', node_face_color=None, node_edge_color=None, node_linewidth=None, 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))

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.

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.

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.

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.

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

class qlinks.visualizer.LocalBasisGridVisualizer(lattice, layout=None, style=None, theme='research', shadow_style=<factory>, periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='sublattice_cell')

Bases: object

Plot local basis patterns on top of the full lattice geometry.

This visualizer is intended for local reduced-density-matrix and local recycler readouts. It embeds each local pattern into a synthetic or user-supplied full-lattice background, draws the full lattice with the usual BasisConfigurationVisualizer geometry, and shadows every site/link outside variable_indices. A full constrained-basis configuration is therefore optional; only the finite local basis is needed for the local variables being inspected.

lattice: LatticeGraph

layout: VariableLayout | None = None

style: LinkVisualStyle | None = None

theme: Literal['research', 'paper'] = 'research'

shadow_style: LocalBasisShadowStyle

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

collapse_duplicate_visual_links: bool = True

coordinate_scale: float = 1.0

coordinate_transform: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None

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

build_render_cache(*, reference_config=None, mode='auto', plaquette_symbols='none')

Build a reusable render cache for local-basis plots.

plot(local_patterns, *, variable_indices, reference_config=None, nrows=None, ncols=None, start_index=0, labels=None, show_local_pattern_label=True, config_label_style='compact', config_label_max_length=48, mode='auto', plaquette_symbols='none', figsize=None, show=True, backend='matplotlib', suptitle=None, suptitle_y=0.995, tight_layout_rect=None, single_plot_kwargs=None, render_cache=None, local_operator=None, show_only_nonzero_matrix_elements=False, matrix_element_tolerance=1e-10, show_matrix_element_values=False, matrix_element_value_role='both', max_matrix_element_values_per_pattern=6, matrix_element_value_precision=3)

Plot local patterns, highlighting only variable_indices.

Parameters

local_patterns:

Local basis patterns with shape (n_patterns, n_local_variables). For a single local variable, a one-dimensional input is interpreted as several one-variable patterns.

variable_indices:

Indices in the full configuration array corresponding to the local pattern entries.

reference_config:

Optional full configuration used as the background outside the local support. If omitted, a synthetic background is used. Nonlocal variables are shadowed, so the synthetic values are not meant to be interpreted as a physical basis state.

local_operator:

Optional local matrix/operator in the same pattern order. When show_only_nonzero_matrix_elements=True, only patterns appearing in a nonzero row or column of this matrix are drawn.

show_matrix_element_values:

If true, append nonzero local matrix entries touching each displayed pattern to the subplot title. Rows are labelled as outgoing <target|O|this> entries and columns as incoming <this|O|source> entries.

plot_readout(readout, *, reference_config=None, labels=None, suptitle=None, show_only_nonzero_matrix_elements=True, matrix_element_tolerance=1e-10, show_matrix_element_values=False, matrix_element_value_role='both', max_matrix_element_values_per_pattern=6, matrix_element_value_precision=3, **plot_kwargs)

Plot the local patterns exposed by a local-RDM-style readout.

The method intentionally uses duck typing so the visualizer does not depend on qlinks.caging or qlinks.open_system.

plot_structure_readout(structure_report, *, reference_config=None, max_structures=None, max_basis_states=None, include_frozen=True, max_frozen=None, nrows=None, ncols=None, mode='auto', coherent_plaquette_symbols='auto', frozen_plaquette_symbols='none', figsize=None, show=True, backend='matplotlib', suptitle=None, suptitle_y=0.995, tight_layout_rect=None, single_plot_kwargs=None)

Visualize local entangled structures from one readout report.

Each coherent pair is shown explicitly as a linear superposition of its basis patterns. Frozen/classical sectors are optionally shown afterward without plaquette symbols.

plot_structure_report(structure_report, *, reference_config=None, max_readouts=None, max_structures_per_readout=None, max_basis_states=None, include_frozen=True, max_frozen_per_readout=None, nrows=None, ncols=None, mode='auto', coherent_plaquette_symbols='auto', frozen_plaquette_symbols='none', figsize=None, show=True, backend='matplotlib', suptitle=None, suptitle_y=0.995, tight_layout_rect=None, single_plot_kwargs=None)

Visualize entangled local structures from a cage-level structure report.

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

class qlinks.visualizer.LocalBasisShadowStyle(shadow_node_color='lightgray', shadow_node_alpha=0.18, shadow_link_color='lightgray', shadow_link_alpha=0.22, shadow_link_width_scale=0.75, label_shadowed_variables=False)

Bases: object

Visual style for variables outside a displayed local support.

LocalBasisGridVisualizer embeds local basis patterns into a full lattice configuration. Variables in the selected local support are drawn normally; all other site/link variables are drawn with this shadow style so the global lattice context remains visible without visually competing with the local state.

shadow_node_color: str

shadow_node_alpha: float

shadow_link_color: str

shadow_link_alpha: float

shadow_link_width_scale: float

label_shadowed_variables: bool

__init__(shadow_node_color='lightgray', shadow_node_alpha=0.18, shadow_link_color='lightgray', shadow_link_alpha=0.22, shadow_link_width_scale=0.75, label_shadowed_variables=False)

class qlinks.visualizer.QuantumDiskBasisGridVisualizer(lattice, layout=None, style=<factory>, hop_pairs=(), coordinate_scale=1.0, site_label_style='site_id')

Bases: object

Plot batches of quantum disk basis states.

The public methods intentionally mirror the generic BasisGridVisualizer API: plot for arbitrary basis-state batches, plot_cage_support for cage records, and plot_interference_zeros for classification reports.

lattice: SquareLattice

layout: VariableLayout | None = None

style: QuantumDiskVisualStyle

hop_pairs: tuple[tuple[int, int], ...] = ()

coordinate_scale: float = 1.0

site_label_style: str = 'site_id'

classmethod from_model(model, *, style=None, coordinate_scale=1.0, site_label_style='site_id')

classmethod from_build_result(result, *, style=None, coordinate_scale=1.0, site_label_style='site_id')

build_render_cache()

Build a reusable render cache for repeated disk-grid plotting.

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

Plot a batch of quantum disk basis configurations.

plot_basis(basis, **plot_kwargs)

Plot all states in a Basis-like object with a states attribute.

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 disk basis states in one cage support.

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

Plot disk basis states corresponding to nontrivial interference zeros.

__init__(lattice, layout=None, style=<factory>, hop_pairs=(), coordinate_scale=1.0, site_label_style='site_id')

class qlinks.visualizer.QuantumDiskConfigurationVisualizer(lattice, layout=None, style=<factory>, hop_pairs=(), coordinate_scale=1.0, site_label_style='site_id')

Bases: object

Draw one quantum disk basis configuration on a square lattice.

The visualizer interprets binary site variables as disk occupations. It is intentionally site-based and therefore avoids the link/dimer-specific drawing conventions used by BasisConfigurationVisualizer.

lattice: SquareLattice

layout: VariableLayout | None = None

style: QuantumDiskVisualStyle

hop_pairs: tuple[tuple[int, int], ...] = ()

coordinate_scale: float = 1.0

site_label_style: str = 'site_id'

classmethod from_model(model, *, style=None, coordinate_scale=1.0, site_label_style='site_id')

Construct a disk visualizer from a disk model instance.

classmethod from_build_result(result, *, style=None, coordinate_scale=1.0, site_label_style='site_id')

Construct a disk visualizer from a model build result.

build_render_cache()

Build reusable disk-plot geometry for this lattice/layout/style.

plot(config, *, ax=None, show=True, backend='matplotlib', with_site_labels=True, with_site_values=False, with_empty_sites=True, with_blockade_edges=True, with_hop_bonds=False, title=None, render_cache=None)

Plot one quantum disk basis state.

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

__init__(lattice, layout=None, style=<factory>, hop_pairs=(), coordinate_scale=1.0, site_label_style='site_id')

class qlinks.visualizer.QuantumDiskVisualStyle(site_marker_size=35.0, site_marker_color='lightgray', site_marker_alpha=0.65, site_label_fontsize=8.0, site_value_fontsize=8.0, disk_radius=0.32, disk_face_color='tab:blue', disk_edge_color='black', disk_alpha=0.82, disk_linewidth=0.9, blockade_edge_color='lightgray', blockade_edge_linewidth=0.9, blockade_edge_alpha=0.75, hop_bond_color='tab:purple', hop_bond_linewidth=1.1, hop_bond_alpha=0.75, hop_bond_linestyle='--', occupied_site_value_color='white', empty_site_value_color='dimgray', axis_margin=0.65)

Bases: object

Visual style for the square quantum disk basis visualizers.

site_marker_size: float

site_marker_color: str

site_marker_alpha: float

site_label_fontsize: float

site_value_fontsize: float

disk_radius: float

disk_face_color: str

disk_edge_color: str

disk_alpha: float

disk_linewidth: float

blockade_edge_color: str

blockade_edge_linewidth: float

blockade_edge_alpha: float

hop_bond_color: str

hop_bond_linewidth: float

hop_bond_alpha: float

hop_bond_linestyle: str

occupied_site_value_color: str

empty_site_value_color: str

axis_margin: float

__init__(site_marker_size=35.0, site_marker_color='lightgray', site_marker_alpha=0.65, site_label_fontsize=8.0, site_value_fontsize=8.0, disk_radius=0.32, disk_face_color='tab:blue', disk_edge_color='black', disk_alpha=0.82, disk_linewidth=0.9, blockade_edge_color='lightgray', blockade_edge_linewidth=0.9, blockade_edge_alpha=0.75, hop_bond_color='tab:purple', hop_bond_linewidth=1.1, hop_bond_alpha=0.75, hop_bond_linestyle='--', occupied_site_value_color='white', empty_site_value_color='dimgray', axis_margin=0.65)

class qlinks.visualizer.SquareQDMTensorNetworkVisualStyle(tensor_size=0.46, site_radius=0.06, occupied_width=3.0, empty_width=0.8, physical_leg_length=0.42, wrap_offset=0.22, parameter_floor=1e-14)

Bases: object

Plotting controls for the square-QDM tensor-network visualizer.

tensor_size: float

site_radius: float

occupied_width: float

empty_width: float

physical_leg_length: float

wrap_offset: float

parameter_floor: float

__init__(tensor_size=0.46, site_radius=0.06, occupied_width=3.0, empty_width=0.8, physical_leg_length=0.42, wrap_offset=0.22, parameter_floor=1e-14)

class qlinks.visualizer.SquareQDMTensorNetworkVisualizer(tile_basis, style=SquareQDMTensorNetworkVisualStyle(tensor_size=0.46, site_radius=0.06, occupied_width=3.0, empty_width=0.8, physical_leg_length=0.42, wrap_offset=0.22, parameter_floor=1e-14))

Bases: object

Visualize the PEPS graph, local tensor entries, and optimization traces.

tile_basis: SquareQDMRectangularTileTensorBasis

style: SquareQDMTensorNetworkVisualStyle

plot_network(*, n_tiles_x=3, n_tiles_y=2, periodic=True, show_bond_dimensions=True, show_physical_legs=True, ax=None, title=None)

Draw the repeated tensor graph and grouped virtual dimensions.

plot_entry(entry_index, *, ax=None, title=None, show_empty_links=True)

Draw one allowed local tensor entry as a dimer configuration.

plot_parameter_magnitudes(parameters, *, max_entries=24, ax=None, title=None)

Plot the largest compact tensor-entry amplitudes.

plot_optimization_history(result, *, ax=None, log_scale=True, title=None)

Plot the exact finite-cluster variance during optimization.

plot_type1_interference_decomposition(decomposition, *, ax=None, title=None)

Compare coherent and incoherent kinetic leakage by tile boundary class.

plot_type1_parameter_sensitivity(sensitivity, *, max_entries=16, ax=None, title=None)

Plot tensor entries that most strongly control one seam loss.

plot_type1_adaptive_parameterization(parameterization, *, ax=None, title=None)

Show which compact entries are duplicated in the enlarged unit cell.

plot_type1_components(report, *, ax=None, title=None)

Compare the separated type-1 PEPS objective components.

plot_type1_optimization_history(result, *, ax=None, log_scale=True, title=None)

Plot the chiral-projected type-1 objective during optimization.

plot_type1_cluster_validation(report, *, ax=None, log_scale=False, title=None)

Compare native type-1 losses across finite clusters.

plot_chiral_physical_charges(rule, model, *, ax=None, title=None)

Show the native Z2 charge of each compressed physical state.

__init__(tile_basis, style=SquareQDMTensorNetworkVisualStyle(tensor_size=0.46, site_radius=0.06, occupied_width=3.0, empty_width=0.8, physical_leg_length=0.42, wrap_offset=0.22, parameter_floor=1e-14))

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).

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.

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.

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.

__init__(graph_visualizer, trajectory, jump_visualizers=())

class qlinks.visualizer.StochasticSchrodingerTrajectory(times, states)

Bases: object

One stochastic Schrödinger / quantum trajectory.

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

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

property n_times: int

property hilbert_dim: int

state_at(frame)

__init__(times, states)

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

Validate and normalize trajectory arrays.

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.

qlinks.visualizer.basis_visual_style(theme='research')

Return the default LinkVisualStyle for a named basis theme.

"research" reproduces the historical qlinks appearance. "paper" uses a compact publication style with hollow lattice sites and the paper QDM plaquette convention. The returned dataclass is immutable and can be customized with dataclasses.replace() when a figure needs a small local override.

qlinks.visualizer.bipartition_labels(adjacency_matrix)

Compute bipartition labels for an undirected graph.

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

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

Flatten a density matrix using the requested vectorization convention.

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.

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

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

qlinks.visualizer.plot_basis_config(lattice, config, *, layout=None, ax=None, show=True, backend='matplotlib', mode='auto', with_site_labels=None, with_coordinate_labels=None, 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', theme='research', style=None)

Functional convenience wrapper around BasisConfigurationVisualizer.

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', theme='research', style=None, figsize=None, show=True, suptitle=None, single_plot_kwargs=None, render_cache=None)

Functional wrapper around BasisGridVisualizer.

qlinks.visualizer.plot_local_basis_grid(lattice, local_patterns, *, variable_indices, reference_config=None, layout=None, nrows=None, ncols=None, start_index=0, labels=None, show_local_pattern_label=True, config_label_style='compact', config_label_max_length=48, backend='matplotlib', mode='auto', plaquette_symbols='none', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='sublattice_cell', theme='research', style=None, shadow_style=None, figsize=None, show=True, suptitle=None, single_plot_kwargs=None, render_cache=None, local_operator=None, show_only_nonzero_matrix_elements=False, matrix_element_tolerance=1e-10, show_matrix_element_values=False, matrix_element_value_role='both', max_matrix_element_values_per_pattern=6, matrix_element_value_precision=3)

Functional wrapper around LocalBasisGridVisualizer.

qlinks.visualizer.plot_local_structure_readout(lattice, structure_report, *, reference_config=None, layout=None, max_structures=None, max_basis_states=None, include_frozen=True, max_frozen=None, nrows=None, ncols=None, backend='matplotlib', mode='auto', coherent_plaquette_symbols='auto', frozen_plaquette_symbols='none', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='sublattice_cell', theme='research', style=None, shadow_style=None, figsize=None, show=True, suptitle=None, single_plot_kwargs=None)

Functional wrapper around LocalBasisGridVisualizer.plot_structure_readout().

qlinks.visualizer.plot_local_structure_report(lattice, structure_report, *, reference_config=None, layout=None, max_readouts=None, max_structures_per_readout=None, max_basis_states=None, include_frozen=True, max_frozen_per_readout=None, nrows=None, ncols=None, backend='matplotlib', mode='auto', coherent_plaquette_symbols='auto', frozen_plaquette_symbols='none', periodic_image_mode='positive_patch', collapse_duplicate_visual_links=True, coordinate_scale=1.0, coordinate_transform=None, site_label_style='sublattice_cell', theme='research', style=None, shadow_style=None, figsize=None, show=True, suptitle=None, single_plot_kwargs=None)

Functional wrapper around LocalBasisGridVisualizer.plot_structure_report().

qlinks.visualizer.plot_quantum_disk_basis_grid(states, *, lattice=None, layout=None, model=None, result=None, nrows=None, ncols=None, start_index=0, labels=None, show_config_label=False, config_label_style='compact', config_label_max_length=48, style=None, figsize=None, show=True, backend='matplotlib', suptitle=None, single_plot_kwargs=None)

Functional wrapper around QuantumDiskBasisGridVisualizer.

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

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

Parameters:

• index (int) – Flat Liouville-space index.

• hilbert_dim (int) – Hilbert-space dimension.

• convention (Literal['column_major', 'row_major']) – Vectorization convention used to flatten the operator.

Returns:

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

Return type:

tuple[int, int]