qlinks.models package

Submodules

qlinks.models.base module

qlinks.models.base.normalize_sector_label_for_display(label)

Normalize sector labels exposed by model-level APIs.

Fractions with denominator 1 are converted to ints recursively. Other Fractions are kept exact.

qlinks.models.base.normalize_sector_labels_for_display(labels)

Normalize a collection of model-facing sector labels.

class qlinks.models.base.HamiltonianTermSpec(name, operators, kind='other')

Bases: object

Symbolic Hamiltonian term before sparse matrix construction.

A model returns these specs from make_terms(). The shared builder then chooses the requested sparse backend and turns each operator tuple into a matrix.

name

Stable term name, such as "kinetic" or "potential".

Type:

str

operators

Local operator objects that contribute to this term.

Type:

tuple[object, …]

kind

Coarse term category used by diagnostics and local-term assembly.

Type:

Literal[‘kinetic’, ‘potential’, ‘other’]

Examples

>>> HamiltonianTermSpec(
...     name="kinetic",
...     kind="kinetic",
...     operators=(op0, op1),
... )

name: str

operators: tuple[object, ...]

kind: Literal['kinetic', 'potential', 'other']

classmethod from_operators(name, operators, *, kind='other')

property is_empty: bool

__init__(name, operators, kind='other')

class qlinks.models.base.BuiltHamiltonianTerm(name, kind, operators, matrix)

Bases: object

Sparse matrix and metadata for one built Hamiltonian term.

name

Term name copied from HamiltonianTermSpec.

Type:

str

kind

Coarse term category.

Type:

Literal[‘kinetic’, ‘potential’, ‘other’]

operators

Operators used to build the term.

Type:

tuple[object, …]

matrix

Built sparse matrix, or None when the term has no operators.

Type:

Any | None

name: str

kind: Literal['kinetic', 'potential', 'other']

operators: tuple[object, ...]

matrix: Any | None

__init__(name, kind, operators, matrix)

class qlinks.models.base.ModelBuildResult(model, lattice, layout, constraints, sectors, basis, terms, hamiltonian)

Bases: object

Basis, terms, and total Hamiltonian returned by model.build().

Use this result when downstream code needs both the total Hamiltonian and named pieces such as the kinetic or potential terms. Keeping them together avoids rebuilding the basis and matrices repeatedly.

model

Model instance that produced the result.

Type:

object

lattice

Cached lattice used by the model.

Type:

object

layout

Physical variable layout.

Type:

qlinks.variables.layout.VariableLayout

constraints

Constraints used for basis construction.

Type:

tuple[qlinks.constraints.base.Constraint, …]

sectors

Sector filters used for basis construction.

Type:

tuple[qlinks.constraints.base.SectorCondition, …]

basis

Basis object used by the selected builder. For builder= "bitmask" this can be a BinaryEncodedBasis.

Type:

qlinks.basis.basis.Basis | qlinks.encoded.binary_basis.BinaryEncodedBasis

terms

Mapping from term name to built term metadata.

Type:

dict[str, qlinks.models.base.BuiltHamiltonianTerm]

hamiltonian

Sparse total Hamiltonian, equal to the sum of all built nonempty term matrices.

Type:

Any

Examples

>>> result = model.build(builder="optimized")
>>> hamiltonian = result.hamiltonian
>>> kinetic = result.kinetic

model: object

lattice: object

layout: VariableLayout

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

basis: Basis | BinaryEncodedBasis

terms: dict[str, BuiltHamiltonianTerm]

hamiltonian: Any

property kinetic: Any | None

property potential: Any | None

property kinetic_operators: tuple[object, ...]

property potential_operators: tuple[object, ...]

property operators: tuple[object, ...]

basis_operator(name)

__init__(model, lattice, layout, constraints, sectors, basis, terms, hamiltonian)

