test_labeling

Model.test_labeling(output='print', return_type='dict', plot_type='combined', overlap_threshold=None, overlaps='relevant', decimals=3)

Inspect eigenstate labeling quality in the local-\(S_z\) product basis.

Computes np.abs(model.eigenbasis)**2 row-wise and reports overlaps with local-\(S_z\) product-basis states for each eigenstate. When overlap_threshold is provided, only eigenstates below that diagonal overlap are included.

Parameters:

  • output (str) – Output mode. 'return' returns data, 'print' prints a formatted dict-style report, and 'plot' visualizes the overlap matrix.

  • return_type (str) – Return payload used when output='return'. 'dict' returns structured overlap data and 'matrix' returns the overlap matrix as a plain numpy.ndarray.

  • plot_type (str) – Plot style used when output='plot'. 'combined' uses a shared grayscale colormap. 'diag_offdiag_separate' colors diagonal and off-diagonal overlaps separately and uses independent scales.

  • overlap_threshold (float | None) – Optional dominant local-\(S_z\) product-basis overlap threshold. None reports all eigenstates.

  • overlaps (str | int) – Overlap selection used in return_type='dict' and output='print' mode. 'all' keeps all overlaps, an integer keeps the largest n overlaps, and 'relevant' keeps the smallest prefix whose cumulative overlap reaches 0.99.

  • decimals (int) – Number of digits printed after the decimal point for overlaps.

Return type:

List[Dict[str, object]] | ndarray | None

Returns:

If output='return' and return_type='dict', returns a list sorted by increasing diagonal overlap. Each entry contains eigenstate and overlaps. The overlaps value is a list of dictionaries with product_state and overlap keys, sorted by decreasing overlap. If return_type='matrix', returns the overlap matrix as a numpy.ndarray. Otherwise returns None.