qlinks.caging package#
The caging package contains high-level cage search, classification, diagnostics,
local-cage search, and thermodynamic witness helpers. Shared local algebra lives
in qlinks.local_structure; open-system construction lives separately in
qlinks.open_system.
Submodules#
qlinks.caging.candidate module#
qlinks.caging.classification module#
- class qlinks.caging.classification.CageClassificationConfig(amplitude_tolerance=1e-10, cancellation_tolerance=1e-09, action_tolerance=1e-09, sector_policy='raise_if_disconnected', collective_cancellation_mode='same_local_support_nullspace', collective_min_group_size=2, collective_relation_tolerance=None, fock_dense_fraction_threshold=0.5, potential_shell_tolerance=None)[source]#
Bases:
objectNumerical parameters for regional/extended cage diagnostics.
- collective_cancellation_mode: Literal['disabled', 'same_local_support_sum', 'same_local_support_nullspace', 'all_problematic_sum', 'all_problematic_nullspace']#
- __init__(amplitude_tolerance=1e-10, cancellation_tolerance=1e-09, action_tolerance=1e-09, sector_policy='raise_if_disconnected', collective_cancellation_mode='same_local_support_nullspace', collective_min_group_size=2, collective_relation_tolerance=None, fock_dense_fraction_threshold=0.5, potential_shell_tolerance=None)#
- class qlinks.caging.classification.LocalTransitionPattern(source_local, target_local, matrix_element)[source]#
Bases:
objectLocal transition induced by one active edge u -> h.
The local mask represents Omega - Lambda_h.
- __init__(source_local, target_local, matrix_element)#
- class qlinks.caging.classification.InterferenceZeroReport(zero_index, active_neighbors, active_matrix_elements, active_amplitudes, cancellation_residual, common_mask, local_mask, local_transitions, q_sector_weight, reduced_action_norm, complement_action_norm, complement_target_indices, explained_complement_target_indices, unexplained_complement_target_indices, complement_targets_are_known_zeros, trivial_target_indices, known_nonprojector_iz_target_indices, projector_like_iz_target_indices, unexpected_target_indices, complement_support_indices, complement_contributing_input_indices, projector_like_annihilated_input_indices, source_projector_like, has_unexpected_targets, has_nonzero_complement_action, unexpected_target_probe_failure_indices, nonzero_complement_action_target_indices, probe_mechanism_label, collective_cancellation_group_id=None, collective_cancellation_partner_zero_indices=<factory>, collective_cancellation_coefficient=0j, collective_cancellation_norm=inf, reduced_action_vector=<factory>, local_variable_indices=())[source]#
Bases:
objectDiagnostics for one source nontrivial interference zero.
The field
zero_indexis the source zero h used to construct the reduced IZ probe Z_h^(R). The mechanism label describes the behavior of this source probe on the cage state.- local_transitions: tuple[LocalTransitionPattern, ...]#
- probe_mechanism_label: Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage']#
- __init__(zero_index, active_neighbors, active_matrix_elements, active_amplitudes, cancellation_residual, common_mask, local_mask, local_transitions, q_sector_weight, reduced_action_norm, complement_action_norm, complement_target_indices, explained_complement_target_indices, unexplained_complement_target_indices, complement_targets_are_known_zeros, trivial_target_indices, known_nonprojector_iz_target_indices, projector_like_iz_target_indices, unexpected_target_indices, complement_support_indices, complement_contributing_input_indices, projector_like_annihilated_input_indices, source_projector_like, has_unexpected_targets, has_nonzero_complement_action, unexpected_target_probe_failure_indices, nonzero_complement_action_target_indices, probe_mechanism_label, collective_cancellation_group_id=None, collective_cancellation_partner_zero_indices=<factory>, collective_cancellation_coefficient=0j, collective_cancellation_norm=inf, reduced_action_vector=<factory>, local_variable_indices=())#
- class qlinks.caging.classification.CollectiveCancellationReport(group_id, source_zero_indices, coefficients, individual_complement_action_norms, collective_action_norm, collective_target_indices, local_mask, local_region_size, relation_kind, grouping_kind)[source]#
Bases:
objectA group of reduced IZ probes whose complement leakages cancel together.
- __init__(group_id, source_zero_indices, coefficients, individual_complement_action_norms, collective_action_norm, collective_target_indices, local_mask, local_region_size, relation_kind, grouping_kind)#
- class qlinks.caging.classification.ClosureMechanismSummary(label='no_nontrivial_zeros', n_q_empty_source_probes=0, n_closed_by_known_zero_network_source_probes=0, n_domain_blocked_source_probes=0, n_projector_like_source_probes=0, n_collective_cancellation_source_probes=0, n_unexplained_leakage_source_probes=0, n_projector_like_iz_targets=0, n_unexpected_targets=0, n_nonzero_complement_action_failures=0)[source]#
Bases:
objectState-level summary of reduced-IZ closure mechanisms.
This is intentionally separated from Fock-space and real-space support morphology. It summarizes how boundary/interference-zero probes close, not how large or spatially extended the cage support is.
- label: Literal['no_nontrivial_zeros', 'unexplained_leakage', 'collective_cancellation', 'projector_network', 'pure_domain_blocked', 'zero_network_closed', 'q_empty', 'mixed_individual_closure']#
- __init__(label='no_nontrivial_zeros', n_q_empty_source_probes=0, n_closed_by_known_zero_network_source_probes=0, n_domain_blocked_source_probes=0, n_projector_like_source_probes=0, n_collective_cancellation_source_probes=0, n_unexplained_leakage_source_probes=0, n_projector_like_iz_targets=0, n_unexpected_targets=0, n_nonzero_complement_action_failures=0)#
- class qlinks.caging.classification.FockSupportMorphology(label='unknown', support_size=0, effective_support_size=0.0, hilbert_size=0, support_fraction=0.0, effective_hilbert_fraction=0.0, boundary_size=0, boundary_to_support_ratio=0.0, support_internal_matrix_entries=0, potential_shell_value=None, potential_shell_size=None, support_shell_fraction=None, effective_shell_fraction=None, potential_shell_residual=None)[source]#
Bases:
objectFinite-size morphology diagnostics for the support in Fock space.
The
labelis a finite-size proxy only. Scaling labels such as finite, polynomial, or shell-extended require comparing a family of systems across sizes.- label: Literal['unknown', 'finite_size_empty', 'finite_size_singleton', 'finite_size_sector_sparse', 'finite_size_sector_dense', 'finite_size_shell_sparse', 'finite_size_shell_dense']#
- __init__(label='unknown', support_size=0, effective_support_size=0.0, hilbert_size=0, support_fraction=0.0, effective_hilbert_fraction=0.0, boundary_size=0, boundary_to_support_ratio=0.0, support_internal_matrix_entries=0, potential_shell_value=None, potential_shell_size=None, support_shell_fraction=None, effective_shell_fraction=None, potential_shell_residual=None)#
- class qlinks.caging.classification.RealSpaceSupportMorphology(label='unknown', n_variables=0, active_variable_indices=(), active_variable_count=0, active_variable_fraction=0.0, frozen_variable_count=0, reduced_iz_region_variable_indices=(), reduced_iz_region_variable_count=0, reduced_iz_region_variable_fraction=0.0, exact_support_component_count=0, exact_support_component_sizes=(), connected_support_component_count=0, connected_support_component_sizes=())[source]#
Bases:
objectFinite-size morphology diagnostics in the microscopic variable space.
The variable indices are model-layout indices. Connectivity, diameter, and winding/wrapping require lattice adjacency metadata and are therefore left to higher-level lattice-aware helpers.
- __init__(label='unknown', n_variables=0, active_variable_indices=(), active_variable_count=0, active_variable_fraction=0.0, frozen_variable_count=0, reduced_iz_region_variable_indices=(), reduced_iz_region_variable_count=0, reduced_iz_region_variable_fraction=0.0, exact_support_component_count=0, exact_support_component_sizes=(), connected_support_component_count=0, connected_support_component_sizes=())#
- class qlinks.caging.classification.ReducedIZProbeSupport(zero_index, mechanism_label, variable_indices, local_region_size, complement_action_norm, reduced_action_norm, n_local_transitions, n_complement_targets, n_unexplained_complement_targets)[source]#
Bases:
objectCached support data for one reduced IZ probe
Z_h^(R).- mechanism_label: Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage']#
- __init__(zero_index, mechanism_label, variable_indices, local_region_size, complement_action_norm, reduced_action_norm, n_local_transitions, n_complement_targets, n_unexplained_complement_targets)#
- class qlinks.caging.classification.ReducedIZMonitorComponentGroup(component_id, decomposition, zero_indices, support_variables, state_action_vector=<factory>)[source]#
Bases:
objectCached report-side plan for one reduced-IZ monitor component.
The construction layer can consume these groups directly instead of rediscovering reduced-IZ supports and frustration-free decompositions. When available,
state_action_vectorstores the cached action of this component monitor on the classified cage state.- __init__(component_id, decomposition, zero_indices, support_variables, state_action_vector=<factory>)#
- class qlinks.caging.classification.CageClassificationReport(label, support_size, hilbert_size, support_fraction, n_nontrivial_zeros, n_distinct_local_patterns, n_complement_targets, n_unexplained_complement_targets, fraction_zeros_with_closed_complement_targets, n_q_empty_source_probes, n_closed_by_known_zero_network_source_probes, n_projector_like_source_probes, n_invalid_source_probes, n_regional_source_probes, n_collective_cancellation_source_probes, collective_cancellation_source_zero_indices, q_empty_source_zero_indices, closed_by_known_zero_network_source_zero_indices, projector_like_source_zero_indices, invalid_source_zero_indices, regional_source_zero_indices, n_trivial_targets, n_known_nonprojector_iz_targets, n_projector_like_iz_targets, n_unexpected_targets, n_unexpected_target_probe_failures, n_nonzero_complement_action_probe_failures, unexpected_target_probe_failure_indices, nonzero_complement_action_probe_failure_indices, n_source_projector_like_probes, n_indirect_projector_like_probes, n_projector_like_annihilated_inputs, source_projector_like_probe_indices, indirect_projector_like_probe_indices, projector_like_annihilated_input_indices, mean_q_sector_weight, max_q_sector_weight, mean_reduced_action_norm, max_reduced_action_norm, mean_complement_action_norm, max_complement_action_norm, zero_reports, collective_cancellation_reports, reduced_iz_probe_supports=<factory>, reduced_iz_region_variable_indices=(), reduced_iz_monitor_component_groups=<factory>, closure_summary=<factory>, fock_support_morphology=<factory>, real_space_support_morphology=<factory>, metadata=<factory>)[source]#
Bases:
objectRegional/extended diagnostic report for one cage state.
- zero_reports: tuple[InterferenceZeroReport, ...]#
- collective_cancellation_reports: tuple[CollectiveCancellationReport, ...]#
- reduced_iz_probe_supports: tuple[ReducedIZProbeSupport, ...]#
- reduced_iz_monitor_component_groups: dict[Literal['single_sum', 'exact_support', 'connected_support'], tuple[ReducedIZMonitorComponentGroup, ...]]#
- closure_summary: ClosureMechanismSummary#
- fock_support_morphology: FockSupportMorphology#
- real_space_support_morphology: RealSpaceSupportMorphology#
- property closure_mechanism_label: Literal['no_nontrivial_zeros', 'unexplained_leakage', 'collective_cancellation', 'projector_network', 'pure_domain_blocked', 'zero_network_closed', 'q_empty', 'mixed_individual_closure']#
- property fock_support_morphology_label: Literal['unknown', 'finite_size_empty', 'finite_size_singleton', 'finite_size_sector_sparse', 'finite_size_sector_dense', 'finite_size_shell_sparse', 'finite_size_shell_dense']#
- property real_space_support_morphology_label: Literal['unknown', 'frozen', 'partially_active', 'fully_active']#
- property domain_blocked_source_zero_indices: ndarray[tuple[Any, ...], dtype[int64]]#
Source-zero indices whose probe is domain-blocked.
Domain-blocked probes have finite complement support, but that complement support contains no input configuration on which the transplanted reduced-IZ operator can fire. They are a regional closure mechanism in the state-level classification.
- selected_reduced_iz_reports(*, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Return reduced-IZ reports selected for monitor assembly.
- reduced_iz_report_groups(*, decomposition, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Return report groups for a reduced-IZ monitor decomposition.
- reduced_iz_component_groups(*, decomposition, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True, use_collective_coefficients=True)[source]#
Return cached/recomputed reduced-IZ component-group metadata.
- reduced_iz_local_rdm_readouts(*, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Return local-RDM readouts for reduced-IZ component supports.
This is a convenience wrapper around
qlinks.caging.reduced_iz_local_rdm_readouts_from_report(). It makes the frustration-free reduced-IZ decompositions cached in the classification report directly inspectable from notebooks.
- frustration_free_local_rdm_readouts(*, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Alias for
reduced_iz_local_rdm_readouts().
- local_structure_report(*, basis_configs, state, model=None, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=None, include_empty_supports=False)[source]#
Return an automatic local-structure report from reduced-IZ RDMs.
- to_text(*, verbose=False, max_zero_reports=10, width=120)[source]#
Return a plain-text Rich rendering of the classification report.
- __init__(label, support_size, hilbert_size, support_fraction, n_nontrivial_zeros, n_distinct_local_patterns, n_complement_targets, n_unexplained_complement_targets, fraction_zeros_with_closed_complement_targets, n_q_empty_source_probes, n_closed_by_known_zero_network_source_probes, n_projector_like_source_probes, n_invalid_source_probes, n_regional_source_probes, n_collective_cancellation_source_probes, collective_cancellation_source_zero_indices, q_empty_source_zero_indices, closed_by_known_zero_network_source_zero_indices, projector_like_source_zero_indices, invalid_source_zero_indices, regional_source_zero_indices, n_trivial_targets, n_known_nonprojector_iz_targets, n_projector_like_iz_targets, n_unexpected_targets, n_unexpected_target_probe_failures, n_nonzero_complement_action_probe_failures, unexpected_target_probe_failure_indices, nonzero_complement_action_probe_failure_indices, n_source_projector_like_probes, n_indirect_projector_like_probes, n_projector_like_annihilated_inputs, source_projector_like_probe_indices, indirect_projector_like_probe_indices, projector_like_annihilated_input_indices, mean_q_sector_weight, max_q_sector_weight, mean_reduced_action_norm, max_reduced_action_norm, mean_complement_action_norm, max_complement_action_norm, zero_reports, collective_cancellation_reports, reduced_iz_probe_supports=<factory>, reduced_iz_region_variable_indices=(), reduced_iz_monitor_component_groups=<factory>, closure_summary=<factory>, fock_support_morphology=<factory>, real_space_support_morphology=<factory>, metadata=<factory>)#
- qlinks.caging.classification.classify_cage_state(cage_state, *, kinetic_matrix, basis_configs, hilbert_size=None, sector_mask=None, potential_diagonal=None, config=None)[source]#
Classify one compact cage state from solver output.
- Parameters:
cage_state (CageState) – Compact cage state returned by the caging solver.
kinetic_matrix (spmatrix | sparray | ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Off-diagonal Hamiltonian or kinetic matrix used to identify interference zeros and local
Z_hpatterns.basis_configs (ndarray[tuple[Any, ...], dtype[integer]]) – Integer array with shape
(n_basis, n_variables). Rows are product-state configurations in the global constrained basis.hilbert_size (int | None) – Full Hilbert-space dimension. Defaults to
basis_configs.shape[0].sector_mask (ndarray[tuple[Any, ...], dtype[bool]] | None) – Optional mask selecting the sector used for local diagnostics.
potential_diagonal (ndarray[tuple[Any, ...], dtype[number]] | None) – Optional diagonal potential/self-loop values. When provided, the report includes shell-relative Fock-space support diagnostics if the state has a sharp potential value.
config (CageClassificationConfig | None) – Numerical classification parameters.
- Returns:
Classification report describing reduced-IZ zeros, regional/extended labels, and monitor decompositions.
- Return type:
- qlinks.caging.classification.classify_full_state(full_state, *, kinetic_matrix, basis_configs, sector_mask=None, potential_diagonal=None, config=None, metadata=None)[source]#
Classify a full Hilbert-space vector.
- qlinks.caging.classification.reduced_iz_probe_support_from_report(zero_report)[source]#
Return cached public support metadata for a reduced IZ probe.
- qlinks.caging.classification.select_reduced_iz_monitor_reports(report, *, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Select reduced-IZ reports from a classification report for monitor use.
- qlinks.caging.classification.select_reduced_iz_monitor_reports_from_zero_reports(zero_reports, *, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Select non-invalid reduced-IZ zero reports for monitor assembly.
- qlinks.caging.classification.support_key_from_mask(local_mask)[source]#
Return the variable-index support key for a local reduced-IZ mask.
- qlinks.caging.classification.support_key_for_zero_report(zero_report)[source]#
Return the variable-index support key for one reduced-IZ report.
- qlinks.caging.classification.group_reduced_iz_reports_by_exact_support(reports)[source]#
Group reduced-IZ reports with identical support variables.
- qlinks.caging.classification.group_reduced_iz_reports_by_connected_support(reports)[source]#
Group reduced-IZ reports whose supports overlap transitively.
qlinks.caging.diagnostics module#
- class qlinks.caging.diagnostics.LocalReducedDensityMatrixReadout(variable_indices, reduced_density_matrix, n_matrix_unit_terms, matrix_unit_terms, matrix_unit_terms_truncated, component_index=None, component_id=None, decomposition=None, zero_indices=())[source]#
Bases:
objectNotebook-friendly readout for one local reduced density matrix.
The readout keeps the full
LocalReducedDensityMatrixobject and a truncated local matrix-unit expansion of its density matrix. The optional component metadata is populated when the readout comes from a reduced-IZ frustration-free decomposition of a classification report.- reduced_density_matrix: LocalReducedDensityMatrix#
- matrix_unit_terms: tuple[LocalMatrixUnitTerm, ...]#
- __init__(variable_indices, reduced_density_matrix, n_matrix_unit_terms, matrix_unit_terms, matrix_unit_terms_truncated, component_index=None, component_id=None, decomposition=None, zero_indices=())#
- qlinks.caging.diagnostics.local_reduced_density_matrix_readout_from_state(*, basis_configs, state, variable_indices, tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, component_index=None, component_id=None, decomposition=None, zero_indices=())[source]#
Compute a local RDM and expose its matrix-unit expansion.
This is a thin caging-facing wrapper around the local-RDM utilities used by the open-system local-recycling layer. No global basis outside
basis_configsis constructed.
- qlinks.caging.diagnostics.reduced_iz_local_rdm_readouts_from_report(report, *, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Return local-RDM readouts for reduced-IZ monitor components.
The components are the same frustration-free reduced-IZ groups cached by
CageClassificationReportand used by the Lindblad-construction layer. For each component support, this function computes the target state reduced density matrix and expands that RDM in local matrix units so that it can be inspected in notebooks.
- class qlinks.caging.diagnostics.LocalCoherentPatternPair(pattern_a, pattern_b, weight, coefficient, relative_phase, hamming_distance, equal_weight_residual, rank_one_residual, is_equal_weight, is_singlet_like)[source]#
Bases:
objectDetected coherent two-pattern sector in a local RDM.
- __init__(pattern_a, pattern_b, weight, coefficient, relative_phase, hamming_distance, equal_weight_residual, rank_one_residual, is_equal_weight, is_singlet_like)#
- class qlinks.caging.diagnostics.LocalClassicalPatternSector(pattern, weight)[source]#
Bases:
objectDiagonal-only local pattern sector not absorbed into a coherent pair.
- __init__(pattern, weight)#
- class qlinks.caging.diagnostics.LocalPlaquetteActivityReport(plaquette_id, link_ids, local_positions, n_weighted_patterns, n_flippable_patterns, flippable_weight, status)[source]#
Bases:
objectFlippability summary for one plaquette fully contained in a readout.
- __init__(plaquette_id, link_ids, local_positions, n_weighted_patterns, n_flippable_patterns, flippable_weight, status)#
- class qlinks.caging.diagnostics.LocalStructureReadoutReport(readout, coherent_pairs, classical_sectors, plaquette_activity, offdiagonal_weight, coherent_weight, classical_weight, tolerance)[source]#
Bases:
objectAutomatic structure summary for one local-RDM readout.
- readout: LocalReducedDensityMatrixReadout#
- coherent_pairs: tuple[LocalCoherentPatternPair, ...]#
- classical_sectors: tuple[LocalClassicalPatternSector, ...]#
- plaquette_activity: tuple[LocalPlaquetteActivityReport, ...]#
- __init__(readout, coherent_pairs, classical_sectors, plaquette_activity, offdiagonal_weight, coherent_weight, classical_weight, tolerance)#
- class qlinks.caging.diagnostics.CageLocalStructureReport(readout_reports, decomposition, tolerance)[source]#
Bases:
objectAutomatic text/formula report for local structure of a cage state.
- readout_reports: tuple[LocalStructureReadoutReport, ...]#
- __init__(readout_reports, decomposition, tolerance)#
- qlinks.caging.diagnostics.analyze_local_rdm_structure(readout, *, model=None, tolerance=1e-10, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Identify simple local structures in one RDM readout.
The first version deliberately recognizes only robust, notebook-readable motifs: rank-one two-pattern coherent sectors and diagonal classical/frozen sectors. If a QDM
modelis supplied, fully contained plaquettes are also classified as always inactive, always flippable, or mixed on the RDM support.
- qlinks.caging.diagnostics.local_structure_report_from_readouts(readouts, *, model=None, decomposition=None, tolerance=1e-10, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Build an automatic local-structure report from local RDM readouts.
- qlinks.caging.diagnostics.local_structure_report_from_classification_report(report, *, basis_configs, state, model=None, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=None, include_empty_supports=False, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Compute reduced-IZ RDM readouts and summarize local cage motifs.
- class qlinks.caging.diagnostics.SupportPermutationDiagnostic(permutation, moved_support_count, cycle_lengths, boundary_fixed_residual, boundary_fixed_relative_residual, internal_commutator_residual, internal_commutator_relative_residual, state_phase, state_eigen_residual, state_eigen_relative_residual, is_nontrivial_state_sector, explains_boundary_closure)[source]#
Bases:
objectDiagnostics for one support permutation as a possible CLS symmetry.
The permutation maps old local support positions to new local support positions. It is tested as a unitary
Uacting inside the support. A boundary-fixed local symmetry satisfiesK U = Kfor the leakage matrixK = H_{boundary,support}. If the state is also an eigenvector ofUwith a nontrivial phase, then the permutation gives a symmetry-sector explanation for the destructive-interference closure.- __init__(permutation, moved_support_count, cycle_lengths, boundary_fixed_residual, boundary_fixed_relative_residual, internal_commutator_residual, internal_commutator_relative_residual, state_phase, state_eigen_residual, state_eigen_relative_residual, is_nontrivial_state_sector, explains_boundary_closure)#
- class qlinks.caging.diagnostics.FockSpaceAutomorphismDiagnostic(support_indices, boundary_indices, hilbert_size, support_size, boundary_size, selected_graph_size, state_boundary_residual, state_boundary_relative_residual, n_automorphisms_tested, n_nontrivial_automorphisms, n_explaining_automorphisms, automorphism_search_truncated, skipped_reason, permutation_diagnostics)[source]#
Bases:
objectBoundary-fixed Fock-space automorphism diagnostics for a cage state.
The diagnostic searches automorphisms of the support-plus-boundary graph while fixing every boundary vertex individually. This is intentionally the conservative CLS test: a nontrivial support irrep is certified only when the exterior/boundary channels are symmetry-trivial.
- permutation_diagnostics: tuple[SupportPermutationDiagnostic, ...]#
- property best_explaining_permutation: SupportPermutationDiagnostic | None#
- __init__(support_indices, boundary_indices, hilbert_size, support_size, boundary_size, selected_graph_size, state_boundary_residual, state_boundary_relative_residual, n_automorphisms_tested, n_nontrivial_automorphisms, n_explaining_automorphisms, automorphism_search_truncated, skipped_reason, permutation_diagnostics)#
- class qlinks.caging.diagnostics.OperatorStateActionDiagnostic(name, action_norm, relative_action_norm, eigenvalue, eigen_residual, relative_eigen_residual, annihilates_state, is_eigen_operator)[source]#
Bases:
objectAction of one candidate operator on the target state.
- __init__(name, action_norm, relative_action_norm, eigenvalue, eigen_residual, relative_eigen_residual, annihilates_state, is_eigen_operator)#
- class qlinks.caging.diagnostics.LocalAnnihilatorDiagnostic(operator_names, state_norm, action_matrix_shape, action_matrix_rank, annihilator_nullity, singular_values, annihilator_coefficients, annihilator_residuals, operator_action_diagnostics, tolerance)[source]#
Bases:
objectLinear-annihilator diagnostics in a supplied operator basis.
If the operator basis is
{O_a}, this diagnostic computes the nullspace of the action matrix with columnsO_a |psi>. Every null vector gives a linear combinationsum_a c_a O_athat annihilates the state. The same action data also reports which individual operators have the state as an eigenvector.- operator_action_diagnostics: tuple[OperatorStateActionDiagnostic, ...]#
- __init__(operator_names, state_norm, action_matrix_shape, action_matrix_rank, annihilator_nullity, singular_values, annihilator_coefficients, annihilator_residuals, operator_action_diagnostics, tolerance)#
- class qlinks.caging.diagnostics.CommutantAlgebraDiagnostic(operator_names, term_names, commutator_matrix_shape, commutant_rank, commutant_nullity, singular_values, commutant_coefficients, commutant_residuals, individual_commutator_norms, tolerance)[source]#
Bases:
objectCommutant diagnostics in a supplied operator basis.
Given candidate operators
O_aand Hamiltonian/local termsh_j, this solves for linear combinationsX=sum_a c_a O_asatisfying[X, h_j]=0for all supplied terms. This is a small-system diagnostic and is meant for reverse engineering candidate commutant generators after exact cage states have been found.- __init__(operator_names, term_names, commutator_matrix_shape, commutant_rank, commutant_nullity, singular_values, commutant_coefficients, commutant_residuals, individual_commutator_norms, tolerance)#
- qlinks.caging.diagnostics.fock_space_automorphism_diagnostic(*, kinetic_matrix, support_indices, state, tolerance=1e-10, weight_tolerance=0.0, max_graph_vertices=96, max_automorphisms=128, include_identity=False)[source]#
Diagnose boundary-fixed Fock-space automorphisms of a cage support.
- Parameters:
kinetic_matrix – Sparse or dense matrix defining Fock-space hopping.
support_indices (Sequence[int]) – Global basis indices carrying the compact state.
state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Either the local state on
support_indicesor a full Hilbert vector in the same basis askinetic_matrix.tolerance (float) – Numerical tolerance used for symmetry/eigenstate tests.
weight_tolerance (float) – Matrix entries with smaller absolute value are ignored when building the graph and boundary map.
max_graph_vertices (int | None) – Skip automorphism enumeration above this selected support-plus-boundary graph size. Use
Noneto disable.max_automorphisms (int) – Maximum number of graph automorphisms to test.
include_identity (bool) – Whether to keep the identity permutation in the returned per-permutation diagnostics.
- Returns:
Boundary-fixed automorphism diagnostic.
skipped_reasonis populated when the selected graph is intentionally too large for this lightweight diagnostic.- Return type:
- qlinks.caging.diagnostics.fock_space_automorphism_diagnostic_for_cage_state(*, kinetic_matrix, cage_state, tolerance=1e-10, weight_tolerance=0.0, max_graph_vertices=96, max_automorphisms=128, include_identity=False)[source]#
Run
fock_space_automorphism_diagnostic()on aCageState.
qlinks.caging.local_search module#
Temporary compatibility facade for the decomposed local-search implementation.
Active qlinks code imports the focused modules directly. This facade exists only until the post-refactor API cleanup and must not receive new implementation logic.
- class qlinks.caging.local_search.AdaptiveRegionProposal(model, max_plaquettes, config=<factory>, seed_plaquette_ids=None, min_plaquettes=1, beam_width=8, branch_factor=8, max_regions=None, max_links=None, use_search_feedback=False, adapter=None)[source]#
Bases:
objectDynamically grow local QDM regions with a beam-search heuristic.
Unlike
StripeRegionProposal, this strategy does not assume a fixed region shape. It starts from one seed plaquette at a time, repeatedly adds neighboring plaquettes sharing links with the current region, and keeps only the best-scoring partial regions under hard size limits.use_search_feedback=Falsekeeps proposal generation cheap and scores regions by structural proxies: small kinetic boundary, moderate link count, and compact shared-link connectivity. Settinguse_search_feedback=Trueadditionally runs the local cage searcher while growing and boosts regions that already contain candidate local cages.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, seed_plaquette_ids=None, min_plaquettes=1, beam_width=8, branch_factor=8, max_regions=None, max_links=None, use_search_feedback=False, adapter=None)#
- class qlinks.caging.local_search.AdaptiveRegionProposalRecord(region, plaquette_ids, seed_plaquette_ids, generation, score, link_count, unresolved_boundary_count, local_hilbert_size=None, n_records=None, counts_by_signature=<factory>)[source]#
Bases:
objectOne dynamically grown plaquette-region proposal.
The adaptive proposal stores the seed plaquettes, the selected plaquette set, and the cheap heuristic score that was used by the beam search. Optional local-search feedback is filled only when
use_search_feedback=TrueonAdaptiveRegionProposal.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_ids, generation, score, link_count, unresolved_boundary_count, local_hilbert_size=None, n_records=None, counts_by_signature=<factory>)#
- qlinks.caging.local_search.CertifiedLocalCageSearchResult#
alias of
CertifiedLocalQDMCageSearchResult
- class qlinks.caging.local_search.CertifiedLocalQDMCageSearchResult(cage_search_result, basis, kinetic_matrix, self_loop_values, reports, padding_config)[source]#
Bases:
objectA certified local-first result with CageSearchResult-compatible records.
cage_search_resultis an ordinaryCageSearchResultwhose Hilbert space is the limited certified basis, not the full global Hilbert space. The companionbasis,kinetic_matrix, andself_loop_valuesare the limited objects needed by visualizers/classifiers/adapters.- cage_search_result: CageSearchResult#
- padding_config: LocalQDMPaddingConfig | LocalQDMMultiPaddingConfig#
- property records: list[CageRecord]#
- property config: CageSearchConfig#
- __init__(cage_search_result, basis, kinetic_matrix, self_loop_values, reports, padding_config)#
- class qlinks.caging.local_search.ConnectedRegionProposal(model, max_plaquettes, config=<factory>, min_plaquettes=1, seed_plaquette_ids=None, max_regions=None, max_links=None, adapter=None)[source]#
Bases:
objectEnumerate connected plaquette regions under explicit size budgets.
This is the robust, shape-agnostic counterpart of the stripe/adaptive proposals. It exhaustively enumerates connected plaquette sets on the shared-link plaquette graph up to
max_plaquettesand optionallymax_links. It is deliberately simple: the only physics assumption is connectedness on the kinetic plaquette graph, while the local solver and global certification decide which regions are useful.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, min_plaquettes=1, seed_plaquette_ids=None, max_regions=None, max_links=None, adapter=None)#
- class qlinks.caging.local_search.ConnectedRegionProposalRecord(region, plaquette_ids, seed_plaquette_id, size, link_count, unresolved_boundary_count)[source]#
Bases:
objectOne connected plaquette-set local-region proposal.
Unlike the adaptive beam proposal, this record comes from exhaustive connected-region enumeration under explicit size limits. It is intended as a robust fallback when the cage shape is not known a priori.
- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_id, size, link_count, unresolved_boundary_count)#
- class qlinks.caging.local_search.FactorizedLocalQDMPadding(block_ids, exterior_link_ids, exterior_config)[source]#
Bases:
objectShared exterior for a product of local blocks without support expansion.
Unlike
MultiLocalQDMPadding, this object never forms the Cartesian product of block support configurations. Its memory cost is therefore independent ofprod(block.support_size).- __init__(block_ids, exterior_link_ids, exterior_config)#
- class qlinks.caging.local_search.LocalCageModelAdapter(*args, **kwargs)[source]#
Bases:
ProtocolModel-specific local variable interface used by
LocalCageSearcher.The generic local searcher owns the caging algebra. The adapter owns the model/lattice details: how to build a local region, enumerate compatible local configurations, construct local kinetic transitions, and compute the local diagonal/self-loop values. New models should add an adapter rather than adding branches to
LocalCageSearcher.- build_region_from_plaquettes(*, plaquette_ids, config, scoring_plaquette_ids=None)[source]#
Build a local region from seed plaquettes/local kinetic terms.
- build_region_from_links(*, link_ids, config, active_plaquette_ids=None, scoring_plaquette_ids=None)[source]#
Build a local region from explicit local variables.
- build_local_kinetic_matrix(region, local_basis)[source]#
Build the local kinetic matrix on
local_basis.
- make_local_record(*, cage_state, signature, candidate, local_basis, region)[source]#
Wrap one solved local cage state in a model-specific record.
- __init__(*args, **kwargs)#
- qlinks.caging.local_search.LocalCageRecord#
alias of
LocalQDMCageRecord
- qlinks.caging.local_search.LocalCageRegion#
alias of
LocalQDMRegion
- qlinks.caging.local_search.LocalCageSearchConfig#
alias of
LocalQDMCageSearchConfig
- qlinks.caging.local_search.LocalCageSearchResult#
alias of
LocalQDMCageSearchResult
- class qlinks.caging.local_search.LocalCageSearcher(model, region, config=<factory>, adapter=None)[source]#
Bases:
objectLocal-first type-1 cage searcher over a model adapter.
The searcher owns only the generic caging algebra: build a local kinetic graph, find bipartite/uniform-self-loop type-1 candidates, and solve the fixed-kappa cage problem. The adapter owns all model/lattice details such as local variable ids, constraints, local kinetic moves, and padding.
- region: LocalQDMRegion#
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None = None#
- classmethod from_plaquettes(model, plaquette_ids, *, config=None, scoring_plaquette_ids=None, adapter=None)[source]#
Construct a local searcher from seed plaquettes/local kinetic terms.
- classmethod from_links(model, link_ids, *, config=None, active_plaquette_ids=None, scoring_plaquette_ids=None, adapter=None)[source]#
Construct a local searcher from explicit local variable ids.
- classmethod full_model_region(model, *, config=None, adapter=None)[source]#
Construct a local searcher whose region is the full model.
This is mostly useful as a regression bridge: the implementation path is still local-first/no-full-Hamiltonian, but the local region happens to contain every variable and local kinetic term.
- __init__(model, region, config=<factory>, adapter=None)#
- class qlinks.caging.local_search.LocalQDMCageBlock(block_id, record, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts)[source]#
Bases:
objectA placed local QDM cage usable as one independent padding block.
- record: LocalQDMCageRecord#
- __init__(block_id, record, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts)#
- class qlinks.caging.local_search.LocalQDMCageRecord(cage_state, signature, candidate, support_configs, local_link_ids, active_plaquette_ids, scoring_plaquette_ids, unresolved_boundary_plaquette_ids)[source]#
Bases:
objectOne local cage certificate.
- candidate: CandidateSubgraph#
- __init__(cage_state, signature, candidate, support_configs, local_link_ids, active_plaquette_ids, scoring_plaquette_ids, unresolved_boundary_plaquette_ids)#
- class qlinks.caging.local_search.LocalQDMCageSearchConfig(tolerance=1e-10, allowed_kappas=(0,), min_component_size=2, halo_layers=1, boundary_mode='relaxed', include_sectors_when_full=True, prune_inactive_local_basis_states=False, max_local_states=None, sort_basis=True, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0)[source]#
Bases:
objectConfiguration for the QDM local-first type-1 cage search.
- allowed_kappas#
Kinetic eigenvalues to target. The local-first path is intended for type-1 cages, so the default is
(0,).
- halo_layers#
Number of plaquette-neighbor expansions applied when the search region is supplied by plaquettes. Neighbors share at least one link.
- Type:
- boundary_mode#
"relaxed"enforces exact dimer constraints only at internally complete sites; boundary sites use an at-most constraint."closed"requires all touched sites to be complete and then enforces exact constraints.- Type:
Literal[‘relaxed’, ‘closed’]
- include_sectors_when_full#
If the local link set is the full model link set, also apply model sector conditions during local basis generation.
- Type:
- prune_inactive_local_basis_states#
For genuine local regions, ask DFS to prune branches that can no longer produce a configuration flippable on any active plaquette.
- Type:
- validate_full_residual#
Whether local cage states should be validated against the full local kinetic graph columns.
- Type:
- degenerate_basis_strategy#
How to choose representatives from degenerate local cage subspaces.
- Type:
Literal[‘none’, ‘ipr’]
- __init__(tolerance=1e-10, allowed_kappas=(0,), min_component_size=2, halo_layers=1, boundary_mode='relaxed', include_sectors_when_full=True, prune_inactive_local_basis_states=False, max_local_states=None, sort_basis=True, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0)#
- class qlinks.caging.local_search.LocalQDMCageSearchResult(records, region, local_basis, kinetic_matrix, self_loop_values, config, model=None, adapter=None, type1_candidates=<factory>)[source]#
Bases:
objectPassive result contract for a local QDM cage search.
- records: list[LocalQDMCageRecord]#
- region: LocalQDMRegion#
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None = None#
- type1_candidates: list[CandidateSubgraph]#
- __init__(records, region, local_basis, kinetic_matrix, self_loop_values, config, model=None, adapter=None, type1_candidates=<factory>)#
- class qlinks.caging.local_search.LocalQDMCageSearcher(model, region, config=<factory>, adapter=None)[source]#
Bases:
LocalCageSearcherBackward-compatible QDM name for
LocalCageSearcher.New code should prefer
LocalCageSearcher. The old name remains as a thin subclass so existing notebooks/tests keep working while the core solver is routed through the model-adapter interface.
- class qlinks.caging.local_search.LocalQDMCertificationReport(local_record_index, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)[source]#
Bases:
objectNumerical certificate for one padded local QDM cage.
- padding: LocalQDMPadding#
- __init__(local_record_index, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)#
- class qlinks.caging.local_search.LocalQDMMultiPaddingConfig(min_blocks=2, max_blocks=None, max_paddings=1, max_padding_attempts=None, max_paddings_per_packing=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, max_product_support_size=512, require_kinetic_separation=True, sort_limited_basis=True, store_full_states=True)[source]#
Bases:
objectConfiguration for Lego-style multi-block QDM padding.
The multi-block path chooses compatible, disjoint local cage blocks from a pool, solves one shared static exterior for the union of their fixed boundary charges, and then certifies the resulting product state by applying all global QDM flips. Every selected block must have support-independent site counts; otherwise an independent tensor-product block cannot be padded by one shared exterior configuration.
- as_single_padding_config()[source]#
Return the shared options in the single-block padding config form.
- __init__(min_blocks=2, max_blocks=None, max_paddings=1, max_padding_attempts=None, max_paddings_per_packing=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, max_product_support_size=512, require_kinetic_separation=True, sort_limited_basis=True, store_full_states=True)#
- class qlinks.caging.local_search.LocalQDMPadding(exterior_link_ids, exterior_config, global_support_configs)[source]#
Bases:
objectOne shared-exterior padding of a local QDM cage record.
- __init__(exterior_link_ids, exterior_config, global_support_configs)#
- class qlinks.caging.local_search.LocalQDMPaddingConfig(max_paddings_per_record=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, sort_limited_basis=True, store_full_states=True)[source]#
Bases:
objectConfiguration for global padding/certification of local QDM cages.
The first certification backend is intentionally conservative: it searches for a single shared exterior product configuration that can be tensored with every local support configuration of the cage state. It then verifies the resulting global state by applying all QDM plaquette flips reachable in one kinetic step from the support, keyed by configurations rather than by a globally enumerated Hilbert space.
- __init__(max_paddings_per_record=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, sort_limited_basis=True, store_full_states=True)#
- class qlinks.caging.local_search.LocalQDMRegion(link_ids, seed_plaquette_ids, active_plaquette_ids, scoring_plaquette_ids, closed_site_ids, boundary_site_ids, unresolved_boundary_plaquette_ids)[source]#
Bases:
objectA real-space region used by
LocalQDMCageSearcher.- __init__(link_ids, seed_plaquette_ids, active_plaquette_ids, scoring_plaquette_ids, closed_site_ids, boundary_site_ids, unresolved_boundary_plaquette_ids)#
- class qlinks.caging.local_search.LocalRegionProposal(*args, **kwargs)[source]#
Bases:
ProtocolProtocol for objects that propose local regions to the local cage searcher.
- __init__(*args, **kwargs)#
- class qlinks.caging.local_search.LocalRegionProposalSearchRecord(proposal_index, region_index, region, result, proposal_record=None)[source]#
Bases:
objectResult for one local region emitted by a proposal.
- region: LocalQDMRegion#
- result: LocalQDMCageSearchResult#
- property records: list[LocalQDMCageRecord]#
- __init__(proposal_index, region_index, region, result, proposal_record=None)#
- class qlinks.caging.local_search.LocalRegionProposalSearchResult(records)[source]#
Bases:
objectPassive result container for proposal-driven local cage scans.
- records: list[LocalRegionProposalSearchRecord]#
- property local_results: list[LocalQDMCageSearchResult]#
- property cage_records: list[LocalQDMCageRecord]#
- property nonempty_records: list[LocalRegionProposalSearchRecord]#
- __init__(records)#
- class qlinks.caging.local_search.MultiLocalQDMCertificationReport(block_ids, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)[source]#
Bases:
objectNumerical certificate for one multi-block QDM padding.
- padding: MultiLocalQDMPadding#
- __init__(block_ids, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)#
- class qlinks.caging.local_search.MultiLocalQDMPadding(block_ids, exterior_link_ids, exterior_config, global_support_configs, global_amplitudes, block_support_indices)[source]#
Bases:
objectOne shared-exterior padding for a product of several local QDM blocks.
- __init__(block_ids, exterior_link_ids, exterior_config, global_support_configs, global_amplitudes, block_support_indices)#
- class qlinks.caging.local_search.QDMFactorizedProductCertificationReport(block_ids, padding, support_size, kinetic_eigenvalue, self_loop_value, energy, kinetic_residual, potential_residual, hamiltonian_residual, signature, n_kinetic_product_terms, n_potential_product_terms, max_blocks_touched_by_plaquette, sector_validation, failure_reason=None)[source]#
Bases:
objectPolynomial-cost certificate for a separated product of QDM cage blocks.
- padding: FactorizedLocalQDMPadding#
- __init__(block_ids, padding, support_size, kinetic_eigenvalue, self_loop_value, energy, kinetic_residual, potential_residual, hamiltonian_residual, signature, n_kinetic_product_terms, n_potential_product_terms, max_blocks_touched_by_plaquette, sector_validation, failure_reason=None)#
- class qlinks.caging.local_search.QDMLocalCageAdapter(model, source_label='qdm')[source]#
Bases:
objectQDM implementation of the local variable interface.
This is intentionally the only place where the generic local searcher needs to know how QDM variables/plaquette flips are represented. Later QLM/PXP adapters can implement the same protocol without modifying the solver core.
- build_region_from_links(*, link_ids, config, active_plaquette_ids=None, scoring_plaquette_ids=None)[source]#
- __init__(model, source_label='qdm')#
- class qlinks.caging.local_search.QDMMultiPaddingDiagnostics(paddings, reports, failures, config, padding_attempts=None, first_certified_padding_index=None)[source]#
Bases:
objectCertification diagnostics for a pool of multi-block padding candidates.
- paddings: list[MultiLocalQDMPadding]#
- reports: list[MultiLocalQDMCertificationReport]#
- failures: list[QDMMultiPaddingFailureReport]#
- config: LocalQDMMultiPaddingConfig#
- property leakage_failure_counts_by_class: dict[str, int]#
Count leakage failures by their dominant plaquette class.
- property leakage_failure_norms_by_class: dict[str, float]#
Sum leakage norms by plaquette class over all leakage failures.
- __init__(paddings, reports, failures, config, padding_attempts=None, first_certified_padding_index=None)#
- class qlinks.caging.local_search.QDMMultiPaddingFailureReport(block_ids, padding_index, reason, padding, leakage_residual=None, support_kinetic_residual=None, support_hamiltonian_residual=None, full_residual=None, leakage_counts_by_class=<factory>, leakage_norms_by_class=<factory>)[source]#
Bases:
objectReason one candidate multi-block padding failed certification.
- padding: MultiLocalQDMPadding#
- property dominant_leakage_class: str | None#
Return the plaquette class with the largest leakage norm, if known.
- __init__(block_ids, padding_index, reason, padding, leakage_residual=None, support_kinetic_residual=None, support_hamiltonian_residual=None, full_residual=None, leakage_counts_by_class=<factory>, leakage_norms_by_class=<factory>)#
- class qlinks.caging.local_search.RobustQDMLocalCageSearchConfig(local_config=<factory>, region_strategies=('stripe', 'snake_stripe', 'connected', 'adaptive'), max_region_plaquettes=6, min_region_plaquettes=1, max_region_links=None, max_regions_per_strategy=128, stripe_motif_sizes=(2, 3), stripe_motif_sources=('stripe', 'snake_stripe'), stripe_motif_subset_mode='all', stripe_motif_max_motifs_per_stripe=None, stripe_motif_component_sizes=None, stripe_motif_component_subset_mode='full', stripe_motif_component_min_seed_motifs=1, stripe_motif_component_max_seed_motifs_per_stripe=None, stripe_motif_component_max_components_per_stripe=1, stripe_motif_component_motif_signatures=None, stripe_widths=(1, 2), stripe_directions=None, snake_stripe_max_turns=None, snake_stripe_allow_kind_changes=False, snake_stripe_kind_pattern='constant_or_alternating', snake_stripe_require_induced_cycle=False, snake_stripe_plaquette_kinds=None, snake_stripe_winding_vectors=None, adaptive_beam_width=8, adaptive_branch_factor=8, adaptive_seed_plaquette_ids=None, adaptive_use_search_feedback=False, block_signatures=None, max_records_per_region=2, max_blocks=4, min_blocks=1, max_product_support_size=2048, max_paddings_per_stage=64, max_padding_attempts_per_stage=None, max_paddings_per_packing=4, max_dfs_nodes=None, include_sectors=True, padding_stages=('loose', 'static', 'strict'), tolerance=1e-09, sort_limited_basis=True, store_full_states=True, skip_incompatible_blocks=True)[source]#
Bases:
objectBudget-oriented configuration for robust local QDM cage discovery.
This config intentionally exposes budgets and strategy choices rather than delicate geometry assumptions.
robust_qdm_local_cage_searchuses a portfolio of region proposals, collects compatible local-cage blocks, then runs a schedule of permissive-to-strict multi-block padding configurations and lets global certification decide which candidates survive.- local_config: LocalQDMCageSearchConfig#
- __init__(local_config=<factory>, region_strategies=('stripe', 'snake_stripe', 'connected', 'adaptive'), max_region_plaquettes=6, min_region_plaquettes=1, max_region_links=None, max_regions_per_strategy=128, stripe_motif_sizes=(2, 3), stripe_motif_sources=('stripe', 'snake_stripe'), stripe_motif_subset_mode='all', stripe_motif_max_motifs_per_stripe=None, stripe_motif_component_sizes=None, stripe_motif_component_subset_mode='full', stripe_motif_component_min_seed_motifs=1, stripe_motif_component_max_seed_motifs_per_stripe=None, stripe_motif_component_max_components_per_stripe=1, stripe_motif_component_motif_signatures=None, stripe_widths=(1, 2), stripe_directions=None, snake_stripe_max_turns=None, snake_stripe_allow_kind_changes=False, snake_stripe_kind_pattern='constant_or_alternating', snake_stripe_require_induced_cycle=False, snake_stripe_plaquette_kinds=None, snake_stripe_winding_vectors=None, adaptive_beam_width=8, adaptive_branch_factor=8, adaptive_seed_plaquette_ids=None, adaptive_use_search_feedback=False, block_signatures=None, max_records_per_region=2, max_blocks=4, min_blocks=1, max_product_support_size=2048, max_paddings_per_stage=64, max_padding_attempts_per_stage=None, max_paddings_per_packing=4, max_dfs_nodes=None, include_sectors=True, padding_stages=('loose', 'static', 'strict'), tolerance=1e-09, sort_limited_basis=True, store_full_states=True, skip_incompatible_blocks=True)#
- class qlinks.caging.local_search.RobustQDMLocalCageSearchContext(config, scan, blocks, padding_config, diagnostics_by_stage)[source]#
Bases:
objectDebug context for
robust_qdm_local_cage_search().The ordinary robust search returns a
CertifiedLocalQDMCageSearchResultso downstream tools can consume it directly. Whenreturn_context=True, this companion object exposes the intermediate proposal scan, block pool, and per-padding-stage diagnostics that explain where candidates were found or rejected.- config: RobustQDMLocalCageSearchConfig#
- blocks: list[LocalQDMCageBlock]#
- padding_config: LocalQDMMultiPaddingConfig#
- diagnostics_by_stage: dict[str, QDMMultiPaddingDiagnostics]#
- property reports_by_stage: dict[str, list[MultiLocalQDMCertificationReport]]#
- property reports: list[MultiLocalQDMCertificationReport]#
- __init__(config, scan, blocks, padding_config, diagnostics_by_stage)#
- class qlinks.caging.local_search.SnakeStripeRegionProposal(model, max_plaquettes, config=<factory>, min_plaquettes=3, seed_plaquette_ids=None, max_records=None, max_links=None, max_turns=None, plaquette_kinds=None, allow_kind_changes=False, kind_pattern='constant_or_alternating', require_induced_cycle=False, winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate width-one noncontractible snake stripes on the plaquette graph.
A snake stripe is a simple cycle of plaquettes, adjacent by shared links, whose lifted anchor-cell displacement winds around a periodic lattice. This proposal does not assume the stripe is straight in anchor coordinates; it is therefore a better first pass for honeycomb and triangular QDM where useful width-one stripes can turn while wrapping the torus.
Optional
require_induced_cycleandkind_patternfilters turn the broad cycle enumerator into a more motif-like proposal: the examples seen in exact QDM cages are usually chordless width-one cycles whose plaquette kinds are either constant or strictly alternating between two kinds.The enumeration is intentionally budgeted by
max_plaquettes,max_links,max_turns, andmax_records.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, min_plaquettes=3, seed_plaquette_ids=None, max_records=None, max_links=None, max_turns=None, plaquette_kinds=None, allow_kind_changes=False, kind_pattern='constant_or_alternating', require_induced_cycle=False, winding_vectors=None, adapter=None)#
- class qlinks.caging.local_search.SnakeStripeRegionProposalRecord(region, plaquette_ids, seed_plaquette_id, winding, length, turn_count, plaquette_kinds)[source]#
Bases:
objectOne width-one noncontractible snake-stripe region proposal.
Unlike
StripeRegionProposalRecord, this record is generated from simple noncontractible cycles on the plaquette shared-link graph. It is useful on lattices where natural stripe cages wrap around the torus but do not follow a straight anchor-coordinate line.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_id, winding, length, turn_count, plaquette_kinds)#
- class qlinks.caging.local_search.StripeMotifComponentRegionProposal(model, config=<factory>, motif_sizes=(2, 3), motif_subset_mode='windows', motif_signatures=None, min_seed_motifs=1, max_seed_motifs_per_stripe=None, component_sizes=None, component_subset_mode='full', sources=('snake_stripe', ), max_components_per_stripe=1, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate merged stripe components seeded by small coherent motifs.
The proposal first cuts small motifs from each straight/snake stripe skeleton and runs the existing local cage searcher on those tiny motifs. If enough motifs have local cage records, it emits a larger component region, by default the whole stripe skeleton. This is intended for triangular and honeycomb QDM cages where the exact state is a stripe-local object rather than a product of independent two-plaquette blocks.
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- __init__(model, config=<factory>, motif_sizes=(2, 3), motif_subset_mode='windows', motif_signatures=None, min_seed_motifs=1, max_seed_motifs_per_stripe=None, component_sizes=None, component_subset_mode='full', sources=('snake_stripe', ), max_components_per_stripe=1, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)#
- class qlinks.caging.local_search.StripeMotifComponentRegionProposalRecord(region, plaquette_ids, source, source_index, source_plaquette_ids, component_size, component_index, n_seed_motifs, seed_motif_plaquette_ids, seed_motif_signatures)[source]#
Bases:
objectOne merged stripe component selected by small local motif probes.
The record represents the second-stage fast path: small two-/three-plaquette motifs are used only as cheap evidence that a stripe skeleton is promising; the emitted region is a larger component, usually the whole stripe/snake, so coherent units inside the stripe can cancel jointly instead of being forced into independent product blocks.
- region: LocalQDMRegion#
- __init__(region, plaquette_ids, source, source_index, source_plaquette_ids, component_size, component_index, n_seed_motifs, seed_motif_plaquette_ids, seed_motif_signatures)#
- class qlinks.caging.local_search.StripeMotifRegionProposal(model, config=<factory>, motif_sizes=(2, 3), sources=('stripe', 'snake_stripe'), subset_mode='all', max_motifs_per_stripe=None, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate small QDM motif regions cut from stripe-like plaquette paths.
This is a fast path for QDM cages whose real-space organization is a width-one stripe but whose coherent local objects are only small two- or three-plaquette singlet/triplet motifs. It first constructs cheap straight and/or snake stripe skeletons, then emits small motif subsets from each skeleton. The ordinary local cage algebra is still used afterward, but on much smaller regions than a full stripe.
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, config=<factory>, motif_sizes=(2, 3), sources=('stripe', 'snake_stripe'), subset_mode='all', max_motifs_per_stripe=None, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)#
- class qlinks.caging.local_search.StripeMotifRegionProposalRecord(region, plaquette_ids, source, source_index, source_plaquette_ids, motif_size, motif_index)[source]#
Bases:
objectOne small stripe-motif local-region proposal.
The proposal is meant to capture the QDM pattern seen in exact cages: a width-one stripe supplies the global organizing structure, but the coherent local object is often only a two- or three-plaquette motif on that stripe.
sourcerecords whether the motif was cut from a straight stripe or from a snake-stripe cycle.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, source, source_index, source_plaquette_ids, motif_size, motif_index)#
- class qlinks.caging.local_search.StripeRegionProposal(model, config=<factory>, directions=None, width=1, plaquette_kinds=None, adapter=None)[source]#
Bases:
objectGenerate QDM stripe/band local regions from plaquette anchor coordinates.
A stripe is selected on the plaquette-anchor lattice. For
direction=0on a square torus, the proposal keeps all plaquettes along the x direction at fixed y; fordirection=1it keeps all plaquettes along y at fixed x.widththickens the stripe in the transverse coordinate.The default search config uses
halo_layers=0because the stripe itself is meant to be the active region. Passing a config withhalo_layers > 0intentionally asks for the old shared-link halo around each stripe.- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, config=<factory>, directions=None, width=1, plaquette_kinds=None, adapter=None)#
- class qlinks.caging.local_search.StripeRegionProposalRecord(region, plaquette_ids, direction, transverse_origin, width, plaquette_kind)[source]#
Bases:
objectOne plaquette-stripe local-region proposal.
directionis the anchor-coordinate axis along which the stripe runs.transverse_originlabels the first transverse coordinate included in the band. For periodic lattices andwidth > 1, the band is thickened by wrapping forward from this origin.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, direction, transverse_origin, width, plaquette_kind)#
- qlinks.caging.local_search.build_qdm_global_limited_kinetic_matrix(model, basis)[source]#
Build QDM kinetic transitions restricted to an explicitly supplied basis.
- qlinks.caging.local_search.build_qdm_local_kinetic_matrix(model, region, local_basis)[source]#
Build the local kinetic matrix without using a global basis/Hamiltonian.
- qlinks.caging.local_search.build_qdm_local_region_from_links(model, *, link_ids, boundary_mode, active_plaquette_ids=None, scoring_plaquette_ids=None, seed_plaquette_ids=None)[source]#
Build a local QDM region from explicit link ids.
- qlinks.caging.local_search.build_qdm_local_region_from_plaquettes(model, *, plaquette_ids, halo_layers, boundary_mode, scoring_plaquette_ids=None)[source]#
Build a local QDM region by expanding seed plaquettes by shared-link halo.
- qlinks.caging.local_search.certified_qdm_result_from_multi_block_reports(model, reports, *, config=None)[source]#
Wrap multi-block QDM certificates as a limited-basis cage result.
The returned object uses the same
CertifiedLocalQDMCageSearchResultcontainer as the single-block local-padding path. Its basis is the limited union of certified support configurations and their one-hop kinetic shell, so downstream classification and visualization tools can consume it without enumerating the full global Hilbert space.
- qlinks.caging.local_search.certify_qdm_factorized_product_state(model, blocks, padding, *, config=None)[source]#
Certify a separated product cage without forming its global support.
The Hamiltonian action is represented as a sum of tensor-product vectors. Norms and expectation values are evaluated by factor contractions. The cost is polynomial in the number of blocks and plaquettes and exponential only in the largest single-block support, rather than in the product of all block support sizes.
Exact factorization currently requires every plaquette to touch at most one selected block. This is precisely the kinetic-separation condition used by the strict multi-padding workflow.
- qlinks.caging.local_search.certify_qdm_local_record(model, local_record, *, local_record_index=0, config=None)[source]#
Return certified shared-exterior paddings for one local QDM record.
- qlinks.caging.local_search.certify_qdm_local_result(model, local_result, *, config=None)[source]#
Pad and certify all local QDM records without a full basis/Hamiltonian.
The certification uses a limited global basis made from the union of each certified support and its one-hop kinetic shell. It returns ordinary
CageRecordobjects inside aCageSearchResultso downstream code that only depends on the cage-result protocol can consume the output.
- qlinks.caging.local_search.certify_qdm_multi_block_padding(model, blocks, padding, *, padding_index=0, config=None)[source]#
Certify one multi-block QDM padding by explicit global one-hop action.
- qlinks.caging.local_search.certify_qdm_multi_block_paddings(model, block_pool, *, config=None)[source]#
Find and certify Lego-style multi-block QDM paddings from a block pool.
Candidate padding generation is interleaved with certification. The search stops after
config.max_paddingscertified reports or afterconfig.max_padding_attemptsraw padding attempts. Ifmax_padding_attemptsisNone, there is no separate raw-attempt cap.
- qlinks.caging.local_search.certify_qdm_multi_block_result(model, blocks, *, config=None)[source]#
Find/certify multi-block QDM paddings and return a certified result.
This is the multi-block analogue of
certify_qdm_local_result: it keeps the basis limited to the certified product support plus one-hop shell, but exposes ordinaryCageRecordentries for existing tools.
- qlinks.caging.local_search.collect_qdm_cage_blocks_from_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)#
Run proposal searches and return a QDM block pool for multi-padding.
- qlinks.caging.local_search.collect_qdm_cage_blocks_from_region_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)[source]#
Run proposal searches and return a QDM block pool for multi-padding.
- qlinks.caging.local_search.collect_qdm_cage_blocks_with_scan_from_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)#
Run proposal searches and stream compatible QDM blocks.
This is the block-oriented counterpart of
run_local_region_proposals(). It converts records intoLocalQDMCageBlockobjects immediately after each region is searched and stops as soon asmax_blocksis reached. This is important for expensive proposal portfolios: the older two-stage workflow searched every proposed region first and only then applied the block cap, so robust scans could spend most of their time in local DFS branches that would never contribute to the requested block pool.
- qlinks.caging.local_search.collect_qdm_cage_blocks_with_scan_from_region_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)[source]#
Run proposal searches and stream compatible QDM blocks.
This is the block-oriented counterpart of
run_local_region_proposals(). It converts records intoLocalQDMCageBlockobjects immediately after each region is searched and stops as soon asmax_blocksis reached. This is important for expensive proposal portfolios: the older two-stage workflow searched every proposed region first and only then applied the block cap, so robust scans could spend most of their time in local DFS branches that would never contribute to the requested block pool.
- qlinks.caging.local_search.diagnose_qdm_multi_block_paddings(model, block_pool, *, config=None)[source]#
Find multi-block paddings and report both successes and failures.
This diagnostic path uses the same interleaved padding/certification loop as
certify_qdm_multi_block_paddings().paddingsstores the raw candidates actually attempted, whilen_padding_attemptsrecords that count explicitly for notebook/debug summaries.
- qlinks.caging.local_search.enumerate_qdm_local_basis(model, region, *, include_sectors_when_full, prune_inactive_states=False, max_states=None, sort=True)[source]#
Enumerate local dimer configurations on
region.link_ids.The local-search layer deliberately reuses
DFSBasisSolverrather than maintaining a separate DFS. QDM-specific local rules are represented as lightweight constraints on the local binary-link layout, so future DFS optimizations immediately benefit both full-basis enumeration and local cage searches.
- qlinks.caging.local_search.factorized_qdm_padding_from_multi_padding(padding)[source]#
Drop the materialized Cartesian-product support from an old padding.
- qlinks.caging.local_search.find_factorized_qdm_block_paddings(model, block_pool, *, config=None)[source]#
Materialize a bounded list of factorized QDM exterior assignments.
- qlinks.caging.local_search.find_multi_qdm_block_paddings(model, block_pool, *, config=None)[source]#
Find shared-exterior paddings built from a pool of local QDM blocks.
This materialized API keeps the original raw-padding semantics:
config.max_paddingsis the maximum number of candidate paddings returned. Certification helpers useiter_multi_qdm_block_paddings()directly so they can keep trying candidates until enough certified cages are found.
- qlinks.caging.local_search.find_qdm_multi_block_paddings(model, block_pool, *, config=None)#
Find shared-exterior paddings built from a pool of local QDM blocks.
This materialized API keeps the original raw-padding semantics:
config.max_paddingsis the maximum number of candidate paddings returned. Certification helpers useiter_multi_qdm_block_paddings()directly so they can keep trying candidates until enough certified cages are found.
Find shared exterior configurations compatible with a local QDM cage.
A shared exterior is a single assignment on all nonlocal links such that every local support configuration becomes a full valid dimer covering. This is the simplest product padding that preserves the local superposition.
- qlinks.caging.local_search.iter_factorized_qdm_block_paddings(model, block_pool, *, config=None, max_yielded=None)[source]#
Yield exterior assignments without materializing block support products.
This mirrors
iter_multi_qdm_block_paddings(), but the returned object contains only the block ids and shared exterior configuration. The search therefore remains usable whenprod(block.support_size)is too large to enumerate.max_product_support_sizeis intentionally not applied on this path because the Cartesian-product support is never materialized.
- qlinks.caging.local_search.iter_multi_qdm_block_paddings(model, block_pool, *, config=None, max_yielded=None)[source]#
Yield shared-exterior paddings built from a pool of QDM blocks.
This is the streaming counterpart of
find_multi_qdm_block_paddings(). It is intended for certification-in-the-loop workflows, where a caller may want to keep trying raw exterior completions until enough certified cages are found.max_yieldedlimits the number of raw candidate paddings yielded by this iterator; if omitted,config.max_padding_attemptsis used.
- qlinks.caging.local_search.local_cage_adapter_for_model(model, adapter=None)[source]#
Return a local-search adapter for
model.Passing
adapteris the explicit, model-generic path. Without an explicit adapter, the registered factories are tried in order.
- qlinks.caging.local_search.make_qdm_cage_block(model, local_record, *, block_id=0, guard_plaquette_ids=None)[source]#
Create a constant-boundary Lego block from a local QDM cage record.
Independent product padding requires the number of dimers contributed by the block at every global site to be independent of the local support configuration. If this fails, one shared exterior cannot tensor with the entire block support, so this function raises
ValueError.
- qlinks.caging.local_search.qdm_global_self_loop_values(model, configs)[source]#
Compute full QDM potential/self-loop values for explicit configs.
- qlinks.caging.local_search.qdm_local_self_loop_values(model, region, local_basis)[source]#
Return local potential/self-loop values on the scoring plaquettes.
- qlinks.caging.local_search.qdm_multi_padding_config_schedule(config=None, *, stages=('loose', 'static', 'strict'))[source]#
Return a permissive-to-strict schedule of multi-padding configs.
- qlinks.caging.local_search.register_local_cage_adapter_factory(factory, *, prepend=False)[source]#
Register a factory that can adapt models for
LocalCageSearcher.Factories receive a model and return either a
LocalCageModelAdapterorNonewhen they do not support that model. The built-in QDM factory is registered by default; future model families can register their adapters without branching inside the solver core.
- qlinks.caging.local_search.robust_certify_qdm_multi_block_result(model, blocks, *, config=None, stages=('loose', 'static', 'strict'))[source]#
Certify a block pool with a multi-stage padding schedule.
The early stages are deliberately permissive; exact global certification is still the only acceptance criterion. Duplicate certified supports found at multiple stages are deduplicated before wrapping into a limited-basis result.
- qlinks.caging.local_search.robust_local_qdm_cage_search(model, *, config=None, adapter=None, return_context=False)#
Run a budgeted robust local QDM cage search.
The search builds a portfolio of region proposals, converts successful local records into independent Lego blocks, then certifies the block pool with a permissive-to-strict padding schedule. By default, the return value is the existing
CertifiedLocalQDMCageSearchResultcontainer used by downstream tools. Passreturn_context=Trueto also receive the intermediate scan, block pool, and per-stage diagnostics for debugging.
- qlinks.caging.local_search.robust_qdm_local_cage_search(model, *, config=None, adapter=None, return_context=False)[source]#
Run a budgeted robust local QDM cage search.
The search builds a portfolio of region proposals, converts successful local records into independent Lego blocks, then certifies the block pool with a permissive-to-strict padding schedule. By default, the return value is the existing
CertifiedLocalQDMCageSearchResultcontainer used by downstream tools. Passreturn_context=Trueto also receive the intermediate scan, block pool, and per-stage diagnostics for debugging.
- qlinks.caging.local_search.run_local_region_proposal(proposal, *, model=None, config=None, adapter=None, max_regions=None)[source]#
Run the local cage searcher over every region emitted by one proposal.
- qlinks.caging.local_search.run_local_region_proposals(proposals, *, model=None, config=None, adapter=None, max_regions=None)[source]#
Run local cage searches over a stream of proposal-generated regions.
The helper is intentionally lightweight: proposal objects only need to provide
iter_regions(). If they provide richeriter_records()records with aregionattribute, that metadata is retained in the scan result.StripeRegionProposalfollows this richer path.
qlinks.caging.thermodynamic module#
- class qlinks.caging.thermodynamic.LocalWitnessTemplate(pattern_key, local_patterns, local_operator, source_zero_indices=(), mechanism_labels=(), metadata=<factory>)[source]#
Bases:
objectSize-independent local row operator reconstructed from a reduced-IZ pattern.
The template stores only local configurations and matrix elements. It does not store global variable indices, so the same object can be embedded in several system sizes or translated to several locations.
- mechanism_labels: tuple[Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage'], ...]#
- normalized(normalization='operator_norm')[source]#
Return a canonically normalized copy of the local row operator.
operator_normis the preferred ETH convention because it fixes||Q_R|| = ||L_R||^2 = 1. Thermal expectations are then directly comparable between witnesses and system sizes.
- __init__(pattern_key, local_patterns, local_operator, source_zero_indices=(), mechanism_labels=(), metadata=<factory>)#
- qlinks.caging.thermodynamic.directed_transition_witness_template(*, target_pattern, source_patterns, amplitudes, pattern_key=(), source_zero_indices=(), mechanism_labels=(), metadata=None, normalization='none')[source]#
Construct a directed local transition map from sources into one target.
The returned local operator has the rank-one form
A_R = |target><v|,|v> = sum_j amplitudes[j]^* |source_j>.The target pattern is stored first, followed by the source patterns. This helper is model independent and is useful when a boundary-row cancellation is retained as a one-sided local channel rather than Hermitianized into an IZ operator.
- qlinks.caging.thermodynamic.hermitianize_local_witness_template(template, *, normalization='none', metadata=None)[source]#
Return the Hermitian symmetrization
L_R + L_R^dagger.The local patterns, source rows, and mechanism labels are preserved. This makes it straightforward to compare a directed transfer witness with the corresponding Hermitian IZ witness using exactly the same local embedding.
- class qlinks.caging.thermodynamic.LocalWitness(template, variable_indices)[source]#
Bases:
objectOne embedding of a size-independent local witness template.
- template: LocalWitnessTemplate#
- __init__(template, variable_indices)#
- class qlinks.caging.thermodynamic.LocalChannelSpectrumReport(channel_shape, operator_norm, q_eigenvalues, rank, nullity, dark_channel_gap, tolerance)[source]#
Bases:
objectPositive spectrum and conditioning gap of one local channel.
- __init__(channel_shape, operator_norm, q_eigenvalues, rank, nullity, dark_channel_gap, tolerance)#
- qlinks.caging.thermodynamic.diagnose_local_channel_spectrum(channel, *, normalize_operator=False, tolerance=1e-10)[source]#
Diagnose
Q_R=A_R^dagger A_Rand its smallest positive eigenvalue.dark_channel_gapis the quantity denotedDelta_Qin the predictive deformation criterion. It is a conditioning scale for the local dark subspace, not by itself an exact-protection criterion.
- class qlinks.caging.thermodynamic.ThermalActivityMarginReport(parameters, activities, secant_slopes, reference_parameter, reference_activity, minimum_activity, susceptibility_bound, half_activity_radius, tolerance)[source]#
Bases:
objectFinite-difference estimate of a local witness’s thermal margin.
- __init__(parameters, activities, secant_slopes, reference_parameter, reference_activity, minimum_activity, susceptibility_bound, half_activity_radius, tolerance)#
- qlinks.caging.thermodynamic.thermal_activity_margin_from_samples(parameters, activities, *, reference_parameter=0.0, tolerance=1e-10)[source]#
Estimate
tau_Q,chi_Q, and the half-activity radius on a path.The susceptibility is conservatively taken as the largest absolute secant slope between neighboring sampled points. The returned radius implements the draft bound
tau_0/(2 chi_Q). It is an empirical finite-size bound over the sampled neighborhood, not a proof of differentiability or a thermodynamic uniform bound.
- class qlinks.caging.thermodynamic.LocalWitnessEvaluation(expectation, second_moment, variance, annihilation_residual, normalized_expectation, n_states, effective_state_count, per_state_expectations=(), metadata=<factory>)[source]#
Bases:
objectExpectation and variance of
Q_R = L_R^dagger L_R.- __init__(expectation, second_moment, variance, annihilation_residual, normalized_expectation, n_states, effective_state_count, per_state_expectations=(), metadata=<factory>)#
- class qlinks.caging.thermodynamic.MicrocanonicalWitnessEvaluation(evaluation, shell_indices, energy_center, half_width, shell_energy_min, shell_energy_max, mean_energy, mean_energy_density)[source]#
Bases:
objectLocal-witness evaluation in a finite-size microcanonical shell.
- evaluation: LocalWitnessEvaluation#
- __init__(evaluation, shell_indices, energy_center, half_width, shell_energy_min, shell_energy_max, mean_energy, mean_energy_density)#
- class qlinks.caging.thermodynamic.LocalWitnessEmbeddingRecord(system_label, witnesses)[source]#
Bases:
objectAll exact embeddings of one template in one finite system.
- witnesses: tuple[LocalWitness, ...]#
- __init__(system_label, witnesses)#
- class qlinks.caging.thermodynamic.LocalWitnessFamily(template, embeddings)[source]#
Bases:
objectOne reduced-IZ local pattern found in several finite systems.
- template: LocalWitnessTemplate#
- embeddings: tuple[LocalWitnessEmbeddingRecord, ...]#
- __init__(template, embeddings)#
- class qlinks.caging.thermodynamic.ETHScalingPoint(system_size, cage, thermal, energy=None, energy_density=None, system_label=None, metadata=<factory>)[source]#
Bases:
objectOne finite-size comparison between a cage state and a thermal ensemble.
- cage: LocalWitnessEvaluation#
- thermal: LocalWitnessEvaluation#
- __init__(system_size, cage, thermal, energy=None, energy_density=None, system_label=None, metadata=<factory>)#
- class qlinks.caging.thermodynamic.InverseSizeFit(order, coefficients, thermodynamic_limit, root_mean_square_residual, system_sizes, observed_values, fitted_values)[source]#
Bases:
objectDescriptive fit
y(N) = c_0 + c_1/N + ....- __init__(order, coefficients, thermodynamic_limit, root_mean_square_residual, system_sizes, observed_values, fitted_values)#
- class qlinks.caging.thermodynamic.ETHScalingReport(template, points)[source]#
Bases:
objectFinite-size scaling data for one fixed local witness template.
- template: LocalWitnessTemplate#
- points: tuple[ETHScalingPoint, ...]#
- tail_liminf_lower_bound(*, tail_points=2)[source]#
Return the minimum absolute gap among the largest available sizes.
This is a finite-data lower bound, not a proof of the mathematical liminf. Its explicit name is intended to prevent overinterpretation.
- __init__(template, points)#
- class qlinks.caging.thermodynamic.EnergyDensityMatchReport(cage_energy_density, thermal_energy_density, tolerance=1e-08, comparator='beta_zero', metadata=<factory>)[source]#
Bases:
objectCompare a cage-family energy density with a thermal comparator.
- __init__(cage_energy_density, thermal_energy_density, tolerance=1e-08, comparator='beta_zero', metadata=<factory>)#
- qlinks.caging.thermodynamic.local_witness_template_from_pattern_support(pattern_support, *, normalization='none', metadata=None)[source]#
Reconstruct a local row operator from a reduced-IZ transition pattern.
- qlinks.caging.thermodynamic.local_witnesses_from_classification_report(report, *, include_projector_like=True, normalization='none')[source]#
Return all trusted reduced-IZ witness embeddings in one finite system.
- qlinks.caging.thermodynamic.common_local_witness_families(reports, *, include_projector_like=True, require_all_systems=True, normalization='none')[source]#
Match identical reduced-IZ local patterns across system sizes.
Matching is exact in the ordered local pattern basis. Translations are automatically matched because global variable indices are not part of the template key. Rotations or reflections require the caller to relabel local variables consistently before classification.
- qlinks.caging.thermodynamic.evaluate_local_witness_on_states(witness, *, basis_configs, states, weights=None, normalize_columns=True, metadata=None)[source]#
Evaluate
Q_Ron a pure state or a weighted ensemble of states.The constrained-basis embedding of
L_Ris sparse. The variance is the quantum variance ofQ_Rin the mixed state represented by the supplied weights, not the variance of the per-eigenstate expectation values.
- qlinks.caging.thermodynamic.evaluate_local_witness_on_diagonal_ensemble(witness, *, basis_configs, probabilities=None, metadata=None)[source]#
Evaluate
Q_Rin an ensemble diagonal in the constrained basis.With
probabilities=Nonethis is the exact infinite-temperature trace in the supplied constrained basis and symmetry sector.
- qlinks.caging.thermodynamic.evaluate_local_witness_microcanonical(witness, *, basis_configs, eigenvectors, eigenvalues, energy_center, half_width, system_size=None, metadata=None)[source]#
Evaluate
Q_Rin an equal-weight finite-size energy shell.
- qlinks.caging.thermodynamic.make_eth_scaling_point(*, system_size, witness, basis_configs, cage_state, thermal_states=None, thermal_weights=None, diagonal_probabilities=None, energy=None, energy_density=None, system_label=None, metadata=None)[source]#
Build one finite-size ETH comparison for a fixed witness embedding.
If
thermal_statesis omitted, the thermal side is evaluated in a basis- diagonal ensemble. Passing neither thermal states nor diagonal probabilities selects the exact infinite-temperature constrained ensemble.
qlinks.caging.search module#
High-level assembly API for interference-cage searches.
- class qlinks.caging.search.CageSearchConfig(search_type='type1_and_type2', tolerance=1e-10, min_component_size=2, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, type1_kappas=(0,), type2_kappas=(-2, 2), deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0, store_full_states=True, include_type1=None, include_type2=None)[source]#
Bases:
objectConfiguration for the high-level interference-cage search.
- search_type#
Candidate family to search.
"type1"targets bipartitekappa=0cages;"type2"targets fixed nonzero kinetic eigenvalues;"type1_and_type2"runs both.- Type:
Literal[‘type1’, ‘type2’, ‘type1_and_type2’, ‘custom’]
- validate_full_residual#
Whether to validate candidate eigenstates against the full Hamiltonian columns.
- Type:
- degenerate_basis_strategy#
How to choose representatives from degenerate cage subspaces.
- Type:
Literal[‘none’, ‘ipr’]
- deduplicate_by_rank#
Whether to remove linearly dependent discoveries within each signature.
- Type:
- __init__(search_type='type1_and_type2', tolerance=1e-10, min_component_size=2, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, type1_kappas=(0,), type2_kappas=(-2, 2), deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0, store_full_states=True, include_type1=None, include_type2=None)#
- class qlinks.caging.search.CageRecord(cage_state, signature, candidate, full_state=None)[source]#
Bases:
objectOne discovered cage state together with its search metadata.
- cage_state#
Compact cage state on its support.
- signature#
Integer signature
(kappa, z)inferred from kinetic and potential/self-loop values.
- candidate#
Candidate subgraph that produced the state.
- full_state#
Optional full Hilbert-space vector.
- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.complex128]] | None
- candidate: CandidateSubgraph#
- __init__(cage_state, signature, candidate, full_state=None)#
- class qlinks.caging.search.CageRecordView(records, signature=None)[source]#
Bases:
objectIndexable view into a subset of cage records.
- records: Sequence[CageRecord]#
- __init__(records, signature=None)#
- class qlinks.caging.search.CageSearchResult(records, hilbert_size, config, type1_candidates=<factory>, type2_candidates=<factory>, search_stage_seconds=<factory>)[source]#
Bases:
objectCollection returned by
CageSearcher.The result behaves like a sequence of
CageRecordobjects and also supports signature-based indexing, for exampleresult[(0, 6)]orresult[(0, 6), 0].- records#
Discovered cage records.
- config#
Search configuration used to produce the result.
- type1_candidates#
Type-1 candidate subgraphs inspected by the search.
- type2_candidates#
Type-2 candidate subgraphs inspected by the search.
- records: list[CageRecord]#
- config: CageSearchConfig#
- type1_candidates: list[CandidateSubgraph]#
- type2_candidates: list[CandidateSubgraph]#
- __init__(records, hilbert_size, config, type1_candidates=<factory>, type2_candidates=<factory>, search_stage_seconds=<factory>)#
- class qlinks.caging.search.CageSearcher(hamiltonian_matrix, kinetic_matrix, self_loop_values, config=<factory>)[source]#
Bases:
objectHigh-level cage-search driver for sparse Hamiltonian matrices.
The searcher combines graph candidate generation, candidate solving, signature grouping, optional IPR localization, and deduplication into a single workflow.
- config: CageSearchConfig#
- classmethod from_model_build_result(build_result, *, config=None)[source]#
Construct from a model build result containing H, K, and V.
- __init__(hamiltonian_matrix, kinetic_matrix, self_loop_values, config=<factory>)#
- qlinks.caging.search.diagonal_values(matrix)[source]#
Return diagonal values from a dense or sparse matrix.
- qlinks.caging.search.embed_cage_state(cage_state, *, hilbert_size)[source]#
Embed a compact cage state into the full Hilbert space.
- qlinks.caging.search.signature_from_energy_and_self_loop(energy_value, self_loop_value, *, tolerance, potential_unit=1.0)[source]#
Infer integer
(kappa, Z)signature from energy and self-loop value.self_loop_valueis the actual diagonal potential value, including any scalar potential coupling.potential_unitis the unit used to report the potential signature. For example, ifV = lambda * V_tildeandself_loop_value = lambda * Z, thenpotential_unit=lambdareports the lazy-index signature as(kappa, Z)while all internal residuals use the coupled Hamiltonian.
qlinks.caging.solver module#
- qlinks.caging.solver.solve_candidate_for_kinetic_targets(hamiltonian, kinetic_matrix, self_loop_values, candidate, *, target_kappas, config=None)[source]#
Solve cage states with fixed kinetic eigenvalues.
This is the fast path used by the high-level cage searcher for QDM/QLM Type-1 and Type-2 searches. For candidates with a uniform diagonal potential value
zon the support, a cage with kinetic eigenvaluekappahas full Hamiltonian energykappa + z. We can therefore solve the fixed-kappa linear system directly,K_out,S psi = 0, (K_S - kappa I) psi = 0,
instead of first computing the whole invariant boundary subspace and then diagonalizing the projected Hamiltonian.
Module contents#
- class qlinks.caging.AdaptiveRegionProposal(model, max_plaquettes, config=<factory>, seed_plaquette_ids=None, min_plaquettes=1, beam_width=8, branch_factor=8, max_regions=None, max_links=None, use_search_feedback=False, adapter=None)[source]#
Bases:
objectDynamically grow local QDM regions with a beam-search heuristic.
Unlike
StripeRegionProposal, this strategy does not assume a fixed region shape. It starts from one seed plaquette at a time, repeatedly adds neighboring plaquettes sharing links with the current region, and keeps only the best-scoring partial regions under hard size limits.use_search_feedback=Falsekeeps proposal generation cheap and scores regions by structural proxies: small kinetic boundary, moderate link count, and compact shared-link connectivity. Settinguse_search_feedback=Trueadditionally runs the local cage searcher while growing and boosts regions that already contain candidate local cages.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, seed_plaquette_ids=None, min_plaquettes=1, beam_width=8, branch_factor=8, max_regions=None, max_links=None, use_search_feedback=False, adapter=None)#
- class qlinks.caging.AdaptiveRegionProposalRecord(region, plaquette_ids, seed_plaquette_ids, generation, score, link_count, unresolved_boundary_count, local_hilbert_size=None, n_records=None, counts_by_signature=<factory>)[source]#
Bases:
objectOne dynamically grown plaquette-region proposal.
The adaptive proposal stores the seed plaquettes, the selected plaquette set, and the cheap heuristic score that was used by the beam search. Optional local-search feedback is filled only when
use_search_feedback=TrueonAdaptiveRegionProposal.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_ids, generation, score, link_count, unresolved_boundary_count, local_hilbert_size=None, n_records=None, counts_by_signature=<factory>)#
- class qlinks.caging.AdjacentGapRatioReport(mean_ratio, ratios, spacings, n_levels_input, n_levels_used, trim_fraction, degeneracy_tolerance, expected_poisson=np.float64(0.3862943611198906), expected_goe=0.5307, expected_gue=0.5996)[source]#
Bases:
objectAdjacent-gap-ratio statistics in one fully resolved symmetry sector.
- __init__(mean_ratio, ratios, spacings, n_levels_input, n_levels_used, trim_fraction, degeneracy_tolerance, expected_poisson=np.float64(0.3862943611198906), expected_goe=0.5307, expected_gue=0.5996)#
- class qlinks.caging.BetaZeroMatchingReport(scar_term_expectations, thermal_term_expectations, mismatch_vector, constraint_rank, compatible_dimension, compatible_basis, tolerance)[source]#
Bases:
objectLinear coefficient space matching a scar energy to the beta-zero mean.
- __init__(scar_term_expectations, thermal_term_expectations, mismatch_vector, constraint_rank, compatible_dimension, compatible_basis, tolerance)#
- class qlinks.caging.BoundaryCancellationCircuitEntry(region_index, columns, rank, dependency_dimension, singular_gap, is_circuit)[source]#
Bases:
objectOne regional dependency of the weighted boundary-column matroid.
- __init__(region_index, columns, rank, dependency_dimension, singular_gap, is_circuit)#
- class qlinks.caging.BoundaryCancellationMatroidBranchPoint(parameter, report)[source]#
Bases:
objectOne parameter point in a weighted dependency-quotient scan.
- __init__(parameter, report)#
- class qlinks.caging.BoundaryCancellationMatroidBranchReport(points, tolerance)[source]#
Bases:
objectInteger dependency data tracked along a boundary-matrix deformation.
- points: tuple[BoundaryCancellationMatroidBranchPoint, ...]#
- __init__(points, tolerance)#
- class qlinks.caging.BoundaryCancellationMatroidReport(n_rows, n_columns, rank, dependency_dimension, singular_gap, regional_entries, regional_dependency_span_dimension, intersection_dimension, relative_dependency_dimension, inclusion_residual, full_dependency_basis, regional_dependency_basis, relative_dependency_basis, relative_edge_flow_basis, edge_labels, edge_flow_conservation_residual, tolerance)[source]#
Bases:
objectWeighted dependency quotient of a boundary matrix modulo local circuits.
The columns of the boundary matrix represent a linear matroid. Its dependency space is the cage kernel. Regional kernels generate a local dependency subspace, and the remaining quotient records collective cancellation classes that cannot be assembled from those regional dependencies.
- regional_entries: tuple[BoundaryCancellationCircuitEntry, ...]#
- __init__(n_rows, n_columns, rank, dependency_dimension, singular_gap, regional_entries, regional_dependency_span_dimension, intersection_dimension, relative_dependency_dimension, inclusion_residual, full_dependency_basis, regional_dependency_basis, relative_dependency_basis, relative_edge_flow_basis, edge_labels, edge_flow_conservation_residual, tolerance)#
- class qlinks.caging.BoundaryCancellationMomentumPoint(momentum_index, momentum, dependency_dimension, regional_dependency_span_dimension, relative_dependency_dimension, singular_gap, relative_singular_gap, regional_inclusion_residual)[source]#
Bases:
objectWeighted cancellation data for one Bloch momentum sector.
- __init__(momentum_index, momentum, dependency_dimension, regional_dependency_span_dimension, relative_dependency_dimension, singular_gap, relative_singular_gap, regional_inclusion_residual)#
- class qlinks.caging.BoundaryCancellationScalingPoint(n_repeats, n_rows, n_columns, dependency_dimension, regional_dependency_span_dimension, relative_dependency_dimension, relative_dependency_density, relative_zero_momentum_indices, minimum_relative_singular_gap, minimum_positive_relative_singular_gap, maximum_regional_inclusion_residual, momentum_points)[source]#
Bases:
objectOne finite periodic repetition in a cancellation-matroid sequence.
- momentum_points: tuple[BoundaryCancellationMomentumPoint, ...]#
- __init__(n_repeats, n_rows, n_columns, dependency_dimension, regional_dependency_span_dimension, relative_dependency_dimension, relative_dependency_density, relative_zero_momentum_indices, minimum_relative_singular_gap, minimum_positive_relative_singular_gap, maximum_regional_inclusion_residual, momentum_points)#
- class qlinks.caging.BoundaryIncidenceCohomologyReport(n_support_vertices, n_boundary_rows, n_active_constraints, active_row_weight_histogram, is_two_channel, equal_magnitude_residual, gauge_flatness_residual, incidence_residual, connected_component_count, betti_0, betti_1, kernel_dimension, h0_intersection_dimension, state_h0_weight, interference_gap, gauge_basis, edge_endpoints, tolerance)[source]#
Bases:
objectCohomology of a two-channel support-to-boundary constraint map.
Every active boundary row is interpreted as an edge joining the two support configurations on which it acts. If the coefficient ratios define a flat multiplicative gauge, the boundary map is diagonally equivalent to an oriented graph-incidence matrix. Its right kernel is then the zeroth cohomology of the support graph: one gauge-covariantly constant vector per connected component.
betti_1counts graph cycles, but the cage vectors reported here belong toH^0rather than to the loop sectorH^1. This distinction is important when comparing persistent many-body cages with noncontractible loop states in singular flat bands.- __init__(n_support_vertices, n_boundary_rows, n_active_constraints, active_row_weight_histogram, is_two_channel, equal_magnitude_residual, gauge_flatness_residual, incidence_residual, connected_component_count, betti_0, betti_1, kernel_dimension, h0_intersection_dimension, state_h0_weight, interference_gap, gauge_basis, edge_endpoints, tolerance)#
- class qlinks.caging.BoundaryNullityFilter(min_nullity=1, tolerance=1e-10, matrix_name='kinetic')[source]#
Bases:
objectRequire the leakage matrix from support to outside to have nonzero nullity.
By default this uses
context.hamiltonian. ForH = K + V, if the potential is diagonal, usingcontext.kinetic_matrixis equivalent for the boundary block and is usually conceptually cleaner.- __init__(min_nullity=1, tolerance=1e-10, matrix_name='kinetic')#
- class qlinks.caging.CageBranchPoint(parameter, diagnostic, minimum_principal_overlap, projector_distance_from_reference, continued_state, continued_energy, continued_overlap_with_previous, continued_overlap_with_reference, continued_boundary_residual, continued_internal_eigen_residual, continued_full_residual)[source]#
Bases:
objectOne point in a one-parameter cage-continuation scan.
- diagnostic: CageStabilityDiagnostic#
- __init__(parameter, diagnostic, minimum_principal_overlap, projector_distance_from_reference, continued_state, continued_energy, continued_overlap_with_previous, continued_overlap_with_reference, continued_boundary_residual, continued_internal_eigen_residual, continued_full_residual)#
- class qlinks.caging.CageBranchReport(support, reference_dimension, points, tolerance)[source]#
Bases:
objectResult of scanning a cage support along a one-parameter deformation.
- points: tuple[CageBranchPoint, ...]#
- __init__(support, reference_dimension, points, tolerance)#
- class qlinks.caging.CageClassificationConfig(amplitude_tolerance=1e-10, cancellation_tolerance=1e-09, action_tolerance=1e-09, sector_policy='raise_if_disconnected', collective_cancellation_mode='same_local_support_nullspace', collective_min_group_size=2, collective_relation_tolerance=None, fock_dense_fraction_threshold=0.5, potential_shell_tolerance=None)[source]#
Bases:
objectNumerical parameters for regional/extended cage diagnostics.
- collective_cancellation_mode: Literal['disabled', 'same_local_support_sum', 'same_local_support_nullspace', 'all_problematic_sum', 'all_problematic_nullspace']#
- __init__(amplitude_tolerance=1e-10, cancellation_tolerance=1e-09, action_tolerance=1e-09, sector_policy='raise_if_disconnected', collective_cancellation_mode='same_local_support_nullspace', collective_min_group_size=2, collective_relation_tolerance=None, fock_dense_fraction_threshold=0.5, potential_shell_tolerance=None)#
- class qlinks.caging.CageClassificationReport(label, support_size, hilbert_size, support_fraction, n_nontrivial_zeros, n_distinct_local_patterns, n_complement_targets, n_unexplained_complement_targets, fraction_zeros_with_closed_complement_targets, n_q_empty_source_probes, n_closed_by_known_zero_network_source_probes, n_projector_like_source_probes, n_invalid_source_probes, n_regional_source_probes, n_collective_cancellation_source_probes, collective_cancellation_source_zero_indices, q_empty_source_zero_indices, closed_by_known_zero_network_source_zero_indices, projector_like_source_zero_indices, invalid_source_zero_indices, regional_source_zero_indices, n_trivial_targets, n_known_nonprojector_iz_targets, n_projector_like_iz_targets, n_unexpected_targets, n_unexpected_target_probe_failures, n_nonzero_complement_action_probe_failures, unexpected_target_probe_failure_indices, nonzero_complement_action_probe_failure_indices, n_source_projector_like_probes, n_indirect_projector_like_probes, n_projector_like_annihilated_inputs, source_projector_like_probe_indices, indirect_projector_like_probe_indices, projector_like_annihilated_input_indices, mean_q_sector_weight, max_q_sector_weight, mean_reduced_action_norm, max_reduced_action_norm, mean_complement_action_norm, max_complement_action_norm, zero_reports, collective_cancellation_reports, reduced_iz_probe_supports=<factory>, reduced_iz_region_variable_indices=(), reduced_iz_monitor_component_groups=<factory>, closure_summary=<factory>, fock_support_morphology=<factory>, real_space_support_morphology=<factory>, metadata=<factory>)[source]#
Bases:
objectRegional/extended diagnostic report for one cage state.
- zero_reports: tuple[InterferenceZeroReport, ...]#
- collective_cancellation_reports: tuple[CollectiveCancellationReport, ...]#
- reduced_iz_probe_supports: tuple[ReducedIZProbeSupport, ...]#
- reduced_iz_monitor_component_groups: dict[Literal['single_sum', 'exact_support', 'connected_support'], tuple[ReducedIZMonitorComponentGroup, ...]]#
- closure_summary: ClosureMechanismSummary#
- fock_support_morphology: FockSupportMorphology#
- real_space_support_morphology: RealSpaceSupportMorphology#
- property closure_mechanism_label: Literal['no_nontrivial_zeros', 'unexplained_leakage', 'collective_cancellation', 'projector_network', 'pure_domain_blocked', 'zero_network_closed', 'q_empty', 'mixed_individual_closure']#
- property fock_support_morphology_label: Literal['unknown', 'finite_size_empty', 'finite_size_singleton', 'finite_size_sector_sparse', 'finite_size_sector_dense', 'finite_size_shell_sparse', 'finite_size_shell_dense']#
- property real_space_support_morphology_label: Literal['unknown', 'frozen', 'partially_active', 'fully_active']#
- property domain_blocked_source_zero_indices: ndarray[tuple[Any, ...], dtype[int64]]#
Source-zero indices whose probe is domain-blocked.
Domain-blocked probes have finite complement support, but that complement support contains no input configuration on which the transplanted reduced-IZ operator can fire. They are a regional closure mechanism in the state-level classification.
- selected_reduced_iz_reports(*, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Return reduced-IZ reports selected for monitor assembly.
- reduced_iz_report_groups(*, decomposition, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Return report groups for a reduced-IZ monitor decomposition.
- reduced_iz_component_groups(*, decomposition, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True, use_collective_coefficients=True)[source]#
Return cached/recomputed reduced-IZ component-group metadata.
- reduced_iz_local_rdm_readouts(*, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Return local-RDM readouts for reduced-IZ component supports.
This is a convenience wrapper around
qlinks.caging.reduced_iz_local_rdm_readouts_from_report(). It makes the frustration-free reduced-IZ decompositions cached in the classification report directly inspectable from notebooks.
- frustration_free_local_rdm_readouts(*, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Alias for
reduced_iz_local_rdm_readouts().
- local_structure_report(*, basis_configs, state, model=None, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=None, include_empty_supports=False)[source]#
Return an automatic local-structure report from reduced-IZ RDMs.
- to_text(*, verbose=False, max_zero_reports=10, width=120)[source]#
Return a plain-text Rich rendering of the classification report.
- __init__(label, support_size, hilbert_size, support_fraction, n_nontrivial_zeros, n_distinct_local_patterns, n_complement_targets, n_unexplained_complement_targets, fraction_zeros_with_closed_complement_targets, n_q_empty_source_probes, n_closed_by_known_zero_network_source_probes, n_projector_like_source_probes, n_invalid_source_probes, n_regional_source_probes, n_collective_cancellation_source_probes, collective_cancellation_source_zero_indices, q_empty_source_zero_indices, closed_by_known_zero_network_source_zero_indices, projector_like_source_zero_indices, invalid_source_zero_indices, regional_source_zero_indices, n_trivial_targets, n_known_nonprojector_iz_targets, n_projector_like_iz_targets, n_unexpected_targets, n_unexpected_target_probe_failures, n_nonzero_complement_action_probe_failures, unexpected_target_probe_failure_indices, nonzero_complement_action_probe_failure_indices, n_source_projector_like_probes, n_indirect_projector_like_probes, n_projector_like_annihilated_inputs, source_projector_like_probe_indices, indirect_projector_like_probe_indices, projector_like_annihilated_input_indices, mean_q_sector_weight, max_q_sector_weight, mean_reduced_action_norm, max_reduced_action_norm, mean_complement_action_norm, max_complement_action_norm, zero_reports, collective_cancellation_reports, reduced_iz_probe_supports=<factory>, reduced_iz_region_variable_indices=(), reduced_iz_monitor_component_groups=<factory>, closure_summary=<factory>, fock_support_morphology=<factory>, real_space_support_morphology=<factory>, metadata=<factory>)#
- class qlinks.caging.CageCompatibilityHierarchyReport(first_order, fixed_state, tangent_only_coefficient_basis, fixed_subspace_inclusion_residual)[source]#
Bases:
objectCompare first-order continuation with exact fixed-state compatibility.
- first_order: LinearizedCageObstructionReport#
- fixed_state: FixedCageStateCompatibilityReport#
- tangent_only_coefficient_basis: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- property tangent_only_dimension: int#
Number of first-order directions not preserving the state exactly.
- __init__(first_order, fixed_state, tangent_only_coefficient_basis, fixed_subspace_inclusion_residual)#
- class qlinks.caging.CageFiniteSizeScorecard(hilbert_dimension, candidate_shell_size, actual_support_size, boundary_shape, boundary_rank, boundary_nullity, boundary_singular_gap, internal_residual, boundary_residual, eigenpair_residual, relative_eigenpair_residual, energy, tolerance, metadata=<factory>, singular_values=())[source]#
Bases:
objectReproducible finite-size certificate for one candidate caged state.
- __init__(hilbert_dimension, candidate_shell_size, actual_support_size, boundary_shape, boundary_rank, boundary_nullity, boundary_singular_gap, internal_residual, boundary_residual, eigenpair_residual, relative_eigenpair_residual, energy, tolerance, metadata=<factory>, singular_values=())#
- class qlinks.caging.CageHamiltonianBlocks(support, complement, internal, boundary, external)[source]#
Bases:
objectHamiltonian blocks associated with one proposed cage support.
The basis is ordered conceptually as
support + complement. Theboundaryblock maps amplitudes on the support to the complementary Hilbert-space configurations.- __init__(support, complement, internal, boundary, external)#
- class qlinks.caging.CageJacobianConditioningReport(support, energy, jacobian, singular_values, rank, nullity, cage_gap, internal_residual, boundary_residual, full_residual, tolerance)[source]#
Bases:
objectConditioning spectrum of the gauge-fixed caged-eigenpair equations.
- __init__(support, energy, jacobian, singular_values, rank, nullity, cage_gap, internal_residual, boundary_residual, full_residual, tolerance)#
- class qlinks.caging.CageLocalStructureReport(readout_reports, decomposition, tolerance)[source]#
Bases:
objectAutomatic text/formula report for local structure of a cage state.
- readout_reports: tuple[LocalStructureReadoutReport, ...]#
- __init__(readout_reports, decomposition, tolerance)#
- class qlinks.caging.CageRecord(cage_state, signature, candidate, full_state=None)[source]#
Bases:
objectOne discovered cage state together with its search metadata.
- cage_state#
Compact cage state on its support.
- signature#
Integer signature
(kappa, z)inferred from kinetic and potential/self-loop values.
- candidate#
Candidate subgraph that produced the state.
- full_state#
Optional full Hilbert-space vector.
- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.complex128]] | None
- candidate: CandidateSubgraph#
- __init__(cage_state, signature, candidate, full_state=None)#
- class qlinks.caging.CageRecordStabilitySummary(record_index, signature, support_size, inverse_participation_ratio, classification_label, n_collective_cancellation_source_probes, formal_compatible_dimension, exact_fixed_state_dimension, tangent_only_dimension)[source]#
Bases:
objectRecord-wise stability data for a preferred basis of a degenerate cage manifold.
- __init__(record_index, signature, support_size, inverse_participation_ratio, classification_label, n_collective_cancellation_source_probes, formal_compatible_dimension, exact_fixed_state_dimension, tangent_only_dimension)#
- class qlinks.caging.CageRecordView(records, signature=None)[source]#
Bases:
objectIndexable view into a subset of cage records.
- records: Sequence[CageRecord]#
- __init__(records, signature=None)#
- class qlinks.caging.CageRegionSupport(variable_indices, probe_supports, ignored_probe_supports, n_total_probes, n_used_probes, n_ignored_probes, n_unexplained_leakage_probes, max_complement_action_norm, max_reduced_action_norm, metadata)[source]#
Bases:
objectUnion support R extracted from reduced IZ probes.
- probe_supports: tuple[ReducedIZProbeSupport, ...]#
- ignored_probe_supports: tuple[ReducedIZProbeSupport, ...]#
- __init__(variable_indices, probe_supports, ignored_probe_supports, n_total_probes, n_used_probes, n_ignored_probes, n_unexplained_leakage_probes, max_complement_action_norm, max_reduced_action_norm, metadata)#
- class qlinks.caging.CageSearchConfig(search_type='type1_and_type2', tolerance=1e-10, min_component_size=2, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, type1_kappas=(0,), type2_kappas=(-2, 2), deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0, store_full_states=True, include_type1=None, include_type2=None)[source]#
Bases:
objectConfiguration for the high-level interference-cage search.
- search_type#
Candidate family to search.
"type1"targets bipartitekappa=0cages;"type2"targets fixed nonzero kinetic eigenvalues;"type1_and_type2"runs both.- Type:
Literal[‘type1’, ‘type2’, ‘type1_and_type2’, ‘custom’]
- validate_full_residual#
Whether to validate candidate eigenstates against the full Hamiltonian columns.
- Type:
- degenerate_basis_strategy#
How to choose representatives from degenerate cage subspaces.
- Type:
Literal[‘none’, ‘ipr’]
- deduplicate_by_rank#
Whether to remove linearly dependent discoveries within each signature.
- Type:
- __init__(search_type='type1_and_type2', tolerance=1e-10, min_component_size=2, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, type1_kappas=(0,), type2_kappas=(-2, 2), deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0, store_full_states=True, include_type1=None, include_type2=None)#
- class qlinks.caging.CageSearchResult(records, hilbert_size, config, type1_candidates=<factory>, type2_candidates=<factory>, search_stage_seconds=<factory>)[source]#
Bases:
objectCollection returned by
CageSearcher.The result behaves like a sequence of
CageRecordobjects and also supports signature-based indexing, for exampleresult[(0, 6)]orresult[(0, 6), 0].- records#
Discovered cage records.
- config#
Search configuration used to produce the result.
- type1_candidates#
Type-1 candidate subgraphs inspected by the search.
- type2_candidates#
Type-2 candidate subgraphs inspected by the search.
- records: list[CageRecord]#
- config: CageSearchConfig#
- type1_candidates: list[CandidateSubgraph]#
- type2_candidates: list[CandidateSubgraph]#
- __init__(records, hilbert_size, config, type1_candidates=<factory>, type2_candidates=<factory>, search_stage_seconds=<factory>)#
- class qlinks.caging.CageSearcher(hamiltonian_matrix, kinetic_matrix, self_loop_values, config=<factory>)[source]#
Bases:
objectHigh-level cage-search driver for sparse Hamiltonian matrices.
The searcher combines graph candidate generation, candidate solving, signature grouping, optional IPR localization, and deduplication into a single workflow.
- config: CageSearchConfig#
- classmethod from_model_build_result(build_result, *, config=None)[source]#
Construct from a model build result containing H, K, and V.
- __init__(hamiltonian_matrix, kinetic_matrix, self_loop_values, config=<factory>)#
- class qlinks.caging.CageSolverConfig(tolerance=1e-10, max_power=None, stabilization_rounds=1, validate_full_residual=True, normalize_states=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_convergence_tolerance=1e-12, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_support_tolerance_factor=100.0, ipr_rank_tolerance_factor=100.0, ipr_random_seed=None, timing_collector=None)[source]#
Bases:
objectNumerical configuration for the interference-caging eigensolver.
- validate_full_residual#
Whether to validate against full Hamiltonian columns when available.
- Type:
- degenerate_basis_strategy#
How to choose representatives from degenerate cage subspaces.
- Type:
Literal[‘none’, ‘ipr’]
- timing_collector#
Optional mutable dictionary accumulating per-stage runtime in seconds.
- __init__(tolerance=1e-10, max_power=None, stabilization_rounds=1, validate_full_residual=True, normalize_states=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_convergence_tolerance=1e-12, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_support_tolerance_factor=100.0, ipr_rank_tolerance_factor=100.0, ipr_random_seed=None, timing_collector=None)#
- class qlinks.caging.CageStabilityDiagnostic(support, boundary_singular_values, boundary_rank, boundary_nullity, interference_gap, boundary_kernel_basis, invariant_cage_basis, invariant_cage_dimension, hermiticity_residual, state_energy=None, state_boundary_residual=None, state_internal_eigen_residual=None, state_full_residual=None, state_invariant_weight=None)[source]#
Bases:
objectStatic interference-kernel diagnostic for one Hamiltonian and support.
- __init__(support, boundary_singular_values, boundary_rank, boundary_nullity, interference_gap, boundary_kernel_basis, invariant_cage_basis, invariant_cage_dimension, hermiticity_residual, state_energy=None, state_boundary_residual=None, state_internal_eigen_residual=None, state_full_residual=None, state_invariant_weight=None)#
- class qlinks.caging.CageState(energy, local_state, support, boundary_residual, eigen_residual, full_residual=None, metadata=None)[source]#
Bases:
objectValidated interference-caged eigenstate on compact support.
- local_state#
State amplitudes restricted to
support.- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.complex128]]
- support#
Global basis indices carrying nonzero amplitudes.
- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.int64]]
- __init__(energy, local_state, support, boundary_residual, eigen_residual, full_residual=None, metadata=None)#
- class qlinks.caging.CandidateFilter(*args, **kwargs)[source]#
Bases:
ProtocolProtocol for candidate prefilters.
- __init__(*args, **kwargs)#
- class qlinks.caging.CandidateFilterContext(hamiltonian=None, kinetic_matrix=None, self_loop_values=None, bipartition_labels=None)[source]#
Bases:
objectMatrix-level context used by candidate prefilters.
- kinetic_matrix#
Optional off-diagonal or kinetic matrix. For
H = K + V, this should beK.- Type:
object | None
- self_loop_values#
Optional diagonal/self-loop data. Shape can be
(hilbert_size,)for scalar values or(hilbert_size, n_parameters)for multi-parameter coefficients.- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.complex128]] | None
- bipartition_labels#
Optional integer labels for bipartite subsets.
- Type:
numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.int64]] | None
- __init__(hamiltonian=None, kinetic_matrix=None, self_loop_values=None, bipartition_labels=None)#
- class qlinks.caging.CandidateFilterResult(accepted, reason='', metadata=None)[source]#
Bases:
objectResult returned by a candidate prefilter.
- __init__(accepted, reason='', metadata=None)#
- class qlinks.caging.CandidateSubgraph(vertices, label=None, metadata=<factory>)[source]#
Bases:
objectCandidate support for an interference-caged state.
- __init__(vertices, label=None, metadata=<factory>)#
- qlinks.caging.CertifiedLocalCageSearchResult#
alias of
CertifiedLocalQDMCageSearchResult
- class qlinks.caging.CertifiedLocalQDMCageSearchResult(cage_search_result, basis, kinetic_matrix, self_loop_values, reports, padding_config)[source]#
Bases:
objectA certified local-first result with CageSearchResult-compatible records.
cage_search_resultis an ordinaryCageSearchResultwhose Hilbert space is the limited certified basis, not the full global Hilbert space. The companionbasis,kinetic_matrix, andself_loop_valuesare the limited objects needed by visualizers/classifiers/adapters.- cage_search_result: CageSearchResult#
- padding_config: LocalQDMPaddingConfig | LocalQDMMultiPaddingConfig#
- property records: list[CageRecord]#
- property config: CageSearchConfig#
- __init__(cage_search_result, basis, kinetic_matrix, self_loop_values, reports, padding_config)#
- class qlinks.caging.ChiralIndexReport(n_plus, n_minus, rank, kernel_plus_dimension, kernel_minus_dimension, index, index_protected_plus_zero_modes, index_protected_minus_zero_modes, paired_zero_mode_count, singular_gap, tolerance)[source]#
Bases:
objectFinite-dimensional chiral index diagnostic for an off-diagonal block.
For
K = [[0, A^†], [A, 0]], the index isdim ker(A) - dim ker(A^†) = n_plus - n_minus. Only the signed index is stable under arbitrary chiral-symmetric rank-preserving deformations; any additional paired zero modes are interference-protected rather than index-protected.- __init__(n_plus, n_minus, rank, kernel_plus_dimension, kernel_minus_dimension, index, index_protected_plus_zero_modes, index_protected_minus_zero_modes, paired_zero_mode_count, singular_gap, tolerance)#
- class qlinks.caging.ClosureMechanismSummary(label='no_nontrivial_zeros', n_q_empty_source_probes=0, n_closed_by_known_zero_network_source_probes=0, n_domain_blocked_source_probes=0, n_projector_like_source_probes=0, n_collective_cancellation_source_probes=0, n_unexplained_leakage_source_probes=0, n_projector_like_iz_targets=0, n_unexpected_targets=0, n_nonzero_complement_action_failures=0)[source]#
Bases:
objectState-level summary of reduced-IZ closure mechanisms.
This is intentionally separated from Fock-space and real-space support morphology. It summarizes how boundary/interference-zero probes close, not how large or spatially extended the cage support is.
- label: Literal['no_nontrivial_zeros', 'unexplained_leakage', 'collective_cancellation', 'projector_network', 'pure_domain_blocked', 'zero_network_closed', 'q_empty', 'mixed_individual_closure']#
- __init__(label='no_nontrivial_zeros', n_q_empty_source_probes=0, n_closed_by_known_zero_network_source_probes=0, n_domain_blocked_source_probes=0, n_projector_like_source_probes=0, n_collective_cancellation_source_probes=0, n_unexplained_leakage_source_probes=0, n_projector_like_iz_targets=0, n_unexpected_targets=0, n_nonzero_complement_action_failures=0)#
- class qlinks.caging.CollectiveCancellationReport(group_id, source_zero_indices, coefficients, individual_complement_action_norms, collective_action_norm, collective_target_indices, local_mask, local_region_size, relation_kind, grouping_kind)[source]#
Bases:
objectA group of reduced IZ probes whose complement leakages cancel together.
- __init__(group_id, source_zero_indices, coefficients, individual_complement_action_norms, collective_action_norm, collective_target_indices, local_mask, local_region_size, relation_kind, grouping_kind)#
- class qlinks.caging.CombinedBoundaryKineticTargetNullityFilter(target_kappas, min_nullity=1, tolerance=1e-10, require_nonzero_kappa=False)[source]#
Bases:
objectRequire nonzero nullity of the combined matrix
[K_out,S] [K_S - kappa I]
for at least one target kappa.
This is stronger than
KineticTargetNullityFilterand is almost the fixed-kappa caging test. It is still useful as a prefilter before building full states or doing validation.- __init__(target_kappas, min_nullity=1, tolerance=1e-10, require_nonzero_kappa=False)#
- class qlinks.caging.CommutantAlgebraDiagnostic(operator_names, term_names, commutator_matrix_shape, commutant_rank, commutant_nullity, singular_values, commutant_coefficients, commutant_residuals, individual_commutator_norms, tolerance)[source]#
Bases:
objectCommutant diagnostics in a supplied operator basis.
Given candidate operators
O_aand Hamiltonian/local termsh_j, this solves for linear combinationsX=sum_a c_a O_asatisfying[X, h_j]=0for all supplied terms. This is a small-system diagnostic and is meant for reverse engineering candidate commutant generators after exact cage states have been found.- __init__(operator_names, term_names, commutator_matrix_shape, commutant_rank, commutant_nullity, singular_values, commutant_coefficients, commutant_residuals, individual_commutator_norms, tolerance)#
- class qlinks.caging.ConnectedRegionProposal(model, max_plaquettes, config=<factory>, min_plaquettes=1, seed_plaquette_ids=None, max_regions=None, max_links=None, adapter=None)[source]#
Bases:
objectEnumerate connected plaquette regions under explicit size budgets.
This is the robust, shape-agnostic counterpart of the stripe/adaptive proposals. It exhaustively enumerates connected plaquette sets on the shared-link plaquette graph up to
max_plaquettesand optionallymax_links. It is deliberately simple: the only physics assumption is connectedness on the kinetic plaquette graph, while the local solver and global certification decide which regions are useful.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, min_plaquettes=1, seed_plaquette_ids=None, max_regions=None, max_links=None, adapter=None)#
- class qlinks.caging.ConnectedRegionProposalRecord(region, plaquette_ids, seed_plaquette_id, size, link_count, unresolved_boundary_count)[source]#
Bases:
objectOne connected plaquette-set local-region proposal.
Unlike the adaptive beam proposal, this record comes from exhaustive connected-region enumeration under explicit size limits. It is intended as a robust fallback when the cage shape is not known a priori.
- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_id, size, link_count, unresolved_boundary_count)#
- class qlinks.caging.CyclicAmplitudeBondProfile(length, support_size, alphabet_size, cut_ranks, maximum_cut_rank, periodic_bond_dimension_lower_bound, translation_support_closed, translation_eigenvalue, translation_residual, tolerance)[source]#
Bases:
objectExact finite-state bond-rank profile of a cyclic column amplitude.
The rank at a cut is the Schmidt rank of the sparse amplitude tensor after grouping the columns to the left and right of that cut. The maximum cut rank is the minimal exact open-boundary MPS bond dimension for this finite state. A periodic MPS of bond dimension
Dhas Schmidt rank at mostD**2, giving the reported rigorous lower bound.- __init__(length, support_size, alphabet_size, cut_ranks, maximum_cut_rank, periodic_bond_dimension_lower_bound, translation_support_closed, translation_eigenvalue, translation_residual, tolerance)#
- class qlinks.caging.ETHScalingPoint(system_size, cage, thermal, energy=None, energy_density=None, system_label=None, metadata=<factory>)[source]#
Bases:
objectOne finite-size comparison between a cage state and a thermal ensemble.
- cage: LocalWitnessEvaluation#
- thermal: LocalWitnessEvaluation#
- __init__(system_size, cage, thermal, energy=None, energy_density=None, system_label=None, metadata=<factory>)#
- class qlinks.caging.ETHScalingReport(template, points)[source]#
Bases:
objectFinite-size scaling data for one fixed local witness template.
- template: LocalWitnessTemplate#
- points: tuple[ETHScalingPoint, ...]#
- tail_liminf_lower_bound(*, tail_points=2)[source]#
Return the minimum absolute gap among the largest available sizes.
This is a finite-data lower bound, not a proof of the mathematical liminf. Its explicit name is intended to prevent overinterpretation.
- __init__(template, points)#
- class qlinks.caging.EigenpairResidualReport(energy, residual_norm, relative_residual_norm, variance, state_norm)[source]#
Bases:
objectFinite-size residual data for a proposed eigenpair.
- __init__(energy, residual_norm, relative_residual_norm, variance, state_norm)#
- class qlinks.caging.EnergyDensityMatchReport(cage_energy_density, thermal_energy_density, tolerance=1e-08, comparator='beta_zero', metadata=<factory>)[source]#
Bases:
objectCompare a cage-family energy density with a thermal comparator.
- __init__(cage_energy_density, thermal_energy_density, tolerance=1e-08, comparator='beta_zero', metadata=<factory>)#
- class qlinks.caging.FactorizedLocalQDMPadding(block_ids, exterior_link_ids, exterior_config)[source]#
Bases:
objectShared exterior for a product of local blocks without support expansion.
Unlike
MultiLocalQDMPadding, this object never forms the Cartesian product of block support configurations. Its memory cost is therefore independent ofprod(block.support_size).- __init__(block_ids, exterior_link_ids, exterior_config)#
- class qlinks.caging.FixedCageManifoldCompatibilityReport(coefficient_field, manifold_dimension, n_parameters, action_matrix, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, perturbation_residuals, tolerance)[source]#
Bases:
objectExact perturbation space preserving a cage subspace as a whole.
The basis vectors may rotate inside the manifold. A perturbation is compatible when it neither leaks through the support boundary nor couples the selected manifold to its orthogonal complement inside the support.
- constraint_matrix: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- compatible_coefficient_basis: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- __init__(coefficient_field, manifold_dimension, n_parameters, action_matrix, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, perturbation_residuals, tolerance)#
- class qlinks.caging.FixedCageStateCompatibilityReport(coefficient_field, n_parameters, action_matrix, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, perturbation_residuals, tolerance)[source]#
Bases:
objectExact affine perturbation space that preserves one cage vector.
A coefficient vector belongs to this space when its perturbation
Vsatisfies bothdelta_B phi = 0and(I - |phi><phi|) delta_A phi = 0. Therefore the same compact vector remains an exact eigenstate ofH0 + lambda Vfor everylambda.- constraint_matrix: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- compatible_coefficient_basis: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- __init__(coefficient_field, n_parameters, action_matrix, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, perturbation_residuals, tolerance)#
- class qlinks.caging.FockSpaceAutomorphismDiagnostic(support_indices, boundary_indices, hilbert_size, support_size, boundary_size, selected_graph_size, state_boundary_residual, state_boundary_relative_residual, n_automorphisms_tested, n_nontrivial_automorphisms, n_explaining_automorphisms, automorphism_search_truncated, skipped_reason, permutation_diagnostics)[source]#
Bases:
objectBoundary-fixed Fock-space automorphism diagnostics for a cage state.
The diagnostic searches automorphisms of the support-plus-boundary graph while fixing every boundary vertex individually. This is intentionally the conservative CLS test: a nontrivial support irrep is certified only when the exterior/boundary channels are symmetry-trivial.
- permutation_diagnostics: tuple[SupportPermutationDiagnostic, ...]#
- property best_explaining_permutation: SupportPermutationDiagnostic | None#
- __init__(support_indices, boundary_indices, hilbert_size, support_size, boundary_size, selected_graph_size, state_boundary_residual, state_boundary_relative_residual, n_automorphisms_tested, n_nontrivial_automorphisms, n_explaining_automorphisms, automorphism_search_truncated, skipped_reason, permutation_diagnostics)#
- class qlinks.caging.FockSupportMorphology(label='unknown', support_size=0, effective_support_size=0.0, hilbert_size=0, support_fraction=0.0, effective_hilbert_fraction=0.0, boundary_size=0, boundary_to_support_ratio=0.0, support_internal_matrix_entries=0, potential_shell_value=None, potential_shell_size=None, support_shell_fraction=None, effective_shell_fraction=None, potential_shell_residual=None)[source]#
Bases:
objectFinite-size morphology diagnostics for the support in Fock space.
The
labelis a finite-size proxy only. Scaling labels such as finite, polynomial, or shell-extended require comparing a family of systems across sizes.- label: Literal['unknown', 'finite_size_empty', 'finite_size_singleton', 'finite_size_sector_sparse', 'finite_size_sector_dense', 'finite_size_shell_sparse', 'finite_size_shell_dense']#
- __init__(label='unknown', support_size=0, effective_support_size=0.0, hilbert_size=0, support_fraction=0.0, effective_hilbert_fraction=0.0, boundary_size=0, boundary_to_support_ratio=0.0, support_internal_matrix_entries=0, potential_shell_value=None, potential_shell_size=None, support_shell_fraction=None, effective_shell_fraction=None, potential_shell_residual=None)#
- class qlinks.caging.HamiltonianGraphChainComplex(constraint_map, generator_map, support_indices=None, test_indices=None, generator_labels=())[source]#
Bases:
objectFinite Hamiltonian-graph caging complex
C2 -> C1 -> C0.constraint_mapis the physical leakage/eigenvalue mapD_Efrom support amplitudes to violated Hamiltonian rows.generator_mapmaps a chosen library of bounded-support cage motifs into the support-amplitude space. The chain condition isconstraint_map @ generator_map == 0.The basis conventions are:
columns of
generator_mapare local cage generators;columns of
ker(constraint_map)are all exact cage amplitudes on the chosen support shell;H_1 = ker(D_E) / im(T_R)is the many-body CLS-completeness defect;H_2 = ker(T_R)records linear relations among translated motifs.
- __init__(constraint_map, generator_map, support_indices=None, test_indices=None, generator_labels=())#
- class qlinks.caging.HamiltonianGraphHomologyReport(c0_dimension, c1_dimension, c2_dimension, constraint_rank, generator_rank, cage_dimension, h1_dimension, h2_dimension, chain_residual, relative_chain_residual, generator_containment_residual, cage_basis, local_generator_basis, h1_basis, h2_basis, cocycle_basis, hodge_operator, hodge_eigenvalues, hodge_gap, tolerance)[source]#
Bases:
objectNumerical homology/cohomology report for a caging chain complex.
- pairing_matrix(cage_representatives=None)[source]#
Pair dual cocycles with supplied cage representatives.
With no argument, harmonic
H_1representatives are used. Under the Euclidean inner product the returned matrix should be the identity up to numerical tolerance.
- __init__(c0_dimension, c1_dimension, c2_dimension, constraint_rank, generator_rank, cage_dimension, h1_dimension, h2_dimension, chain_residual, relative_chain_residual, generator_containment_residual, cage_basis, local_generator_basis, h1_basis, h2_basis, cocycle_basis, hodge_operator, hodge_eigenvalues, hodge_gap, tolerance)#
- class qlinks.caging.HardCoreLaurentLiftReport(length, particle_number, support_size, exchange_constraint_count, all_constraints_are_nearest_neighbor_exchanges, uniform_transport_factor, transport_residual, primitive_root_order, periodic_compatibility_residual, amplitude_factorization_residual, one_site_translation_character, one_site_translation_residual, has_unit_circle_symbol_zero, incidence_cohomology, tolerance)[source]#
Bases:
objectHard-core many-body lift of a scalar Laurent transfer root.
Support configurations are interpreted as fixed-particle-number binary words on a periodic chain. Two-channel boundary constraints must exchange one occupied site with an adjacent empty site. If every right-moving exchange transports the cage amplitude by the same factor
zeta, the many-body state is the hard-core lift of the scalar local relation whose Laurent symbol vanishes atz=zeta.A unit-modulus root has a discrete primitive order, but the corresponding Toeplitz symbol is not Fredholm because it vanishes on the unit circle. The primitive order is therefore a translation/cyclotomic invariant of the exact interference rule, not a conventional Fredholm winding number.
- incidence_cohomology: BoundaryIncidenceCohomologyReport#
- __init__(length, particle_number, support_size, exchange_constraint_count, all_constraints_are_nearest_neighbor_exchanges, uniform_transport_factor, transport_residual, primitive_root_order, periodic_compatibility_residual, amplitude_factorization_residual, one_site_translation_character, one_site_translation_residual, has_unit_circle_symbol_zero, incidence_cohomology, tolerance)#
- class qlinks.caging.IPRLocalizationConfig(n_restarts=128, max_iter=1000, step_size=0.1, convergence_tolerance=1e-12, candidate_count=64, amplitude_tolerance=1e-08, rank_tolerance=1e-08, minimum_gap_ratio=10.0, random_seed=None, rank_completion_patience=None, batch_size=16)[source]#
Bases:
objectConfiguration for many-start IPR localization.
- __init__(n_restarts=128, max_iter=1000, step_size=0.1, convergence_tolerance=1e-12, candidate_count=64, amplitude_tolerance=1e-08, rank_tolerance=1e-08, minimum_gap_ratio=10.0, random_seed=None, rank_completion_patience=None, batch_size=16)#
- class qlinks.caging.IncidenceConstraintInterfaceReport(left_support_dimension, right_support_dimension, left_kernel_dimension, right_kernel_dimension, decoupled_kernel_dimension, interface_constraint_count, combined_constraint_map, combined_kernel_basis, combined_kernel_dimension, surviving_bulk_kernel_dimension, interface_created_dimension, interface_removed_dimension, active_row_weight_histogram, is_two_channel, connected_component_count, betti_1, gauge_flatness_residual, kernel_equals_h0, classification, tolerance)[source]#
Bases:
objectInterface obtained by gluing two local incidence constraint modules.
The combined differential contains both complete bulk constraint maps plus additional interface rows. Consequently, any interface kernel lies inside the direct sum of the two original bulk kernels. The report tests whether gluing merely merges the local
H^0sectors, frustrates them, or creates a higher-arity problem; it cannot create a new quotient mode without modifying or removing bulk constraints near the interface.- __init__(left_support_dimension, right_support_dimension, left_kernel_dimension, right_kernel_dimension, decoupled_kernel_dimension, interface_constraint_count, combined_constraint_map, combined_kernel_basis, combined_kernel_dimension, surviving_bulk_kernel_dimension, interface_created_dimension, interface_removed_dimension, active_row_weight_histogram, is_two_channel, connected_component_count, betti_1, gauge_flatness_residual, kernel_equals_h0, classification, tolerance)#
- class qlinks.caging.InterferenceZeroReport(zero_index, active_neighbors, active_matrix_elements, active_amplitudes, cancellation_residual, common_mask, local_mask, local_transitions, q_sector_weight, reduced_action_norm, complement_action_norm, complement_target_indices, explained_complement_target_indices, unexplained_complement_target_indices, complement_targets_are_known_zeros, trivial_target_indices, known_nonprojector_iz_target_indices, projector_like_iz_target_indices, unexpected_target_indices, complement_support_indices, complement_contributing_input_indices, projector_like_annihilated_input_indices, source_projector_like, has_unexpected_targets, has_nonzero_complement_action, unexpected_target_probe_failure_indices, nonzero_complement_action_target_indices, probe_mechanism_label, collective_cancellation_group_id=None, collective_cancellation_partner_zero_indices=<factory>, collective_cancellation_coefficient=0j, collective_cancellation_norm=inf, reduced_action_vector=<factory>, local_variable_indices=())[source]#
Bases:
objectDiagnostics for one source nontrivial interference zero.
The field
zero_indexis the source zero h used to construct the reduced IZ probe Z_h^(R). The mechanism label describes the behavior of this source probe on the cage state.- local_transitions: tuple[LocalTransitionPattern, ...]#
- probe_mechanism_label: Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage']#
- __init__(zero_index, active_neighbors, active_matrix_elements, active_amplitudes, cancellation_residual, common_mask, local_mask, local_transitions, q_sector_weight, reduced_action_norm, complement_action_norm, complement_target_indices, explained_complement_target_indices, unexplained_complement_target_indices, complement_targets_are_known_zeros, trivial_target_indices, known_nonprojector_iz_target_indices, projector_like_iz_target_indices, unexpected_target_indices, complement_support_indices, complement_contributing_input_indices, projector_like_annihilated_input_indices, source_projector_like, has_unexpected_targets, has_nonzero_complement_action, unexpected_target_probe_failure_indices, nonzero_complement_action_target_indices, probe_mechanism_label, collective_cancellation_group_id=None, collective_cancellation_partner_zero_indices=<factory>, collective_cancellation_coefficient=0j, collective_cancellation_norm=inf, reduced_action_vector=<factory>, local_variable_indices=())#
- class qlinks.caging.InverseSizeFit(order, coefficients, thermodynamic_limit, root_mean_square_residual, system_sizes, observed_values, fitted_values)[source]#
Bases:
objectDescriptive fit
y(N) = c_0 + c_1/N + ....- __init__(order, coefficients, thermodynamic_limit, root_mean_square_residual, system_sizes, observed_values, fitted_values)#
- class qlinks.caging.KineticTargetNullityFilter(target_kappas, min_nullity=1, tolerance=1e-10, require_nonzero_kappa=False)[source]#
Bases:
objectRequire
K_S - kappa Ito have nonzero nullity for at least one kappa.This is a Type-2 prefilter. It does not include the boundary cancellation condition. It only checks whether the internal kinetic block can support the requested kinetic eigenvalue.
- __init__(target_kappas, min_nullity=1, tolerance=1e-10, require_nonzero_kappa=False)#
- class qlinks.caging.LaurentDimensionDivisibilityViolation(divisor_repeat_count, multiple_repeat_count, divisor_torsion_dimension, multiple_torsion_dimension)[source]#
Bases:
objectViolation of root-set inclusion between two periodic lengths.
- __init__(divisor_repeat_count, multiple_repeat_count, divisor_torsion_dimension, multiple_torsion_dimension)#
- class qlinks.caging.LaurentPeriodicDimensionConsistencyReport(repeat_counts, observed_dimensions, assumed_free_rank, torsion_dimensions, divisibility_violations, primitive_order_multiplicities, incomplete_primitive_orders)[source]#
Bases:
objectNecessary Laurent-module consistency test for observed periodic nullities.
For a fixed Laurent symbol, every root of
z**N - 1is also a root ofz**M - 1wheneverNdividesM. After subtracting the extensive free contribution, periodic torsion dimensions must therefore be monotone under divisibility. On a divisor-closed data set, Möbius inversion also gives non-negative primitive-order multiplicities.Passing these tests is necessary, not sufficient, for the data to come from one fixed finite-range translation-invariant Laurent module.
- divisibility_violations: tuple[LaurentDimensionDivisibilityViolation, ...]#
- __init__(repeat_counts, observed_dimensions, assumed_free_rank, torsion_dimensions, divisibility_violations, primitive_order_multiplicities, incomplete_primitive_orders)#
- class qlinks.caging.LaurentPeriodicKernelPoint(length, twist, rank, nullity, singular_values, smallest_positive_singular_value)[source]#
Bases:
objectKernel diagnostic for one Laurent operator on a twisted finite ring.
- __init__(length, twist, rank, nullity, singular_values, smallest_positive_singular_value)#
- class qlinks.caging.LaurentPolynomialConstraintModuleReport(n_rows, n_columns, displacements, generic_rank, free_kernel_rank, generic_rank_sample_count, generic_rank_is_stable, periodic_points, torsion_orders, tolerance)[source]#
Bases:
objectFree and root-of-unity torsion data of a finite-range Laurent module.
A translation-invariant finite-range constraint family is represented by
B(z) = sum_d z**d B_dover the Laurent ring
C[z, z**-1]. The generic kernel dimension is the rank of the free module. Additional kernel vectors occurring only at roots of unity are torsion modes on periodic systems. Their primitive root orders are discrete and remain fixed until a determinantal factor changes.The calculation is numerical but uses only the small Bloch symbol. It is exact up to
tolerancefor the supplied coefficient matrices and sampled roots of unity.- periodic_points: tuple[LaurentPolynomialPeriodicPoint, ...]#
- torsion_orders: tuple[LaurentPolynomialTorsionOrder, ...]#
- __init__(n_rows, n_columns, displacements, generic_rank, free_kernel_rank, generic_rank_sample_count, generic_rank_is_stable, periodic_points, torsion_orders, tolerance)#
- class qlinks.caging.LaurentPolynomialPeriodicPoint(repeat_count, total_kernel_dimension, free_kernel_dimension, torsion_kernel_dimension, root_modes)[source]#
Bases:
objectPeriodic-kernel dimensions of a Laurent module at one repetition count.
- root_modes: tuple[LaurentPolynomialRootMode, ...]#
- __init__(repeat_count, total_kernel_dimension, free_kernel_dimension, torsion_kernel_dimension, root_modes)#
- class qlinks.caging.LaurentPolynomialRootMode(repeat_count, momentum_index, primitive_order, root, kernel_dimension, free_dimension, torsion_dimension, singular_gap)[source]#
Bases:
objectKernel multiplicity of a Laurent constraint symbol at one root of unity.
- __init__(repeat_count, momentum_index, primitive_order, root, kernel_dimension, free_dimension, torsion_dimension, singular_gap)#
- class qlinks.caging.LaurentPolynomialTorsionOrder(primitive_order, multiplicity, primitive_root_count)[source]#
Bases:
objectTotal torsion multiplicity carried by primitive roots of one order.
- __init__(primitive_order, multiplicity, primitive_root_count)#
- class qlinks.caging.LinearizedCageObstructionReport(coefficient_field, n_parameters, obstruction_matrix, boundary_obstruction_matrix, tangent_operator, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, left_boundary_nullspace, left_tangent_nullspace, perturbation_diagnostics, tolerance)[source]#
Bases:
objectFirst-order obstruction map for a basis of local perturbations.
- constraint_matrix: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- compatible_coefficient_basis: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]]#
- perturbation_diagnostics: tuple[PerturbationCompatibilityDiagnostic, ...]#
- __init__(coefficient_field, n_parameters, obstruction_matrix, boundary_obstruction_matrix, tangent_operator, constraint_matrix, singular_values, rank, compatible_dimension, compatible_coefficient_basis, left_boundary_nullspace, left_tangent_nullspace, perturbation_diagnostics, tolerance)#
- class qlinks.caging.LocalAnnihilatorDiagnostic(operator_names, state_norm, action_matrix_shape, action_matrix_rank, annihilator_nullity, singular_values, annihilator_coefficients, annihilator_residuals, operator_action_diagnostics, tolerance)[source]#
Bases:
objectLinear-annihilator diagnostics in a supplied operator basis.
If the operator basis is
{O_a}, this diagnostic computes the nullspace of the action matrix with columnsO_a |psi>. Every null vector gives a linear combinationsum_a c_a O_athat annihilates the state. The same action data also reports which individual operators have the state as an eigenvector.- operator_action_diagnostics: tuple[OperatorStateActionDiagnostic, ...]#
- __init__(operator_names, state_norm, action_matrix_shape, action_matrix_rank, annihilator_nullity, singular_values, annihilator_coefficients, annihilator_residuals, operator_action_diagnostics, tolerance)#
- class qlinks.caging.LocalCageModelAdapter(*args, **kwargs)[source]#
Bases:
ProtocolModel-specific local variable interface used by
LocalCageSearcher.The generic local searcher owns the caging algebra. The adapter owns the model/lattice details: how to build a local region, enumerate compatible local configurations, construct local kinetic transitions, and compute the local diagonal/self-loop values. New models should add an adapter rather than adding branches to
LocalCageSearcher.- build_region_from_plaquettes(*, plaquette_ids, config, scoring_plaquette_ids=None)[source]#
Build a local region from seed plaquettes/local kinetic terms.
- build_region_from_links(*, link_ids, config, active_plaquette_ids=None, scoring_plaquette_ids=None)[source]#
Build a local region from explicit local variables.
- build_local_kinetic_matrix(region, local_basis)[source]#
Build the local kinetic matrix on
local_basis.
- make_local_record(*, cage_state, signature, candidate, local_basis, region)[source]#
Wrap one solved local cage state in a model-specific record.
- __init__(*args, **kwargs)#
- qlinks.caging.LocalCageRecord#
alias of
LocalQDMCageRecord
- qlinks.caging.LocalCageRegion#
alias of
LocalQDMRegion
- qlinks.caging.LocalCageSearchConfig#
alias of
LocalQDMCageSearchConfig
- qlinks.caging.LocalCageSearchResult#
alias of
LocalQDMCageSearchResult
- class qlinks.caging.LocalCageSearcher(model, region, config=<factory>, adapter=None)[source]#
Bases:
objectLocal-first type-1 cage searcher over a model adapter.
The searcher owns only the generic caging algebra: build a local kinetic graph, find bipartite/uniform-self-loop type-1 candidates, and solve the fixed-kappa cage problem. The adapter owns all model/lattice details such as local variable ids, constraints, local kinetic moves, and padding.
- region: LocalQDMRegion#
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None = None#
- classmethod from_plaquettes(model, plaquette_ids, *, config=None, scoring_plaquette_ids=None, adapter=None)[source]#
Construct a local searcher from seed plaquettes/local kinetic terms.
- classmethod from_links(model, link_ids, *, config=None, active_plaquette_ids=None, scoring_plaquette_ids=None, adapter=None)[source]#
Construct a local searcher from explicit local variable ids.
- classmethod full_model_region(model, *, config=None, adapter=None)[source]#
Construct a local searcher whose region is the full model.
This is mostly useful as a regression bridge: the implementation path is still local-first/no-full-Hamiltonian, but the local region happens to contain every variable and local kinetic term.
- __init__(model, region, config=<factory>, adapter=None)#
- class qlinks.caging.LocalChannelSpectrumReport(channel_shape, operator_norm, q_eigenvalues, rank, nullity, dark_channel_gap, tolerance)[source]#
Bases:
objectPositive spectrum and conditioning gap of one local channel.
- __init__(channel_shape, operator_norm, q_eigenvalues, rank, nullity, dark_channel_gap, tolerance)#
- class qlinks.caging.LocalClassicalPatternSector(pattern, weight)[source]#
Bases:
objectDiagonal-only local pattern sector not absorbed into a coherent pair.
- __init__(pattern, weight)#
- class qlinks.caging.LocalCoherentPatternPair(pattern_a, pattern_b, weight, coefficient, relative_phase, hamming_distance, equal_weight_residual, rank_one_residual, is_equal_weight, is_singlet_like)[source]#
Bases:
objectDetected coherent two-pattern sector in a local RDM.
- __init__(pattern_a, pattern_b, weight, coefficient, relative_phase, hamming_distance, equal_weight_residual, rank_one_residual, is_equal_weight, is_singlet_like)#
- class qlinks.caging.LocalMatrixUnitTerm(coefficient, target_pattern, source_pattern)[source]#
Bases:
objectOne local matrix-unit term
coefficient * |target><source|.- __init__(coefficient, target_pattern, source_pattern)#
- class qlinks.caging.LocalPlaquetteActivityReport(plaquette_id, link_ids, local_positions, n_weighted_patterns, n_flippable_patterns, flippable_weight, status)[source]#
Bases:
objectFlippability summary for one plaquette fully contained in a readout.
- __init__(plaquette_id, link_ids, local_positions, n_weighted_patterns, n_flippable_patterns, flippable_weight, status)#
- class qlinks.caging.LocalQDMCageBlock(block_id, record, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts)[source]#
Bases:
objectA placed local QDM cage usable as one independent padding block.
- record: LocalQDMCageRecord#
- __init__(block_id, record, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts)#
- class qlinks.caging.LocalQDMCageRecord(cage_state, signature, candidate, support_configs, local_link_ids, active_plaquette_ids, scoring_plaquette_ids, unresolved_boundary_plaquette_ids)[source]#
Bases:
objectOne local cage certificate.
- candidate: CandidateSubgraph#
- __init__(cage_state, signature, candidate, support_configs, local_link_ids, active_plaquette_ids, scoring_plaquette_ids, unresolved_boundary_plaquette_ids)#
- class qlinks.caging.LocalQDMCageSearchConfig(tolerance=1e-10, allowed_kappas=(0,), min_component_size=2, halo_layers=1, boundary_mode='relaxed', include_sectors_when_full=True, prune_inactive_local_basis_states=False, max_local_states=None, sort_basis=True, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0)[source]#
Bases:
objectConfiguration for the QDM local-first type-1 cage search.
- allowed_kappas#
Kinetic eigenvalues to target. The local-first path is intended for type-1 cages, so the default is
(0,).
- halo_layers#
Number of plaquette-neighbor expansions applied when the search region is supplied by plaquettes. Neighbors share at least one link.
- Type:
- boundary_mode#
"relaxed"enforces exact dimer constraints only at internally complete sites; boundary sites use an at-most constraint."closed"requires all touched sites to be complete and then enforces exact constraints.- Type:
Literal[‘relaxed’, ‘closed’]
- include_sectors_when_full#
If the local link set is the full model link set, also apply model sector conditions during local basis generation.
- Type:
- prune_inactive_local_basis_states#
For genuine local regions, ask DFS to prune branches that can no longer produce a configuration flippable on any active plaquette.
- Type:
- validate_full_residual#
Whether local cage states should be validated against the full local kinetic graph columns.
- Type:
- degenerate_basis_strategy#
How to choose representatives from degenerate local cage subspaces.
- Type:
Literal[‘none’, ‘ipr’]
- __init__(tolerance=1e-10, allowed_kappas=(0,), min_component_size=2, halo_layers=1, boundary_mode='relaxed', include_sectors_when_full=True, prune_inactive_local_basis_states=False, max_local_states=None, sort_basis=True, validate_full_residual=True, degenerate_basis_strategy='none', ipr_n_restarts=128, ipr_max_iter=1000, ipr_step_size=0.1, ipr_candidate_count=64, ipr_rank_completion_patience=None, ipr_batch_size=16, ipr_random_seed=None, deduplicate_by_rank=True, rank_tolerance_factor=100.0, signature_tolerance_factor=10.0, potential_signature_unit=1.0)#
- class qlinks.caging.LocalQDMCageSearchResult(records, region, local_basis, kinetic_matrix, self_loop_values, config, model=None, adapter=None, type1_candidates=<factory>)[source]#
Bases:
objectPassive result contract for a local QDM cage search.
- records: list[LocalQDMCageRecord]#
- region: LocalQDMRegion#
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None = None#
- type1_candidates: list[CandidateSubgraph]#
- __init__(records, region, local_basis, kinetic_matrix, self_loop_values, config, model=None, adapter=None, type1_candidates=<factory>)#
- class qlinks.caging.LocalQDMCageSearcher(model, region, config=<factory>, adapter=None)[source]#
Bases:
LocalCageSearcherBackward-compatible QDM name for
LocalCageSearcher.New code should prefer
LocalCageSearcher. The old name remains as a thin subclass so existing notebooks/tests keep working while the core solver is routed through the model-adapter interface.
- class qlinks.caging.LocalQDMCertificationReport(local_record_index, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)[source]#
Bases:
objectNumerical certificate for one padded local QDM cage.
- padding: LocalQDMPadding#
- __init__(local_record_index, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)#
- class qlinks.caging.LocalQDMMultiPaddingConfig(min_blocks=2, max_blocks=None, max_paddings=1, max_padding_attempts=None, max_paddings_per_packing=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, max_product_support_size=512, require_kinetic_separation=True, sort_limited_basis=True, store_full_states=True)[source]#
Bases:
objectConfiguration for Lego-style multi-block QDM padding.
The multi-block path chooses compatible, disjoint local cage blocks from a pool, solves one shared static exterior for the union of their fixed boundary charges, and then certifies the resulting product state by applying all global QDM flips. Every selected block must have support-independent site counts; otherwise an independent tensor-product block cannot be padded by one shared exterior configuration.
- as_single_padding_config()[source]#
Return the shared options in the single-block padding config form.
- __init__(min_blocks=2, max_blocks=None, max_paddings=1, max_padding_attempts=None, max_paddings_per_packing=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, max_product_support_size=512, require_kinetic_separation=True, sort_limited_basis=True, store_full_states=True)#
- class qlinks.caging.LocalQDMPadding(exterior_link_ids, exterior_config, global_support_configs)[source]#
Bases:
objectOne shared-exterior padding of a local QDM cage record.
- __init__(exterior_link_ids, exterior_config, global_support_configs)#
- class qlinks.caging.LocalQDMPaddingConfig(max_paddings_per_record=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, sort_limited_basis=True, store_full_states=True)[source]#
Bases:
objectConfiguration for global padding/certification of local QDM cages.
The first certification backend is intentionally conservative: it searches for a single shared exterior product configuration that can be tensored with every local support configuration of the cage state. It then verifies the resulting global state by applying all QDM plaquette flips reachable in one kinetic step from the support, keyed by configurations rather than by a globally enumerated Hilbert space.
- __init__(max_paddings_per_record=1, max_dfs_nodes=None, include_sectors=True, require_static_exterior=False, tolerance=1e-10, sort_limited_basis=True, store_full_states=True)#
- class qlinks.caging.LocalQDMRegion(link_ids, seed_plaquette_ids, active_plaquette_ids, scoring_plaquette_ids, closed_site_ids, boundary_site_ids, unresolved_boundary_plaquette_ids)[source]#
Bases:
objectA real-space region used by
LocalQDMCageSearcher.- __init__(link_ids, seed_plaquette_ids, active_plaquette_ids, scoring_plaquette_ids, closed_site_ids, boundary_site_ids, unresolved_boundary_plaquette_ids)#
- class qlinks.caging.LocalReducedDensityMatrix(variable_indices, local_patterns, density_matrix, eigenvalues, support_basis, null_basis)[source]#
Bases:
objectReduced density matrix of a pure state or subspace on selected variables.
- __init__(variable_indices, local_patterns, density_matrix, eigenvalues, support_basis, null_basis)#
- class qlinks.caging.LocalReducedDensityMatrixReadout(variable_indices, reduced_density_matrix, n_matrix_unit_terms, matrix_unit_terms, matrix_unit_terms_truncated, component_index=None, component_id=None, decomposition=None, zero_indices=())[source]#
Bases:
objectNotebook-friendly readout for one local reduced density matrix.
The readout keeps the full
LocalReducedDensityMatrixobject and a truncated local matrix-unit expansion of its density matrix. The optional component metadata is populated when the readout comes from a reduced-IZ frustration-free decomposition of a classification report.- reduced_density_matrix: LocalReducedDensityMatrix#
- matrix_unit_terms: tuple[LocalMatrixUnitTerm, ...]#
- __init__(variable_indices, reduced_density_matrix, n_matrix_unit_terms, matrix_unit_terms, matrix_unit_terms_truncated, component_index=None, component_id=None, decomposition=None, zero_indices=())#
- class qlinks.caging.LocalRegionProposal(*args, **kwargs)[source]#
Bases:
ProtocolProtocol for objects that propose local regions to the local cage searcher.
- __init__(*args, **kwargs)#
- class qlinks.caging.LocalRegionProposalSearchRecord(proposal_index, region_index, region, result, proposal_record=None)[source]#
Bases:
objectResult for one local region emitted by a proposal.
- region: LocalQDMRegion#
- result: LocalQDMCageSearchResult#
- property records: list[LocalQDMCageRecord]#
- __init__(proposal_index, region_index, region, result, proposal_record=None)#
- class qlinks.caging.LocalRegionProposalSearchResult(records)[source]#
Bases:
objectPassive result container for proposal-driven local cage scans.
- records: list[LocalRegionProposalSearchRecord]#
- property local_results: list[LocalQDMCageSearchResult]#
- property cage_records: list[LocalQDMCageRecord]#
- property nonempty_records: list[LocalRegionProposalSearchRecord]#
- __init__(records)#
- class qlinks.caging.LocalStructureReadoutReport(readout, coherent_pairs, classical_sectors, plaquette_activity, offdiagonal_weight, coherent_weight, classical_weight, tolerance)[source]#
Bases:
objectAutomatic structure summary for one local-RDM readout.
- readout: LocalReducedDensityMatrixReadout#
- coherent_pairs: tuple[LocalCoherentPatternPair, ...]#
- classical_sectors: tuple[LocalClassicalPatternSector, ...]#
- plaquette_activity: tuple[LocalPlaquetteActivityReport, ...]#
- __init__(readout, coherent_pairs, classical_sectors, plaquette_activity, offdiagonal_weight, coherent_weight, classical_weight, tolerance)#
- class qlinks.caging.LocalTermOperatorBasis(descriptors, operator_names, operators)[source]#
Bases:
objectBuilt local-term matrices suitable for SGA operator-basis diagnostics.
- descriptors: tuple[LocalTermDescriptor, ...]#
- __init__(descriptors, operator_names, operators)#
- class qlinks.caging.LocalTransitionPattern(source_local, target_local, matrix_element)[source]#
Bases:
objectLocal transition induced by one active edge u -> h.
The local mask represents Omega - Lambda_h.
- __init__(source_local, target_local, matrix_element)#
- class qlinks.caging.LocalWitness(template, variable_indices)[source]#
Bases:
objectOne embedding of a size-independent local witness template.
- template: LocalWitnessTemplate#
- __init__(template, variable_indices)#
- class qlinks.caging.LocalWitnessEmbeddingRecord(system_label, witnesses)[source]#
Bases:
objectAll exact embeddings of one template in one finite system.
- witnesses: tuple[LocalWitness, ...]#
- __init__(system_label, witnesses)#
- class qlinks.caging.LocalWitnessEvaluation(expectation, second_moment, variance, annihilation_residual, normalized_expectation, n_states, effective_state_count, per_state_expectations=(), metadata=<factory>)[source]#
Bases:
objectExpectation and variance of
Q_R = L_R^dagger L_R.- __init__(expectation, second_moment, variance, annihilation_residual, normalized_expectation, n_states, effective_state_count, per_state_expectations=(), metadata=<factory>)#
- class qlinks.caging.LocalWitnessFamily(template, embeddings)[source]#
Bases:
objectOne reduced-IZ local pattern found in several finite systems.
- template: LocalWitnessTemplate#
- embeddings: tuple[LocalWitnessEmbeddingRecord, ...]#
- __init__(template, embeddings)#
- class qlinks.caging.LocalWitnessTemplate(pattern_key, local_patterns, local_operator, source_zero_indices=(), mechanism_labels=(), metadata=<factory>)[source]#
Bases:
objectSize-independent local row operator reconstructed from a reduced-IZ pattern.
The template stores only local configurations and matrix elements. It does not store global variable indices, so the same object can be embedded in several system sizes or translated to several locations.
- mechanism_labels: tuple[Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage'], ...]#
- normalized(normalization='operator_norm')[source]#
Return a canonically normalized copy of the local row operator.
operator_normis the preferred ETH convention because it fixes||Q_R|| = ||L_R||^2 = 1. Thermal expectations are then directly comparable between witnesses and system sizes.
- __init__(pattern_key, local_patterns, local_operator, source_zero_indices=(), mechanism_labels=(), metadata=<factory>)#
- class qlinks.caging.LocalityRestrictedChiralProfileReport(entries, covered_support, uncovered_target_weight, n_regional_target_zero_modes, tolerance)[source]#
Bases:
objectRegional chiral profile for a state under a prescribed locality cover.
- entries: tuple[RegionalChiralIndexEntry, ...]#
- __init__(entries, covered_support, uncovered_target_weight, n_regional_target_zero_modes, tolerance)#
- class qlinks.caging.LocalizedState(local_state, coefficients, support_mask, ipr_value)[source]#
Bases:
objectOne localized vector found inside a degenerate eigenspace.
- __init__(local_state, coefficients, support_mask, ipr_value)#
- class qlinks.caging.ManyBodyCLSCompletenessReport(hilbert_dimension, target_dimension, generator_seed_count, generator_seed_span_dimension, translated_generator_span_dimension, intersection_dimension, quotient_dimension, generator_containment_residual, orbit_entries, target_basis, local_generator_basis, quotient_basis, quotient_projector, tolerance)[source]#
Bases:
objectMany-body analogue of the CLS completeness defect.
target_manifoldis the complete exact cage manifold under study.local_generatorscontains bounded or otherwise locally generated cage seeds. Their full translation orbit spanslocal_generator_basis. If this span is contained in the target manifold, the quotienttarget_manifold / local_generator_spanis the direct many-body counterpart of the flat-band sector missed by translated compact localized states.
A positive quotient dimension is a finite-size completeness defect. It is not, by itself, a topological invariant: persistence along a thermodynamic sequence and a noncontractible or otherwise quantized label must be tested separately.
- orbit_entries: tuple[ManyBodyCLSGeneratorOrbitEntry, ...]#
- __init__(hilbert_dimension, target_dimension, generator_seed_count, generator_seed_span_dimension, translated_generator_span_dimension, intersection_dimension, quotient_dimension, generator_containment_residual, orbit_entries, target_basis, local_generator_basis, quotient_basis, quotient_projector, tolerance)#
- class qlinks.caging.ManyBodyCLSCompletenessSequencePoint(size_label, linear_sizes, target_dimension, local_generator_span_dimension, quotient_dimension, interference_gap=None, exact_open_bond_dimension=None, quotient_sector_signature=())[source]#
Bases:
objectOne system size in a many-body CLS-completeness sequence.
- __init__(size_label, linear_sizes, target_dimension, local_generator_span_dimension, quotient_dimension, interference_gap=None, exact_open_bond_dimension=None, quotient_sector_signature=())#
- class qlinks.caging.ManyBodyCLSCompletenessSequenceReport(model_label, points)[source]#
Bases:
objectFinite-size persistence test for a CLS-completeness defect.
- points: tuple[ManyBodyCLSCompletenessSequencePoint, ...]#
- __init__(model_label, points)#
- class qlinks.caging.ManyBodyCLSGeneratorOrbitEntry(generator_index, orbit_dimension)[source]#
Bases:
objectDimension of the translation orbit generated by one local cage seed.
- __init__(generator_index, orbit_dimension)#
- class qlinks.caging.ManyBodyCLSTranslationSector(momentum_indices, momenta, target_multiplicity, local_generator_multiplicity, quotient_multiplicity)[source]#
Bases:
objectMultiplicity of one Abelian translation character.
- __init__(momentum_indices, momenta, target_multiplicity, local_generator_multiplicity, quotient_multiplicity)#
- class qlinks.caging.ManyBodyTopologicalLocalizationReport(completeness, translation_orders, target_translation_residual, local_translation_residual, quotient_translation_residual, translation_commutator_residual, sectors, quotient_characters, tolerance)[source]#
Bases:
objectCLS-completeness defect resolved under commuting translations.
This report deliberately uses the term
candidaterather than assigning a winding number automatically. Momentum resolution is well defined from the translation representation, while a real-space homology class requires additional geometric information about how a quotient state winds around the physical torus.- completeness: ManyBodyCLSCompletenessReport#
- sectors: tuple[ManyBodyCLSTranslationSector, ...]#
- __init__(completeness, translation_orders, target_translation_residual, local_translation_residual, quotient_translation_residual, translation_commutator_residual, sectors, quotient_characters, tolerance)#
- class qlinks.caging.MicrocanonicalWindowSelection(indices, target_energy, half_width, energy_min, energy_max, mean_energy, center_offset)[source]#
Bases:
objectA finite-size energy window selected around a target energy.
- __init__(indices, target_energy, half_width, energy_min, energy_max, mean_energy, center_offset)#
- class qlinks.caging.MicrocanonicalWitnessEvaluation(evaluation, shell_indices, energy_center, half_width, shell_energy_min, shell_energy_max, mean_energy, mean_energy_density)[source]#
Bases:
objectLocal-witness evaluation in a finite-size microcanonical shell.
- evaluation: LocalWitnessEvaluation#
- __init__(evaluation, shell_indices, energy_center, half_width, shell_energy_min, shell_energy_max, mean_energy, mean_energy_density)#
- class qlinks.caging.MotifRadiusHomologyPoint(radius, generator_rank, h1_dimension, h2_dimension, chain_residual, hodge_gap)[source]#
Bases:
objectOne motif-radius point in a local-generator saturation scan.
- __init__(radius, generator_rank, h1_dimension, h2_dimension, chain_residual, hodge_gap)#
- class qlinks.caging.MotifRadiusSaturationReport(points, plateau_length=2, tolerance=1e-10)[source]#
Bases:
objectTrack whether
nu_MBstabilizes as the motif library grows.- points: tuple[MotifRadiusHomologyPoint, ...]#
- __init__(points, plateau_length=2, tolerance=1e-10)#
- class qlinks.caging.MultiLocalQDMCertificationReport(block_ids, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)[source]#
Bases:
objectNumerical certificate for one multi-block QDM padding.
- padding: MultiLocalQDMPadding#
- __init__(block_ids, padding_index, signature, energy, kinetic_eigenvalue, self_loop_value, support_size, one_hop_shell_size, leakage_residual, support_kinetic_residual, support_hamiltonian_residual, full_residual, padding, leakage_configs)#
- class qlinks.caging.MultiLocalQDMPadding(block_ids, exterior_link_ids, exterior_config, global_support_configs, global_amplitudes, block_support_indices)[source]#
Bases:
objectOne shared-exterior padding for a product of several local QDM blocks.
- __init__(block_ids, exterior_link_ids, exterior_config, global_support_configs, global_amplitudes, block_support_indices)#
- class qlinks.caging.OperatorCoefficientCompatibilityReport(n_operators, target_dimension, mode, rank, compatible_dimension, singular_gap, constraint_matrix, compatible_basis, singular_values, tolerance)[source]#
Bases:
objectLinear coefficient space preserving vectors or their common subspace.
- __init__(n_operators, target_dimension, mode, rank, compatible_dimension, singular_gap, constraint_matrix, compatible_basis, singular_values, tolerance)#
- class qlinks.caging.OperatorStateActionDiagnostic(name, action_norm, relative_action_norm, eigenvalue, eigen_residual, relative_eigen_residual, annihilates_state, is_eigen_operator)[source]#
Bases:
objectAction of one candidate operator on the target state.
- __init__(name, action_norm, relative_action_norm, eigenvalue, eigen_residual, relative_eigen_residual, annihilates_state, is_eigen_operator)#
- class qlinks.caging.PeriodicBoundaryCancellationScalingReport(n_rows_per_cell, n_columns_per_cell, coupling_displacements, points, tolerance)[source]#
Bases:
objectThermodynamic diagnostic for a finite-range periodic boundary family.
The repeated boundary map is block circulant,
B_N = I_N tensor B_0 + sum_d S_N**d tensor C_d.A discrete Fourier transform decomposes it into small Bloch symbols
B(k) = B_0 + sum_d exp(i k d) C_d. The global weighted dependency, regional dependency, and relative dependency dimensions are therefore exact sums of the corresponding symbol dimensions. This avoids constructing the exponentially large many-body Hilbert space and isolates whether the collective cancellation class forms an extensive flat zero band, survives only at isolated momenta, or is fully lifted by a local repeated coupling.- points: tuple[BoundaryCancellationScalingPoint, ...]#
- estimate_positive_relative_gap_exponent(*, minimum_repeats=0)[source]#
Fit the positive relative gap after an optional finite-size cutoff.
- __init__(n_rows_per_cell, n_columns_per_cell, coupling_displacements, points, tolerance)#
- class qlinks.caging.PerturbationCompatibilityDiagnostic(perturbation_index, boundary_residual, eigenvector_residual, first_order_boundary_obstruction_residual, first_order_eigenstate_obstruction_residual, preserves_state, first_order_boundary_compatible, first_order_eigenstate_compatible)[source]#
Bases:
objectCompatibility of one perturbation with a selected cage vector.
- __init__(perturbation_index, boundary_residual, eigenvector_residual, first_order_boundary_obstruction_residual, first_order_eigenstate_obstruction_residual, preserves_state, first_order_boundary_compatible, first_order_eigenstate_compatible)#
- class qlinks.caging.QDMBiperiodicInstanceCertificate(repeats_x, repeats_y, block_certificates, seam_diagnostics, energy, winding_sector, tolerance)[source]#
Bases:
objectExact local-decomposition check for one finite tile array.
- block_certificates: tuple[QDMIndependentBlockCertificate, ...]#
- seam_diagnostics: QDMBiperiodicSeamDiagnostics#
- __init__(repeats_x, repeats_y, block_certificates, seam_diagnostics, energy, winding_sector, tolerance)#
- class qlinks.caging.QDMBiperiodicPlacedBlock(block_id, source_block_id, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts_by_support)[source]#
Bases:
objectOne translated tile block, retaining support-dependent boundary charge.
- __init__(block_id, source_block_id, link_ids, active_plaquette_ids, guard_plaquette_ids, support_configs, amplitudes, site_counts_by_support)#
- class qlinks.caging.QDMBiperiodicSeamDiagnostics(plaquette_counts, inert_pattern_checks, flippable_inert_patterns, multi_block_plaquettes, max_site_constraint_residuals)[source]#
Bases:
objectPlaquette and dimer-constraint diagnostics grouped by tile boundary class.
- __init__(plaquette_counts, inert_pattern_checks, flippable_inert_patterns, multi_block_plaquettes, max_site_constraint_residuals)#
- class qlinks.caging.QDMBlockProductSubspaceReport(block_ids, block_support_sizes, padding, support_hamiltonian, leakage_matrix, leakage_output_configs, leakage_rank, leakage_nullity, product_energy, product_residual, exact_states, tolerance)[source]#
Bases:
objectHamiltonian closure diagnostic for one finite block-product support.
leakage_matrixmaps coefficient vectors onglobal_support_configsto all one-hop configurations outside that support. Thereforeleakage_nullity == 0rules out not only the independent product state, but every correlated coefficient tensor on the same local singlet labels.- padding: MultiLocalQDMPadding#
- exact_states: tuple[QDMProductSubspaceEigenstate, ...]#
- property is_ruled_out_within_product_support: bool#
Whether no coefficient tensor can cancel the external leakage.
- property requires_enlarged_local_basis: bool#
Whether an MPS/PEPS over the current singlet labels cannot work.
- __init__(block_ids, block_support_sizes, padding, support_hamiltonian, leakage_matrix, leakage_output_configs, leakage_rank, leakage_nullity, product_energy, product_residual, exact_states, tolerance)#
- class qlinks.caging.QDMBoundaryResolvedTileBasis(region, configurations, boundary_site_ids, boundary_deficits, unique_boundary_signatures, signature_indices, local_hamiltonian)[source]#
Bases:
objectFinite local QDM basis resolved by the dimer deficit at boundary sites.
A signature entry is the number of dimers that must be supplied by links outside the tile. These signatures are the natural virtual labels for a constrained tensor network.
- region: LocalQDMRegion#
- __init__(region, configurations, boundary_site_ids, boundary_deficits, unique_boundary_signatures, signature_indices, local_hamiltonian)#
- class qlinks.caging.QDMCompactCageReducedWindingPoint(repeats, system_size, support_size, shell_size, state_complement, kinetic_term_count, kinetic_compatible_dimension, kinetic_quotient_dimension, kinetic_quotient_singular_values, kinetic_quotient_gap, local_pair_offsets, intercell_gram_norm, unit_cell_gram_residual)[source]#
Bases:
objectReduced state- and coupling-space data for one fixed-width member.
- state_complement: ReducedConstraintFredholmCandidateReport#
- __init__(repeats, system_size, support_size, shell_size, state_complement, kinetic_term_count, kinetic_compatible_dimension, kinetic_quotient_dimension, kinetic_quotient_singular_values, kinetic_quotient_gap, local_pair_offsets, intercell_gram_norm, unit_cell_gram_residual)#
- class qlinks.caging.QDMCompactCageReducedWindingReport(repeat_axis, unit_cell_size, local_pair_offsets, reduced_coupling_symbol, reduced_coupling_winding, reduced_coupling_gap, points, classification, tolerance)[source]#
Bases:
objectFredholm-winding audit of the compact square-QDM cage sequence.
- points: tuple[QDMCompactCageReducedWindingPoint, ...]#
- __init__(repeat_axis, unit_cell_size, local_pair_offsets, reduced_coupling_symbol, reduced_coupling_winding, reduced_coupling_gap, points, classification, tolerance)#
- class qlinks.caging.QDMCyclicColumnGrammar(circumference, reference_length, window_size, symbols, allowed_windows)[source]#
Bases:
objectFinite-range column grammar inferred from square-QDM support states.
A column symbol stores
(incoming_mask, outgoing_mask, vertical_mask)on a fixed-circumference cylinder.allowed_windowscontains every cyclic window ofwindow_sizecolumns observed in the reference support.- __init__(circumference, reference_length, window_size, symbols, allowed_windows)#
- class qlinks.caging.QDMCyclicGrammarSupport(length, words, configs, potential_value)[source]#
Bases:
objectExplicit finite support generated by one cyclic column grammar.
- __init__(length, words, configs, potential_value)#
- class qlinks.caging.QDMExplicitProductSupport(configs, amplitudes, block_support_indices)[source]#
Bases:
objectMaterialized finite support of a factorized periodic QDM cage.
This object is intentionally limited to moderate product supports. It is used to verify the physical finite-size boundary map without enumerating the full constrained Hilbert space.
- __init__(configs, amplitudes, block_support_indices)#
- class qlinks.caging.QDMExplicitSupportBoundaryMap(support_configs, shell_configs, boundary)[source]#
Bases:
objectOne-hop QDM boundary map built from an explicit support only.
- boundary: csr_matrix#
- __init__(support_configs, shell_configs, boundary)#
- class qlinks.caging.QDMFactorizedProductCertificationReport(block_ids, padding, support_size, kinetic_eigenvalue, self_loop_value, energy, kinetic_residual, potential_residual, hamiltonian_residual, signature, n_kinetic_product_terms, n_potential_product_terms, max_blocks_touched_by_plaquette, sector_validation, failure_reason=None)[source]#
Bases:
objectPolynomial-cost certificate for a separated product of QDM cage blocks.
- padding: FactorizedLocalQDMPadding#
- __init__(block_ids, padding, support_size, kinetic_eigenvalue, self_loop_value, energy, kinetic_residual, potential_residual, hamiltonian_residual, signature, n_kinetic_product_terms, n_potential_product_terms, max_blocks_touched_by_plaquette, sector_validation, failure_reason=None)#
- class qlinks.caging.QDMIndependentBlockCertificate(block_id, n_plaquettes, kinetic_eigenvalue, potential_eigenvalue, kinetic_residual, potential_residual, leakage_residual)[source]#
Bases:
objectLocal eigenvalue certificate for one coherent product factor.
- __init__(block_id, n_plaquettes, kinetic_eigenvalue, potential_eigenvalue, kinetic_residual, potential_residual, leakage_residual)#
- class qlinks.caging.QDMLocalCageAdapter(model, source_label='qdm')[source]#
Bases:
objectQDM implementation of the local variable interface.
This is intentionally the only place where the generic local searcher needs to know how QDM variables/plaquette flips are represented. Later QLM/PXP adapters can implement the same protocol without modifying the solver core.
- build_region_from_links(*, link_ids, config, active_plaquette_ids=None, scoring_plaquette_ids=None)[source]#
- __init__(model, source_label='qdm')#
- class qlinks.caging.QDMLocalGrammarExtensionPoint(window_size, length, support_size, shell_size, boundary_nullity, nullity_is_resolved, interference_gap, product_translation_span_dimension, kernel_product_intersection_dimension, collective_quotient_dimension, product_containment_residual, principal_overlaps, localized_support_sizes, localized_iprs)[source]#
Bases:
objectOne fixed-width extension test for a collective cage support grammar.
- property locality_extension_index: int#
Integer dimension of non-product cage modes in this local language.
- __init__(window_size, length, support_size, shell_size, boundary_nullity, nullity_is_resolved, interference_gap, product_translation_span_dimension, kernel_product_intersection_dimension, collective_quotient_dimension, product_containment_residual, principal_overlaps, localized_support_sizes, localized_iprs)#
- class qlinks.caging.QDMLocalGrammarExtensionReport(reference_length, circumference, points, tolerance)[source]#
Bases:
objectFixed-width locality test for a non-factorized collective extension.
- points: tuple[QDMLocalGrammarExtensionPoint, ...]#
- __init__(reference_length, circumference, points, tolerance)#
- class qlinks.caging.QDMLocalKineticCompatibilityReport(plaquette_ids, obstruction_matrix, singular_values, rank, compatible_dimension, active_plaquette_ids, equal_coupling_pairs, singular_gap, tolerance)[source]#
Bases:
objectCompatibility of independent plaquette kinetic couplings for one state.
- __init__(plaquette_ids, obstruction_matrix, singular_values, rank, compatible_dimension, active_plaquette_ids, equal_coupling_pairs, singular_gap, tolerance)#
- class qlinks.caging.QDMLocalPotentialCompatibilityReport(plaquette_ids, obstruction_matrix, rank, compatible_dimension, varying_plaquette_ids, tolerance)[source]#
Bases:
objectUniform-on-support test for independent plaquette potential couplings.
- __init__(plaquette_ids, obstruction_matrix, rank, compatible_dimension, varying_plaquette_ids, tolerance)#
- class qlinks.caging.QDMMultiPaddingDiagnostics(paddings, reports, failures, config, padding_attempts=None, first_certified_padding_index=None)[source]#
Bases:
objectCertification diagnostics for a pool of multi-block padding candidates.
- paddings: list[MultiLocalQDMPadding]#
- reports: list[MultiLocalQDMCertificationReport]#
- failures: list[QDMMultiPaddingFailureReport]#
- config: LocalQDMMultiPaddingConfig#
- property leakage_failure_counts_by_class: dict[str, int]#
Count leakage failures by their dominant plaquette class.
- property leakage_failure_norms_by_class: dict[str, float]#
Sum leakage norms by plaquette class over all leakage failures.
- __init__(paddings, reports, failures, config, padding_attempts=None, first_certified_padding_index=None)#
- class qlinks.caging.QDMMultiPaddingFailureReport(block_ids, padding_index, reason, padding, leakage_residual=None, support_kinetic_residual=None, support_hamiltonian_residual=None, full_residual=None, leakage_counts_by_class=<factory>, leakage_norms_by_class=<factory>)[source]#
Bases:
objectReason one candidate multi-block padding failed certification.
- padding: MultiLocalQDMPadding#
- property dominant_leakage_class: str | None#
Return the plaquette class with the largest leakage norm, if known.
- __init__(block_ids, padding_index, reason, padding, leakage_residual=None, support_kinetic_residual=None, support_hamiltonian_residual=None, full_residual=None, leakage_counts_by_class=<factory>, leakage_norms_by_class=<factory>)#
- class qlinks.caging.QDMPeriodicInstanceCertificate(repeats, block_certificates, n_exterior_only_plaquettes, n_multi_block_plaquettes, n_inert_pattern_checks, n_flippable_inert_patterns, max_site_constraint_residual, energy, winding_sector, tolerance)[source]#
Bases:
objectLocal-decomposition certificate for one finite repeated instance.
- block_certificates: tuple[QDMIndependentBlockCertificate, ...]#
- __init__(repeats, block_certificates, n_exterior_only_plaquettes, n_multi_block_plaquettes, n_inert_pattern_checks, n_flippable_inert_patterns, max_site_constraint_residual, energy, winding_sector, tolerance)#
- class qlinks.caging.QDMPhysicalCancellationScalingPoint(repeats, system_size, n_blocks, support_size, shell_size, n_boundary_transitions, boundary_rank, boundary_nullity, interference_gap, product_state_boundary_residual, product_state_kernel_weight, kinetic_compatibility, potential_compatibility)[source]#
Bases:
objectExact finite-support cancellation data for one periodic product member.
- kinetic_compatibility: QDMLocalKineticCompatibilityReport#
- potential_compatibility: QDMLocalPotentialCompatibilityReport#
- __init__(repeats, system_size, n_blocks, support_size, shell_size, n_boundary_transitions, boundary_rank, boundary_nullity, interference_gap, product_state_boundary_residual, product_state_kernel_weight, kinetic_compatibility, potential_compatibility)#
- class qlinks.caging.QDMPhysicalCancellationScalingReport(repeat_axis, unit_cell_size, support_size_per_unit_cell, points, tolerance)[source]#
Bases:
objectPhysical finite-size scaling for a certified periodic QDM product cage.
- points: tuple[QDMPhysicalCancellationScalingPoint, ...]#
- __init__(repeat_axis, unit_cell_size, support_size_per_unit_cell, points, tolerance)#
- class qlinks.caging.QDMProductSubspaceEigenstate(energy, coefficients, residual)[source]#
Bases:
objectOne exact eigenvector found inside a selected block-product support.
- __init__(energy, coefficients, residual)#
- class qlinks.caging.QDMSingletTNProblem(physical_dimensions, support_hamiltonian, leakage_matrix, reference_coefficients, tolerance=1e-10, metadata=<factory>)[source]#
Bases:
objectBackend-neutral finite objective for a singlet-label TN ansatz.
This object is useful for prototyping MPS/PEPS optimizers with an external tensor-network package. It also states a rigorous limitation: when
leakage_nullity == 0, increasing the bond dimension while keeping the same physical singlet label cannot yield an exact state. The local physical basis must first be enlarged, e.g. by adding halo/boundary configurations.- loss(coefficients, *, energy=None)[source]#
Return
||Kc||² + ||Hc-Ec||²for a normalized dense vector.
- to_quimb_mps(coefficients=None, *, max_bond=None, cutoff=0.0)[source]#
Convert a dense coefficient tensor to a quimb MPS.
This bridge is intended for diagnostics and initialization. It does not imply that the current physical support is sufficient for an exact state; check
requires_enlarged_local_basisfirst.
- __init__(physical_dimensions, support_hamiltonian, leakage_matrix, reference_coefficients, tolerance=1e-10, metadata=<factory>)#
- class qlinks.caging.Quasi1DAuditReport(points, energy_density_mismatch, thermal_comparison, level_gap_ratio, zero_mode_fraction, issues, established, tolerance)[source]#
Bases:
objectConservative assessment of what a fixed-width sequence establishes.
- points: tuple[Quasi1DSequencePoint, ...]#
- __init__(points, energy_density_mismatch, thermal_comparison, level_gap_ratio, zero_mode_fraction, issues, established, tolerance)#
- class qlinks.caging.Quasi1DSequencePoint(length, width, exact_residual, witness_radius, transverse_witness_span=None, thermal_second_moment=None, interference_gap=None, compatibility_rank=None, local_parameter_count=None, support_size=None, sector_dimension=None, metadata=<factory>)[source]#
Bases:
objectOne system-size point entering a fixed-width thermodynamic audit.
- __init__(length, width, exact_residual, witness_radius, transverse_witness_span=None, thermal_second_moment=None, interference_gap=None, compatibility_rank=None, local_parameter_count=None, support_size=None, sector_dimension=None, metadata=<factory>)#
- class qlinks.caging.RandomCageStabilityAggregate(strength, n_samples, n_survived, survival_fraction, minimum_interference_gap, median_interference_gap, median_projector_distance, median_minimum_principal_overlap)[source]#
Bases:
objectAggregate random-ensemble statistics at one perturbation strength.
- __init__(strength, n_samples, n_survived, survival_fraction, minimum_interference_gap, median_interference_gap, median_projector_distance, median_minimum_principal_overlap)#
- class qlinks.caging.RandomCageStabilityReport(support, reference_dimension, minimum_subspace_overlap, samples, aggregates, random_seed, tolerance)[source]#
Bases:
objectRandom compatible- or control-perturbation ensemble report.
- samples: tuple[RandomCageStabilitySample, ...]#
- aggregates: tuple[RandomCageStabilityAggregate, ...]#
- __init__(support, reference_dimension, minimum_subspace_overlap, samples, aggregates, random_seed, tolerance)#
- class qlinks.caging.RandomCageStabilitySample(strength, sample_index, coefficients, boundary_nullity, invariant_cage_dimension, interference_gap, minimum_principal_overlap, projector_distance_from_reference, fixed_state_full_residual, preserves_dimension, follows_reference_subspace, cage_survives)[source]#
Bases:
objectOne random multi-parameter deformation sample.
- __init__(strength, sample_index, coefficients, boundary_nullity, invariant_cage_dimension, interference_gap, minimum_principal_overlap, projector_distance_from_reference, fixed_state_full_residual, preserves_dimension, follows_reference_subspace, cage_survives)#
- class qlinks.caging.RealLocalSignObstructionReport(window_size, n_words, n_local_windows, incidence_rank_mod2, augmented_rank_mod2, obstruction_dimension, magnitude_factorization_residual, real_structure_residual, obstruction_witness, local_sign_solution)[source]#
Bases:
objectMod-two obstruction to a real finite-range local sign factorization.
For cyclic support words
wand real nonzero amplitudespsi_w, letN[w, e]count occurrences of each local column windowe. A real scalar local phase rule exists when the sign bits obeyN s = sign(psi) (mod 2).The cokernel class of the sign vector is discrete. It can change only if an amplitude crosses zero, the support language changes, or the real structure is abandoned.
- __init__(window_size, n_words, n_local_windows, incidence_rank_mod2, augmented_rank_mod2, obstruction_dimension, magnitude_factorization_residual, real_structure_residual, obstruction_witness, local_sign_solution)#
- class qlinks.caging.RealSpaceSupportMorphology(label='unknown', n_variables=0, active_variable_indices=(), active_variable_count=0, active_variable_fraction=0.0, frozen_variable_count=0, reduced_iz_region_variable_indices=(), reduced_iz_region_variable_count=0, reduced_iz_region_variable_fraction=0.0, exact_support_component_count=0, exact_support_component_sizes=(), connected_support_component_count=0, connected_support_component_sizes=())[source]#
Bases:
objectFinite-size morphology diagnostics in the microscopic variable space.
The variable indices are model-layout indices. Connectivity, diameter, and winding/wrapping require lattice adjacency metadata and are therefore left to higher-level lattice-aware helpers.
- __init__(label='unknown', n_variables=0, active_variable_indices=(), active_variable_count=0, active_variable_fraction=0.0, frozen_variable_count=0, reduced_iz_region_variable_indices=(), reduced_iz_region_variable_count=0, reduced_iz_region_variable_fraction=0.0, exact_support_component_count=0, exact_support_component_sizes=(), connected_support_component_count=0, connected_support_component_sizes=())#
- class qlinks.caging.ReducedConstraintFredholmCandidateReport(codomain_dimension, domain_dimension, kernel_dimension, reduced_domain_dimension, reduced_rank, codomain_excess, reduced_singular_values, reduced_gap, canonical_log_abs_determinant, canonical_determinant_phase, is_reduced_injective, is_square_symbol_candidate, classification, tolerance)[source]#
Bases:
objectReduced constraint map after quotienting a known exact kernel.
The report deliberately distinguishes a square Fredholm-symbol candidate from a strictly rectangular injective map. For a tall complex map, the polar part takes values in a complex Stiefel manifold with trivial first homotopy group, so a determinant winding is not intrinsic without an additional choice of codomain frame.
- __init__(codomain_dimension, domain_dimension, kernel_dimension, reduced_domain_dimension, reduced_rank, codomain_excess, reduced_singular_values, reduced_gap, canonical_log_abs_determinant, canonical_determinant_phase, is_reduced_injective, is_square_symbol_candidate, classification, tolerance)#
- class qlinks.caging.ReducedIZMonitorComponentGroup(component_id, decomposition, zero_indices, support_variables, state_action_vector=<factory>)[source]#
Bases:
objectCached report-side plan for one reduced-IZ monitor component.
The construction layer can consume these groups directly instead of rediscovering reduced-IZ supports and frustration-free decompositions. When available,
state_action_vectorstores the cached action of this component monitor on the classified cage state.- __init__(component_id, decomposition, zero_indices, support_variables, state_action_vector=<factory>)#
- class qlinks.caging.ReducedIZPatternSupport(pattern_key, variable_indices, source_zero_indices, mechanism_labels)[source]#
Bases:
objectOne distinct reduced IZ local pattern and the variables it uses.
- mechanism_labels: tuple[Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage'], ...]#
- __init__(pattern_key, variable_indices, source_zero_indices, mechanism_labels)#
- class qlinks.caging.ReducedIZProbeSupport(zero_index, mechanism_label, variable_indices, local_region_size, complement_action_norm, reduced_action_norm, n_local_transitions, n_complement_targets, n_unexplained_complement_targets)[source]#
Bases:
objectCached support data for one reduced IZ probe
Z_h^(R).- mechanism_label: Literal['q_empty', 'closed_by_known_zeros', 'domain_blocked', 'projector_like', 'collective_cancellation', 'unexplained_leakage']#
- __init__(zero_index, mechanism_label, variable_indices, local_region_size, complement_action_norm, reduced_action_norm, n_local_transitions, n_complement_targets, n_unexplained_complement_targets)#
- class qlinks.caging.RegionalCageQuotientReport(target_dimension, regional_span_dimension, intersection_dimension, quotient_dimension, inclusion_residual, quotient_basis, quotient_projector, tolerance)[source]#
Bases:
objectRelative quotient of a target cage manifold by regional kernels.
The quotient is represented canonically by the component of the target manifold orthogonal to the regional-kernel span. It is therefore basis-independent up to a unitary rotation within the quotient itself.
- __init__(target_dimension, regional_span_dimension, intersection_dimension, quotient_dimension, inclusion_residual, quotient_basis, quotient_projector, tolerance)#
- class qlinks.caging.RegionalChiralIndexEntry(region_index, support, active_boundary_size, chiral_index, target_weight, target_boundary_residual, target_is_regional_zero_mode)[source]#
Bases:
objectChiral-index and zero-mode data for one selected support region.
- chiral_index: ChiralIndexReport#
- __init__(region_index, support, active_boundary_size, chiral_index, target_weight, target_boundary_residual, target_is_regional_zero_mode)#
- class qlinks.caging.RegionalChiralKernelSpanReport(n_regions, regional_raw_kernel_dimension, regional_span_dimension, target_dimension, principal_overlaps, captured_target_dimension, uncaptured_target_dimension, target_projector_residual, tolerance)[source]#
Bases:
objectBasis-independent overlap of a target manifold with regional kernels.
- __init__(n_regions, regional_raw_kernel_dimension, regional_span_dimension, target_dimension, principal_overlaps, captured_target_dimension, uncaptured_target_dimension, target_projector_residual, tolerance)#
- class qlinks.caging.RelativeMod2CycleReport(full_cycle_dimension, regional_cycle_span_dimension, relative_cycle_dimension, n_edges, n_regions, full_cycle_basis, regional_cycle_basis, relative_cycle_basis, edge_labels, tolerance)[source]#
Bases:
objectRelative cycle space of a full boundary graph modulo regional cycles.
- __init__(full_cycle_dimension, regional_cycle_span_dimension, relative_cycle_dimension, n_edges, n_regions, full_cycle_basis, regional_cycle_basis, relative_cycle_basis, edge_labels, tolerance)#
- class qlinks.caging.RobustQDMLocalCageSearchConfig(local_config=<factory>, region_strategies=('stripe', 'snake_stripe', 'connected', 'adaptive'), max_region_plaquettes=6, min_region_plaquettes=1, max_region_links=None, max_regions_per_strategy=128, stripe_motif_sizes=(2, 3), stripe_motif_sources=('stripe', 'snake_stripe'), stripe_motif_subset_mode='all', stripe_motif_max_motifs_per_stripe=None, stripe_motif_component_sizes=None, stripe_motif_component_subset_mode='full', stripe_motif_component_min_seed_motifs=1, stripe_motif_component_max_seed_motifs_per_stripe=None, stripe_motif_component_max_components_per_stripe=1, stripe_motif_component_motif_signatures=None, stripe_widths=(1, 2), stripe_directions=None, snake_stripe_max_turns=None, snake_stripe_allow_kind_changes=False, snake_stripe_kind_pattern='constant_or_alternating', snake_stripe_require_induced_cycle=False, snake_stripe_plaquette_kinds=None, snake_stripe_winding_vectors=None, adaptive_beam_width=8, adaptive_branch_factor=8, adaptive_seed_plaquette_ids=None, adaptive_use_search_feedback=False, block_signatures=None, max_records_per_region=2, max_blocks=4, min_blocks=1, max_product_support_size=2048, max_paddings_per_stage=64, max_padding_attempts_per_stage=None, max_paddings_per_packing=4, max_dfs_nodes=None, include_sectors=True, padding_stages=('loose', 'static', 'strict'), tolerance=1e-09, sort_limited_basis=True, store_full_states=True, skip_incompatible_blocks=True)[source]#
Bases:
objectBudget-oriented configuration for robust local QDM cage discovery.
This config intentionally exposes budgets and strategy choices rather than delicate geometry assumptions.
robust_qdm_local_cage_searchuses a portfolio of region proposals, collects compatible local-cage blocks, then runs a schedule of permissive-to-strict multi-block padding configurations and lets global certification decide which candidates survive.- local_config: LocalQDMCageSearchConfig#
- __init__(local_config=<factory>, region_strategies=('stripe', 'snake_stripe', 'connected', 'adaptive'), max_region_plaquettes=6, min_region_plaquettes=1, max_region_links=None, max_regions_per_strategy=128, stripe_motif_sizes=(2, 3), stripe_motif_sources=('stripe', 'snake_stripe'), stripe_motif_subset_mode='all', stripe_motif_max_motifs_per_stripe=None, stripe_motif_component_sizes=None, stripe_motif_component_subset_mode='full', stripe_motif_component_min_seed_motifs=1, stripe_motif_component_max_seed_motifs_per_stripe=None, stripe_motif_component_max_components_per_stripe=1, stripe_motif_component_motif_signatures=None, stripe_widths=(1, 2), stripe_directions=None, snake_stripe_max_turns=None, snake_stripe_allow_kind_changes=False, snake_stripe_kind_pattern='constant_or_alternating', snake_stripe_require_induced_cycle=False, snake_stripe_plaquette_kinds=None, snake_stripe_winding_vectors=None, adaptive_beam_width=8, adaptive_branch_factor=8, adaptive_seed_plaquette_ids=None, adaptive_use_search_feedback=False, block_signatures=None, max_records_per_region=2, max_blocks=4, min_blocks=1, max_product_support_size=2048, max_paddings_per_stage=64, max_padding_attempts_per_stage=None, max_paddings_per_packing=4, max_dfs_nodes=None, include_sectors=True, padding_stages=('loose', 'static', 'strict'), tolerance=1e-09, sort_limited_basis=True, store_full_states=True, skip_incompatible_blocks=True)#
- class qlinks.caging.RobustQDMLocalCageSearchContext(config, scan, blocks, padding_config, diagnostics_by_stage)[source]#
Bases:
objectDebug context for
robust_qdm_local_cage_search().The ordinary robust search returns a
CertifiedLocalQDMCageSearchResultso downstream tools can consume it directly. Whenreturn_context=True, this companion object exposes the intermediate proposal scan, block pool, and per-padding-stage diagnostics that explain where candidates were found or rejected.- config: RobustQDMLocalCageSearchConfig#
- blocks: list[LocalQDMCageBlock]#
- padding_config: LocalQDMMultiPaddingConfig#
- diagnostics_by_stage: dict[str, QDMMultiPaddingDiagnostics]#
- property reports_by_stage: dict[str, list[MultiLocalQDMCertificationReport]]#
- property reports: list[MultiLocalQDMCertificationReport]#
- __init__(config, scan, blocks, padding_config, diagnostics_by_stage)#
- class qlinks.caging.SGALadderBasisDiagnostic(frequency, operator_names, energies, state_eigen_residuals, gram_residual, constraint_matrix_shape, constraint_rank, ladder_nullity, singular_values, ladder_coefficients, ladder_residuals, candidate_diagnostics, tolerance, frequency_tolerance)[source]#
Bases:
objectNullspace search for SGA-like ladders in an operator basis.
The constraint matrix encodes two requirements for
Q=sum_a c_a O_a:Qmaps the supplied manifold back into itself.the projected action only connects states with
E_target-E_sourceequal tofrequency.
The returned coefficient columns are candidate analytical ladder operators in the supplied basis.
- candidate_diagnostics: tuple[SGAOperatorDiagnostic, ...]#
- __init__(frequency, operator_names, energies, state_eigen_residuals, gram_residual, constraint_matrix_shape, constraint_rank, ladder_nullity, singular_values, ladder_coefficients, ladder_residuals, candidate_diagnostics, tolerance, frequency_tolerance)#
- class qlinks.caging.SGAOperatorDiagnostic(operator_name, frequency, energies, state_eigen_residuals, gram_residual, projected_action, projected_action_norm, total_action_norm, in_frequency_action_norm, off_frequency_action_norm, leakage_norm, relative_leakage_norm, relative_off_frequency_norm, algebra_residual_norm, relative_algebra_residual_norm, transitions, tolerance, frequency_tolerance)[source]#
Bases:
objectDiagnostic for one operator as an approximate SGA ladder on a manifold.
- transitions: tuple[SGATransition, ...]#
- __init__(operator_name, frequency, energies, state_eigen_residuals, gram_residual, projected_action, projected_action_norm, total_action_norm, in_frequency_action_norm, off_frequency_action_norm, leakage_norm, relative_leakage_norm, relative_off_frequency_norm, algebra_residual_norm, relative_algebra_residual_norm, transitions, tolerance, frequency_tolerance)#
- class qlinks.caging.SGATransition(target_index, source_index, energy_difference, amplitude, weight)[source]#
Bases:
objectOne sizeable projected transition induced by a candidate ladder operator.
- __init__(target_index, source_index, energy_difference, amplitude, weight)#
- class qlinks.caging.SameBipartitionSideFilter[source]#
Bases:
objectRequire the whole support to lie on one bipartite subset.
- __init__()#
- class qlinks.caging.ScalarLaurentBulkPhaseReport(transport, root_modulus, unit_circle_gap, winding_number, toeplitz_index, is_fredholm, localization_length, tolerance)[source]#
Bases:
objectFredholm phase data for a scalar first-order Laurent constraint.
The local relation is
psi[j + 1] = transport * psi[j]with symbolb(z) = z - transport. Whenabs(transport) != 1the symbol is nonzero on the unit circle and its winding is well defined. Unit-modulus transport lies exactly on the non-Fredholm transition locus.- __init__(transport, root_modulus, unit_circle_gap, winding_number, toeplitz_index, is_fredholm, localization_length, tolerance)#
- class qlinks.caging.ScalarLaurentDomainWallReport(left_bulk, right_bulk, left_length, right_length, constraint_matrix, kernel_dimension, kernel_basis, canonical_mode, residual, inverse_participation_ratio, interface_site_weight, interface_window_weight, center_of_mass, predicted_right_interface_modes, predicted_left_interface_modes, is_exponentially_interface_localized, classification, tolerance)[source]#
Bases:
objectFinite-chain domain wall between two scalar Laurent constraints.
Sites are arranged as
left_lengthbonds, one interface site, andright_lengthbonds. The constraint matrix imposes the left transport on bonds to the left of the interface and the right transport on bonds to the right. A right-chiral interface mode is topologically predicted only when both bulks are Fredholm and their winding numbers differ in the appropriate orientation.- left_bulk: ScalarLaurentBulkPhaseReport#
- right_bulk: ScalarLaurentBulkPhaseReport#
- __init__(left_bulk, right_bulk, left_length, right_length, constraint_matrix, kernel_dimension, kernel_basis, canonical_mode, residual, inverse_participation_ratio, interface_site_weight, interface_window_weight, center_of_mass, predicted_right_interface_modes, predicted_left_interface_modes, is_exponentially_interface_localized, classification, tolerance)#
- class qlinks.caging.SignedBoundaryCycle(rows, columns, edge_indices, sign, log_absolute_holonomy)[source]#
Bases:
objectGauge-invariant signed holonomy on one bipartite boundary cycle.
- __init__(rows, columns, edge_indices, sign, log_absolute_holonomy)#
- class qlinks.caging.SignedBoundaryHolonomyReport(n_rows, n_columns, n_edges, n_components, cycle_rank, positive_cycle_count, negative_cycle_count, zero_edge_count, cycles, tolerance)[source]#
Bases:
objectDiscrete and continuous cycle data of a support-to-boundary map.
- cycles: tuple[SignedBoundaryCycle, ...]#
- __init__(n_rows, n_columns, n_edges, n_components, cycle_rank, positive_cycle_count, negative_cycle_count, zero_edge_count, cycles, tolerance)#
- class qlinks.caging.SmoothSpectralFilter(weights, target_energy, sigma, mean_energy, energy_variance, effective_state_count)[source]#
Bases:
objectNormalized smooth energy-filter weights and their diagnostics.
- __init__(weights, target_energy, sigma, mean_energy, energy_variance, effective_state_count)#
- class qlinks.caging.SnakeStripeRegionProposal(model, max_plaquettes, config=<factory>, min_plaquettes=3, seed_plaquette_ids=None, max_records=None, max_links=None, max_turns=None, plaquette_kinds=None, allow_kind_changes=False, kind_pattern='constant_or_alternating', require_induced_cycle=False, winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate width-one noncontractible snake stripes on the plaquette graph.
A snake stripe is a simple cycle of plaquettes, adjacent by shared links, whose lifted anchor-cell displacement winds around a periodic lattice. This proposal does not assume the stripe is straight in anchor coordinates; it is therefore a better first pass for honeycomb and triangular QDM where useful width-one stripes can turn while wrapping the torus.
Optional
require_induced_cycleandkind_patternfilters turn the broad cycle enumerator into a more motif-like proposal: the examples seen in exact QDM cages are usually chordless width-one cycles whose plaquette kinds are either constant or strictly alternating between two kinds.The enumeration is intentionally budgeted by
max_plaquettes,max_links,max_turns, andmax_records.- config: LocalQDMCageSearchConfig#
- seed_plaquette_ids: Sequence[int] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, max_plaquettes, config=<factory>, min_plaquettes=3, seed_plaquette_ids=None, max_records=None, max_links=None, max_turns=None, plaquette_kinds=None, allow_kind_changes=False, kind_pattern='constant_or_alternating', require_induced_cycle=False, winding_vectors=None, adapter=None)#
- class qlinks.caging.SnakeStripeRegionProposalRecord(region, plaquette_ids, seed_plaquette_id, winding, length, turn_count, plaquette_kinds)[source]#
Bases:
objectOne width-one noncontractible snake-stripe region proposal.
Unlike
StripeRegionProposalRecord, this record is generated from simple noncontractible cycles on the plaquette shared-link graph. It is useful on lattices where natural stripe cages wrap around the torus but do not follow a straight anchor-coordinate line.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, seed_plaquette_id, winding, length, turn_count, plaquette_kinds)#
- class qlinks.caging.SpectralMicrocanonicalEnsemble(selection, eigenvalues, eigenvectors, weights, volume=None)[source]#
Bases:
objectLow-rank representation of a finite-size microcanonical ensemble.
The selected eigenvectors are stored as columns and carry equal weights. This avoids materializing a dense density matrix unless explicitly requested, while still exposing the ensemble used for observable traces.
- selection: MicrocanonicalWindowSelection#
- observable_moments(operator, *, squared_operator=None, hermiticity_tolerance=1e-10)[source]#
Return mean, second moment, and variance in this ensemble.
- __init__(selection, eigenvalues, eigenvectors, weights, volume=None)#
- class qlinks.caging.SpectralObservableMoments(mean, second_moment, variance, n_states, effective_state_count, minimum_expectation, maximum_expectation)[source]#
Bases:
objectFirst two measurement moments of one Hermitian observable.
- __init__(mean, second_moment, variance, n_states, effective_state_count, minimum_expectation, maximum_expectation)#
- class qlinks.caging.SquareQDMBetaZeroEnergyDensityEvaluation(circumference, length, horizontal_flippability, vertical_flippability, potential_coupling, winding_sector, metadata=<factory>)[source]#
Bases:
objectInfinite-temperature square-QDM energy-density estimate.
- winding_sector: SquareQDMStripWindingSector | None#
- __init__(circumference, length, horizontal_flippability, vertical_flippability, potential_coupling, winding_sector, metadata=<factory>)#
- class qlinks.caging.SquareQDMBetaZeroEnergyDensityScalingReport(evaluations)[source]#
Bases:
objectTwo-dimensional finite-size sequence for the beta-zero energy density.
- evaluations: tuple[SquareQDMBetaZeroEnergyDensityEvaluation, ...]#
- __init__(evaluations)#
- class qlinks.caging.SquareQDMBiperiodicProductInstance(model, blocks, padding, repeats_x, repeats_y, tile_lx, tile_ly)[source]#
Bases:
objectOne finite member of a two-directionally repeated product-tile family.
- model: SquareQDMModel#
- blocks: tuple[QDMBiperiodicPlacedBlock, ...]#
- padding: FactorizedLocalQDMPadding#
- __init__(model, blocks, padding, repeats_x, repeats_y, tile_lx, tile_ly)#
- class qlinks.caging.SquareQDMBiperiodicProductTile(model, blocks, padding, metadata=<factory>)[source]#
Bases:
objectA finite square-QDM tile proposed for independent x/y repetition.
The tile stores coherent local blocks and one fixed exterior on a periodic reference torus. Repetition is performed by coordinate translation into a larger torus. Exactness is not assumed: the bi-periodic certificate checks all dimer constraints and all seam/corner plaquette environments explicitly.
- model: SquareQDMModel#
- blocks: tuple[LocalQDMCageBlock, ...]#
- padding: FactorizedLocalQDMPadding#
- __init__(model, blocks, padding, metadata=<factory>)#
- class qlinks.caging.SquareQDMBiperiodicSequenceCertificate(tile, finite_checks, verification_repeats, minimum_proven_repeats, tile_energy, energy_density, tile_winding_sector, tolerance, proof_statement)[source]#
Bases:
objectCertificate for an exact two-parameter square-QDM product-tile family.
- finite_checks: tuple[QDMBiperiodicInstanceCertificate, ...]#
- property generic_environment_check: QDMBiperiodicInstanceCertificate | None#
- property failed_checks: tuple[QDMBiperiodicInstanceCertificate, ...]#
- __init__(tile, finite_checks, verification_repeats, minimum_proven_repeats, tile_energy, energy_density, tile_winding_sector, tolerance, proof_statement)#
- class qlinks.caging.SquareQDMBiperiodicTileSearchConfig(min_blocks=1, max_blocks=None, max_padding_attempts=256, max_paddings_per_packing=4, max_results=64, max_certified_results=None, max_tile_support_size=4096, verification_repeats=3, check_smaller_repeats=True, require_kinetic_separation=True, require_static_exterior=False, include_sectors=True, tolerance=1e-09)[source]#
Bases:
objectBudget and acceptance rules for direct periodic product-tile search.
- __init__(min_blocks=1, max_blocks=None, max_padding_attempts=256, max_paddings_per_packing=4, max_results=64, max_certified_results=None, max_tile_support_size=4096, verification_repeats=3, check_smaller_repeats=True, require_kinetic_separation=True, require_static_exterior=False, include_sectors=True, tolerance=1e-09)#
- class qlinks.caging.SquareQDMBiperiodicTileSearchRecord(tile, certificate, score)[source]#
Bases:
objectOne periodic exterior completion and its two-dimensional diagnosis.
- certificate: SquareQDMBiperiodicSequenceCertificate#
- __init__(tile, certificate, score)#
- class qlinks.caging.SquareQDMBiperiodicTileSearchResult(records, config, n_padding_candidates_examined)[source]#
Bases:
objectDirect product-tile search output, including informative failures.
- records: tuple[SquareQDMBiperiodicTileSearchRecord, ...]#
- property certified_records: tuple[SquareQDMBiperiodicTileSearchRecord, ...]#
- property failed_records: tuple[SquareQDMBiperiodicTileSearchRecord, ...]#
- __init__(records, config, n_padding_candidates_examined)#
- class qlinks.caging.SquareQDMChiralPEPSAnsatz(tile_basis, parameters, physical_charges, global_charge_sector=0, metadata=<factory>)[source]#
Bases:
objectNative
Z2-symmetric PEPS for one selected type-1 chiral subset.Each original virtual index is augmented by one parity bit. For every locally allowed QDM tensor entry, the four parity bits are summed modulo two and constrained to equal the tile physical chiral charge. On a closed torus all virtual charges cancel pairwise, so the PEPS has support only in the globally even sector of the inferred chiral operator. The parity-rule offset is chosen by
build_square_qdm_type1_peps_problem()so that this even sector is precisely the selected type-1 subset.The additional charge configurations do not introduce new variational parameters: all eight parity-compatible copies of an allowed structural entry share the same compact amplitude.
- tile_basis: SquareQDMRectangularTileTensorBasis#
- classmethod from_type1_problem(problem, parameters)[source]#
Build the native chiral tensor associated with a finite problem.
- tensor_data(*, charge_shift=0)[source]#
Return the dense charge-augmented
urdlptensor.charge_shiftinserts a single globalZ2flux. On a periodic connected network, placing this shift on one tensor selects odd total physical charge while leaving every variational amplitude unchanged.
- finite_cluster_state_vector(problem, *, normalize=True)[source]#
Contract the native charge rule on an exact constrained basis.
The virtual charge sum can be performed analytically: every compatible physical configuration has the same charge multiplicity, so normalized amplitudes are the compact PEPS products restricted by the native total
Z2sector. No post-hoc graph bipartition projector is used.
- static charge_degeneracy(*, n_tiles_x, n_tiles_y)[source]#
Return the constant virtual-charge multiplicity on a periodic torus.
- to_quimb_tensor_network(*, n_tiles_x, n_tiles_y, tags=('QLINKS', 'TYPE1', 'UNIT_CELL'))[source]#
Build a periodic quimb network with explicit chiral charge bonds.
- __init__(tile_basis, parameters, physical_charges, global_charge_sector=0, metadata=<factory>)#
- class qlinks.caging.SquareQDMChiralParityRule(link_coefficients, offset=0, n_edge_equations=0, metadata=<factory>)[source]#
Bases:
objectLinear
Z2representation of the Fock-space chiral operator.The rule assigns a parity
q(config) = offset + link_coefficients @ config (mod 2).Every nonzero kinetic matrix element must connect configurations with opposite parity. The corresponding chiral sign is
(-1)**q. A linear rule is especially useful for tensor networks because the physical links are partitioned between tiles, so the global parity becomes a sum of local physical charges.- tile_physical_charges(model, tile_basis)[source]#
Return local physical
Z2charges when the rule is tile-periodic.- Raises:
ValueError – If equivalent owned links in translated tiles carry different chiral coefficients. In that case a larger or multi-tensor unit cell is required for a native symmetric PEPS.
- __init__(link_coefficients, offset=0, n_edge_equations=0, metadata=<factory>)#
- class qlinks.caging.SquareQDMClassificationWitnessStripRecord(witness_index, witness, placement, scaling_report)[source]#
Bases:
objectOne actual reduced-IZ witness extracted from a cage classification.
- witness: LocalWitness#
- placement: SquareQDMWitnessPlacement#
- scaling_report: SquareQDMStripScalingReport#
- __init__(witness_index, witness, placement, scaling_report)#
- class qlinks.caging.SquareQDMClassificationWitnessStripReport(records, normalization)[source]#
Bases:
objectTransfer results for every trusted reduced-IZ witness of one cage.
- records: tuple[SquareQDMClassificationWitnessStripRecord, ...]#
- __init__(records, normalization)#
- class qlinks.caging.SquareQDMColumnTransition(incoming_mask, outgoing_mask, vertical_mask)[source]#
Bases:
objectOne allowed column of a fully packed square-lattice dimer covering.
- __init__(incoming_mask, outgoing_mask, vertical_mask)#
- class qlinks.caging.SquareQDMFiniteBondTransferInvariantReport(system_size, support_size, kernel_dimension, reference_dimension, relative_dimension, reference_containment_residual, kernel_symmetry_residual, reference_symmetry_residual, relative_symmetry_residual, translation_commutator_residual, group_relation_residual, sectors, quotient_translation_x_character, quotient_translation_y_character, quotient_reflection_x_character, quotient_reflection_y_character, quotient_quarter_turn_character, tolerance)[source]#
Bases:
objectDiscrete spatial representation carried by a fixed-width cage kernel.
The exact boundary kernel is treated as a finite transfer/bond space. The reference subspace may contain known compact or regional cage modes. The quotient then carries a basis-independent representation of the commuting translations. Momentum-sector multiplicities are integers and can change only when the kernel/reference dimensions change or the spatial symmetry is broken.
This is a physical symmetry representation, not automatically a virtual projective (SPT) invariant.
group_relation_residualexplicitly checks that the quotient realizes the ordinary square-lattice relations.- sectors: tuple[SquareQDMTransferSectorMultiplicity, ...]#
- __init__(system_size, support_size, kernel_dimension, reference_dimension, relative_dimension, reference_containment_residual, kernel_symmetry_residual, reference_symmetry_residual, relative_symmetry_residual, translation_commutator_residual, group_relation_residual, sectors, quotient_translation_x_character, quotient_translation_y_character, quotient_reflection_x_character, quotient_reflection_y_character, quotient_quarter_turn_character, tolerance)#
- class qlinks.caging.SquareQDMLinkCoordinate(x, y, kind)[source]#
Bases:
objectOne square-QDM link in strip coordinates.
xlabels the site column anchoring the link. Anxlink joins(x, y)to(x + 1, y); aylink joins(x, y)to(x, y + 1 mod circumference).- __init__(x, y, kind)#
- class qlinks.caging.SquareQDMPEPSAnsatz(tile_basis, parameters, parameterization='entry', metadata=<factory>)[source]#
Bases:
objectOne translationally invariant constrained PEPS unit-cell tensor.
- tile_basis: SquareQDMRectangularTileTensorBasis#
- to_quimb_tensor_network(*, n_tiles_x, n_tiles_y, tags=('QLINKS', 'UNIT_CELL'))[source]#
Build the periodic PEPS as a generic quimb tensor network.
The bonds are named explicitly, so this representation also handles one- and two-tile periodic directions, where a pair of neighbouring tensors is connected by parallel bonds.
- to_quimb_peps(*, n_tiles_x, n_tiles_y, tags=('QLINKS', 'UNIT_CELL'))[source]#
Build a structured periodic
quimb.tensor.PEPS.Quimb’s structured constructor identifies bonds by the unordered pair of neighbouring coordinates. Periodic directions of length one or two contain parallel bonds between the same coordinates, so use
to_quimb_tensor_network()for those short tori.
- __init__(tile_basis, parameters, parameterization='entry', metadata=<factory>)#
- class qlinks.caging.SquareQDMPEPSFiniteClusterProblem(model, tile_basis, basis_states, hamiltonian, tile_coordinates, entry_parameter_indices, tensor_coordinates, tolerance=1e-10, metadata=<factory>)[source]#
Bases:
objectExact small-torus objective for one translational PEPS unit tensor.
- tile_basis: SquareQDMRectangularTileTensorBasis#
- state_vector(parameters, *, normalize=True)[source]#
Evaluate the PEPS amplitudes on the exact constrained basis.
The virtual indices are fixed uniquely by a global link configuration, so evaluating a basis amplitude reduces to multiplying the selected unit-tensor entries across tiles.
- perturb_parameters(parameters, *, scale=0.01, seed=0, normalize=True)[source]#
Add a reproducible real perturbation to escape sparse stationary points.
The exact singlet-core tensor has only two nonzero entries and is a stationary point of the variance within the enlarged PEPS manifold. A small perturbation activates the boundary-compatible halo entries and produces a useful Autograd search direction.
- loss_and_gradient_autograd(parameters)[source]#
Evaluate the exact variance and its gradient using Autograd.
- make_quimb_optimizer(parameters, *, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=True, loss_target=None, **backend_options)[source]#
Create a compact quimb
TNOptimizerfor the exact variance.Only the locally allowed tensor entries are variational. Quimb’s
PTensorembeds the compact vector into the denseurdlptensor, reducing the optimization dimension from the full tensor size totile_basis.n_entries(108 for the 3-by-2 tile).The current Autograd path is real-valued. Complex tensors can later be handled through a JAX or PyTorch backend with an explicit real/imaginary parameter split.
- optimize_with_quimb(parameters, *, max_steps=20, noise_scale=0.01, seed=0, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=False, loss_target=None, exact_tolerance=1e-10, **backend_options)[source]#
Optimize the shared unit tensor against the exact cluster variance.
- __init__(model, tile_basis, basis_states, hamiltonian, tile_coordinates, entry_parameter_indices, tensor_coordinates, tolerance=1e-10, metadata=<factory>)#
- class qlinks.caging.SquareQDMPEPSOptimizationResult(initial_parameters, optimized_parameters, loss_history, initial_report, final_report, requested_steps, optimizer, autodiff_backend, metadata=<factory>)[source]#
Bases:
objectResult of an exact small-cluster PEPS optimization.
- initial_report: SquareQDMPEPSResidualReport#
- final_report: SquareQDMPEPSResidualReport#
- __init__(initial_parameters, optimized_parameters, loss_history, initial_report, final_report, requested_steps, optimizer, autodiff_backend, metadata=<factory>)#
- class qlinks.caging.SquareQDMPEPSResidualReport(norm, energy, residual, energy_variance, nonzero_basis_amplitudes, hilbert_dimension)[source]#
Bases:
objectExact finite-cluster eigenstate diagnostic for a PEPS parameter vector.
- __init__(norm, energy, residual, energy_variance, nonzero_basis_amplitudes, hilbert_dimension)#
- class qlinks.caging.SquareQDMPeriodicProductInstance(model, blocks, padding, repeats, repeat_axis)[source]#
Bases:
objectOne finite member of a periodically repeated factorized cage family.
- model: SquareQDMModel#
- blocks: tuple[LocalQDMCageBlock, ...]#
- padding: FactorizedLocalQDMPadding#
- __init__(model, blocks, padding, repeats, repeat_axis)#
- class qlinks.caging.SquareQDMPeriodicProductUnitCell(model, blocks, padding, repeat_axis='y', metadata=<factory>)[source]#
Bases:
objectCoordinate-level unit cell for an arbitrary-repeat square-QDM cage.
The unit cell may contain several coherent blocks and a fixed exterior. Repetition is exact at the link-pattern level; no global basis or Cartesian product support is formed.
- model: SquareQDMModel#
- blocks: tuple[LocalQDMCageBlock, ...]#
- padding: FactorizedLocalQDMPadding#
- with_couplings(*, coup_kin=None, coup_pot=None)[source]#
Reuse the geometric cage cell with new translation-invariant couplings.
This is useful when a cage was discovered in a model with a diagnostic potential term but the thermodynamic ETH comparison is made for the pure kinetic Hamiltonian. The local sequence certificate is recomputed after the replacement; no spectral property is assumed to survive automatically.
- __init__(model, blocks, padding, repeat_axis='y', metadata=<factory>)#
- class qlinks.caging.SquareQDMPeriodicSequenceCertificate(unit_cell, finite_checks, verification_repeats, minimum_proven_repeats, unit_cell_energy, energy_density, unit_cell_winding_sector, tolerance, proof_statement)[source]#
Bases:
objectCertificate for an exact one-axis infinite sequence of cage states.
- unit_cell: SquareQDMPeriodicProductUnitCell#
- finite_checks: tuple[QDMPeriodicInstanceCertificate, ...]#
- winding_sector_for_repeats(repeats)[source]#
Return the electric winding label of the repeated family member.
Translation by an even unit-cell period preserves the staggered electric convention. Repeating along y adds the x-cut flux of each copy while leaving the y-cut flux fixed; repeating along x gives the converse.
- match_energy_density(thermal_energy_density, *, tolerance=1e-08, comparator='beta_zero', metadata=None)[source]#
- __init__(unit_cell, finite_checks, verification_repeats, minimum_proven_repeats, unit_cell_energy, energy_density, unit_cell_winding_sector, tolerance, proof_statement)#
- class qlinks.caging.SquareQDMPeriodicWitnessCertificate(witness, touched_block_ids, annihilation_residual, q_expectation, tolerance, sequence_is_certified, support_crosses_repeat_seam)[source]#
Bases:
objectLocal annihilation certificate propagated to the repeated sequence.
- witness: LocalWitness#
- __init__(witness, touched_block_ids, annihilation_residual, q_expectation, tolerance, sequence_is_certified, support_crosses_repeat_seam)#
- class qlinks.caging.SquareQDMRectangularTileTensorBasis(tile_shape, origin, owned_link_ids, owned_link_keys, physical_configurations, entry_coordinates, required_count=1, metadata=<factory>)[source]#
Bases:
objectLocally allowed entries of one rectangular square-QDM vertex tensor.
The tensor-index order is
(up, right, down, left, physical). The physical index labels configurations of all+xand+ylinks whose source lies inside the tile. Thus physical links are disjoint between translated tiles. A tensor entry is retained exactly when the incoming left/down occupations complete every site in the tile to one dimer and the outgoing right/up patterns agree with the owned physical configuration.- tensor_data_from_parameters(parameters, *, parameterization='entry')[source]#
Embed a compact parameter vector into the masked dense PEPS tensor.
- __init__(tile_shape, origin, owned_link_ids, owned_link_keys, physical_configurations, entry_coordinates, required_count=1, metadata=<factory>)#
- class qlinks.caging.SquareQDMSingletBoundaryTile(singlet, basis, core_sector_indices)[source]#
Bases:
objectOne singlet core embedded in an enlarged boundary-resolved halo basis.
- singlet: SquareQDMTwoPlaquetteSingletBlock#
- core_sector_indices: tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[int64]]]#
- __init__(singlet, basis, core_sector_indices)#
- class qlinks.caging.SquareQDMSingletProductTiling(blocks, n_horizontal, n_vertical)[source]#
Bases:
objectOne exact cover of all square-lattice sites by singlet rectangles.
- blocks: tuple[SquareQDMTwoPlaquetteSingletBlock, ...]#
- __init__(blocks, n_horizontal, n_vertical)#
- class qlinks.caging.SquareQDMSingletStripeProductReport(direction, transverse_coordinate, selected_blocks, subspace_reports, failure_reason=None)[source]#
Bases:
objectAll shared-exterior tests for one regularly spaced singlet stripe.
- selected_blocks: tuple[SquareQDMTwoPlaquetteSingletBlock, ...]#
- subspace_reports: tuple[QDMBlockProductSubspaceReport, ...]#
- __init__(direction, transverse_coordinate, selected_blocks, subspace_reports, failure_reason=None)#
- class qlinks.caging.SquareQDMSingletTilingRecord(tiling, report)[source]#
Bases:
objectSubspace analysis for one exact-cover singlet tiling.
- tiling: SquareQDMSingletProductTiling#
- report: QDMBlockProductSubspaceReport#
- __init__(tiling, report)#
- class qlinks.caging.SquareQDMSingletTilingSearchResult(records, n_tilings_enumerated, truncated)[source]#
Bases:
objectCollection of exact-cover singlet-product diagnostics.
- records: tuple[SquareQDMSingletTilingRecord, ...]#
- __init__(records, n_tilings_enumerated, truncated)#
- class qlinks.caging.SquareQDMStripScalingReport(placement, evaluations)[source]#
Bases:
objectA fixed-circumference sequence of strip witness expectations.
- placement: SquareQDMWitnessPlacement#
- evaluations: tuple[SquareQDMStripWitnessEvaluation, ...]#
- property winding_sector: SquareQDMStripWindingSector | None#
- tail_estimate(*, tail_points=3)[source]#
Return a descriptive tail mean and spread.
The result is deliberately not named a thermodynamic-limit fit. Strip transfer sequences can retain parity oscillations, especially at small circumference, so the tail spread should be inspected explicitly.
- __init__(placement, evaluations)#
- class qlinks.caging.SquareQDMStripTransferMatrix(circumference)[source]#
Bases:
objectExact transfer matrix for fully packed dimers on a square cylinder.
The y direction is periodic and has fixed
circumference. Boundary states are bit masks of horizontal dimers entering a site column. A column transition stores the outgoing horizontal mask and the occupied vertical links inside that column.- transitions: tuple[SquareQDMColumnTransition, ...]#
- witness_insertion_matrix(placement)[source]#
Contract the exact local
Q_Rweight into one strip insertion.
- witness_insertion_matrices_by_winding_y(placement, *, insertion_x=0)[source]#
Return insertion matrices resolved by electric y-winding charge.
The dictionary key is the contribution of the witness window to the electric winding measured across the y-wrapping links.
insertion_xfixes the checkerboard parity of the first column in the window.
- evaluate_witness(placement, *, length, boundary_x='open', insertion_x=None, winding_sector=None, winding_projection='auto', fourier_points=None)[source]#
Evaluate
Tr(Q_R)/dim(H)without enumerating dimer coverings.
- scan_witness(placement, *, lengths, boundary_x='open', centered=True, winding_sector=None, periodic_insertion_x=0, winding_projection='auto', fourier_points=None)[source]#
Evaluate a fixed witness over several strip lengths.
- periodic_winding_sector_counts(*, length, winding_projection='auto', fourier_points=None)[source]#
Count periodic dimer coverings in every electric winding sector.
- __init__(circumference)#
- class qlinks.caging.SquareQDMStripWindingSector(winding_x, winding_y, convention='electric')[source]#
Bases:
objectOne electric winding sector of a periodic square-QDM strip.
The labels use the same convention as
qlinks.constraints.SquareQDMElectricWindingSector. The x label is measured on the x-wrapping horizontal links, while the y label is measured on the y-wrapping vertical links.- __init__(winding_x, winding_y, convention='electric')#
- class qlinks.caging.SquareQDMStripWitnessEvaluation(circumference, length, boundary_x, insertion_x, window_width, expectation, log_partition_count, log_weighted_count, partition_count, weighted_count, winding_sector=None, metadata=<factory>)[source]#
Bases:
objectInfinite-temperature expectation from an exact strip contraction.
- winding_sector: SquareQDMStripWindingSector | None#
- __init__(circumference, length, boundary_x, insertion_x, window_width, expectation, log_partition_count, log_weighted_count, partition_count, weighted_count, winding_sector=None, metadata=<factory>)#
- class qlinks.caging.SquareQDMTransferSectorMultiplicity(momentum_x_index, momentum_y_index, momentum_x, momentum_y, kernel_multiplicity, reference_multiplicity, relative_multiplicity)[source]#
Bases:
objectMultiplicity of one lattice-momentum sector in a finite bond space.
- __init__(momentum_x_index, momentum_y_index, momentum_x, momentum_y, kernel_multiplicity, reference_multiplicity, relative_multiplicity)#
- class qlinks.caging.SquareQDMTwoPlaquetteSingletBlock(block, plaquette_ids, anchor_cells, direction)[source]#
Bases:
objectA translated two-plaquette antisymmetric square-QDM cage block.
- block: LocalQDMCageBlock#
- __init__(block, plaquette_ids, anchor_cells, direction)#
- class qlinks.caging.SquareQDMType1AdaptiveJointClusterProblem(problems, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>, tolerance=1e-10)[source]#
Bases:
objectShared targeted multi-tensor objective over several exact clusters.
- property parameterization: SquareQDMType1AdaptiveParameterization#
- loss_and_gradient_exact(parameters)[source]#
Evaluate the adaptive joint loss and analytic real gradient.
This path is independent of Autograd and quimb. It is useful for regression tests and for diagnosing the targeted enlargement before a more expensive tensor-network optimization is launched.
- optimize_with_scipy(parameters, *, max_steps=20, noise_scale=0.01, seed=0, optimizer='L-BFGS-B')[source]#
Optimize the targeted enlargement with its analytic exact gradient.
- make_quimb_optimizer(parameters, *, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=True, loss_target=None, **backend_options)[source]#
- optimize_with_quimb(parameters, *, max_steps=20, noise_scale=0.01, seed=0, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=False, loss_target=None, **backend_options)[source]#
- __init__(problems, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>, tolerance=1e-10)#
- class qlinks.caging.SquareQDMType1AdaptiveJointOptimizationResult(initial_parameters, optimized_parameters, loss_history, initial_validation, final_validation, parameterization, requested_steps, optimizer, autodiff_backend, metadata=<factory>)[source]#
Bases:
objectJoint optimization result for a targeted enlarged type-1 unit cell.
- initial_validation: SquareQDMType1ClusterValidationReport#
- final_validation: SquareQDMType1ClusterValidationReport#
- parameterization: SquareQDMType1AdaptiveParameterization#
- __init__(initial_parameters, optimized_parameters, loss_history, initial_validation, final_validation, parameterization, requested_steps, optimizer, autodiff_backend, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1AdaptivePEPSFiniteClusterProblem(base_problem, parameterization, parameter_indices)[source]#
Bases:
objectOne finite cluster evaluated with a targeted enlarged unit cell.
- base_problem: SquareQDMType1PEPSFiniteClusterProblem#
- parameterization: SquareQDMType1AdaptiveParameterization#
- __init__(base_problem, parameterization, parameter_indices)#
- class qlinks.caging.SquareQDMType1AdaptiveParameterization(tile_basis, selected_entry_indices, split_axis, period=2, metadata=<factory>)[source]#
Bases:
objectTargeted multi-tensor enlargement of the compact type-1 PEPS ansatz.
Most of the 108 locally allowed entries remain shared across the whole lattice. Only
selected_entry_indicesreceive independent copies on a period-two tile sublattice. This tests whether a specific seam obstruction requires a larger unit cell without duplicating the complete tensor.- tile_basis: SquareQDMRectangularTileTensorBasis#
- __init__(tile_basis, selected_entry_indices, split_axis, period=2, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1ClusterValidationRecord(label, n_plaquettes, report)[source]#
Bases:
objectType-1 diagnostics for one member of a shared-tensor cluster family.
- __init__(label, n_plaquettes, report)#
- class qlinks.caging.SquareQDMType1ClusterValidationReport(records, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>)[source]#
Bases:
objectCross-cluster type-1 diagnostics for one common PEPS tensor.
- records: tuple[SquareQDMType1ClusterValidationRecord, ...]#
- property by_label: dict[str, SquareQDMType1ClusterValidationRecord]#
- __init__(records, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>)#
- class qlinks.caging.SquareQDMType1InterferenceClassRecord(plaquette_class, n_plaquettes, residual_norm_squared, incoherent_norm_squared, coherent_contribution, max_residual, n_nonzero_targets)[source]#
Bases:
objectCoherent interference residual accumulated over one plaquette class.
- __init__(plaquette_class, n_plaquettes, residual_norm_squared, incoherent_norm_squared, coherent_contribution, max_residual, n_nonzero_targets)#
- class qlinks.caging.SquareQDMType1InterferenceDecomposition(total_norm_squared, reconstruction_residual, plaquette_records, class_records, metadata=<factory>)[source]#
Bases:
objectPlaquette- and seam-resolved decomposition of
B psi.component_norm_squaredmeasures each plaquette before coherent summation.coherent_contribution = Re <r_p, r_total>partitions the exact total residual norm, including negative contributions from destructive interference. The class records sum plaquettes before taking their norm, revealing whether interior, seam, or corner processes remain uncancelled.- plaquette_records: tuple[SquareQDMType1PlaquetteResidualRecord, ...]#
- class_records: tuple[SquareQDMType1InterferenceClassRecord, ...]#
- property by_class: dict[Literal['interior', 'x_seam', 'y_seam', 'corner'], SquareQDMType1InterferenceClassRecord]#
- __init__(total_norm_squared, reconstruction_residual, plaquette_records, class_records, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1PEPSFiniteClusterProblem(base_problem, kinetic_matrix, potential_values, chiral_labels, target_chiral_label, parity_rule=None, potential_weight=1.0, target_potential_value=None, tolerance=1e-10, metadata=<factory>)[source]#
Bases:
objectType-1 specialization of the finite-cluster constrained PEPS problem.
The underlying PEPS generates amplitudes on the complete constrained basis. Before any objective is evaluated, the state is projected exactly onto one bipartite subset of the kinetic graph. The loss then contains only the two defining type-1 conditions: kinetic destructive interference and uniform diagonal potential on the retained support.
- base_problem: SquareQDMPEPSFiniteClusterProblem#
- parity_rule: SquareQDMChiralParityRule | None#
- property tile_basis: SquareQDMRectangularTileTensorBasis#
- property target_basis_indices: ndarray[tuple[Any, ...], dtype[int64]]#
Indices of configurations in the occupied type-1 chiral subset.
- property opposite_basis_indices: ndarray[tuple[Any, ...], dtype[int64]]#
Indices of configurations on the empty opposite chiral subset.
- property target_entry_parameter_indices: ndarray[tuple[Any, ...], dtype[int64]]#
Compact tensor entries needed only for the occupied chiral block.
- property target_tensor_coordinates: ndarray[tuple[Any, ...], dtype[int64]]#
Dense tensor coordinates needed only for the occupied chiral block.
- property kinetic_interference_matrix: csr_array#
Rectangular type-1 map
B: H_target -> H_opposite.This is the block that must annihilate the occupied-subset amplitude vector. Storing and applying this rectangular block avoids forming a full projected wavefunction or multiplying by the complete kinetic matrix during optimization.
- interference_decomposition(parameters)[source]#
Resolve the type-1 kinetic residual by plaquette and tile seam.
- interference_parameter_sensitivity(parameters, plaquette_class)[source]#
Differentiate one seam-class residual density by compact tensor entry.
The derivative is evaluated analytically from the product-state Jacobian, so entries with zero amplitude are handled exactly. Large scores identify local boundary sectors whose amplitudes most strongly control the selected uncancelled interference channel.
- native_state_vector(parameters, *, normalize=True)[source]#
Evaluate amplitudes directly in the occupied chiral block.
Unlike
projected_state_vector(), this never constructs amplitudes on the opposite Fock-space subset and then discards them. It is the finite-cluster counterpart of contracting the nativeZ2-symmetric PEPS in a fixed total-charge sector.
- diagnose_native(parameters)[source]#
Diagnose the native occupied-block state without post-projection.
- make_quimb_optimizer(parameters, *, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=True, loss_target=None, **backend_options)[source]#
- optimize_with_quimb(parameters, *, max_steps=20, noise_scale=0.01, seed=0, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=False, loss_target=None, **backend_options)[source]#
- __init__(base_problem, kinetic_matrix, potential_values, chiral_labels, target_chiral_label, parity_rule=None, potential_weight=1.0, target_potential_value=None, tolerance=1e-10, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1PEPSJointClusterProblem(problems, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>, tolerance=1e-10)[source]#
Bases:
objectOne native type-1 tensor optimized on several finite clusters at once.
Kinetic interference and potential nonuniformity are aggregated separately across clusters and combined only after each component has been converted to a smooth
p-norm. This prevents a low-potential-error cluster from masking a large kinetic leakage, or vice versa.- problems: Mapping[str, SquareQDMType1PEPSFiniteClusterProblem]#
- property tile_basis: SquareQDMRectangularTileTensorBasis#
- make_quimb_optimizer(parameters, *, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=True, loss_target=None, **backend_options)[source]#
- optimize_with_quimb(parameters, *, max_steps=20, noise_scale=0.01, seed=0, autodiff_backend='autograd', optimizer='L-BFGS-B', progbar=False, loss_target=None, **backend_options)[source]#
- __init__(problems, aggregation_power=4.0, potential_weight=1.0, cluster_weights=<factory>, tolerance=1e-10)#
- class qlinks.caging.SquareQDMType1PEPSJointOptimizationResult(initial_parameters, optimized_parameters, loss_history, initial_validation, final_validation, requested_steps, optimizer, autodiff_backend, metadata=<factory>)[source]#
Bases:
objectJoint optimization result for separated type-1 losses across clusters.
- initial_validation: SquareQDMType1ClusterValidationReport#
- final_validation: SquareQDMType1ClusterValidationReport#
- __init__(initial_parameters, optimized_parameters, loss_history, initial_validation, final_validation, requested_steps, optimizer, autodiff_backend, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1PEPSOptimizationResult(initial_parameters, optimized_parameters, loss_history, initial_report, final_report, requested_steps, optimizer, autodiff_backend, metadata=<factory>)[source]#
Bases:
objectResult of a quimb optimization of the type-1 separated objective.
- initial_report: SquareQDMType1PEPSResidualReport#
- final_report: SquareQDMType1PEPSResidualReport#
- __init__(initial_parameters, optimized_parameters, loss_history, initial_report, final_report, requested_steps, optimizer, autodiff_backend, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1PEPSResidualReport(norm_before_projection, norm_after_projection, retained_chiral_weight, discarded_chiral_weight, target_chiral_label, kinetic_interference_norm, kinetic_interference_density, potential_mean, potential_variance, potential_variance_density, total_variance, objective, max_interference_residual, n_nonzero_interference_targets, nonzero_projected_amplitudes, hilbert_dimension, target_potential_value=None, target_potential_residual=None)[source]#
Bases:
objectSeparated type-1 cage diagnostics for one finite-cluster PEPS state.
- __init__(norm_before_projection, norm_after_projection, retained_chiral_weight, discarded_chiral_weight, target_chiral_label, kinetic_interference_norm, kinetic_interference_density, potential_mean, potential_variance, potential_variance_density, total_variance, objective, max_interference_residual, n_nonzero_interference_targets, nonzero_projected_amplitudes, hilbert_dimension, target_potential_value=None, target_potential_residual=None)#
- class qlinks.caging.SquareQDMType1ParameterSensitivity(plaquette_class, gradient, scores, entry_coordinates, loss, metadata=<factory>)[source]#
Bases:
objectGradient of one plaquette-class interference density by tensor entry.
- __init__(plaquette_class, gradient, scores, entry_coordinates, loss, metadata=<factory>)#
- class qlinks.caging.SquareQDMType1PlaquetteResidualRecord(plaquette_id, anchor_cell, plaquette_class, component_norm_squared, coherent_contribution, max_residual, n_nonzero_targets)[source]#
Bases:
objectKinetic residual generated by one plaquette in a type-1 PEPS state.
- __init__(plaquette_id, anchor_cell, plaquette_class, component_norm_squared, coherent_contribution, max_residual, n_nonzero_targets)#
- class qlinks.caging.SquareQDMWitnessFamilyStripRecord(system_label, embedding_index, placement, scaling_report)[source]#
Bases:
objectOne finite-system embedding of a common witness family on a strip.
- placement: SquareQDMWitnessPlacement#
- scaling_report: SquareQDMStripScalingReport#
- __init__(system_label, embedding_index, placement, scaling_report)#
- class qlinks.caging.SquareQDMWitnessFamilyStripReport(family, records)[source]#
Bases:
objectStrip evaluations of one cage-derived local witness family.
- family: LocalWitnessFamily#
- records: tuple[SquareQDMWitnessFamilyStripRecord, ...]#
- __init__(family, records)#
- class qlinks.caging.SquareQDMWitnessPlacement(template, circumference, link_coordinates, reference_origin_x=None, metadata=<factory>)[source]#
Bases:
objectPlace a local witness on an infinite square-QDM cylinder.
The local-variable ordering is exactly the ordering used by
LocalWitnessTemplate.link_coordinatesare normalized so the first affected site column is zero. This makes the placement independent of the finite reference system from which the witness was extracted.- template: LocalWitnessTemplate#
- link_coordinates: tuple[SquareQDMLinkCoordinate, ...]#
- with_circumference(circumference)[source]#
Reuse the same local operator and link coordinates on a wider cylinder.
- instantiate_on_model(model, *, origin_x=0, origin_y=0)[source]#
Embed the normalized strip placement in a finite square-QDM model.
- classmethod from_local_witness(model, witness, *, metadata=None)[source]#
Extract strip link coordinates from a finite square-QDM embedding.
For a periodic reference lattice, the shortest unwrapped interval is selected automatically. A witness crossing the finite-system x seam therefore becomes an ordinary bounded placement on the infinite strip.
- __init__(template, circumference, link_coordinates, reference_origin_x=None, metadata=<factory>)#
- class qlinks.caging.StripeMotifComponentRegionProposal(model, config=<factory>, motif_sizes=(2, 3), motif_subset_mode='windows', motif_signatures=None, min_seed_motifs=1, max_seed_motifs_per_stripe=None, component_sizes=None, component_subset_mode='full', sources=('snake_stripe', ), max_components_per_stripe=1, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate merged stripe components seeded by small coherent motifs.
The proposal first cuts small motifs from each straight/snake stripe skeleton and runs the existing local cage searcher on those tiny motifs. If enough motifs have local cage records, it emits a larger component region, by default the whole stripe skeleton. This is intended for triangular and honeycomb QDM cages where the exact state is a stripe-local object rather than a product of independent two-plaquette blocks.
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- __init__(model, config=<factory>, motif_sizes=(2, 3), motif_subset_mode='windows', motif_signatures=None, min_seed_motifs=1, max_seed_motifs_per_stripe=None, component_sizes=None, component_subset_mode='full', sources=('snake_stripe', ), max_components_per_stripe=1, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)#
- class qlinks.caging.StripeMotifComponentRegionProposalRecord(region, plaquette_ids, source, source_index, source_plaquette_ids, component_size, component_index, n_seed_motifs, seed_motif_plaquette_ids, seed_motif_signatures)[source]#
Bases:
objectOne merged stripe component selected by small local motif probes.
The record represents the second-stage fast path: small two-/three-plaquette motifs are used only as cheap evidence that a stripe skeleton is promising; the emitted region is a larger component, usually the whole stripe/snake, so coherent units inside the stripe can cancel jointly instead of being forced into independent product blocks.
- region: LocalQDMRegion#
- __init__(region, plaquette_ids, source, source_index, source_plaquette_ids, component_size, component_index, n_seed_motifs, seed_motif_plaquette_ids, seed_motif_signatures)#
- class qlinks.caging.StripeMotifRegionProposal(model, config=<factory>, motif_sizes=(2, 3), sources=('stripe', 'snake_stripe'), subset_mode='all', max_motifs_per_stripe=None, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)[source]#
Bases:
objectGenerate small QDM motif regions cut from stripe-like plaquette paths.
This is a fast path for QDM cages whose real-space organization is a width-one stripe but whose coherent local objects are only small two- or three-plaquette singlet/triplet motifs. It first constructs cheap straight and/or snake stripe skeletons, then emits small motif subsets from each skeleton. The ordinary local cage algebra is still used afterward, but on much smaller regions than a full stripe.
- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, config=<factory>, motif_sizes=(2, 3), sources=('stripe', 'snake_stripe'), subset_mode='all', max_motifs_per_stripe=None, max_records=None, max_links=None, stripe_widths=(1, ), stripe_directions=None, plaquette_kinds=None, snake_max_plaquettes=None, snake_min_plaquettes=3, snake_max_turns=None, snake_allow_kind_changes=False, snake_kind_pattern='constant_or_alternating', snake_require_induced_cycle=False, snake_winding_vectors=None, adapter=None)#
- class qlinks.caging.StripeMotifRegionProposalRecord(region, plaquette_ids, source, source_index, source_plaquette_ids, motif_size, motif_index)[source]#
Bases:
objectOne small stripe-motif local-region proposal.
The proposal is meant to capture the QDM pattern seen in exact cages: a width-one stripe supplies the global organizing structure, but the coherent local object is often only a two- or three-plaquette motif on that stripe.
sourcerecords whether the motif was cut from a straight stripe or from a snake-stripe cycle.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, source, source_index, source_plaquette_ids, motif_size, motif_index)#
- class qlinks.caging.StripeRegionProposal(model, config=<factory>, directions=None, width=1, plaquette_kinds=None, adapter=None)[source]#
Bases:
objectGenerate QDM stripe/band local regions from plaquette anchor coordinates.
A stripe is selected on the plaquette-anchor lattice. For
direction=0on a square torus, the proposal keeps all plaquettes along the x direction at fixed y; fordirection=1it keeps all plaquettes along y at fixed x.widththickens the stripe in the transverse coordinate.The default search config uses
halo_layers=0because the stripe itself is meant to be the active region. Passing a config withhalo_layers > 0intentionally asks for the old shared-link halo around each stripe.- config: LocalQDMCageSearchConfig#
- adapter: LocalCageModelAdapter | None#
- iter_regions()[source]#
Yield only the local regions from
iter_records().
- __init__(model, config=<factory>, directions=None, width=1, plaquette_kinds=None, adapter=None)#
- class qlinks.caging.StripeRegionProposalRecord(region, plaquette_ids, direction, transverse_origin, width, plaquette_kind)[source]#
Bases:
objectOne plaquette-stripe local-region proposal.
directionis the anchor-coordinate axis along which the stripe runs.transverse_originlabels the first transverse coordinate included in the band. For periodic lattices andwidth > 1, the band is thickened by wrapping forward from this origin.- region: LocalQDMRegion#
- __init__(region, plaquette_ids, direction, transverse_origin, width, plaquette_kind)#
- class qlinks.caging.SupportEigenstateBranchPoint(parameter, state, energy, overlap_with_previous, overlap_with_reference, boundary_residual, internal_eigen_residual, full_residual, boundary_nullity, invariant_cage_dimension, interference_gap, exact_cage)[source]#
Bases:
objectOne support-local eigenstate tracked even after exact caging is lost.
- __init__(parameter, state, energy, overlap_with_previous, overlap_with_reference, boundary_residual, internal_eigen_residual, full_residual, boundary_nullity, invariant_cage_dimension, interference_gap, exact_cage)#
- class qlinks.caging.SupportEigenstateBranchReport(support, points, tolerance)[source]#
Bases:
objectContinuation of an internal eigenstate with its boundary leakage.
- points: tuple[SupportEigenstateBranchPoint, ...]#
- __init__(support, points, tolerance)#
- class qlinks.caging.SupportPermutationDiagnostic(permutation, moved_support_count, cycle_lengths, boundary_fixed_residual, boundary_fixed_relative_residual, internal_commutator_residual, internal_commutator_relative_residual, state_phase, state_eigen_residual, state_eigen_relative_residual, is_nontrivial_state_sector, explains_boundary_closure)[source]#
Bases:
objectDiagnostics for one support permutation as a possible CLS symmetry.
The permutation maps old local support positions to new local support positions. It is tested as a unitary
Uacting inside the support. A boundary-fixed local symmetry satisfiesK U = Kfor the leakage matrixK = H_{boundary,support}. If the state is also an eigenvector ofUwith a nontrivial phase, then the permutation gives a symmetry-sector explanation for the destructive-interference closure.- __init__(permutation, moved_support_count, cycle_lengths, boundary_fixed_residual, boundary_fixed_relative_residual, internal_commutator_residual, internal_commutator_relative_residual, state_phase, state_eigen_residual, state_eigen_relative_residual, is_nontrivial_state_sector, explains_boundary_closure)#
- class qlinks.caging.SupportSizeFilter(min_size=2, max_size=None)[source]#
Bases:
objectFilter candidates by support size.
- __init__(min_size=2, max_size=None)#
- class qlinks.caging.SymmetrySectorBasis(basis, labels=<factory>, unitarity_residual=0.0)[source]#
Bases:
objectOrthonormal basis for a symmetry-resolved subspace.
basishas shape(full_dimension, sector_dimension)and orthonormal columns. It may be sparse for cyclic sectors and dense after further refinement by an involution.- __init__(basis, labels=<factory>, unitarity_residual=0.0)#
- class qlinks.caging.TermResolvedCagingReport(physical_constraint_map, resolved_constraint_map, physical_kernel_basis, resolved_kernel_basis, collective_quotient_basis, physical_nullity, resolved_nullity, collective_quotient_dimension, resolved_containment_residual, tolerance)[source]#
Bases:
objectCompare separately vanishing local channels with collective cancellation.
- __init__(physical_constraint_map, resolved_constraint_map, physical_kernel_basis, resolved_kernel_basis, collective_quotient_basis, physical_nullity, resolved_nullity, collective_quotient_dimension, resolved_containment_residual, tolerance)#
- class qlinks.caging.ThermalActivityMarginReport(parameters, activities, secant_slopes, reference_parameter, reference_activity, minimum_activity, susceptibility_bound, half_activity_radius, tolerance)[source]#
Bases:
objectFinite-difference estimate of a local witness’s thermal margin.
- __init__(parameters, activities, secant_slopes, reference_parameter, reference_activity, minimum_activity, susceptibility_bound, half_activity_radius, tolerance)#
- class qlinks.caging.ThermodynamicEnergyWindowPlan(volume, energy_density, target_energy, half_width, energy_density_half_width, width_prefactor, local_energy_scale, width_exponent)[source]#
Bases:
objectSize-scaled energy window for a thermodynamic microcanonical sequence.
A width
Delta E_L = c * epsilon * volume**alphawithalpha < 1has a vanishing energy-density width. The defaultalpha=1/2is the square-root-volume choice used in the manuscript notebooks.- __init__(volume, energy_density, target_energy, half_width, energy_density_half_width, width_prefactor, local_energy_scale, width_exponent)#
- class qlinks.caging.UniformSelfLoopFilter(tolerance=1e-10, use_hamiltonian_diagonal=True)[source]#
Bases:
objectRequire uniform self-loop values on the candidate support.
If
context.self_loop_valuesis provided, this filter uses it directly. Otherwise, ifuse_hamiltonian_diagonalis true, it falls back to the diagonal ofcontext.hamiltonian.- __init__(tolerance=1e-10, use_hamiltonian_diagonal=True)#
- class qlinks.caging.VertexSignature(values)[source]#
Bases:
objectHashable vertex signature used for candidate partitioning.
- __init__(values)#
- class qlinks.caging.WindowedAnnihilatorPoint(radius, center, selected_operator_indices, active_operator_indices, minimum_residual, rank, nullity, coefficient_support_size, best_coefficients, singular_values)[source]#
Bases:
objectBest coefficient-normalized annihilator inside one spatial window.
- __init__(radius, center, selected_operator_indices, active_operator_indices, minimum_residual, rank, nullity, coefficient_support_size, best_coefficients, singular_values)#
- class qlinks.caging.WindowedAnnihilatorScan(points, metric, periodic_box, action_normalization, action_tolerance, rank_tolerance)[source]#
Bases:
objectMinimum local-annihilation residual as a function of allowed radius.
- points: tuple[WindowedAnnihilatorPoint, ...]#
- __init__(points, metric, periodic_box, action_normalization, action_tolerance, rank_tolerance)#
- class qlinks.caging.ZeroInternalKineticFilter(tolerance=1e-10)[source]#
Bases:
objectRequire the internal kinetic block to be zero.
This is useful for Type-1 cages on one side of a bipartite kinetic graph. If the graph is exactly bipartite and the support lies on one side, this should hold automatically, but this filter certifies it numerically.
- __init__(tolerance=1e-10)#
- qlinks.caging.adjacent_gap_ratio_report(eigenvalues, *, trim_fraction=0.1, degeneracy_tolerance=1e-10)[source]#
Compute adjacent-gap ratios after trimming spectral edges.
The input must already belong to one fully desymmetrized sector. Pairs touching a spacing below
degeneracy_toleranceare omitted and their number remains visible throughn_levels_usedandn_ratios.
- qlinks.caging.analyze_local_rdm_structure(readout, *, model=None, tolerance=1e-10, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Identify simple local structures in one RDM readout.
The first version deliberately recognizes only robust, notebook-readable motifs: rank-one two-pattern coherent sectors and diagonal classical/frozen sectors. If a QDM
modelis supplied, fully contained plaquettes are also classified as always inactive, always flippable, or mixed on the RDM support.
- qlinks.caging.analyze_qdm_block_product_subspace(model, blocks, padding, *, tolerance=1e-10)[source]#
Build the exact restricted Hamiltonian and external leakage map.
- qlinks.caging.analyze_square_qdm_singlet_product_tilings(model, *, max_tilings=None, tolerance=1e-10)[source]#
Analyze exact-cover tilings without invoking a global cage search.
- qlinks.caging.analyze_square_qdm_singlet_stripe_product(model, *, direction='x', transverse_coordinate=0, offset=0, spacing=3, max_paddings=1, include_sectors=False, require_static_exterior=True, tolerance=1e-10)[source]#
Test a regular stripe of independent two-plaquette singlet factors.
- qlinks.caging.as_dense_array(matrix)[source]#
Convert a dense or sparse matrix to a dense complex NumPy array.
- qlinks.caging.audit_quasi_1d_sequence(points, *, energy_density_mismatch=None, thermal_comparison='beta_zero', level_gap_ratio=None, zero_mode_fraction=None, tolerance=1e-09)[source]#
Separate exact quasi-1D results from unresolved ETH/topology claims.
- qlinks.caging.autograd_available()[source]#
Return whether the optional Autograd optimization backend is installed.
- qlinks.caging.basis_permutation_from_transform(basis_configs, transform)[source]#
Return the basis-index permutation induced by a configuration transform.
The returned array
puses the conventionU |i> = |p[i]>.
- qlinks.caging.basis_permutation_from_variable_permutation(basis_configs, variable_permutation)[source]#
Return a basis permutation from
new_config = old_config[permutation].
- qlinks.caging.beta_zero_matching_subspace(scar_term_expectations, thermal_term_expectations, *, tolerance=1e-10)[source]#
Return coefficients
csatisfyingc·(scar-thermal)=0.
- qlinks.caging.boundary_cancellation_matroid_from_hamiltonian(hamiltonian, support, regions, *, tolerance=1e-10)[source]#
Hamiltonian wrapper using global Hilbert-space indices for regions.
- qlinks.caging.boundary_nullity(boundary_matrix, *, tolerance=1e-10)[source]#
Return the nullity of the boundary-leakage matrix.
- qlinks.caging.build_hamiltonian_graph_chain_complex(hamiltonian, support_indices, local_generators, *, energy=0.0, test_indices=None, generators_are_full_hilbert_vectors=False, generator_labels=())[source]#
Build
D_EandT_Rfrom a Hamiltonian and a support shell.D_Eis the selected-row block of(H - E I) P_support. Local generators may be supplied either in support coordinates or as full Hilbert-space vectors.
- qlinks.caging.build_qdm_boundary_resolved_tile_basis(model, *, plaquette_ids, halo_layers=1, max_states=100000)[source]#
Build the enlarged local basis needed after a singlet-support no-go.
The basis keeps every locally valid configuration in a finite plaquette halo and groups configurations by the outside dimer deficits on boundary sites. No tensor-network backend is required for this preprocessing step.
- qlinks.caging.build_qdm_explicit_support_boundary(model, support_configs)[source]#
Build the support-to-exterior QDM kinetic map without a global basis.
- qlinks.caging.build_qdm_global_limited_kinetic_matrix(model, basis)[source]#
Build QDM kinetic transitions restricted to an explicitly supplied basis.
- qlinks.caging.build_qdm_local_kinetic_matrix(model, region, local_basis)[source]#
Build the local kinetic matrix without using a global basis/Hamiltonian.
- qlinks.caging.build_qdm_local_region_from_links(model, *, link_ids, boundary_mode, active_plaquette_ids=None, scoring_plaquette_ids=None, seed_plaquette_ids=None)[source]#
Build a local QDM region from explicit link ids.
- qlinks.caging.build_qdm_local_region_from_plaquettes(model, *, plaquette_ids, halo_layers, boundary_mode, scoring_plaquette_ids=None)[source]#
Build a local QDM region by expanding seed plaquettes by shared-link halo.
- qlinks.caging.build_square_qdm_peps_finite_cluster_problem(model, tile_basis, *, basis_solver='dfs', builder='sparse', tolerance=1e-10)[source]#
Map a translational tile tensor to an exact finite periodic QDM basis.
- qlinks.caging.build_square_qdm_rectangular_tile_tensor_basis(model, *, tile_shape, origin=(0, 0), max_owned_links=20)[source]#
Enumerate the exact structural support of a rectangular QDM tile tensor.
- qlinks.caging.build_square_qdm_singlet_boundary_tile(model, singlet, *, halo_layers=1, max_states=100000)[source]#
Embed a two-state singlet core in a halo basis for TN construction.
- qlinks.caging.build_square_qdm_singlet_peps_ansatz(model, singlet, *, origin=None, normalize_parameters=True)[source]#
Construct the singlet-core starting tensor in a rectangular PEPS tile.
- qlinks.caging.build_square_qdm_type1_adaptive_joint_cluster_problem(problems, parameterization, *, aggregation_power=4.0, potential_weight=1.0, cluster_weights=None, tolerance=1e-10)[source]#
Map several native type-1 problems to one targeted enlarged unit cell.
- qlinks.caging.build_square_qdm_type1_adaptive_parameterization(problem, parameters, *, plaquette_class=None, split_axis='auto', max_selected_entries=12, probe_scale=0.001, seed=0)[source]#
Build a period-two enlargement targeted at the dominant seam residual.
- qlinks.caging.build_square_qdm_type1_joint_cluster_problem(problems, *, aggregation_power=4.0, potential_weight=1.0, cluster_weights=None, tolerance=1e-10)[source]#
Build a shared-tensor type-1 objective over several finite clusters.
- qlinks.caging.build_square_qdm_type1_peps_problem(model, tile_basis, *, target_chiral_label=None, reference_parameters=None, cage_record=None, potential_weight=1.0, infer_parity_rule=True, basis_solver='dfs', builder='sparse', tolerance=1e-10)[source]#
Build the finite-cluster type-1 PEPS objective.
cage_recordmay be an existing type-1CageRecord; its support fixes the occupied chiral subset and records the exact potential value of the finite cage. Otherwise,reference_parameterscan select the sector carrying the larger PEPS norm. If neither is supplied, sector zero is used.
- qlinks.caging.cage_compatibility_hierarchy_from_hamiltonians(base_hamiltonian, perturbations, support, cage_state, *, coefficient_field='real', tolerance=1e-10)[source]#
Compare infinitesimal continuation and exact affine compatibility.
- qlinks.caging.cage_finite_size_scorecard(hamiltonian, candidate_shell, state, *, kinetic=None, actual_support=None, amplitude_tolerance=1e-10, rank_tolerance=1e-10, metadata=None)[source]#
Build the manuscript scorecard for one finite-size cage.
The boundary matrix is evaluated on the complete candidate shell, while the internal/boundary residuals are evaluated on the actual nonzero support. This keeps the shell nullity separate from a postselected localized basis.
- qlinks.caging.cage_jacobian_conditioning(internal_matrix, boundary_matrix, cage_state, *, support=None, tolerance=1e-10)[source]#
Evaluate the gauge-fixed Jacobian and
Delta_cage.The domain consists of state variations orthogonal to the normalized cage vector together with one energy variation. This is the finite-dimensional Jacobian in Eq. (45) of the current deformation criterion. Its smallest positive singular value is a conditioning scale after a deformation has passed the obstruction test; it does not by itself guarantee compatibility.
- qlinks.caging.cage_jacobian_conditioning_from_hamiltonian(hamiltonian, support, cage_state, *, tolerance=1e-10)[source]#
Build the cage Jacobian directly from a full Hamiltonian.
- qlinks.caging.cage_state_to_full_vector(cage_state, hilbert_size)[source]#
Lift a compact cage state to the full Hilbert-space vector.
- qlinks.caging.cage_states_to_full_matrix(cage_states, hilbert_size)[source]#
Lift many compact cage states to dense full-Hilbert vectors.
- qlinks.caging.certified_qdm_result_from_multi_block_reports(model, reports, *, config=None)[source]#
Wrap multi-block QDM certificates as a limited-basis cage result.
The returned object uses the same
CertifiedLocalQDMCageSearchResultcontainer as the single-block local-padding path. Its basis is the limited union of certified support configurations and their one-hop kinetic shell, so downstream classification and visualization tools can consume it without enumerating the full global Hilbert space.
- qlinks.caging.certify_local_witness_on_square_qdm_periodic_sequence(sequence, witness, *, normalization='operator_norm', tolerance=1e-10)[source]#
Verify
L_R |Psi_n> = 0from one unit-cell-local calculation.
- qlinks.caging.certify_qdm_factorized_product_state(model, blocks, padding, *, config=None)[source]#
Certify a separated product cage without forming its global support.
The Hamiltonian action is represented as a sum of tensor-product vectors. Norms and expectation values are evaluated by factor contractions. The cost is polynomial in the number of blocks and plaquettes and exponential only in the largest single-block support, rather than in the product of all block support sizes.
Exact factorization currently requires every plaquette to touch at most one selected block. This is precisely the kinetic-separation condition used by the strict multi-padding workflow.
- qlinks.caging.certify_qdm_local_record(model, local_record, *, local_record_index=0, config=None)[source]#
Return certified shared-exterior paddings for one local QDM record.
- qlinks.caging.certify_qdm_local_result(model, local_result, *, config=None)[source]#
Pad and certify all local QDM records without a full basis/Hamiltonian.
The certification uses a limited global basis made from the union of each certified support and its one-hop kinetic shell. It returns ordinary
CageRecordobjects inside aCageSearchResultso downstream code that only depends on the cage-result protocol can consume the output.
- qlinks.caging.certify_qdm_multi_block_padding(model, blocks, padding, *, padding_index=0, config=None)[source]#
Certify one multi-block QDM padding by explicit global one-hop action.
- qlinks.caging.certify_qdm_multi_block_paddings(model, block_pool, *, config=None)[source]#
Find and certify Lego-style multi-block QDM paddings from a block pool.
Candidate padding generation is interleaved with certification. The search stops after
config.max_paddingscertified reports or afterconfig.max_padding_attemptsraw padding attempts. Ifmax_padding_attemptsisNone, there is no separate raw-attempt cap.
- qlinks.caging.certify_qdm_multi_block_result(model, blocks, *, config=None)[source]#
Find/certify multi-block QDM paddings and return a certified result.
This is the multi-block analogue of
certify_qdm_local_result: it keeps the basis limited to the certified product support plus one-hop shell, but exposes ordinaryCageRecordentries for existing tools.
- qlinks.caging.certify_square_qdm_biperiodic_product_instance(instance, *, tolerance=1e-09)[source]#
Certify one finite bi-periodic product-tile array by local identities.
- qlinks.caging.certify_square_qdm_biperiodic_product_sequence(tile, *, verification_repeats=3, check_smaller_repeats=True, tolerance=1e-09)[source]#
Return the exact two-dimensional sequence certificate for
tile.The function returns a diagnostic object even when certification fails; use
certificate.is_certifiedandcertificate.failed_checksto inspect the obstruction rather than relying on an exception for ordinary search failure.
- qlinks.caging.certify_square_qdm_periodic_product_instance(instance, *, tolerance=1e-09)[source]#
Certify a finite repeated product through strictly local identities.
- qlinks.caging.certify_square_qdm_periodic_product_sequence(unit_cell, *, verification_repeats=3, check_smaller_repeats=True, tolerance=1e-09)[source]#
Prove an arbitrary-repeat one-axis cage sequence from local identities.
Three repeats expose a left neighbor, a central unit, and a right neighbor. Because square-QDM plaquette terms have range one and the construction is an exact coordinate translation with uniform couplings, the verified local action classes then repeat for every larger system. Smaller periodic rings are checked separately by default because they can identify neighboring copies through the short circumference.
- qlinks.caging.classify_cage_state(cage_state, *, kinetic_matrix, basis_configs, hilbert_size=None, sector_mask=None, potential_diagonal=None, config=None)[source]#
Classify one compact cage state from solver output.
- Parameters:
cage_state (CageState) – Compact cage state returned by the caging solver.
kinetic_matrix (spmatrix | sparray | ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Off-diagonal Hamiltonian or kinetic matrix used to identify interference zeros and local
Z_hpatterns.basis_configs (ndarray[tuple[Any, ...], dtype[integer]]) – Integer array with shape
(n_basis, n_variables). Rows are product-state configurations in the global constrained basis.hilbert_size (int | None) – Full Hilbert-space dimension. Defaults to
basis_configs.shape[0].sector_mask (ndarray[tuple[Any, ...], dtype[bool]] | None) – Optional mask selecting the sector used for local diagnostics.
potential_diagonal (ndarray[tuple[Any, ...], dtype[number]] | None) – Optional diagonal potential/self-loop values. When provided, the report includes shell-relative Fock-space support diagnostics if the state has a sharp potential value.
config (CageClassificationConfig | None) – Numerical classification parameters.
- Returns:
Classification report describing reduced-IZ zeros, regional/extended labels, and monitor decompositions.
- Return type:
- qlinks.caging.classify_full_state(full_state, *, kinetic_matrix, basis_configs, sector_mask=None, potential_diagonal=None, config=None, metadata=None)[source]#
Classify a full Hilbert-space vector.
- qlinks.caging.collect_qdm_cage_blocks_from_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)#
Run proposal searches and return a QDM block pool for multi-padding.
- qlinks.caging.collect_qdm_cage_blocks_from_region_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)[source]#
Run proposal searches and return a QDM block pool for multi-padding.
- qlinks.caging.collect_qdm_cage_blocks_with_scan_from_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)#
Run proposal searches and stream compatible QDM blocks.
This is the block-oriented counterpart of
run_local_region_proposals(). It converts records intoLocalQDMCageBlockobjects immediately after each region is searched and stops as soon asmax_blocksis reached. This is important for expensive proposal portfolios: the older two-stage workflow searched every proposed region first and only then applied the block cap, so robust scans could spend most of their time in local DFS branches that would never contribute to the requested block pool.
- qlinks.caging.collect_qdm_cage_blocks_with_scan_from_region_proposals(proposals, *, model=None, config=None, adapter=None, signatures=None, max_regions=None, max_records_per_region=None, max_blocks=None, block_id_start=0, skip_incompatible_blocks=True)[source]#
Run proposal searches and stream compatible QDM blocks.
This is the block-oriented counterpart of
run_local_region_proposals(). It converts records intoLocalQDMCageBlockobjects immediately after each region is searched and stops as soon asmax_blocksis reached. This is important for expensive proposal portfolios: the older two-stage workflow searched every proposed region first and only then applied the block cap, so robust scans could spend most of their time in local DFS branches that would never contribute to the requested block pool.
- qlinks.caging.combine_perturbations_from_coefficients(perturbations, coefficient_basis)[source]#
Convert coefficient-space basis vectors into Hamiltonian perturbations.
- qlinks.caging.common_local_witness_families(reports, *, include_projector_like=True, require_all_systems=True, normalization='none')[source]#
Match identical reduced-IZ local patterns across system sizes.
Matching is exact in the ordered local pattern basis. Translations are automatically matched because global variable indices are not part of the template key. Rotations or reflections require the caller to relabel local variables consistently before classification.
- qlinks.caging.commutant_algebra_diagnostic_from_operator_basis(*, operators, hamiltonian_terms, operator_names=None, term_names=None, tolerance=1e-10, max_commutant_vectors=16)[source]#
Find operator-basis combinations commuting with all supplied terms.
- qlinks.caging.commuting_cyclic_symmetry_sector_basis(index_permutations, *, orders, momentum_indices, labels=None, tolerance=1e-10)[source]#
Build a simultaneous character basis for commuting cyclic permutations.
This is the finite Abelian-group extension of
cyclic_symmetry_sector_basis(). It is particularly useful for the two translation generators of a periodic lattice. One normalized Fourier vector is produced for every compatible group orbit.
- qlinks.caging.cyclic_symmetry_sector_basis(index_permutation, *, order, momentum_index, labels=None, tolerance=1e-10)[source]#
Build a Fourier-orbit basis for one sector of a cyclic permutation.
momentum_indexlabels the eigenvalueexp(2π i k / order). Short orbits are included only when this character is compatible with the orbit stabilizer.
- qlinks.caging.diagnose_boundary_cancellation_matroid(boundary_matrix, regions, *, tolerance=1e-10)[source]#
Diagnose weighted global dependencies modulo regional circuits.
regionscontains boundary-matrix column indices. Every regional right kernel is embedded in the full column space. Their span is quotiented from the complete right kernel, reducing the unweighted graph-cycle problem to cancellation relations that satisfy the actual matrix amplitudes.
- qlinks.caging.diagnose_boundary_incidence_cohomology(boundary, state=None, *, tolerance=1e-10)[source]#
Diagnose whether a boundary map is a flat two-channel incidence problem.
- qlinks.caging.diagnose_cage_stability(hamiltonian, support, *, state=None, tolerance=1e-10, max_power=None, stabilization_rounds=1)[source]#
Diagnose the interference kernel and its internally invariant subspace.
statecan be either a compact support vector or a full Hilbert-space vector. When supplied, the report distinguishes boundary leakage from the internal eigenvector residual.
- qlinks.caging.diagnose_chiral_index(off_diagonal_block, *, trim_isolated_rows=True, trim_isolated_columns=False, tolerance=1e-10)[source]#
Diagnose index-protected and paired zero modes of a chiral block
A.Isolated rows are removed by default because a support-to-boundary block often includes complementary configurations that are not adjacent to the selected support. Their trivial zero modes should not be mistaken for a chiral index of the interference network.
- qlinks.caging.diagnose_cyclic_amplitude_bond_profile(column_words, amplitudes, *, tolerance=1e-10)[source]#
Compute exact finite-state bond ranks of a cyclic column amplitude.
- qlinks.caging.diagnose_eigenpair(hamiltonian, state)[source]#
Return the Rayleigh energy, residual, and variance of a state.
- qlinks.caging.diagnose_hamiltonian_graph_homology(complex_, *, tolerance=1e-10, require_chain_condition=True)[source]#
Compute finite-volume homology, dual cocycles, and the Hodge gap.
- qlinks.caging.diagnose_hard_core_laurent_lift(support_configs, amplitudes, boundary, *, raised_value=1, maximum_root_order=32, tolerance=1e-10)[source]#
Detect a uniform cyclotomic transfer rule in a hard-core cage shell.
- qlinks.caging.diagnose_incidence_constraint_interface(left_constraint_map, right_constraint_map, interface_constraint_map, *, tolerance=1e-10)[source]#
Glue two local constraint modules and test for an excess interface kernel.
- qlinks.caging.diagnose_laurent_periodic_dimension_consistency(repeat_counts, observed_dimensions, *, assumed_free_rank=0)[source]#
Test necessary fixed-symbol constraints on observed periodic dimensions.
- qlinks.caging.diagnose_laurent_polynomial_constraint_module(coefficient_terms, repeat_counts, *, generic_sample_count=12, tolerance=1e-10)[source]#
Diagnose free and root-of-unity torsion sectors of
B(z).generic_sample_countnon-root-of-unity complex points are used to find the maximum symbol rank, which equals the rank overC(z)away from a nongeneric algebraic set. Periodic kernels are then evaluated exactly at every root of unity for the requested repetition counts.
- qlinks.caging.diagnose_local_channel_spectrum(channel, *, normalize_operator=False, tolerance=1e-10)[source]#
Diagnose
Q_R=A_R^dagger A_Rand its smallest positive eigenvalue.dark_channel_gapis the quantity denotedDelta_Qin the predictive deformation criterion. It is a conditioning scale for the local dark subspace, not by itself an exact-protection criterion.
- qlinks.caging.diagnose_locality_restricted_chiral_profile(hamiltonian, regions, *, target_state=None, tolerance=1e-10)[source]#
Diagnose chiral zero modes separately on prescribed support regions.
The regions define the locality restriction. For each region, the function forms the support-to-complement block and computes its finite-dimensional chiral index. If
target_stateis supplied, its projection onto each region is tested against that regional boundary map.
- qlinks.caging.diagnose_many_body_cls_completeness(target_manifold, local_generators=None, *, translation_permutations=(), translation_orders=(), tolerance=1e-10, require_generator_containment=True)[source]#
Compute the quotient missed by translated local cage generators.
- qlinks.caging.diagnose_many_body_topological_localization(target_manifold, local_generators, *, translation_permutations, translation_orders, tolerance=1e-10)[source]#
Resolve a many-body CLS-completeness quotient by lattice momentum.
- qlinks.caging.diagnose_periodic_laurent_kernel(coefficients, length, *, twist=0.0, tolerance=1e-10)[source]#
Compute the finite-ring nullity and smallest nonzero singular value.
- qlinks.caging.diagnose_qdm_local_kinetic_compatibility(model, support_configs, state, *, boundary_map=None, tolerance=1e-10)[source]#
Find multiplicative plaquette-kinetic perturbations preserving one cage.
Each coefficient independently rescales the kinetic operator already stored on one model plaquette. For the uniform unit-coupling QDM this is the usual additive local-coupling basis.
- qlinks.caging.diagnose_qdm_local_potential_compatibility(model, support_configs, *, tolerance=1e-10)[source]#
Find plaquette-potential perturbations uniform on an explicit support.
- qlinks.caging.diagnose_qdm_multi_block_paddings(model, block_pool, *, config=None)[source]#
Find multi-block paddings and report both successes and failures.
This diagnostic path uses the same interleaved padding/certification loop as
certify_qdm_multi_block_paddings().paddingsstores the raw candidates actually attempted, whilen_padding_attemptsrecords that count explicitly for notebook/debug summaries.
- qlinks.caging.diagnose_real_local_sign_obstruction(column_words, amplitudes, *, window_size=3, tolerance=1e-10)[source]#
Diagnose the discrete real-sign class of a finite cage amplitude.
- qlinks.caging.diagnose_reduced_constraint_fredholm_candidate(constraint_map, *, kernel_basis=None, tolerance=1e-10)[source]#
Quotient an exact kernel and test whether a scalar winding is intrinsic.
A square, injective reduced map can be the value of a Fredholm symbol once a translation-dependent family is supplied. A strictly tall map has no intrinsic determinant phase: choosing a frame for its range can shift any apparent square-compression winding.
- qlinks.caging.diagnose_relative_mod2_cycles(boundary, regions, *, tolerance=1e-10)[source]#
Compute full boundary cycles modulo cycles internal to support regions.
regionscontain column indices of the supplied boundary matrix. Every regional graph includes those columns and all incident boundary rows. The resulting quotient is a graph invariant over GF(2); it does not by itself identify which quotient cycles participate in a particular cage vector.
- qlinks.caging.diagnose_scalar_laurent_bulk_phase(transport, *, tolerance=1e-10)[source]#
Diagnose the scalar symbol
b(z)=z-transporton the unit circle.
- qlinks.caging.diagnose_scalar_laurent_domain_wall(left_transport, right_transport, *, left_length=24, right_length=24, interface_window_radius=1, tolerance=1e-10)[source]#
Test the bulk–defect correspondence of two scalar transport modules.
- qlinks.caging.diagnose_signed_boundary_holonomy(boundary, *, tolerance=1e-10)[source]#
Compute real signed holonomies on a fundamental cycle basis.
Row and column rescalings cancel from the alternating cycle product. The sign is therefore a discrete gauge invariant as long as no active edge crosses zero. Complex-valued matrices are rejected because their natural invariant is a U(1) phase rather than a Z2 sign.
- qlinks.caging.diagnose_square_qdm_biperiodic_repeatability(tile, *, verification_repeats=3, check_smaller_repeats=True, tolerance=1e-09)[source]#
Diagnose whether a tile generates an exact family for arbitrary
nx, ny.A
3 x 3tile array contains an interior tile, both one-direction seams, and four-tile corner environments. Because square-QDM terms have range one, exact coordinate repetition with uniform couplings then propagates these identities to every larger torus. Rings of size one and two are checked separately by default because periodic identifications create short-ring environments not present in the generic3 x 3array.
- qlinks.caging.diagnose_square_qdm_compact_cage_reduced_winding(unit_cell, repeat_counts, *, max_support_size=1024, tolerance=1e-10)[source]#
Audit scalar Fredholm winding for the compact QDM cage sequence.
Two reductions are kept separate. In state space the exact product cage is quotiented from the physical support-to-shell map. This map remains strictly rectangular and therefore has no intrinsic determinant winding. In coupling space the cage-compatible directions are quotiented from the independently varying plaquette couplings. The remaining two channels per repeated cell form a constant positive symbol and hence carry winding zero.
- qlinks.caging.diagnose_square_qdm_finite_bond_transfer_invariant(model, support_configs, kernel_basis, reference_basis=None, *, tolerance=1e-10)[source]#
Resolve a fixed-width cage kernel and its quotient into momentum sectors.
The kernel is interpreted as the finite transfer/bond space admitted by the local support language.
reference_basistypically contains translated compact cages. The relative momentum multiplicities are basis independent.
- qlinks.caging.diagnose_term_resolved_caging(local_constraint_maps, *, coefficients=None, tolerance=1e-10)[source]#
Resolve robust channelwise zeros from collectively cancelled cages.
Every local map must have the same row and column dimensions. The physical differential is their coefficient-weighted sum, while the term-resolved differential is the vertical stack of the individual weighted maps.
- qlinks.caging.diagonal_values(matrix, support_indices)[source]#
Return diagonal values of
matrixonsupport_indices.
- qlinks.caging.directed_transition_witness_template(*, target_pattern, source_patterns, amplitudes, pattern_key=(), source_zero_indices=(), mechanism_labels=(), metadata=None, normalization='none')[source]#
Construct a directed local transition map from sources into one target.
The returned local operator has the rank-one form
A_R = |target><v|,|v> = sum_j amplitudes[j]^* |source_j>.The target pattern is stored first, followed by the source patterns. This helper is model independent and is useful when a boundary-row cancellation is retained as a one-sided local channel rather than Hermitianized into an IZ operator.
- qlinks.caging.distinct_reduced_iz_pattern_supports(report, *, include_projector_like=True)[source]#
Group reduced IZ probes by local transition pattern and support.
- qlinks.caging.eigenstate_expectations(operator, eigenvectors)[source]#
Return diagonal matrix elements of an operator in supplied eigenstates.
- qlinks.caging.embed_cage_state(cage_state, *, hilbert_size)[source]#
Embed a compact cage state into the full Hilbert space.
- qlinks.caging.enumerate_qdm_local_basis(model, region, *, include_sectors_when_full, prune_inactive_states=False, max_states=None, sort=True)[source]#
Enumerate local dimer configurations on
region.link_ids.The local-search layer deliberately reuses
DFSBasisSolverrather than maintaining a separate DFS. QDM-specific local rules are represented as lightweight constraints on the local binary-link layout, so future DFS optimizations immediately benefit both full-basis enumeration and local cage searches.
- qlinks.caging.enumerate_square_qdm_singlet_exact_covers(model, *, singlet_blocks=None, max_tilings=None)[source]#
Enumerate exact site covers by horizontal/vertical singlet rectangles.
- qlinks.caging.estimate_power_law_exponent(parameters, residuals, *, minimum_parameter=0.0, minimum_residual=0.0)[source]#
Estimate
residual ~ |parameter|**pby a log-log fit.
- qlinks.caging.evaluate_local_witness_microcanonical(witness, *, basis_configs, eigenvectors, eigenvalues, energy_center, half_width, system_size=None, metadata=None)[source]#
Evaluate
Q_Rin an equal-weight finite-size energy shell.
- qlinks.caging.evaluate_local_witness_on_diagonal_ensemble(witness, *, basis_configs, probabilities=None, metadata=None)[source]#
Evaluate
Q_Rin an ensemble diagonal in the constrained basis.With
probabilities=Nonethis is the exact infinite-temperature trace in the supplied constrained basis and symmetry sector.
- qlinks.caging.evaluate_local_witness_on_states(witness, *, basis_configs, states, weights=None, normalize_columns=True, metadata=None)[source]#
Evaluate
Q_Ron a pure state or a weighted ensemble of states.The constrained-basis embedding of
L_Ris sparse. The variance is the quantum variance ofQ_Rin the mixed state represented by the supplied weights, not the variance of the per-eigenstate expectation values.
- qlinks.caging.evaluate_square_qdm_beta_zero_energy_density(*, circumference, length, potential_coupling=1.0, winding_sector=None, winding_projection='auto', fourier_points=None)[source]#
Evaluate the beta-zero energy density of a uniform square QDM.
The kinetic term is off-diagonal in the dimer basis and has zero trace. The potential part is the coupling times the probability that a plaquette is flippable in either orientation.
- qlinks.caging.evaluate_square_qdm_classification_witnesses_on_strips(report, *, model, lengths, boundary_x='periodic', winding_sector=None, normalization='operator_norm', include_projector_like=True, winding_projection='auto', fourier_points=None)[source]#
Evaluate the actual cage-derived reduced-IZ witnesses on strips.
The default operator-norm normalization fixes
||Q_R|| = 1. This removes the arbitrary coefficient scale from comparisons between distinct interference-zero rows and between different system sizes.
- qlinks.caging.evaluate_square_qdm_witness_family_on_strips(family, *, models, lengths, boundary_x='periodic', winding_sector=None, embedding_index=0, winding_projection='auto', fourier_points=None)[source]#
Evaluate one common cage-derived witness family on square-QDM strips.
familyis usually produced bycommon_local_witness_families(). Each family embedding is paired with the model carrying the same system label, converted to strip coordinates, and evaluated without rebuilding a global dimer basis.
- qlinks.caging.exact_compact_states_from_support(eigenspace_basis, support_mask, *, tolerance)[source]#
Given a trial support C, find exact vectors in span(V) that vanish outside C.
Returns columns with shape (support_size_of_parent, n_exact_states).
- qlinks.caging.extract_cage_region_support(report, *, policy='raise_on_unexplained', include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True, complement_action_tolerance=None)[source]#
Extract the union support R from trusted reduced IZ probes.
This function does not interpret the report label as a scaling statement. It only asks whether each reduced probe has explained complement behavior.
By default, q_empty, closed_by_known_zeros, domain_blocked, and projector_like probes are all allowed. Only unexplained_leakage is rejected.
- qlinks.caging.extract_subblocks(matrix, support_indices)[source]#
Extract internal and boundary blocks for a candidate support.
- Parameters:
- Returns:
Tuple
(internal_matrix, boundary_matrix, outside_indices)whereinternal_matrix = matrix[support, support]andboundary_matrix = matrix[outside, support].- Return type:
- qlinks.caging.factorized_qdm_padding_from_multi_padding(padding)[source]#
Drop the materialized Cartesian-product support from an old padding.
- qlinks.caging.filter_candidates(context, candidates, candidate_filters)[source]#
Return candidates accepted by all filters.
- qlinks.caging.find_factorized_qdm_block_paddings(model, block_pool, *, config=None)[source]#
Materialize a bounded list of factorized QDM exterior assignments.
- qlinks.caging.find_multi_qdm_block_paddings(model, block_pool, *, config=None)[source]#
Find shared-exterior paddings built from a pool of local QDM blocks.
This materialized API keeps the original raw-padding semantics:
config.max_paddingsis the maximum number of candidate paddings returned. Certification helpers useiter_multi_qdm_block_paddings()directly so they can keep trying candidates until enough certified cages are found.
- qlinks.caging.find_qdm_multi_block_paddings(model, block_pool, *, config=None)#
Find shared-exterior paddings built from a pool of local QDM blocks.
This materialized API keeps the original raw-padding semantics:
config.max_paddingsis the maximum number of candidate paddings returned. Certification helpers useiter_multi_qdm_block_paddings()directly so they can keep trying candidates until enough certified cages are found.
Find shared exterior configurations compatible with a local QDM cage.
A shared exterior is a single assignment on all nonlocal links such that every local support configuration becomes a full valid dimer covering. This is the simplest product padding that preserves the local superposition.
- qlinks.caging.fixed_cage_manifold_compatibility(boundary_matrix, manifold_basis, boundary_perturbations, *, internal_perturbations, coefficient_field='real', tolerance=1e-10)[source]#
Find affine perturbations preserving an entire cage manifold exactly.
- qlinks.caging.fixed_cage_manifold_compatibility_from_hamiltonians(base_hamiltonian, perturbations, *, support, manifold_states, coefficient_field='real', tolerance=1e-10)[source]#
Hamiltonian wrapper for
fixed_cage_manifold_compatibility().
- qlinks.caging.fixed_cage_state_compatibility(boundary_matrix, cage_state, boundary_perturbations, *, internal_perturbations, coefficient_field='real', tolerance=1e-10)[source]#
Find perturbation combinations that preserve one cage vector exactly.
For an affine deformation
H(lambda) = H0 + lambda V, the compact state remains an exact eigenvector for everylambdaprecisely whendelta_B phi = 0and(I - |phi><phi|) delta_A phi = 0.The returned coefficient nullspace imposes these conditions collectively; individual perturbation terms need not preserve the state on their own.
- qlinks.caging.fixed_cage_state_compatibility_from_hamiltonians(base_hamiltonian, perturbations, support, cage_state, *, coefficient_field='real', tolerance=1e-10)[source]#
Build the exact fixed-state compatibility space from full matrices.
- qlinks.caging.fock_space_automorphism_diagnostic(*, kinetic_matrix, support_indices, state, tolerance=1e-10, weight_tolerance=0.0, max_graph_vertices=96, max_automorphisms=128, include_identity=False)[source]#
Diagnose boundary-fixed Fock-space automorphisms of a cage support.
- Parameters:
kinetic_matrix – Sparse or dense matrix defining Fock-space hopping.
support_indices (Sequence[int]) – Global basis indices carrying the compact state.
state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Either the local state on
support_indicesor a full Hilbert vector in the same basis askinetic_matrix.tolerance (float) – Numerical tolerance used for symmetry/eigenstate tests.
weight_tolerance (float) – Matrix entries with smaller absolute value are ignored when building the graph and boundary map.
max_graph_vertices (int | None) – Skip automorphism enumeration above this selected support-plus-boundary graph size. Use
Noneto disable.max_automorphisms (int) – Maximum number of graph automorphisms to test.
include_identity (bool) – Whether to keep the identity permutation in the returned per-permutation diagnostics.
- Returns:
Boundary-fixed automorphism diagnostic.
skipped_reasonis populated when the selected graph is intentionally too large for this lightweight diagnostic.- Return type:
- qlinks.caging.fock_space_automorphism_diagnostic_for_cage_state(*, kinetic_matrix, cage_state, tolerance=1e-10, weight_tolerance=0.0, max_graph_vertices=96, max_automorphisms=128, include_identity=False)[source]#
Run
fock_space_automorphism_diagnostic()on aCageState.
- qlinks.caging.gaussian_spectral_filter(eigenvalues, *, target_energy, sigma, cutoff_sigma=6.0)[source]#
Return normalized Gaussian weights centered on
target_energy.
- qlinks.caging.group_reduced_iz_monitor_reports(reports, *, decomposition)[source]#
Group reports according to a reduced-IZ monitor decomposition.
- qlinks.caging.group_reduced_iz_reports_by_connected_support(reports)[source]#
Group reduced-IZ reports whose supports overlap transitively.
- qlinks.caging.group_reduced_iz_reports_by_exact_support(reports)[source]#
Group reduced-IZ reports with identical support variables.
- qlinks.caging.group_vertices_by_signature(*, self_loop_values, bipartition_labels=None, include_bipartition=False, decimals=12)[source]#
Group vertices by self-loop values and optionally bipartition labels.
- qlinks.caging.has_uniform_diagonal(matrix, support_indices, *, tolerance=1e-10)[source]#
Check whether a candidate support has uniform diagonal values.
- qlinks.caging.has_uniform_values(values, *, tolerance=1e-10)[source]#
Check whether all selected scalar/vector values are uniform.
- Parameters:
- Returns:
Trueif every selected row/value agrees within tolerance.- Return type:
- qlinks.caging.hermitianize_local_witness_template(template, *, normalization='none', metadata=None)[source]#
Return the Hermitian symmetrization
L_R + L_R^dagger.The local patterns, source rows, and mechanism labels are preserved. This makes it straightforward to compare a directed transfer witness with the corresponding Hermitian IZ witness using exactly the same local embedding.
- qlinks.caging.infer_square_qdm_chiral_parity_rule(basis_states, kinetic_matrix, *, reference_labels=None, reference_state_indices=(), reference_label=0, tolerance=1e-12)[source]#
Infer a linear link-occupation representation of the chiral operator.
Each distinct kinetic transition contributes the GF(2) equation
a @ (config_i xor config_j) = 1. Free coefficients are fixed to zero, yielding one deterministic solution. The global offset is then aligned to eitherreference_state_indicesor supplied graph bipartition labels.
- qlinks.caging.infer_square_qdm_cyclic_column_grammar(model, support_configs, *, window_size=3)[source]#
Infer a finite-range cyclic support language from reference states.
- qlinks.caging.infer_square_qdm_tile_chiral_parity_rule(model, basis_states, kinetic_matrix, tile_basis, *, reference_labels=None, reference_state_indices=(), reference_label=0, tolerance=1e-12)[source]#
Infer a chiral parity rule constrained to repeat with the PEPS tile.
The unknown GF(2) coefficients live only on the tile’s owned-link keys. Global links whose source coordinates differ by a tile translation share one coefficient. Existence of a solution means the chiral operator can be encoded natively with the chosen one-tensor unit cell.
- qlinks.caging.invariant_boundary_nullspace(internal_matrix, boundary_matrix, *, tolerance=1e-10, max_power=None, stabilization_rounds=1)[source]#
Compute the stabilized subspace
ker(C) >= ker([C; C A]) >= ker([C; C A; C A^2]) >= …
where
internal_matrixisAandboundary_matrixisC.The returned array has shape
(support_size, subspace_dimension). Its columns form an orthonormal basis of the stabilized subspace.
- qlinks.caging.iter_factorized_qdm_block_paddings(model, block_pool, *, config=None, max_yielded=None)[source]#
Yield exterior assignments without materializing block support products.
This mirrors
iter_multi_qdm_block_paddings(), but the returned object contains only the block ids and shared exterior configuration. The search therefore remains usable whenprod(block.support_size)is too large to enumerate.max_product_support_sizeis intentionally not applied on this path because the Cartesian-product support is never materialized.
- qlinks.caging.iter_multi_qdm_block_paddings(model, block_pool, *, config=None, max_yielded=None)[source]#
Yield shared-exterior paddings built from a pool of QDM blocks.
This is the streaming counterpart of
find_multi_qdm_block_paddings(). It is intended for certification-in-the-loop workflows, where a caller may want to keep trying raw exterior completions until enough certified cages are found.max_yieldedlimits the number of raw candidate paddings yielded by this iterator; if omitted,config.max_padding_attemptsis used.
- qlinks.caging.laurent_polynomial_constraint_symbol(coefficient_terms, z)[source]#
Evaluate
sum_d z**d B_dfor one nonzero complex translation value.
- qlinks.caging.lift_state_from_sector(sector_state, sector)[source]#
Lift sector coordinates into the full basis.
- qlinks.caging.linearized_cage_obstruction(boundary_matrix, cage_state, boundary_perturbations, *, internal_matrix=None, internal_perturbations=None, coefficient_field='real', tolerance=1e-10)[source]#
Build first-order boundary and eigenstate obstruction maps.
The boundary-only condition tests solvability of
B delta_phi = -delta_B phi. When the internal blocks are supplied, the primary obstruction map additionally enforces the linearized eigenvalue equation and the gauge<phi|delta_phi> = 0.For
coefficient_field='real', real and imaginary parts are stacked so the returned coefficient nullspace corresponds to real coupling changes.
- qlinks.caging.linearized_cage_obstruction_from_hamiltonians(base_hamiltonian, perturbations, support, cage_state, *, coefficient_field='real', tolerance=1e-10)[source]#
Build the first-order obstruction map directly from full matrices.
- qlinks.caging.local_annihilator_diagnostic_from_operators(*, operators, state, operator_names=None, tolerance=1e-10, max_annihilator_vectors=16)[source]#
Find linear combinations of supplied operators that annihilate a state.
- qlinks.caging.local_cage_adapter_for_model(model, adapter=None)[source]#
Return a local-search adapter for
model.Passing
adapteris the explicit, model-generic path. Without an explicit adapter, the registered factories are tried in order.
- qlinks.caging.local_operator_matrix_unit_expansion(*, local_patterns, local_operator, tolerance=1e-10)[source]#
Expand a local operator into matrix-unit terms.
- qlinks.caging.local_rank_one_matrix_unit_expansion(*, local_patterns, alpha, beta, tolerance=1e-10)[source]#
Expand
|alpha><beta|into local matrix units|a><b|.
- qlinks.caging.local_reduced_density_matrix_from_state(*, basis_configs, state, variable_indices, tolerance=1e-10)[source]#
Compute the local RDM of a state represented in a constrained basis.
- qlinks.caging.local_reduced_density_matrix_readout_from_state(*, basis_configs, state, variable_indices, tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, component_index=None, component_id=None, decomposition=None, zero_indices=())[source]#
Compute a local RDM and expose its matrix-unit expansion.
This is a thin caging-facing wrapper around the local-RDM utilities used by the open-system local-recycling layer. No global basis outside
basis_configsis constructed.
- qlinks.caging.local_structure_report_from_classification_report(report, *, basis_configs, state, model=None, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=None, include_empty_supports=False, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Compute reduced-IZ RDM readouts and summarize local cage motifs.
- qlinks.caging.local_structure_report_from_readouts(readouts, *, model=None, decomposition=None, tolerance=1e-10, equal_weight_tolerance=None, rank_one_tolerance=None)[source]#
Build an automatic local-structure report from local RDM readouts.
- qlinks.caging.local_term_operator_basis(*, model, build_result, operator_kind='kinetic', term_kind=None, builder=None, backend='scipy', on_missing='skip')[source]#
Build local Hamiltonian terms as an operator basis for SGA diagnostics.
This is the model-generic entry point for QDM/QLM/disk/spin-chain scans. It relies only on
model.local_term_descriptorsandmodel.build_local_term. Whenbuilderis omitted, the builder is inferred frombuild_resultso bitmask-built bases are rebuilt with the bitmask local-term backend.
- qlinks.caging.local_witness_template_from_pattern_support(pattern_support, *, normalization='none', metadata=None)[source]#
Reconstruct a local row operator from a reduced-IZ transition pattern.
- qlinks.caging.local_witnesses_from_classification_report(report, *, include_projector_like=True, normalization='none')[source]#
Return all trusted reduced-IZ witness embeddings in one finite system.
- qlinks.caging.localized_basis_by_many_start_ipr(eigenspace_basis, *, config)[source]#
Build a localized basis inside a degenerate eigenspace.
The workflow is: 1. many-start IPR maximization, 2. infer candidate supports, 3. enforce exact compactness using a nullspace outside each support, 4. rank-select independent compact states.
- qlinks.caging.make_eth_scaling_point(*, system_size, witness, basis_configs, cage_state, thermal_states=None, thermal_weights=None, diagonal_probabilities=None, energy=None, energy_density=None, system_label=None, metadata=None)[source]#
Build one finite-size ETH comparison for a fixed witness embedding.
If
thermal_statesis omitted, the thermal side is evaluated in a basis- diagonal ensemble. Passing neither thermal states nor diagonal probabilities selects the exact infinite-temperature constrained ensemble.
- qlinks.caging.make_qdm_cage_block(model, local_record, *, block_id=0, guard_plaquette_ids=None)[source]#
Create a constant-boundary Lego block from a local QDM cage record.
Independent product padding requires the number of dimers contributed by the block at every global site to be independent of the local support configuration. If this fails, one shared exterior cannot tensor with the entire block support, so this function raises
ValueError.
- qlinks.caging.make_type1_bipartite_prefilters(*, tolerance=1e-10, min_boundary_nullity=1, min_size=2, max_size=None)[source]#
Prefilters for Type-1 caged states.
- Intended physics:
kinetic graph is bipartite;
support lies on one bipartite subset;
internal kinetic block is zero;
self-loop values are uniform;
kappa = 0.
- qlinks.caging.make_type2_integer_kappa_prefilters(*, target_kappas=(2.0, -2.0), tolerance=1e-10, min_boundary_nullity=1, min_kinetic_nullity=1, min_size=2, max_size=None, use_combined_boundary_kinetic_test=False)[source]#
Prefilters for Type-2 caged states.
- Intended physics:
self-loop values are uniform;
kappa is a nonzero integer such as +2 or -2;
boundary cancellation is possible.
If
use_combined_boundary_kinetic_testis true, the final filter checksker([K_out,S; K_S - kappa I])
directly for each target kappa.
- qlinks.caging.materialize_square_qdm_cyclic_grammar_support(grammar, target_model, *, potential_value=None, max_words=100000, tolerance=1e-10)[source]#
Materialize the physical QDM configurations accepted by a grammar.
- qlinks.caging.materialize_square_qdm_periodic_product_state(instance, basis_configs, *, normalize=True, tolerance=1e-12)[source]#
Embed a modest repeated product cage in an enumerated QDM basis.
The coordinate-level sequence certificate avoids an exponentially large Cartesian product. For ED-accessible repeat counts, this helper explicitly forms that product and maps every complete dimer covering to the supplied basis ordering. It is intended for microcanonical overlap checks and figure generation, not for proving the arbitrary-repeat sequence.
- qlinks.caging.materialize_square_qdm_periodic_product_support(instance, *, max_support_size=4096)[source]#
Materialize a moderate finite periodic-product support exactly.
- qlinks.caging.maximize_ipr_once(eigenspace_basis, *, config, rng)[source]#
Find one local IPR maximum inside span(eigenspace_basis).
- qlinks.caging.microcanonical_ensemble_from_spectrum(eigenvalues, eigenvectors, *, target_energy, half_width, exclude_indices=(), degeneracy_tolerance=1e-10, volume=None)[source]#
Construct an equal-weight microcanonical ensemble from an eigensystem.
The interval is selected by
select_microcanonical_window_by_width(). Degenerate levels intersecting the numerical boundary are retained throughdegeneracy_tolerance. The returned object stores only the selected eigenvectors and therefore remains a low-rank representation of the density matrix.
- qlinks.caging.nullspace_from_gram(gram_matrix, *, tolerance=1e-10)[source]#
Return the nullspace of a positive-semidefinite Gram matrix.
gram_matrixis expected to beA.conj().T @ Afor some matrixA. The returned basis spans the same right nullspace asA, but requires diagonalizing only the small square Gram matrix. The tolerance is applied to the Gram-matrix eigenvalues. This is intentionally conservative: final cage states are still checked with direct boundary/eigen residuals.
- qlinks.caging.nullspace_svd(matrix, *, tolerance=1e-10)[source]#
Return an orthonormal basis for the nullspace of a matrix.
The returned array has shape
(n_columns, nullity).
- qlinks.caging.operator_coefficient_compatibility(operators, target_states, *, mode='fixed_vectors', tolerance=1e-10)[source]#
Find local-operator coefficients preserving target vectors or a subspace.
For
fixed_vectors, every supplied orthonormal target vector must remain an eigenvector separately, allowing a different energy shift for each. Forinvariant_subspace, only the span must remain invariant.
- qlinks.caging.partition_cage_hamiltonian(hamiltonian, support)[source]#
Partition a square Hamiltonian into support, boundary, and external blocks.
- qlinks.caging.periodic_boundary_cancellation_symbol(base_boundary, coupling_terms, momentum)[source]#
Return the Bloch boundary symbol for finite-range periodic couplings.
- qlinks.caging.periodic_laurent_operator(coefficients, length, *, twist=0.0)[source]#
Evaluate a finite Laurent-polynomial matrix at twisted translation.
A scalar dictionary such as
{0: 1, 1: 1}constructsI + T. Matrix coefficients construct a block Laurent operator via Kronecker products.
- qlinks.caging.permutation_matrix(index_permutation)[source]#
Construct the sparse permutation matrix for
U |i> = |p[i]>.
- qlinks.caging.product_basis_diagonal_phase_factors(basis_configs, local_phases)[source]#
Return
exp(i sum_j theta_j n_j)for product-basis configurations.
- qlinks.caging.project_coefficients_to_beta_zero_match(coefficients, report, *, normalize=False)[source]#
Orthogonally project coefficients onto a beta-zero matching space.
- qlinks.caging.project_operator_to_sector(operator, sector)[source]#
Project an operator into an orthonormal sector basis.
- qlinks.caging.project_state_to_sector(state, sector)[source]#
Return sector coordinates of a full-space state.
- qlinks.caging.qdm_global_self_loop_values(model, configs)[source]#
Compute full QDM potential/self-loop values for explicit configs.
- qlinks.caging.qdm_local_self_loop_values(model, region, local_basis)[source]#
Return local potential/self-loop values on the scoring plaquettes.
- qlinks.caging.qdm_multi_padding_config_schedule(config=None, *, stages=('loose', 'static', 'strict'))[source]#
Return a permissive-to-strict schedule of multi-padding configs.
- qlinks.caging.quimb_available()[source]#
Return whether the optional quimb tensor-network backend is installed.
- qlinks.caging.random_cage_stability_ensemble(base_hamiltonian, perturbations, support, strengths, *, n_samples=100, reference_state=None, reference_subspace=None, target_dimension=None, minimum_subspace_overlap=0.5, random_seed=None, tolerance=1e-10, max_power=None, stabilization_rounds=1)[source]#
Sample normalized random directions in a supplied perturbation basis.
- qlinks.caging.reduced_iz_component_groups_from_reports(reports, *, decomposition, use_collective_coefficients=True)[source]#
Return cached report-side metadata for reduced-IZ monitor components.
- qlinks.caging.reduced_iz_local_rdm_readouts_from_report(report, *, basis_configs, state, decomposition='exact_support', tolerance=1e-10, matrix_unit_tolerance=None, max_matrix_unit_terms=64, include_empty_supports=False)[source]#
Return local-RDM readouts for reduced-IZ monitor components.
The components are the same frustration-free reduced-IZ groups cached by
CageClassificationReportand used by the Lindblad-construction layer. For each component support, this function computes the target state reduced density matrix and expands that RDM in local matrix units so that it can be inspected in notebooks.
- qlinks.caging.reduced_iz_probe_support_from_report(zero_report)[source]#
Return cached public support metadata for a reduced IZ probe.
- qlinks.caging.refine_sector_by_involution(sector, involution_index_permutation, *, eigenvalue, label='parity', tolerance=1e-09)[source]#
Refine a symmetry sector by a commuting involutive permutation.
- qlinks.caging.regional_cage_quotient(hamiltonian, regions, target_manifold, *, tolerance=1e-10)[source]#
Construct
target_manifold / regional_kernel_spannumerically.The function first embeds every regional right kernel in the full Hilbert space, then projects the target manifold onto the orthogonal complement of their span. If the regional span is contained in the target manifold, the resulting dimension is the usual quotient dimension.
inclusion_residualdiagnoses violations of that containment.
- qlinks.caging.regional_chiral_kernel_span(hamiltonian, regions, target_manifold, *, tolerance=1e-10)[source]#
Compare a target manifold with the direct span of regional chiral kernels.
- qlinks.caging.register_local_cage_adapter_factory(factory, *, prepend=False)[source]#
Register a factory that can adapt models for
LocalCageSearcher.Factories receive a model and return either a
LocalCageModelAdapterorNonewhen they do not support that model. The built-in QDM factory is registered by default; future model families can register their adapters without branching inside the solver core.
- qlinks.caging.robust_certify_qdm_multi_block_result(model, blocks, *, config=None, stages=('loose', 'static', 'strict'))[source]#
Certify a block pool with a multi-stage padding schedule.
The early stages are deliberately permissive; exact global certification is still the only acceptance criterion. Duplicate certified supports found at multiple stages are deduplicated before wrapping into a limited-basis result.
- qlinks.caging.robust_local_qdm_cage_search(model, *, config=None, adapter=None, return_context=False)#
Run a budgeted robust local QDM cage search.
The search builds a portfolio of region proposals, converts successful local records into independent Lego blocks, then certifies the block pool with a permissive-to-strict padding schedule. By default, the return value is the existing
CertifiedLocalQDMCageSearchResultcontainer used by downstream tools. Passreturn_context=Trueto also receive the intermediate scan, block pool, and per-stage diagnostics for debugging.
- qlinks.caging.robust_qdm_local_cage_search(model, *, config=None, adapter=None, return_context=False)[source]#
Run a budgeted robust local QDM cage search.
The search builds a portfolio of region proposals, converts successful local records into independent Lego blocks, then certifies the block pool with a permissive-to-strict padding schedule. By default, the return value is the existing
CertifiedLocalQDMCageSearchResultcontainer used by downstream tools. Passreturn_context=Trueto also receive the intermediate scan, block pool, and per-stage diagnostics for debugging.
- qlinks.caging.run_candidate_filters(context, candidate, candidate_filters)[source]#
Run candidate filters sequentially and stop at the first rejection.
- qlinks.caging.run_local_region_proposal(proposal, *, model=None, config=None, adapter=None, max_regions=None)[source]#
Run the local cage searcher over every region emitted by one proposal.
- qlinks.caging.run_local_region_proposals(proposals, *, model=None, config=None, adapter=None, max_regions=None)[source]#
Run local cage searches over a stream of proposal-generated regions.
The helper is intentionally lightweight: proposal objects only need to provide
iter_regions(). If they provide richeriter_records()records with aregionattribute, that metadata is retained in the scan result.StripeRegionProposalfollows this richer path.
- qlinks.caging.scan_boundary_cancellation_matroid(base_boundary, perturbation_boundary, regions, parameters, *, tolerance=1e-10)[source]#
Track the weighted dependency quotient along an affine deformation.
- qlinks.caging.scan_cage_stability_branch(base_hamiltonian, perturbation, support, parameters, *, reference_state=None, reference_subspace=None, tolerance=1e-10, max_power=None, stabilization_rounds=1)[source]#
Track a compact cage subspace along
H(lambda) = H0 + lambda V.
- qlinks.caging.scan_periodic_boundary_cancellation_scaling(base_boundary, regions, repeat_counts, *, coupling_terms=(), tolerance=1e-10)[source]#
Scan exact weighted-dependency scaling in a 1D periodic repetition.
The calculation is exact for the block-circulant boundary family specified by
base_boundaryand the finite-rangecoupling_terms. Each coupling term is(displacement, matrix)and contributesexp(i k displacement) * matrixto the Bloch symbol. The same regional column cover is used in every cell and every momentum sector.
- qlinks.caging.scan_sga_ladder_basis_frequencies(*, hamiltonian, states, operators, operator_names=None, energies=None, tolerance=1e-10, frequency_tolerance=None, max_frequencies=None, include_zero_frequency=False, max_ladder_candidates=16)[source]#
Scan distinct manifold energy gaps for SGA-like ladder candidates.
This convenience wrapper is intended for QDM/QLM cage manifolds where the relevant SGA spacing is not known a priori. Frequencies are inferred from all distinct
E_target-E_sourcevalues of the supplied states.
- qlinks.caging.scan_square_qdm_beta_zero_energy_density(sizes, *, potential_coupling=1.0, winding_sector=(0, 0), winding_projection='auto', fourier_points=None)[source]#
Evaluate beta-zero energy densities for square tori or
(Lx, Ly)pairs.
- qlinks.caging.scan_square_qdm_collective_locality_extension(reference_model, reference_support_configs, product_unit_cell, cases, *, potential_per_column=1.0, max_words=100000, max_product_support_size=4096, dense_column_limit=512, maximum_nullity=32, ipr_restarts=64, tolerance=1e-09)[source]#
Test non-factorized fixed-width extensions of a collective support.
Each
(window_size, length)case first generates every periodic support configuration compatible with the corresponding local column grammar. The exact physical boundary kernel is then compared with the span of translated certified stripe-product cages. A positive residual quotient is a genuine non-product collective extension within that finite-range support language.
- qlinks.caging.scan_square_qdm_periodic_product_cancellation_scaling(unit_cell, repeat_counts, *, max_support_size=1024, tolerance=1e-10)[source]#
Extract exact physical boundary maps for finite periodic embeddings.
Unlike
scan_periodic_boundary_cancellation_scaling(), this routine materializes the tensor-product support of the actual square-QDM sequence. It is therefore restricted to moderate repeats but includes every physical plaquette flip and every seam transition of the finite torus.
- qlinks.caging.scan_support_eigenstate_branch(base_hamiltonian, perturbation, support, parameters, *, reference_state, tolerance=1e-10, max_power=None, stabilization_rounds=1)[source]#
Track the nearest support-local eigenstate and measure its leakage.
Unlike
scan_cage_stability_branch(), this continuation does not stop when the exact invariant cage subspace disappears. At every parameter it follows the closest eigenspace of the internal support block. Within a degenerate eigenspace it selects the state with minimum boundary leakage, then reports||B phi||. A first-order-compatible but non-integrable direction is therefore visible through a residual that starts at quadratic or higher order.
- qlinks.caging.scan_windowed_operator_annihilators(operators, state, operator_centers, radii, *, periodic_box=None, metric='chebyshev', normalize_actions=True, action_tolerance=1e-12, rank_tolerance=1e-10, coefficient_tolerance=1e-08)[source]#
Optimize a collective local annihilator in growing spatial windows.
For each candidate center and radius, columns of the action matrix are
O_j |psi>for operators whose real-space centers lie in the window. The smallest singular value is the minimum residual over coefficient vectors of unit Euclidean norm. Normalizing individual action columns is useful when comparing locality rather than bare operator conventions.
- qlinks.caging.search_square_qdm_biperiodic_product_tiles(model, block_pool, *, config=None)[source]#
Search periodic static exteriors and certify two-direction repetition.
The search only solves and materializes the finite reference-tile product support, bounded by
max_tile_support_size. Every completion is then diagnosed on tile arrays through3 x 3without constructing the support of the repeated two-dimensional system.
- qlinks.caging.select_microcanonical_window_by_count(eigenvalues, *, target_energy, target_count, exclude_indices=(), include_boundary_degeneracy=True, degeneracy_tolerance=1e-10)[source]#
Select the closest finite-size energy levels to a target energy.
- qlinks.caging.select_microcanonical_window_by_width(eigenvalues, *, target_energy, half_width, exclude_indices=(), degeneracy_tolerance=1e-10)[source]#
Select every level in a prescribed energy interval.
Exact degeneracies at the interval boundary are retained by the tolerance. The returned
half_widthis the largest actual distance of a retained level from the target; the requested width remains known to the caller via its thermodynamic window plan.
- qlinks.caging.select_reduced_iz_monitor_reports(report, *, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Select reduced-IZ reports from a classification report for monitor use.
- qlinks.caging.select_reduced_iz_monitor_reports_from_zero_reports(zero_reports, *, include_q_empty=True, include_closed_by_known_zeros=True, include_projector_like=True, include_collective_cancellation=True)[source]#
Select non-invalid reduced-IZ zero reports for monitor assembly.
- qlinks.caging.sga_ladder_basis_diagnostic(*, hamiltonian, states, operators, frequency, operator_names=None, energies=None, tolerance=1e-10, frequency_tolerance=None, max_ladder_candidates=16, include_leakage_constraints=True)[source]#
Search for SGA-like ladder combinations in a supplied operator basis.
This solves a right-nullspace problem for coefficients
c_asuch thatQ=sum_a c_a O_aboth closes on the supplied manifold and has no projected matrix elements outside the requested SGA frequency.
- qlinks.caging.sga_ladder_basis_diagnostic_from_cage_records(*, hamiltonian, records, operators, frequency, operator_names=None, tolerance=1e-10, frequency_tolerance=None, max_ladder_candidates=16)[source]#
Run
sga_ladder_basis_diagnostic()on full states from cage records.
- qlinks.caging.sga_operator_diagnostic(*, hamiltonian, states, operator, operator_name='Q', frequency=None, energies=None, tolerance=1e-10, frequency_tolerance=None, max_transitions=32)[source]#
Test whether one operator acts as a ladder on a candidate manifold.
- Parameters:
hamiltonian (Any) – Full Hamiltonian matrix in the same basis as
states.states (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Candidate manifold vectors. Rows are interpreted as states; a one-dimensional input is treated as a one-state manifold.
operator (Any) – Candidate ladder operator matrix.
operator_name (str) – Human-readable operator label.
frequency (complex | None) – Target SGA frequency. If omitted, the dominant frequency of the projected action is inferred from
E_target-E_source.energies (Sequence[complex] | None) – Optional eigenvalues for the supplied states. If omitted, expectation values of
hamiltonianare used.tolerance (float) – Numerical tolerance for residual classification.
frequency_tolerance (float | None) – Tolerance used to group energy differences. The default is
10 * tolerance.max_transitions (int | None) – Maximum number of projected transitions to store.
- Returns:
A diagnostic report with projected action, leakage, commutator residual, and prominent transitions.
- Return type:
- qlinks.caging.signature_from_energy_and_self_loop(energy_value, self_loop_value, *, tolerance, potential_unit=1.0)[source]#
Infer integer
(kappa, Z)signature from energy and self-loop value.self_loop_valueis the actual diagonal potential value, including any scalar potential coupling.potential_unitis the unit used to report the potential signature. For example, ifV = lambda * V_tildeandself_loop_value = lambda * Z, thenpotential_unit=lambdareports the lazy-index signature as(kappa, Z)while all internal residuals use the coupled Hamiltonian.
- qlinks.caging.solve_candidate(hamiltonian, candidate, *, config=None)[source]#
Solve interference-caged eigenstates for one candidate support.
- qlinks.caging.solve_candidate_for_kinetic_targets(hamiltonian, kinetic_matrix, self_loop_values, candidate, *, target_kappas, config=None)[source]#
Solve cage states with fixed kinetic eigenvalues.
This is the fast path used by the high-level cage searcher for QDM/QLM Type-1 and Type-2 searches. For candidates with a uniform diagonal potential value
zon the support, a cage with kinetic eigenvaluekappahas full Hamiltonian energykappa + z. We can therefore solve the fixed-kappa linear system directly,K_out,S psi = 0, (K_S - kappa I) psi = 0,
instead of first computing the whole invariant boundary subspace and then diagonalizing the projected Hamiltonian.
- qlinks.caging.solve_candidates(hamiltonian, candidates, *, config=None)[source]#
Solve caged states for many candidate supports.
- qlinks.caging.spectral_observable_moments(operator, eigenvectors, *, squared_operator=None, indices=None, weights=None, hermiticity_tolerance=1e-10)[source]#
Evaluate
Tr(rho O),Tr(rho O^2), and measurement variance.eigenvectorsare columns. The state is an equal-weight mixture overindicesunless explicit non-negative normalizedweightsare given.squared_operatoris useful after symmetry projection. For a local observable that does not preserve the resolved symmetry sector, the correct second moment isP O^2 P, not(P O P)^2. Supply the former assquared_operator. When omitted, the function uses the action norm and therefore evaluates the square of the suppliedoperator.
- qlinks.caging.square_qdm_column_words(model, support_configs)[source]#
Encode square-QDM configurations as periodic column-transition words.
- qlinks.caging.square_qdm_directed_plaquette_witness_placement(*, circumference, orientation)[source]#
Return a unit-normalized directed plaquette-flip witness.
Q_Ris the projector onto one of the two flippable plaquette orientations. Summing the two expectations gives the total local flippability probability and therefore the beta-zero potential-energy density for a uniform square QDM.
- qlinks.caging.square_qdm_two_plaquette_singlet_blocks(model, *, directions=('x', 'y'), tolerance=1e-10, block_id_start=0)[source]#
Find all translated antisymmetric two-plaquette square-QDM blocks.
- qlinks.caging.subspace_complement_basis(parent_basis, child_basis, *, tolerance=1e-10)[source]#
Return the part of
span(parent_basis)orthogonal tochild_basis.child_basisis required to lie inside the parent subspace up to the supplied tolerance. Empty column bases are supported.
- qlinks.caging.subspace_principal_overlaps(basis_a, basis_b)[source]#
Return cosines of principal angles between two column subspaces.
- qlinks.caging.subspace_projector_distance(basis_a, basis_b)[source]#
Return the spectral norm
||P_A - P_B||_2.
- qlinks.caging.summarize_cage_record_stability(base_hamiltonian, perturbations, records, *, classification_reports=None, coefficient_field='real', tolerance=1e-10)[source]#
Compare preferred cage representatives inside one degenerate manifold.
The records are intentionally treated as a chosen basis, such as the output of the IPR degenerate-basis strategy. Manifold-level statements remain basis independent, whereas the returned record-wise quantities diagnose whether one preferred localized representative is more fragile than the others.
- qlinks.caging.support_key_for_zero_report(zero_report)[source]#
Return the variable-index support key for one reduced-IZ report.
- qlinks.caging.support_key_from_mask(local_mask)[source]#
Return the variable-index support key for a local reduced-IZ mask.
- qlinks.caging.thermal_activity_margin_from_samples(parameters, activities, *, reference_parameter=0.0, tolerance=1e-10)[source]#
Estimate
tau_Q,chi_Q, and the half-activity radius on a path.The susceptibility is conservatively taken as the largest absolute secant slope between neighboring sampled points. The returned radius implements the draft bound
tau_0/(2 chi_Q). It is an empirical finite-size bound over the sampled neighborhood, not a proof of differentiability or a thermodynamic uniform bound.
- qlinks.caging.thermodynamic_energy_window_plan(*, volume, energy_density, width_prefactor=1.0, local_energy_scale=1.0, width_exponent=0.5)[source]#
Return a subextensive microcanonical energy-window plan.
The window is centered at
E_L = e * volumeand has half-widthwidth_prefactor * local_energy_scale * volume**width_exponent.0 <= width_exponent < 1guarantees a vanishing energy-density width. Whether the number of states in the window grows must be checked from the spectrum; it is not implied by this kinematic scaling alone.
- qlinks.caging.twisted_translation_matrix(length, twist=0.0)[source]#
Return the unitary one-site translation with
T**L = exp(i twist).
- qlinks.caging.type1_candidates_from_bipartite_self_loops(kinetic_matrix, self_loop_values, bipartition_labels, *, min_component_size=2, decimals=12, neighbor_cache=None)[source]#
Generate Type-1 candidates from
(bipartition_label, self_loop_value).Since same-side vertices of a bipartite kinetic graph have zero direct kinetic adjacency, components are defined by the boundary-overlap graph
K[group, outside] @ K[outside, group].
This is the generalized version of the old
incidence_mat @ incidence_mat.Tworkflow.