class qlinks.models.base.SparseBuildOptions(backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

Bases: object

Shared sparse-build options.

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype

Matrix dtype passed to the builder.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for operator actions that leave the constrained basis. Use "raise" for debugging and "skip" for boundary terms that intentionally leak outside a subspace.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold below which coefficients are dropped.

Type:

float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

__init__(backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

qlinks.models.base.solve_basis(layout, constraints=(), sectors=(), *, solver='dfs', sort=True, max_states=None)

Build an array basis using the requested solver.

When no constraints or sectors are supplied, this function uses direct Cartesian-product enumeration instead of invoking DFS, brute force, or CP-SAT.

Parameters:

• layout (VariableLayout) – Variable layout defining the local state space.

• constraints (Sequence[Constraint]) – Local/global constraints that every basis state must obey.

• sectors (Sequence[SectorCondition]) – Diagonal sector filters.

• solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver name: "dfs", "brute_force", or "cpsat".

• sort (bool) – Whether to lexicographically sort the final basis.

• max_states (int | None) – Optional early-stop limit for first-solution or existence checks.

Returns:

Basis containing the satisfying configurations.

Raises:

ValueError – If max_states is negative or solver is unknown.

Return type:

Basis

qlinks.models.base.validate_builder_name(builder)

Validate a Hamiltonian builder name.

Parameters:

builder (Literal['sparse', 'optimized', 'bitmask']) – Candidate builder name.

Raises:

ValueError – If builder is not one of the supported names.

qlinks.models.base.combine_hamiltonian_terms(matrices)

Sum all nonempty sparse matrices.

Parameters:

matrices (Sequence[Any | None]) – Term matrices. None entries are ignored.

Returns:

Sum of all non-None matrices, preserving the backend matrix type.

Raises:

ValueError – If every entry is None.

Return type:

Any

class qlinks.models.base.HamiltonianModelBase

Bases: object

Base class for model-level basis and Hamiltonian construction.

Subclasses implement the geometry-specific pieces: lattice construction, variable layout, constraints, optional sectors, and symbolic Hamiltonian terms. The base class provides cached lattice/layout properties and shared build_basis(), build(), and build_hamiltonian() methods.

Notes

Subclasses should usually use @dataclass(frozen=True) without slots=True. The cached properties require an instance __dict__.

property lattice: object

property layout: VariableLayout

property model_builder: GenericModelBuilder

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Return type:

dict[str, tuple[object, …]]

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

make_lattice()

Return the cached lattice.

This is a backward-compatible alias for the lattice property.

make_layout()

Return the cached variable layout.

This is a backward-compatible alias for the layout property.

make_constraints(layout=None)

make_sectors(layout=None)

make_terms(layout, *, builder='sparse')

prepare_builder_basis(*, physical_layout, array_basis, input_basis, builder, sort_basis)

Convert the physical basis to the representation required by a builder.

The default sparse and optimized builders use the array Basis. The bitmask builder uses BinaryEncodedBasis. QLM flux models override this method because their physical variables are {-1, +1}, while the bitmask encoding is binary.

Parameters:

• physical_layout (VariableLayout) – Original model layout.

• array_basis (Basis) – Basis in physical variable values.

• input_basis (Basis | BinaryEncodedBasis | None) – User-supplied basis, if any.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Requested builder name.

• sort_basis (bool) – Whether the caller requested sorted basis generation.

Returns:

Pair (operator_layout, build_basis) used for operator assembly.

Return type:

tuple[VariableLayout, Basis | BinaryEncodedBasis]

has_basis_state(*, solver='dfs')

build_basis(*, solver='dfs', sort=True, max_states=None)

build(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

Build the constrained basis, named terms, and total Hamiltonian.

Parameters:

• basis (Basis | BinaryEncodedBasis | None) – Optional precomputed basis. Supplying one avoids basis enumeration and fixes the row/column order.

• basis_solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver used when basis is not supplied.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder: "sparse", "optimized", or "bitmask".

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• sort_basis (bool) – Whether to sort an internally generated basis.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions that leave the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Full model build result containing the basis, named term matrices, and total Hamiltonian.

Return type:

ModelBuildResult

build_hamiltonian(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

Build and return only the total Hamiltonian matrix.

Parameters:

• basis (Basis | BinaryEncodedBasis | None) – Optional precomputed basis.

• basis_solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver used when basis is not supplied.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder name.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• sort_basis (bool) – Whether to sort an internally generated basis.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions that leave the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Sparse total Hamiltonian matrix.

Return type:

Any

Notes

Prefer build() when you also need the basis, kinetic term, or potential term.

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

natural_region_units(*, operator_kind='kinetic', term_kind=None)

Return model-natural local units for open-system region builders.

The default implementation derives the units from local_term_descriptors() by deduplicating each descriptor’s variable support. This gives plaquette units for QDM/QLM plaquette terms and bond units for nearest-neighbor hopping models such as the spin-one XY model. Models with more specialized natural units may override this method.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Local operator family used to infer the natural unit. The default kinetic choice gives hopping bonds for XY-like models and resonating plaquettes for QDM-like models.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional descriptor category filter.

Returns:

A tuple of sorted variable-index regions, with duplicates removed while preserving descriptor order.

Return type:

tuple[tuple[int, …], …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

build_local_term(descriptor, build_result, *, builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

Build one local-term matrix in an existing model basis.

Parameters:

• descriptor (LocalTermDescriptor) – Local term descriptor to build.

• build_result (ModelBuildResult) – Existing model build result whose basis fixes the matrix row/column order.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder name.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions outside the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Sparse matrix for the requested local term.

Return type:

Any

class qlinks.models.base.GenericModelBuilder(model)

Bases: object

Shared implementation behind HamiltonianModelBase.build.

The builder owns the repeated workflow of collecting constraints/sectors, solving or converting the basis, asking the model for symbolic terms, building each term matrix, and summing the total Hamiltonian.

model

Model instance whose hooks provide geometry, constraints, and symbolic terms.

Type:

qlinks.models.base.HamiltonianModelBase

model: HamiltonianModelBase

build_basis(*, solver='dfs', sort=True, max_states=None)

build(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

build_hamiltonian(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

__init__(model)

qlinks.models.couplings module

class qlinks.models.couplings.DirectedPlaquetteCoupling(forward, backward=None)

Bases: object

Forward/backward coupling for an oriented plaquette transition.

If backward is omitted, Hermiticity is imposed by using forward.conjugate().

forward: complex

backward: complex | None

resolved_forward()

resolved_backward()

__init__(forward, backward=None)

qlinks.models.couplings.plaquette_coupling_value(coupling, plaquette_id, *, name)

Resolve a scalar plaquette coupling for one plaquette id.

Parameters:

• coupling (complex | Mapping[int, complex] | Callable[[int], complex]) – Constant, mapping, or callable coupling.

• plaquette_id (int) – Plaquette id to query.

• name (str) – Coupling name used in error messages.

Returns:

Complex coupling value.

Return type:

complex

qlinks.models.couplings.directed_plaquette_coupling_value(coupling, plaquette_id, *, name)

Resolve an oriented plaquette coupling for one plaquette id.

Parameters:

• coupling (DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex]) – Constant, mapping, or callable directed coupling.

• plaquette_id (int) – Plaquette id to query.

• name (str) – Coupling name used in error messages.

Returns:

Directed forward/backward coupling.

Return type:

DirectedPlaquetteCoupling

qlinks.models.couplings.peierls_plaquette_coupling(amplitude, phase)

Return Hermitian Peierls forward/backward couplings.

qlinks.models.couplings.is_zero_coupling(coupling, plaquette_ids)

Return whether a plaquette coupling vanishes on all selected plaquettes.

Parameters:

• coupling (complex | Mapping[int, complex] | Callable[[int], complex]) – Constant, mapping, or callable scalar coupling.

• plaquette_ids (list[int]) – Plaquettes to test.

Returns:

True when every resolved coupling is exactly zero.

Return type:

bool

qlinks.models.couplings.qdm_plaquette_link_gauge_matrix(lattice, plaquette_ids=None)

Return the link-to-Peierls-phase incidence matrix for QDM flips.

For the QDM convention 1010 -> 0101, a diagonal link-gauge unitary exp(i sum_l theta_l n_l) changes the forward plaquette-flip phase by

phi_p = theta_1 + theta_3 - theta_0 - theta_2

in the plaquette-link ordering supplied by the lattice.

qlinks.models.couplings.qdm_peierls_couplings_from_link_phases(lattice, link_phases, *, amplitude=1.0, plaquette_ids=None)

Construct a gauge-generated Hermitian Peierls coupling map.

The returned Hamiltonian is related to the zero-link-phase Hamiltonian by a diagonal product-basis unitary. It therefore has the same spectrum, and every eigenstate and local witness can be transported covariantly.

qlinks.models.local_terms module

class qlinks.models.local_terms.LocalTermDescriptor(term_id, term_kind, operator_kind, support_links, support_sites=(), support_plaquettes=(), support_variables=(), label=None)

Bases: object

Geometry-level descriptor for one local operator term.

This descriptor is intentionally matrix-free. It tells us which local term we want, where it lives in real space, and which model method should assemble it.

term_id: int

term_kind: Literal['plaquette', 'site', 'link', 'bond']

operator_kind: Literal['kinetic', 'potential', 'hamiltonian']

support_links: tuple[int, ...]

support_sites: tuple[int, ...]

support_plaquettes: tuple[int, ...]

support_variables: tuple[int, ...]

label: str | None

property support_link_set: frozenset[int]

property support_variable_set: frozenset[int]

is_inside_links(links)

is_disjoint_from_links(links)

crosses_links(links)

__init__(term_id, term_kind, operator_kind, support_links, support_sites=(), support_plaquettes=(), support_variables=(), label=None)

qlinks.models.pxp module

class qlinks.models.pxp.PXPModel(lattice_input, omega=1.0)

Bases: HamiltonianModelBase

PXP/Rydberg blockade model.

Variables:

binary site occupations n_i in {0, 1}

Constraint:

no two neighboring sites can both be occupied.

Hamiltonian:

H = omega * sum_i P_neighbors X_i P_neighbors

The constrained basis already enforces the blockade, and the operator applies spin flips only when neighboring sites are unoccupied.

lattice_input: ChainLattice | SquareLattice

omega: complex = 1.0

classmethod chain(length, *, boundary_condition=BoundaryCondition.OPEN, omega=1.0)

classmethod square(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, omega=1.0)

make_constraints(layout=None)

make_sectors(layout=None)

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

__init__(lattice_input, omega=1.0)

qlinks.models.qdm module

class qlinks.models.qdm.QDMBase(coup_kin=-1.0, coup_pot=0.0, required_count=1)

Bases: HamiltonianModelBase

Shared implementation for link-binary quantum dimer models.

Subclasses provide the lattice geometry by implementing _make_lattice(). They may also override plaquette_ids() or make_sectors() for geometry-specific topological sectors.

Variables:

n_l in {0, 1}

Constraint:

sum of occupied links touching each site = required_count

Hamiltonian:

H = kinetic * sum_p flip_p

• potential * sum_p flippability_p

coup_kin: DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex] = -1.0

coup_pot: complex | Mapping[int, complex] | Callable[[int], complex] = 0.0

required_count: int = 1

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

nonempty_sector_labels(*args, **kwargs)

make_constraints(layout=None)

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1)

class qlinks.models.qdm.SquareQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None, winding_convention='electric')

Bases: QDMBase

Square-lattice quantum dimer model.

This subclass keeps square-specific functionality, especially winding sectors.

winding_convention:

“cut_count”:

raw count of occupied wrapping links.

“electric”:

staggered electric-flux winding compatible with the square QDM to staggered-charge QLM mapping.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

winding_convention: Literal['cut_count', 'electric'] = 'electric'

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None, winding_convention='electric')

class qlinks.models.qdm.TriangularQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QDMBase

Triangular-lattice QDM.

The QDM resonance plaquettes are rhombi/lozenges, not elementary triangles.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.qdm.HoneycombQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QDMBase

Honeycomb-lattice QDM.

The QDM resonance plaquettes are hexagons.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.qdm.KagomeQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QDMBase

Kagome-lattice QDM with hexagon ring-exchange plaquettes.

This is a minimal kagome QDM backend compatible with the existing QDM machinery: binary link variables, one-dimer-per-site constraints, and alternating dimer flips on kagome hexagons. The exactly solvable kagome dimer-liquid Hamiltonian has additional star/loop structure; this class is intended as the first qlinks-compatible kagome constrained model layer.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.qdm.QDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lattice_input=None)

Bases: QDMBase

Generic lattice-backed QDM model.

Use this when you already have a LatticeGraph instance.

For named geometries, prefer:

SquareQDMModel TriangularQDMModel HoneycombQDMModel KagomeQDMModel

lattice_input: LatticeGraph | None = None

classmethod triangular(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

classmethod kagome(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

classmethod honeycomb(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lattice_input=None)

qlinks.models.qlm module

class qlinks.models.qlm.QLMBase(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half')

Bases: HamiltonianModelBase

Shared implementation for spin-1/2 quantum link models.

Variables:

link electric flux E_l in {-1, +1}

Constraint:

Gauss law at each site.

Hamiltonian:

H = kinetic * sum_p ring_exchange_p

• potential * sum_p flippability_p

Bitmask convention:

physical flux:

-1, +1

encoded binary:

-1 -> 0 +1 -> 1

coup_kin: DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex] = -1.0

coup_pot: complex | Mapping[int, complex] | Callable[[int], complex] = 0.0

charges: int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]] = 0

charge_normalization: Literal['integer_flux', 'spin_half'] = 'spin_half'

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

nonempty_sector_labels(*args, **kwargs)

make_constraints(layout=None)

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

prepare_builder_basis(*, physical_layout, array_basis, input_basis, builder, sort_basis)

Override the default bitmask conversion because physical QLM variables are {-1,+1}, while the bitmask backend needs binary {0,1}.

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half')

class qlinks.models.qlm.SquareQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QLMBase

Square-lattice spin-1/2 QLM.

Square-specific functionality:

• square lattice construction

• optional winding sectors

• optimized update operators for the kinetic term

• specialized bitmask QLM flux flip/projectors

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

classmethod from_staggered_background(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charge_magnitude=None, charge_convention='even_positive', charge_normalization='spin_half', winding_x=None, winding_y=None)

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.qlm.TriangularQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QLMBase

Triangular-lattice QLM.

By default, QLM ring exchange uses rhombus/lozenge plaquettes rather than elementary triangular loops, because the alternating flux pattern requires even-length loops.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.qlm.HoneycombQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QLMBase

Honeycomb-lattice QLM.

The ring-exchange plaquettes are hexagons.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

classmethod staggered_background_charges(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, charge_magnitude=1, charge_convention='even_positive')

Return staggered honeycomb background charges.

For the honeycomb spin-1/2 QLM with integer-flux variables E_l = ±1, each bulk site has degree 3, so allowed local charges are odd: ±1 or ±3.

Sublattice convention:

sublattice 0 = A sublattice 1 = B

charge_convention:

“even_positive”:

A sites carry +charge_magnitude, B sites carry -charge_magnitude.

“even_negative”:

A sites carry -charge_magnitude, B sites carry +charge_magnitude.

classmethod from_staggered_background(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charge_magnitude=1, charge_convention='even_positive', winding_x=None, winding_y=None)

Construct a honeycomb QLM with staggered ±1 or ±3 charges.

Uses charge_normalization=’integer_flux’ because honeycomb spin-1/2 Gauss law needs odd internal charge targets.

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.qlm.KagomeQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QLMBase

Kagome-lattice spin-1/2 QLM with hexagon ring exchange.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.qlm.QLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lattice_input=None)

Bases: QLMBase

Generic lattice-backed QLM model.

Use this when you already have a LatticeGraph instance.

For named geometries, prefer:

SquareQLMModel TriangularQLMModel HoneycombQLMModel KagomeQLMModel

lattice_input: LatticeGraph | None = None

classmethod triangular(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

classmethod kagome(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

classmethod honeycomb(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lattice_input=None)

qlinks.models.spin_one_xy module

class qlinks.models.spin_one_xy.SpinOneXYChainModel(length, boundary_condition=BoundaryCondition.OPEN, j_xy=1.0, h_z=0.0, d_z=0.0, total_sz=None, extra_xy_couplings=(), h_z_by_site=None, d_z_by_site=None)

Bases: HamiltonianModelBase

Spin-1 XY chain in the S^z product basis.

Local basis:

m_i in {-1, 0, +1}

Hamiltonian:

H = J_xy * sum_<ij> (S^x_i S^x_j + S^y_i S^y_j)

= J_xy/2 * sum_<ij> (S^+_i S^-_j + S^-_i S^+_j)

No constraints are imposed at this stage.

length: int

boundary_condition: BoundaryCondition | str = 'open'

j_xy: complex = 1.0

h_z: complex = 0.0

d_z: complex = 0.0

total_sz: int | None = None

extra_xy_couplings: tuple[tuple[int, int, complex], ...] = ()

h_z_by_site: tuple[complex, ...] | None = None

d_z_by_site: tuple[complex, ...] | None = None

make_constraints(layout=None)

make_sectors(layout=None)

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return site/pair local terms for generic diagnostics and builders.

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(length, boundary_condition=BoundaryCondition.OPEN, j_xy=1.0, h_z=0.0, d_z=0.0, total_sz=None, extra_xy_couplings=(), h_z_by_site=None, d_z_by_site=None)

qlinks.models.spin_one_xy.spin_one_xy_scar_tower_states(*, basis_configs, length=None, site_phase_offset=0, normalize=True, include_zero=False)

Return the spin-1 XY scar tower in a supplied product/sector basis.

The tower is generated by (Q^dagger)^n |-1,...,-1> with Q^dagger = sum_j (-1)^(j + site_phase_offset) (S^+_j)^2. Up to a state-dependent normalization, the nonzero amplitudes are on configurations with n sites at +1 and all remaining sites at -1.

If basis_configs is already restricted to one total-Sz sector, only the corresponding tower vector is nonzero unless include_zero=True.

class qlinks.models.spin_one_xy.SpinOneXYTowerThermalActivities(length, total_sz, sector_dimension, one_zero_count, two_site_remainder_count, y2_activity, directed_q_activity, z2_activity, p0_limit, y2_limit, directed_q_limit, z2_limit, xy_matrix_element)

Bases: object

Exact fixed-magnetization witness activities for the pi-bimagnon tower.

xy_matrix_element is the qlinks convention: it is the matrix element connecting |00> with |+->. In the manuscript convention of Eq. (104), xy_matrix_element = 2 J.

length: int

total_sz: int

sector_dimension: int

one_zero_count: int

two_site_remainder_count: int

y2_activity: float

directed_q_activity: float

z2_activity: float

p0_limit: float

y2_limit: float

directed_q_limit: float

z2_limit: float

xy_matrix_element: complex

to_summary_dict()

__init__(length, total_sz, sector_dimension, one_zero_count, two_site_remainder_count, y2_activity, directed_q_activity, z2_activity, p0_limit, y2_limit, directed_q_limit, z2_limit, xy_matrix_element)

class qlinks.models.spin_one_xy.SpinOneXYPhaseCompatibilityReport(residuals, pairs, couplings, phases)

Bases: object

Bondwise compatibility of a generalized tower phase with XY exchanges.

residuals: tuple[complex, ...]

pairs: tuple[tuple[int, int], ...]

couplings: tuple[complex, ...]

phases: tuple[complex, ...]

property max_residual: float

property is_compatible: bool

to_summary_dict()

__init__(residuals, pairs, couplings, phases)

qlinks.models.spin_one_xy.spin_one_xy_periodic_range_couplings(*, length, distance, coefficient)

Return unique undirected periodic pairs at one separation.

The ordered orientation is chosen from r to r + distance before duplicate undirected pairs are removed. Real coefficients therefore give the usual translation-invariant exchange. For complex coefficients the orientation fixes the Peierls phase convention.

qlinks.models.spin_one_xy.spin_one_xy_hxy_h3_model(*, length, j=1.0, j3=0.1, total_sz=None, h_z=0.0, d_z=0.0)

Return the periodic manuscript Hamiltonian H_XY + H_3.

The manuscript convention is

H_XY = J sum_r (S_r^+ S_{r+1}^- + h.c.) and H_3  = J3 sum_r (S_r^+ S_{r+3}^- + h.c.).

SpinOneXYChainModel uses the conventional J_xy/2 prefactor for the ladder-operator form, so the corresponding qlinks coefficients are j_xy=2*J and extra_xy_coupling=2*J3. The third-neighbor term is phase compatible with the staggered tower on even periodic chains.

qlinks.models.spin_one_xy.spin_one_xy_hxy_h3_imaginary_j2_model(*, length, j=1.0, j3=0.1, kappa=0.0, total_sz=None, h_z=0.0, d_z=0.0)

Return H_XY + H_3 + i kappa H_2^- on a periodic chain.

In manuscript ladder-operator conventions,

H_2^-(kappa) = i kappa sum_r (S_r^+ S_{r+2}^- - h.c.).

The corresponding qlinks pair coefficient is 2 i kappa. For the staggered Q=pi bimagnon tower, real odd-range exchanges and purely imaginary even-range exchanges separately satisfy the exact bondwise cancellation rule. Thus this family continuously contains spin_one_xy_hxy_h3_model() at kappa=0 while preserving the same tower and its zero energy.

qlinks.models.spin_one_xy.spin_one_xy_fixed_magnetization_dimension(length, total_sz)

Return [z^M](z^-1 + 1 + z)^L by exact dynamic programming.

qlinks.models.spin_one_xy.spin_one_xy_tower_thermal_activities(*, length, total_sz, xy_matrix_element=1.0)

Evaluate the exact finite-L ratios and their fixed-density limits.

The returned quantities are Tr(rho Y_r^2), the one-sided directed activity Tr(rho A_r^dagger A_r), and Tr(rho Z_{r,r+1}^2) in the infinite-temperature fixed-magnetization ensemble. They correspond to the local channels in the current draft after identifying xy_matrix_element = 2 J.

qlinks.models.spin_one_xy.spin_one_xy_phase_compatibility(couplings, *, phases)

Check t* eta_i + t eta_j = 0 for every Hermitian pair exchange.

qlinks.models.toric_code module

class qlinks.models.toric_code.ToricCodeModel(lx=2, ly=2, boundary_condition=BoundaryCondition.PERIODIC, electric=1.0, magnetic=1.0)

Bases: HamiltonianModelBase

Standard toric code on a square lattice with PBC.

Variables live on links in the Z basis:

z_l in {-1, +1}

Hamiltonian:

H = -electric * sum_v A_v - magnetic * sum_p B_p

where A_v flips all incident links and B_p is diagonal in the Z basis.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'periodic'

electric: complex = 1.0

magnetic: complex = 1.0

make_constraints(layout=None)

make_sectors(layout=None)

make_star_operators(layout=None, *, builder='sparse')

make_plaquette_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

__init__(lx=2, ly=2, boundary_condition=BoundaryCondition.PERIODIC, electric=1.0, magnetic=1.0)

Module contents

class qlinks.models.BuiltHamiltonianTerm(name, kind, operators, matrix)

Bases: object

Sparse matrix and metadata for one built Hamiltonian term.

name

Term name copied from HamiltonianTermSpec.

Type:

str

kind

Coarse term category.

Type:

Literal[‘kinetic’, ‘potential’, ‘other’]

operators

Operators used to build the term.

Type:

tuple[object, …]

matrix

Built sparse matrix, or None when the term has no operators.

Type:

Any | None

name: str

kind: Literal['kinetic', 'potential', 'other']

operators: tuple[object, ...]

matrix: Any | None

__init__(name, kind, operators, matrix)

class qlinks.models.DirectedPlaquetteCoupling(forward, backward=None)

Bases: object

Forward/backward coupling for an oriented plaquette transition.

If backward is omitted, Hermiticity is imposed by using forward.conjugate().

forward: complex

backward: complex | None

resolved_forward()

resolved_backward()

__init__(forward, backward=None)

class qlinks.models.GenericModelBuilder(model)

Bases: object

Shared implementation behind HamiltonianModelBase.build.

The builder owns the repeated workflow of collecting constraints/sectors, solving or converting the basis, asking the model for symbolic terms, building each term matrix, and summing the total Hamiltonian.

model

Model instance whose hooks provide geometry, constraints, and symbolic terms.

Type:

qlinks.models.base.HamiltonianModelBase

model: HamiltonianModelBase

build_basis(*, solver='dfs', sort=True, max_states=None)

build(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

build_hamiltonian(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

__init__(model)

class qlinks.models.HamiltonianModelBase

Bases: object

Base class for model-level basis and Hamiltonian construction.

Subclasses implement the geometry-specific pieces: lattice construction, variable layout, constraints, optional sectors, and symbolic Hamiltonian terms. The base class provides cached lattice/layout properties and shared build_basis(), build(), and build_hamiltonian() methods.

Notes

Subclasses should usually use @dataclass(frozen=True) without slots=True. The cached properties require an instance __dict__.

property lattice: object

property layout: VariableLayout

property model_builder: GenericModelBuilder

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Return type:

dict[str, tuple[object, …]]

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

make_lattice()

Return the cached lattice.

This is a backward-compatible alias for the lattice property.

make_layout()

Return the cached variable layout.

This is a backward-compatible alias for the layout property.

make_constraints(layout=None)

make_sectors(layout=None)

make_terms(layout, *, builder='sparse')

prepare_builder_basis(*, physical_layout, array_basis, input_basis, builder, sort_basis)

Convert the physical basis to the representation required by a builder.

The default sparse and optimized builders use the array Basis. The bitmask builder uses BinaryEncodedBasis. QLM flux models override this method because their physical variables are {-1, +1}, while the bitmask encoding is binary.

Parameters:

• physical_layout (VariableLayout) – Original model layout.

• array_basis (Basis) – Basis in physical variable values.

• input_basis (Basis | BinaryEncodedBasis | None) – User-supplied basis, if any.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Requested builder name.

• sort_basis (bool) – Whether the caller requested sorted basis generation.

Returns:

Pair (operator_layout, build_basis) used for operator assembly.

Return type:

tuple[VariableLayout, Basis | BinaryEncodedBasis]

has_basis_state(*, solver='dfs')

build_basis(*, solver='dfs', sort=True, max_states=None)

build(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

Build the constrained basis, named terms, and total Hamiltonian.

Parameters:

• basis (Basis | BinaryEncodedBasis | None) – Optional precomputed basis. Supplying one avoids basis enumeration and fixes the row/column order.

• basis_solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver used when basis is not supplied.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder: "sparse", "optimized", or "bitmask".

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• sort_basis (bool) – Whether to sort an internally generated basis.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions that leave the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Full model build result containing the basis, named term matrices, and total Hamiltonian.

Return type:

ModelBuildResult

build_hamiltonian(*, basis=None, basis_solver='dfs', builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, sort_basis=True, on_missing='raise', drop_zero_atol=0.0)

Build and return only the total Hamiltonian matrix.

Parameters:

• basis (Basis | BinaryEncodedBasis | None) – Optional precomputed basis.

• basis_solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver used when basis is not supplied.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder name.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• sort_basis (bool) – Whether to sort an internally generated basis.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions that leave the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Sparse total Hamiltonian matrix.

Return type:

Any

Notes

Prefer build() when you also need the basis, kinetic term, or potential term.

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

natural_region_units(*, operator_kind='kinetic', term_kind=None)

Return model-natural local units for open-system region builders.

The default implementation derives the units from local_term_descriptors() by deduplicating each descriptor’s variable support. This gives plaquette units for QDM/QLM plaquette terms and bond units for nearest-neighbor hopping models such as the spin-one XY model. Models with more specialized natural units may override this method.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Local operator family used to infer the natural unit. The default kinetic choice gives hopping bonds for XY-like models and resonating plaquettes for QDM-like models.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional descriptor category filter.

Returns:

A tuple of sorted variable-index regions, with duplicates removed while preserving descriptor order.

Return type:

tuple[tuple[int, …], …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

build_local_term(descriptor, build_result, *, builder='sparse', backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

Build one local-term matrix in an existing model basis.

Parameters:

• descriptor (LocalTermDescriptor) – Local term descriptor to build.

• build_result (ModelBuildResult) – Existing model build result whose basis fixes the matrix row/column order.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Matrix builder name.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for operator actions outside the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

Returns:

Sparse matrix for the requested local term.

Return type:

Any

class qlinks.models.HamiltonianTermSpec(name, operators, kind='other')

Bases: object

Symbolic Hamiltonian term before sparse matrix construction.

A model returns these specs from make_terms(). The shared builder then chooses the requested sparse backend and turns each operator tuple into a matrix.

name

Stable term name, such as "kinetic" or "potential".

Type:

str

operators

Local operator objects that contribute to this term.

Type:

tuple[object, …]

kind

Coarse term category used by diagnostics and local-term assembly.

Type:

Literal[‘kinetic’, ‘potential’, ‘other’]

Examples

>>> HamiltonianTermSpec(
...     name="kinetic",
...     kind="kinetic",
...     operators=(op0, op1),
... )

name: str

operators: tuple[object, ...]

kind: Literal['kinetic', 'potential', 'other']

classmethod from_operators(name, operators, *, kind='other')

property is_empty: bool

__init__(name, operators, kind='other')

class qlinks.models.HoneycombQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QDMBase

Honeycomb-lattice QDM.

The QDM resonance plaquettes are hexagons.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.HoneycombQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QLMBase

Honeycomb-lattice QLM.

The ring-exchange plaquettes are hexagons.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

classmethod staggered_background_charges(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, charge_magnitude=1, charge_convention='even_positive')

Return staggered honeycomb background charges.

For the honeycomb spin-1/2 QLM with integer-flux variables E_l = ±1, each bulk site has degree 3, so allowed local charges are odd: ±1 or ±3.

Sublattice convention:

sublattice 0 = A sublattice 1 = B

charge_convention:

“even_positive”:

A sites carry +charge_magnitude, B sites carry -charge_magnitude.

“even_negative”:

A sites carry -charge_magnitude, B sites carry +charge_magnitude.

classmethod from_staggered_background(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charge_magnitude=1, charge_convention='even_positive', winding_x=None, winding_y=None)

Construct a honeycomb QLM with staggered ±1 or ±3 charges.

Uses charge_normalization=’integer_flux’ because honeycomb spin-1/2 Gauss law needs odd internal charge targets.

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.KagomeQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QDMBase

Kagome-lattice QDM with hexagon ring-exchange plaquettes.

This is a minimal kagome QDM backend compatible with the existing QDM machinery: binary link variables, one-dimer-per-site constraints, and alternating dimer flips on kagome hexagons. The exactly solvable kagome dimer-liquid Hamiltonian has additional star/loop structure; this class is intended as the first qlinks-compatible kagome constrained model layer.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.KagomeQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QLMBase

Kagome-lattice spin-1/2 QLM with hexagon ring exchange.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.LocalTermDescriptor(term_id, term_kind, operator_kind, support_links, support_sites=(), support_plaquettes=(), support_variables=(), label=None)

Bases: object

Geometry-level descriptor for one local operator term.

This descriptor is intentionally matrix-free. It tells us which local term we want, where it lives in real space, and which model method should assemble it.

term_id: int

term_kind: Literal['plaquette', 'site', 'link', 'bond']

operator_kind: Literal['kinetic', 'potential', 'hamiltonian']

support_links: tuple[int, ...]

support_sites: tuple[int, ...]

support_plaquettes: tuple[int, ...]

support_variables: tuple[int, ...]

label: str | None

property support_link_set: frozenset[int]

property support_variable_set: frozenset[int]

is_inside_links(links)

is_disjoint_from_links(links)

crosses_links(links)

__init__(term_id, term_kind, operator_kind, support_links, support_sites=(), support_plaquettes=(), support_variables=(), label=None)

class qlinks.models.ModelBuildResult(model, lattice, layout, constraints, sectors, basis, terms, hamiltonian)

Bases: object

Basis, terms, and total Hamiltonian returned by model.build().

Use this result when downstream code needs both the total Hamiltonian and named pieces such as the kinetic or potential terms. Keeping them together avoids rebuilding the basis and matrices repeatedly.

model

Model instance that produced the result.

Type:

object

lattice

Cached lattice used by the model.

Type:

object

layout

Physical variable layout.

Type:

qlinks.variables.layout.VariableLayout

constraints

Constraints used for basis construction.

Type:

tuple[qlinks.constraints.base.Constraint, …]

sectors

Sector filters used for basis construction.

Type:

tuple[qlinks.constraints.base.SectorCondition, …]

basis

Basis object used by the selected builder. For builder= "bitmask" this can be a BinaryEncodedBasis.

Type:

qlinks.basis.basis.Basis | qlinks.encoded.binary_basis.BinaryEncodedBasis

terms

Mapping from term name to built term metadata.

Type:

dict[str, qlinks.models.base.BuiltHamiltonianTerm]

hamiltonian

Sparse total Hamiltonian, equal to the sum of all built nonempty term matrices.

Type:

Any

Examples

>>> result = model.build(builder="optimized")
>>> hamiltonian = result.hamiltonian
>>> kinetic = result.kinetic

model: object

lattice: object

layout: VariableLayout

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

basis: Basis | BinaryEncodedBasis

terms: dict[str, BuiltHamiltonianTerm]

hamiltonian: Any

property kinetic: Any | None

property potential: Any | None

property kinetic_operators: tuple[object, ...]

property potential_operators: tuple[object, ...]

property operators: tuple[object, ...]

basis_operator(name)

__init__(model, lattice, layout, constraints, sectors, basis, terms, hamiltonian)

class qlinks.models.PXPModel(lattice_input, omega=1.0)

Bases: HamiltonianModelBase

PXP/Rydberg blockade model.

Variables:

binary site occupations n_i in {0, 1}

Constraint:

no two neighboring sites can both be occupied.

Hamiltonian:

H = omega * sum_i P_neighbors X_i P_neighbors

The constrained basis already enforces the blockade, and the operator applies spin flips only when neighboring sites are unoccupied.

lattice_input: ChainLattice | SquareLattice

omega: complex = 1.0

classmethod chain(length, *, boundary_condition=BoundaryCondition.OPEN, omega=1.0)

classmethod square(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, omega=1.0)

make_constraints(layout=None)

make_sectors(layout=None)

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

__init__(lattice_input, omega=1.0)

class qlinks.models.QDMBase(coup_kin=-1.0, coup_pot=0.0, required_count=1)

Bases: HamiltonianModelBase

Shared implementation for link-binary quantum dimer models.

Subclasses provide the lattice geometry by implementing _make_lattice(). They may also override plaquette_ids() or make_sectors() for geometry-specific topological sectors.

Variables:

n_l in {0, 1}

Constraint:

sum of occupied links touching each site = required_count

Hamiltonian:

H = kinetic * sum_p flip_p

• potential * sum_p flippability_p

coup_kin: DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex] = -1.0

coup_pot: complex | Mapping[int, complex] | Callable[[int], complex] = 0.0

required_count: int = 1

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

nonempty_sector_labels(*args, **kwargs)

make_constraints(layout=None)

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1)

class qlinks.models.QDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lattice_input=None)

Bases: QDMBase

Generic lattice-backed QDM model.

Use this when you already have a LatticeGraph instance.

For named geometries, prefer:

SquareQDMModel TriangularQDMModel HoneycombQDMModel KagomeQDMModel

lattice_input: LatticeGraph | None = None

classmethod triangular(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

classmethod kagome(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

classmethod honeycomb(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, required_count=1)

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lattice_input=None)

class qlinks.models.QLMBase(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half')

Bases: HamiltonianModelBase

Shared implementation for spin-1/2 quantum link models.

Variables:

link electric flux E_l in {-1, +1}

Constraint:

Gauss law at each site.

Hamiltonian:

H = kinetic * sum_p ring_exchange_p

• potential * sum_p flippability_p

Bitmask convention:

physical flux:

-1, +1

encoded binary:

-1 -> 0 +1 -> 1

coup_kin: DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex] = -1.0

coup_pot: complex | Mapping[int, complex] | Callable[[int], complex] = 0.0

charges: int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]] = 0

charge_normalization: Literal['integer_flux', 'spin_half'] = 'spin_half'

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

nonempty_sector_labels(*args, **kwargs)

make_constraints(layout=None)

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

prepare_builder_basis(*, physical_layout, array_basis, input_basis, builder, sort_basis)

Override the default bitmask conversion because physical QLM variables are {-1,+1}, while the bitmask backend needs binary {0,1}.

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half')

class qlinks.models.QLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lattice_input=None)

Bases: QLMBase

Generic lattice-backed QLM model.

Use this when you already have a LatticeGraph instance.

For named geometries, prefer:

SquareQLMModel TriangularQLMModel HoneycombQLMModel KagomeQLMModel

lattice_input: LatticeGraph | None = None

classmethod triangular(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

classmethod kagome(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

classmethod honeycomb(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charges=0)

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lattice_input=None)

qlinks.models.QuantumDiskModel

alias of SquareQuantumDiskModel

class qlinks.models.SparseBuildOptions(backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

Bases: object

Shared sparse-build options.

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype

Matrix dtype passed to the builder.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for operator actions that leave the constrained basis. Use "raise" for debugging and "skip" for boundary terms that intentionally leak outside a subspace.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold below which coefficients are dropped.

Type:

float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

__init__(backend='scipy', dtype=<class 'numpy.complex128'>, on_missing='raise', drop_zero_atol=0.0)

class qlinks.models.SpinOneXYChainModel(length, boundary_condition=BoundaryCondition.OPEN, j_xy=1.0, h_z=0.0, d_z=0.0, total_sz=None, extra_xy_couplings=(), h_z_by_site=None, d_z_by_site=None)

Bases: HamiltonianModelBase

Spin-1 XY chain in the S^z product basis.

Local basis:

m_i in {-1, 0, +1}

Hamiltonian:

H = J_xy * sum_<ij> (S^x_i S^x_j + S^y_i S^y_j)

= J_xy/2 * sum_<ij> (S^+_i S^-_j + S^-_i S^+_j)

No constraints are imposed at this stage.

length: int

boundary_condition: BoundaryCondition | str = 'open'

j_xy: complex = 1.0

h_z: complex = 0.0

d_z: complex = 0.0

total_sz: int | None = None

extra_xy_couplings: tuple[tuple[int, int, complex], ...] = ()

h_z_by_site: tuple[complex, ...] | None = None

d_z_by_site: tuple[complex, ...] | None = None

make_constraints(layout=None)

make_sectors(layout=None)

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return site/pair local terms for generic diagnostics and builders.

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(length, boundary_condition=BoundaryCondition.OPEN, j_xy=1.0, h_z=0.0, d_z=0.0, total_sz=None, extra_xy_couplings=(), h_z_by_site=None, d_z_by_site=None)

class qlinks.models.SpinOneXYPhaseCompatibilityReport(residuals, pairs, couplings, phases)

Bases: object

Bondwise compatibility of a generalized tower phase with XY exchanges.

residuals: tuple[complex, ...]

pairs: tuple[tuple[int, int], ...]

couplings: tuple[complex, ...]

phases: tuple[complex, ...]

property max_residual: float

property is_compatible: bool

to_summary_dict()

__init__(residuals, pairs, couplings, phases)

class qlinks.models.SpinOneXYTowerThermalActivities(length, total_sz, sector_dimension, one_zero_count, two_site_remainder_count, y2_activity, directed_q_activity, z2_activity, p0_limit, y2_limit, directed_q_limit, z2_limit, xy_matrix_element)

Bases: object

Exact fixed-magnetization witness activities for the pi-bimagnon tower.

xy_matrix_element is the qlinks convention: it is the matrix element connecting |00> with |+->. In the manuscript convention of Eq. (104), xy_matrix_element = 2 J.

length: int

total_sz: int

sector_dimension: int

one_zero_count: int

two_site_remainder_count: int

y2_activity: float

directed_q_activity: float

z2_activity: float

p0_limit: float

y2_limit: float

directed_q_limit: float

z2_limit: float

xy_matrix_element: complex

to_summary_dict()

__init__(length, total_sz, sector_dimension, one_zero_count, two_site_remainder_count, y2_activity, directed_q_activity, z2_activity, p0_limit, y2_limit, directed_q_limit, z2_limit, xy_matrix_element)

class qlinks.models.SquareQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None, winding_convention='electric')

Bases: QDMBase

Square-lattice quantum dimer model.

This subclass keeps square-specific functionality, especially winding sectors.

winding_convention:

“cut_count”:

raw count of occupied wrapping links.

“electric”:

staggered electric-flux winding compatible with the square QDM to staggered-charge QLM mapping.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

winding_convention: Literal['cut_count', 'electric'] = 'electric'

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None, winding_convention='electric')

class qlinks.models.SquareQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

Bases: QLMBase

Square-lattice spin-1/2 QLM.

Square-specific functionality:

• square lattice construction

• optional winding sectors

• optimized update operators for the kinetic term

• specialized bitmask QLM flux flip/projectors

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_x: int | Fraction | str | None = None

winding_y: int | Fraction | str | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

classmethod from_staggered_background(lx, ly, *, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, charge_magnitude=None, charge_convention='even_positive', charge_normalization='spin_half', winding_x=None, winding_y=None)

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_x=None, winding_y=None)

class qlinks.models.SquareQuantumDiskModel(lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, chemical_potential=0.0, hop_families=('x_plus_y',), hard_core_nearest_neighbor=True, disk_number=None, x_plus_y_sums=None, x_minus_y_sums=None)

Bases: HamiltonianModelBase

Square-lattice quantum disk model with diagonal hopping.

Variables:

Binary disk occupations n_i in {0, 1} on square-lattice sites. The sites should be interpreted as disk centers; this leaves enough geometry metadata for a later basis visualizer without introducing a new cell variable kind yet.

Constraint:

Optional nearest-neighbor hard-core exclusion.

Kinetic term:

A disk hops along selected diagonal lattice lines. A hop in family='x_plus_y' uses displacement (+1, -1) and preserves every x + y line sum. A hop in family='x_minus_y' uses displacement (+1, +1) and preserves every x - y line sum.

Diagonal/topological sectors:

disk_number fixes the total particle number. x_plus_y_sums and x_minus_y_sums fix the conserved diagonal line sums. The model rejects incompatible diagonal sectors when the selected hop families do not preserve them.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

coup_kin: complex = -1.0

coup_pot: complex = 0.0

chemical_potential: complex = 0.0

hop_families: tuple[Literal['x_plus_y', 'x_minus_y'], ...] = ('x_plus_y',)

hard_core_nearest_neighbor: bool = True

disk_number: int | None = None

x_plus_y_sums: tuple[int, ...] | None = None

x_minus_y_sums: tuple[int, ...] | None = None

disk_site_ids()

Return the site ids that carry disk variables.

disk_coordinates()

Return disk-center coordinates for future visualization code.

basis_visualization_data(config)

Return lightweight disk-occupation data for a future visualizer.

diagonal_line_labels(family)

make_constraints(layout=None)

make_sectors(layout=None)

allowed_sector_labels()

Return allowed user-facing labels for symmetry sectors.

Models without user-selectable sectors return an empty dictionary. Geometry-specific subclasses override this to expose labels such as winding numbers.

Returns:

Mapping from sector name to allowed user-facing values.

Examples

SquareQLMModel(...).allowed_sector_labels() may return {"winding_x": (...), "winding_y": (...)}.

nonempty_sector_labels(*args, **kwargs)

diagonal_hop_pairs(family)

make_kinetic_operators(layout=None, *, builder='sparse')

make_potential_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

local_term_descriptors(*, operator_kind=None, term_kind=None)

Return matrix-free descriptors for local Hamiltonian pieces.

Parameters:

• operator_kind (Literal['kinetic', 'potential', 'hamiltonian'] | None) – Optional filter such as kinetic or potential.

• term_kind (Literal['plaquette', 'site', 'link', 'bond'] | None) – Optional physical/local-term category filter.

Returns:

Tuple of local term descriptors. The base implementation returns an empty tuple because not every model exposes local terms.

Return type:

tuple[LocalTermDescriptor, …]

make_local_term(descriptor, layout, *, builder='sparse')

Return the symbolic operator spec for one local term.

Parameters:

• descriptor (LocalTermDescriptor) – Descriptor previously returned by local_term_descriptors().

• layout (VariableLayout) – Layout used for operator construction.

• builder (Literal['sparse', 'optimized', 'bitmask']) – Builder name, allowing subclasses to return optimized or bitmask-specific operator implementations.

Returns:

Symbolic Hamiltonian term containing the local operators.

Raises:

NotImplementedError – If the model does not support local terms.

Return type:

HamiltonianTermSpec

__init__(lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, coup_kin=-1.0, coup_pot=0.0, chemical_potential=0.0, hop_families=('x_plus_y',), hard_core_nearest_neighbor=True, disk_number=None, x_plus_y_sums=None, x_minus_y_sums=None)

class qlinks.models.ToricCodeModel(lx=2, ly=2, boundary_condition=BoundaryCondition.PERIODIC, electric=1.0, magnetic=1.0)

Bases: HamiltonianModelBase

Standard toric code on a square lattice with PBC.

Variables live on links in the Z basis:

z_l in {-1, +1}

Hamiltonian:

H = -electric * sum_v A_v - magnetic * sum_p B_p

where A_v flips all incident links and B_p is diagonal in the Z basis.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'periodic'

electric: complex = 1.0

magnetic: complex = 1.0

make_constraints(layout=None)

make_sectors(layout=None)

make_star_operators(layout=None, *, builder='sparse')

make_plaquette_operators(layout=None, *, builder='sparse')

make_operators(layout=None, *, builder='sparse')

make_terms(layout, *, builder='sparse')

__init__(lx=2, ly=2, boundary_condition=BoundaryCondition.PERIODIC, electric=1.0, magnetic=1.0)

class qlinks.models.TriangularQDMModel(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QDMBase

Triangular-lattice QDM.

The QDM resonance plaquettes are rhombi/lozenges, not elementary triangles.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by the QDM resonance move.

The lattice may define qdm_plaquette_ids() to select only the relevant resonance loops. For example, triangular QDM should use rhombi rather than elementary triangles.

make_sectors(layout=None)

Default QDM sector list.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, required_count=1, lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

class qlinks.models.TriangularQLMModel(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

Bases: QLMBase

Triangular-lattice QLM.

By default, QLM ring exchange uses rhombus/lozenge plaquettes rather than elementary triangular loops, because the alternating flux pattern requires even-length loops.

lx: int = 2

ly: int = 2

boundary_condition: BoundaryCondition | str = 'open'

winding_a: int | None = None

winding_b: int | None = None

plaquette_ids()

Plaquettes used by QLM ring exchange.

The lattice may define qlm_plaquette_ids() to select only valid even-length ring-exchange loops.

make_sectors(layout=None)

Default QLM sectors.

Geometry-specific subclasses can override this.

__init__(coup_kin=-1.0, coup_pot=0.0, charges=0, charge_normalization='spin_half', lx=2, ly=2, boundary_condition=BoundaryCondition.OPEN, winding_a=None, winding_b=None)

qlinks.models.combine_hamiltonian_terms(matrices)

Sum all nonempty sparse matrices.

Parameters:

matrices (Sequence[Any | None]) – Term matrices. None entries are ignored.

Returns:

Sum of all non-None matrices, preserving the backend matrix type.

Raises:

ValueError – If every entry is None.

Return type:

Any

qlinks.models.directed_plaquette_coupling_value(coupling, plaquette_id, *, name)

Resolve an oriented plaquette coupling for one plaquette id.

Parameters:

• coupling (DirectedPlaquetteCoupling | complex | Mapping[int, DirectedPlaquetteCoupling | complex] | Callable[[int], DirectedPlaquetteCoupling | complex]) – Constant, mapping, or callable directed coupling.

• plaquette_id (int) – Plaquette id to query.

• name (str) – Coupling name used in error messages.

Returns:

Directed forward/backward coupling.

Return type:

DirectedPlaquetteCoupling

qlinks.models.is_zero_coupling(coupling, plaquette_ids)

Return whether a plaquette coupling vanishes on all selected plaquettes.

Parameters:

• coupling (complex | Mapping[int, complex] | Callable[[int], complex]) – Constant, mapping, or callable scalar coupling.

• plaquette_ids (list[int]) – Plaquettes to test.

Returns:

True when every resolved coupling is exactly zero.

Return type:

bool

qlinks.models.normalize_sector_label_for_display(label)

Normalize sector labels exposed by model-level APIs.

Fractions with denominator 1 are converted to ints recursively. Other Fractions are kept exact.

qlinks.models.normalize_sector_labels_for_display(labels)

Normalize a collection of model-facing sector labels.

qlinks.models.peierls_plaquette_coupling(amplitude, phase)

Return Hermitian Peierls forward/backward couplings.

qlinks.models.plaquette_coupling_value(coupling, plaquette_id, *, name)

Resolve a scalar plaquette coupling for one plaquette id.

Parameters:

• coupling (complex | Mapping[int, complex] | Callable[[int], complex]) – Constant, mapping, or callable coupling.

• plaquette_id (int) – Plaquette id to query.

• name (str) – Coupling name used in error messages.

Returns:

Complex coupling value.

Return type:

complex

qlinks.models.qdm_peierls_couplings_from_link_phases(lattice, link_phases, *, amplitude=1.0, plaquette_ids=None)

Construct a gauge-generated Hermitian Peierls coupling map.

The returned Hamiltonian is related to the zero-link-phase Hamiltonian by a diagonal product-basis unitary. It therefore has the same spectrum, and every eigenstate and local witness can be transported covariantly.

qlinks.models.qdm_plaquette_link_gauge_matrix(lattice, plaquette_ids=None)

Return the link-to-Peierls-phase incidence matrix for QDM flips.

For the QDM convention 1010 -> 0101, a diagonal link-gauge unitary exp(i sum_l theta_l n_l) changes the forward plaquette-flip phase by

phi_p = theta_1 + theta_3 - theta_0 - theta_2

in the plaquette-link ordering supplied by the lattice.

qlinks.models.solve_basis(layout, constraints=(), sectors=(), *, solver='dfs', sort=True, max_states=None)

Build an array basis using the requested solver.

When no constraints or sectors are supplied, this function uses direct Cartesian-product enumeration instead of invoking DFS, brute force, or CP-SAT.

Parameters:

• layout (VariableLayout) – Variable layout defining the local state space.

• constraints (Sequence[Constraint]) – Local/global constraints that every basis state must obey.

• sectors (Sequence[SectorCondition]) – Diagonal sector filters.

• solver (Literal['brute_force', 'dfs', 'cpsat']) – Solver name: "dfs", "brute_force", or "cpsat".

• sort (bool) – Whether to lexicographically sort the final basis.

• max_states (int | None) – Optional early-stop limit for first-solution or existence checks.

Returns:

Basis containing the satisfying configurations.

Raises:

ValueError – If max_states is negative or solver is unknown.

Return type:

Basis

qlinks.models.spin_one_xy_fixed_magnetization_dimension(length, total_sz)

Return [z^M](z^-1 + 1 + z)^L by exact dynamic programming.

qlinks.models.spin_one_xy_hxy_h3_imaginary_j2_model(*, length, j=1.0, j3=0.1, kappa=0.0, total_sz=None, h_z=0.0, d_z=0.0)

Return H_XY + H_3 + i kappa H_2^- on a periodic chain.

In manuscript ladder-operator conventions,

H_2^-(kappa) = i kappa sum_r (S_r^+ S_{r+2}^- - h.c.).

The corresponding qlinks pair coefficient is 2 i kappa. For the staggered Q=pi bimagnon tower, real odd-range exchanges and purely imaginary even-range exchanges separately satisfy the exact bondwise cancellation rule. Thus this family continuously contains spin_one_xy_hxy_h3_model() at kappa=0 while preserving the same tower and its zero energy.

qlinks.models.spin_one_xy_hxy_h3_model(*, length, j=1.0, j3=0.1, total_sz=None, h_z=0.0, d_z=0.0)

Return the periodic manuscript Hamiltonian H_XY + H_3.

The manuscript convention is

H_XY = J sum_r (S_r^+ S_{r+1}^- + h.c.) and H_3  = J3 sum_r (S_r^+ S_{r+3}^- + h.c.).

SpinOneXYChainModel uses the conventional J_xy/2 prefactor for the ladder-operator form, so the corresponding qlinks coefficients are j_xy=2*J and extra_xy_coupling=2*J3. The third-neighbor term is phase compatible with the staggered tower on even periodic chains.

qlinks.models.spin_one_xy_periodic_range_couplings(*, length, distance, coefficient)

Return unique undirected periodic pairs at one separation.

The ordered orientation is chosen from r to r + distance before duplicate undirected pairs are removed. Real coefficients therefore give the usual translation-invariant exchange. For complex coefficients the orientation fixes the Peierls phase convention.

qlinks.models.spin_one_xy_phase_compatibility(couplings, *, phases)

Check t* eta_i + t eta_j = 0 for every Hermitian pair exchange.

qlinks.models.spin_one_xy_scar_tower_states(*, basis_configs, length=None, site_phase_offset=0, normalize=True, include_zero=False)

Return the spin-1 XY scar tower in a supplied product/sector basis.

The tower is generated by (Q^dagger)^n |-1,...,-1> with Q^dagger = sum_j (-1)^(j + site_phase_offset) (S^+_j)^2. Up to a state-dependent normalization, the nonzero amplitudes are on configurations with n sites at +1 and all remaining sites at -1.

If basis_configs is already restricted to one total-Sz sector, only the corresponding tower vector is nonzero unless include_zero=True.

qlinks.models.spin_one_xy_tower_thermal_activities(*, length, total_sz, xy_matrix_element=1.0)

Evaluate the exact finite-L ratios and their fixed-density limits.

The returned quantities are Tr(rho Y_r^2), the one-sided directed activity Tr(rho A_r^dagger A_r), and Tr(rho Z_{r,r+1}^2) in the infinite-temperature fixed-magnetization ensemble. They correspond to the local channels in the current draft after identifying xy_matrix_element = 2 J.

qlinks.models.validate_builder_name(builder)

Validate a Hamiltonian builder name.

Parameters:

builder (Literal['sparse', 'optimized', 'bitmask']) – Candidate builder name.

Raises:

ValueError – If builder is not one of the supported names.