qlinks.constraints package

Submodules

qlinks.constraints.base module

class qlinks.constraints.base.ConstraintResult(satisfied, name='', residual=None, message='')

Bases: object

Result of checking one constraint or sector condition.

satisfied: bool

name: str

residual: object | None

message: str

__init__(satisfied, name='', residual=None, message='')

class qlinks.constraints.base.ConstraintPropagation(consistent=True, forced_assignments=())

Bases: object

Result of one incremental constraint-propagation step.

forced_assignments contains (variable_index, value) pairs that must hold in every completion of the current partial configuration. Generic constraints do not need to implement propagation; DFSBasisSolver treats this as an optional fast path and falls back to partial_check.

consistent: bool

forced_assignments: tuple[tuple[int, int], ...]

classmethod contradiction()

classmethod no_change()

__init__(consistent=True, forced_assignments=())

class qlinks.constraints.base.Constraint(*args, **kwargs)

Bases: Protocol

General constraint interface.

A constraint decides whether a raw configuration is allowed.

Notes

affected_variables() should return the variable indices that can affect partial_check() or check(). DFSBasisSolver uses this support to avoid unnecessary checks. Returning all variables is correct but slower.

name: str

affected_variables()

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

__init__(*args, **kwargs)

class qlinks.constraints.base.SectorCondition(*args, **kwargs)

Bases: Protocol

Diagonal symmetry-sector filter.

Notes

affected_variables() should return the variable indices that can affect partial_check() or check(). DFSBasisSolver uses this support to avoid unnecessary checks. Returning all variables is correct but slower.

name: str

affected_variables()

value(config)

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

__init__(*args, **kwargs)

class qlinks.constraints.base.BaseConstraint

Bases: object

Convenience base class for concrete constraints.

This is intentionally NOT a dataclass, because dataclass inheritance with default fields causes problems when subclasses add required fields.

layout: VariableLayout

name: str

affected_variables()

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

class qlinks.constraints.base.BaseSectorCondition

Bases: object

Convenience base class for diagonal sector filters.

This is intentionally NOT a dataclass for the same reason as BaseConstraint.

layout: VariableLayout

target: object

name: str

affected_variables()

value(config)

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, **kwargs)

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, **kwargs)

qlinks.constraints.base.all_satisfied(config, constraints=(), sectors=())

Convenience helper used by simple solvers.

qlinks.constraints.blockade module

class qlinks.constraints.blockade.NearestNeighborBlockadeConstraint(layout, site_i, site_j, occupied_value=1, name='nearest_neighbor_blockade')

Bases: BaseConstraint

PXP/Rydberg-blockade-style constraint on one lattice bond.

not (n_i == occupied_value and n_j == occupied_value)

Usually occupied_value = 1.

layout: VariableLayout

site_i: int

site_j: int

occupied_value: int

name: str

classmethod from_lattice(lattice, layout, occupied_value=1)

affected_variables()

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

__init__(layout, site_i, site_j, occupied_value=1, name='nearest_neighbor_blockade')

qlinks.constraints.collection module

class qlinks.constraints.collection.ConstraintCollection(constraints=(), sectors=())

Bases: object

Bundle local constraints and diagonal sector conditions.

The future basis solvers should consume this object or its two lists.

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

classmethod from_sequences(constraints=(), sectors=())

check_constraints(config)

check_sectors(config)

check_all(config)

is_satisfied(config)

first_failure(config)

__init__(constraints=(), sectors=())

qlinks.constraints.dimer module

class qlinks.constraints.dimer.DimerCoveringConstraint(layout, site_id, link_ids, required_count=1, name='dimer_covering')

Bases: BaseConstraint

Dimer covering constraint at one site.

sum_{links incident to site} n_l == required_count

Usually required_count = 1 for a fully packed dimer model.

layout: VariableLayout

site_id: int

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

required_count: int

name: str

classmethod from_lattice_site(lattice, layout, site_id, required_count=1)

classmethod all_sites(lattice, layout, required_counts=1)

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, site_id, link_ids, required_count=1, name='dimer_covering')

qlinks.constraints.gauss_law module

qlinks.constraints.gauss_law.internal_charge_value(charge, *, charge_normalization)

Convert user-facing charge into the raw integer target used by configs.

integer_flux:

config values are interpreted as physical E_l = ±1. charge target is used directly.

spin_half:

config values are stored as s_l = ±1, but physical E_l = s_l / 2. user-facing charge q is converted to raw target 2q.

class qlinks.constraints.gauss_law.GaussLawConstraint(layout, site_id, link_ids, signs, charge, name='gauss_law', charge_normalization='spin_half')

Bases: BaseConstraint

Local Gauss-law-like constraint at one lattice site.

Convention:

sum_l B[site, l] * E_l == charge

where B is the oriented incidence matrix with

B[source, link] = -1 B[target, link] = +1

If the layout is link-only, link_id == variable_index. More generally, this class maps link_id -> variable_index through layout.

layout: VariableLayout

site_id: int

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

signs: ndarray[tuple[Any, ...], dtype[int64]]

charge: int

name: str

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

classmethod from_lattice_site(lattice, layout, site_id, charge=0, charge_normalization='spin_half')

classmethod all_sites(lattice, layout, charges=0, charge_normalization='spin_half')

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, site_id, link_ids, signs, charge, name='gauss_law', charge_normalization='spin_half')

qlinks.constraints.local module

class qlinks.constraints.local.BoundedLocalCountConstraint(layout, variable_indices, min_count, max_count, name='bounded_local_count')

Bases: BaseConstraint

Binary local count constraint with incremental propagation.

The constraint enforces

min_count <= sum(config[variable_indices]) <= max_count

where min_count=None means there is no lower bound. All participating variables must have binary local space {0, 1}. Besides the usual partial feasibility check, the constraint can force remaining variables:

• if the current count already reaches max_count, every unassigned variable in the support must be 0;

• if the lower bound can only be reached by occupying all remaining variables, every unassigned variable in the support must be 1.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

min_count: int | None

max_count: int

name: str

classmethod exact(*, layout, variable_indices, count, name='local_count')

classmethod at_most(*, layout, variable_indices, max_count, name='local_count')

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, variable_indices, min_count, max_count, name='bounded_local_count')

class qlinks.constraints.local.FixedValueConstraint(layout, variable_indices, values, name='fixed_value')

Bases: BaseConstraint

Require selected variables to take fixed values.

Useful for boundary conditions, pinned charges, frozen links, etc.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

values: ndarray[tuple[Any, ...], dtype[int64]]

name: str

classmethod single(layout, variable_index, value)

affected_variables()

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, variable_indices, values, name='fixed_value')

class qlinks.constraints.local.LocalSumConstraint(layout, variable_indices, coefficients, target, name='local_sum')

Bases: BaseConstraint

Require a signed sum over selected variables to equal a target.

sum_i coefficients[i] * config[variable_indices[i]] == target

This is a generic building block for simple local constraints.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

coefficients: ndarray[tuple[Any, ...], dtype[int64]]

target: int

name: str

affected_variables()

value(config)

check(config)

__init__(layout, variable_indices, coefficients, target, name='local_sum')

qlinks.constraints.sectors module

class qlinks.constraints.sectors.TotalValueSector(layout, target, variable_indices=None, coefficients=None, name='total_value_sector')

Bases: BaseSectorCondition

Fix the total signed value over selected variables.

Examples

total particle number total magnetization total electric flux on selected links

layout: VariableLayout

target: int

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

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

name: str

affected_variables()

value(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

__init__(layout, target, variable_indices=None, coefficients=None, name='total_value_sector')

class qlinks.constraints.sectors.ParitySector(layout, target, variable_indices=None, name='parity_sector')

Bases: BaseSectorCondition

Fix the parity of the sum over selected variables.

target should be 0 or 1.

layout: VariableLayout

target: int

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

name: str

affected_variables()

value(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

__init__(layout, target, variable_indices=None, name='parity_sector')

qlinks.constraints.winding module

qlinks.constraints.winding.normalize_winding_target(target)

Normalize a user-facing winding target.

Accepts:

1 Fraction(3, 2) “3/2”

Avoid floats to prevent precision ambiguity.

qlinks.constraints.winding.internal_flux_winding_value(winding, *, flux_normalization)

Convert user-facing winding target into raw integer flux target.

integer_flux:

stored flux s_l ∈ {-1,+1} is the physical electric field. raw_target = winding

spin_half:

stored flux s_l ∈ {-1,+1} represents twice the physical spin-half electric field, E_l = s_l / 2. raw_target = 2 * winding

qlinks.constraints.winding.user_winding_value_from_internal(raw_target, *, flux_normalization)

Convert raw integer winding value back to the user-facing convention.

qlinks.constraints.winding.allowed_signed_sum_targets(*, layout, variable_indices, signs, value_transform=None)

Return all possible raw signed-sum sector values.

Computes all values of sum_i signs[i] * f(x_i) over the local spaces of the selected variables.

Parameters:

• layout (VariableLayout) – Variable layout.

• variable_indices (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Variables included in the diagonal quantum number.

• signs (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Integer signs/covector coefficients.

• value_transform – Optional function mapping local-space values to the internal values used by the sector. If None, values are used directly.

Returns:

Sorted tuple of possible raw signed-sum targets.

Return type:

tuple[int, …]

qlinks.constraints.winding.user_targets_from_raw_flux_targets(raw_targets, *, flux_normalization)

Convert raw stored-flux winding values into user-facing winding labels.

integer_flux:

raw target equals user target.

spin_half:

stored flux s_l in {-1,+1} represents twice the physical spin-half electric field, so raw target = 2 * user target. Only even raw targets are valid integer user labels under the current API.

qlinks.constraints.winding.raw_targets_from_user_targets(user_targets, *, flux_normalization)

Convert user-facing winding labels to internal raw targets.

Parameters:

• user_targets (tuple[int, ...]) – Winding labels in the requested normalization.

• flux_normalization (Literal['integer_flux', 'spin_half']) – Normalization convention used by the user labels.

Returns:

Raw integer winding targets used internally by sector conditions.

Return type:

tuple[int, …]

class qlinks.constraints.winding.WindingCutData(link_ids, signs, variable_indices)

Bases: object

Cached data defining one winding cut.

link_ids:

Physical lattice links participating in the winding cut.

signs:

Integer covector signs used in the winding value.

variable_indices:

VariableLayout indices corresponding to link_ids.

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

signs: ndarray[tuple[Any, ...], dtype[int64]]

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

__init__(link_ids, signs, variable_indices)

class qlinks.constraints.winding.SquareWindingSector(layout, lattice, direction, target, name='square_winding_sector', flux_normalization='spin_half')

Bases: BaseSectorCondition

Square-lattice electric winding sector.

The winding covector is a signed direction-link covector chosen so that it annihilates every plaquette boundary. This guarantees that local plaquette flips preserve the sector, including on small PBC lattices.

layout: VariableLayout

lattice: SquareLattice

direction: Literal['x', 'y']

target: int | Fraction | str

name: str

flux_normalization: Literal['integer_flux', 'spin_half']

classmethod cut_data(*, layout, lattice, direction)

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

property signs: ndarray

Signs used in the winding covector.

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

affected_variables()

value(config)

internal_target()

check(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_internal_targets(*, layout, lattice, direction)

classmethod allowed_targets(*, layout, lattice, direction, flux_normalization='spin_half')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, flux_normalization='spin_half')

__init__(layout, lattice, direction, target, name='square_winding_sector', flux_normalization='spin_half')

class qlinks.constraints.winding.SquareQDMElectricWindingSector(layout, lattice, direction, target, name='square_qdm_electric_winding_sector')

Bases: BaseSectorCondition

Signed QDM winding sector compatible with the staggered-charge QLM mapping.

QDM variables:

n_l in {0, 1}

Electric-flux mapping:

E_l = eta(source(l)) * (2 n_l - 1)

where:

eta(x, y) = (-1)^(x + y)

The winding is computed across wrapping links:

direction=’x’:

sum over x-wrapping links

direction=’y’:

sum over y-wrapping links

This is the sector convention to compare with QLM winding sectors.

layout: VariableLayout

lattice: SquareLattice

direction: Literal['x', 'y']

target: int | Fraction | str

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

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

value(configuration)

internal_target()

check(configuration)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction)

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction)

__init__(layout, lattice, direction, target, name='square_qdm_electric_winding_sector')

class qlinks.constraints.winding.HoneycombElectricWindingSector(layout, lattice, direction, target, value_convention='binary', name='honeycomb_electric_winding_sector', flux_normalization='spin_half')

Bases: BaseSectorCondition

Electric winding sector for the honeycomb QLM on a periodic lattice.

This sector fixes one of the two conserved electric-flux winding numbers on a honeycomb torus. The winding number is the signed electric flux through a non-contractible cut; signs follow the lattice oriented-link convention.

layout

Variable layout.

Type:

qlinks.variables.layout.VariableLayout

lattice

Honeycomb lattice.

Type:

qlinks.lattice.honeycomb.HoneycombLattice

direction

Periodic cell direction, "x" or "y".

Type:

Literal[‘x’, ‘y’]

target

User-facing target winding value.

Type:

int | fractions.Fraction | str

flux_normalization

Convention used to interpret the target.

Type:

Literal[‘integer_flux’, ‘spin_half’]

Notes

direction labels the two independent periodic directions of the integer unit-cell coordinates, not the Cartesian directions of the plotting embedding.

Specifically,

direction=”x”

means the winding sector associated with the first unit-cell direction, and

direction=”y”

means the winding sector associated with the second unit-cell direction.

For a honeycomb lattice these cell directions are generally oblique in the visual embedding. They should be understood as the two primitive torus cycles, or equivalently as a chosen basis of H_1(T^2, Z). Choosing a different pair of independent non-contractible cycles would give an equivalent winding basis, with sector labels related by an integer change of basis.

The primitive vectors and basis offsets used for plotting do not define the winding sector. The winding sector is defined by the combinatorial periodic cell coordinates and the oriented link/cut convention.

layout: VariableLayout

lattice: HoneycombLattice

direction: Literal['x', 'y']

target: int | Fraction | str

value_convention: Literal['binary', 'flux_pm']

name: str

flux_normalization: Literal['integer_flux', 'spin_half']

classmethod cut_data(*, layout, lattice, direction)

affected_variables()

value(config)

internal_target()

is_satisfied(config)

check(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

static electric_values_from_convention(values, *, value_convention)

classmethod allowed_internal_targets(*, layout, lattice, direction, value_convention='binary')

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary', flux_normalization='spin_half')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, value_convention='binary', flux_normalization='spin_half')

__init__(layout, lattice, direction, target, value_convention='binary', name='honeycomb_electric_winding_sector', flux_normalization='spin_half')

qlinks.constraints.z2_winding module

class qlinks.constraints.z2_winding.Z2CutData(link_ids, variable_indices)

Bases: object

Cached link and variable indices for one Z2 winding cut.

link_ids

Physical link ids crossing the cut.

Type:

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

variable_indices

Layout variable indices associated with link_ids.

Type:

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

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

__init__(link_ids, variable_indices)

class qlinks.constraints.z2_winding.TriangularZ2WindingSector(layout, lattice, direction, target, value_convention='binary', name='triangular_z2_winding_sector')

Bases: BaseSectorCondition

Z2 topological winding sector for triangular-lattice QDM/QLM on a torus.

The sector is the parity of occupied/electric-positive links crossing a non-contractible cut. The labels direction="a" and direction="b" refer to the two independent periodic cell directions of the triangular torus, not to filtering links by link.kind.

The cut is constructed from the periodic image shift of each link. This is important because triangular c links can also cross the primitive seams. Counting only wrapping links of kind "a" or "b" is not invariant under all triangular QDM rhombus flips.

layout: VariableLayout

lattice: TriangularLattice

direction: Literal['a', 'b']

target: int

value_convention: Literal['binary', 'flux_pm']

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

value(config)

is_satisfied(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, value_convention='binary')

__init__(layout, lattice, direction, target, value_convention='binary', name='triangular_z2_winding_sector')

class qlinks.constraints.z2_winding.KagomeZ2WindingSector(layout, lattice, direction, target, value_convention='binary', name='kagome_z2_winding_sector')

Bases: BaseSectorCondition

Z2 topological winding sector for kagome QDM/QLM on a torus.

The sector is the parity of occupied/electric-positive kagome links crossing a non-contractible cut of the triangular Bravais torus. The labels direction="a" and direction="b" refer to the two primitive cell directions, not to a bond kind.

layout: VariableLayout

lattice: KagomeLattice

direction: Literal['a', 'b']

target: int

value_convention: Literal['binary', 'flux_pm']

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

value(config)

is_satisfied(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

__init__(layout, lattice, direction, target, value_convention='binary', name='kagome_z2_winding_sector')

Module contents

class qlinks.constraints.BaseConstraint

Bases: object

Convenience base class for concrete constraints.

This is intentionally NOT a dataclass, because dataclass inheritance with default fields causes problems when subclasses add required fields.

layout: VariableLayout

name: str

affected_variables()

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

class qlinks.constraints.BaseSectorCondition

Bases: object

Convenience base class for diagonal sector filters.

This is intentionally NOT a dataclass for the same reason as BaseConstraint.

layout: VariableLayout

target: object

name: str

affected_variables()

value(config)

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, **kwargs)

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, **kwargs)

class qlinks.constraints.BoundedLocalCountConstraint(layout, variable_indices, min_count, max_count, name='bounded_local_count')

Bases: BaseConstraint

Binary local count constraint with incremental propagation.

The constraint enforces

min_count <= sum(config[variable_indices]) <= max_count

where min_count=None means there is no lower bound. All participating variables must have binary local space {0, 1}. Besides the usual partial feasibility check, the constraint can force remaining variables:

• if the current count already reaches max_count, every unassigned variable in the support must be 0;

• if the lower bound can only be reached by occupying all remaining variables, every unassigned variable in the support must be 1.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

min_count: int | None

max_count: int

name: str

classmethod exact(*, layout, variable_indices, count, name='local_count')

classmethod at_most(*, layout, variable_indices, max_count, name='local_count')

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, variable_indices, min_count, max_count, name='bounded_local_count')

class qlinks.constraints.Constraint(*args, **kwargs)

Bases: Protocol

General constraint interface.

A constraint decides whether a raw configuration is allowed.

Notes

affected_variables() should return the variable indices that can affect partial_check() or check(). DFSBasisSolver uses this support to avoid unnecessary checks. Returning all variables is correct but slower.

name: str

affected_variables()

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

__init__(*args, **kwargs)

class qlinks.constraints.ConstraintCollection(constraints=(), sectors=())

Bases: object

Bundle local constraints and diagonal sector conditions.

The future basis solvers should consume this object or its two lists.

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

classmethod from_sequences(constraints=(), sectors=())

check_constraints(config)

check_sectors(config)

check_all(config)

is_satisfied(config)

first_failure(config)

__init__(constraints=(), sectors=())

class qlinks.constraints.ConstraintPropagation(consistent=True, forced_assignments=())

Bases: object

Result of one incremental constraint-propagation step.

forced_assignments contains (variable_index, value) pairs that must hold in every completion of the current partial configuration. Generic constraints do not need to implement propagation; DFSBasisSolver treats this as an optional fast path and falls back to partial_check.

consistent: bool

forced_assignments: tuple[tuple[int, int], ...]

classmethod contradiction()

classmethod no_change()

__init__(consistent=True, forced_assignments=())

class qlinks.constraints.ConstraintResult(satisfied, name='', residual=None, message='')

Bases: object

Result of checking one constraint or sector condition.

satisfied: bool

name: str

residual: object | None

message: str

__init__(satisfied, name='', residual=None, message='')

class qlinks.constraints.DimerCoveringConstraint(layout, site_id, link_ids, required_count=1, name='dimer_covering')

Bases: BaseConstraint

Dimer covering constraint at one site.

sum_{links incident to site} n_l == required_count

Usually required_count = 1 for a fully packed dimer model.

layout: VariableLayout

site_id: int

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

required_count: int

name: str

classmethod from_lattice_site(lattice, layout, site_id, required_count=1)

classmethod all_sites(lattice, layout, required_counts=1)

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, site_id, link_ids, required_count=1, name='dimer_covering')

class qlinks.constraints.FixedValueConstraint(layout, variable_indices, values, name='fixed_value')

Bases: BaseConstraint

Require selected variables to take fixed values.

Useful for boundary conditions, pinned charges, frozen links, etc.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

values: ndarray[tuple[Any, ...], dtype[int64]]

name: str

classmethod single(layout, variable_index, value)

affected_variables()

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, variable_indices, values, name='fixed_value')

class qlinks.constraints.GaussLawConstraint(layout, site_id, link_ids, signs, charge, name='gauss_law', charge_normalization='spin_half')

Bases: BaseConstraint

Local Gauss-law-like constraint at one lattice site.

Convention:

sum_l B[site, l] * E_l == charge

where B is the oriented incidence matrix with

B[source, link] = -1 B[target, link] = +1

If the layout is link-only, link_id == variable_index. More generally, this class maps link_id -> variable_index through layout.

layout: VariableLayout

site_id: int

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

signs: ndarray[tuple[Any, ...], dtype[int64]]

charge: int

name: str

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

classmethod from_lattice_site(lattice, layout, site_id, charge=0, charge_normalization='spin_half')

classmethod all_sites(lattice, layout, charges=0, charge_normalization='spin_half')

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

propagate(config, assigned_mask)

__init__(layout, site_id, link_ids, signs, charge, name='gauss_law', charge_normalization='spin_half')

class qlinks.constraints.HoneycombElectricWindingSector(layout, lattice, direction, target, value_convention='binary', name='honeycomb_electric_winding_sector', flux_normalization='spin_half')

Bases: BaseSectorCondition

Electric winding sector for the honeycomb QLM on a periodic lattice.

This sector fixes one of the two conserved electric-flux winding numbers on a honeycomb torus. The winding number is the signed electric flux through a non-contractible cut; signs follow the lattice oriented-link convention.

layout

Variable layout.

Type:

qlinks.variables.layout.VariableLayout

lattice

Honeycomb lattice.

Type:

qlinks.lattice.honeycomb.HoneycombLattice

direction

Periodic cell direction, "x" or "y".

Type:

Literal[‘x’, ‘y’]

target

User-facing target winding value.

Type:

int | fractions.Fraction | str

flux_normalization

Convention used to interpret the target.

Type:

Literal[‘integer_flux’, ‘spin_half’]

Notes

direction labels the two independent periodic directions of the integer unit-cell coordinates, not the Cartesian directions of the plotting embedding.

Specifically,

direction=”x”

means the winding sector associated with the first unit-cell direction, and

direction=”y”

means the winding sector associated with the second unit-cell direction.

For a honeycomb lattice these cell directions are generally oblique in the visual embedding. They should be understood as the two primitive torus cycles, or equivalently as a chosen basis of H_1(T^2, Z). Choosing a different pair of independent non-contractible cycles would give an equivalent winding basis, with sector labels related by an integer change of basis.

The primitive vectors and basis offsets used for plotting do not define the winding sector. The winding sector is defined by the combinatorial periodic cell coordinates and the oriented link/cut convention.

layout: VariableLayout

lattice: HoneycombLattice

direction: Literal['x', 'y']

target: int | Fraction | str

value_convention: Literal['binary', 'flux_pm']

name: str

flux_normalization: Literal['integer_flux', 'spin_half']

classmethod cut_data(*, layout, lattice, direction)

affected_variables()

value(config)

internal_target()

is_satisfied(config)

check(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

static electric_values_from_convention(values, *, value_convention)

classmethod allowed_internal_targets(*, layout, lattice, direction, value_convention='binary')

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary', flux_normalization='spin_half')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, value_convention='binary', flux_normalization='spin_half')

__init__(layout, lattice, direction, target, value_convention='binary', name='honeycomb_electric_winding_sector', flux_normalization='spin_half')

class qlinks.constraints.KagomeZ2WindingSector(layout, lattice, direction, target, value_convention='binary', name='kagome_z2_winding_sector')

Bases: BaseSectorCondition

Z2 topological winding sector for kagome QDM/QLM on a torus.

The sector is the parity of occupied/electric-positive kagome links crossing a non-contractible cut of the triangular Bravais torus. The labels direction="a" and direction="b" refer to the two primitive cell directions, not to a bond kind.

layout: VariableLayout

lattice: KagomeLattice

direction: Literal['a', 'b']

target: int

value_convention: Literal['binary', 'flux_pm']

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

value(config)

is_satisfied(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

__init__(layout, lattice, direction, target, value_convention='binary', name='kagome_z2_winding_sector')

class qlinks.constraints.LocalSumConstraint(layout, variable_indices, coefficients, target, name='local_sum')

Bases: BaseConstraint

Require a signed sum over selected variables to equal a target.

sum_i coefficients[i] * config[variable_indices[i]] == target

This is a generic building block for simple local constraints.

layout: VariableLayout

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

coefficients: ndarray[tuple[Any, ...], dtype[int64]]

target: int

name: str

affected_variables()

value(config)

check(config)

__init__(layout, variable_indices, coefficients, target, name='local_sum')

class qlinks.constraints.NearestNeighborBlockadeConstraint(layout, site_i, site_j, occupied_value=1, name='nearest_neighbor_blockade')

Bases: BaseConstraint

PXP/Rydberg-blockade-style constraint on one lattice bond.

not (n_i == occupied_value and n_j == occupied_value)

Usually occupied_value = 1.

layout: VariableLayout

site_i: int

site_j: int

occupied_value: int

name: str

classmethod from_lattice(lattice, layout, occupied_value=1)

affected_variables()

check(config)

partial_check(config, assigned_mask)

Default partial check.

If all affected variables are assigned, perform the exact full check. Otherwise, do not prune.

Subclasses should override this for stronger pruning.

__init__(layout, site_i, site_j, occupied_value=1, name='nearest_neighbor_blockade')

class qlinks.constraints.ParitySector(layout, target, variable_indices=None, name='parity_sector')

Bases: BaseSectorCondition

Fix the parity of the sum over selected variables.

target should be 0 or 1.

layout: VariableLayout

target: int

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

name: str

affected_variables()

value(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

__init__(layout, target, variable_indices=None, name='parity_sector')

class qlinks.constraints.SectorCondition(*args, **kwargs)

Bases: Protocol

Diagonal symmetry-sector filter.

Notes

affected_variables() should return the variable indices that can affect partial_check() or check(). DFSBasisSolver uses this support to avoid unnecessary checks. Returning all variables is correct but slower.

name: str

affected_variables()

value(config)

check(config)

is_satisfied(config)

partial_check(config, assigned_mask)

__init__(*args, **kwargs)

class qlinks.constraints.SquareDiskDiagonalLineSumSector(layout, lattice, family, target, occupied_value=1, name='square_disk_diagonal_line_sum_sector')

Bases: BaseSectorCondition

Fix all disk-number sums along one square-lattice diagonal family.

This is a diagonal symmetry-sector filter for the quantum disk model. It is intentionally independent of the Hamiltonian implementation: a model can use it whenever its local moves preserve one of the two diagonal line-sum families.

layout: VariableLayout

lattice: SquareLattice

family: Literal['x_plus_y', 'x_minus_y']

target: tuple[int, ...]

occupied_value: int

name: str

property labels: tuple[int, ...]

affected_variables()

value(config)

check(config)

partial_check(config, assigned_mask)

__init__(layout, lattice, family, target, occupied_value=1, name='square_disk_diagonal_line_sum_sector')

class qlinks.constraints.SquareQDMElectricWindingSector(layout, lattice, direction, target, name='square_qdm_electric_winding_sector')

Bases: BaseSectorCondition

Signed QDM winding sector compatible with the staggered-charge QLM mapping.

QDM variables:

n_l in {0, 1}

Electric-flux mapping:

E_l = eta(source(l)) * (2 n_l - 1)

where:

eta(x, y) = (-1)^(x + y)

The winding is computed across wrapping links:

direction=’x’:

sum over x-wrapping links

direction=’y’:

sum over y-wrapping links

This is the sector convention to compare with QLM winding sectors.

layout: VariableLayout

lattice: SquareLattice

direction: Literal['x', 'y']

target: int | Fraction | str

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

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

value(configuration)

internal_target()

check(configuration)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction)

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction)

__init__(layout, lattice, direction, target, name='square_qdm_electric_winding_sector')

class qlinks.constraints.SquareWindingSector(layout, lattice, direction, target, name='square_winding_sector', flux_normalization='spin_half')

Bases: BaseSectorCondition

Square-lattice electric winding sector.

The winding covector is a signed direction-link covector chosen so that it annihilates every plaquette boundary. This guarantees that local plaquette flips preserve the sector, including on small PBC lattices.

layout: VariableLayout

lattice: SquareLattice

direction: Literal['x', 'y']

target: int | Fraction | str

name: str

flux_normalization: Literal['integer_flux', 'spin_half']

classmethod cut_data(*, layout, lattice, direction)

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

property signs: ndarray

Signs used in the winding covector.

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

affected_variables()

value(config)

internal_target()

check(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_internal_targets(*, layout, lattice, direction)

classmethod allowed_targets(*, layout, lattice, direction, flux_normalization='spin_half')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, flux_normalization='spin_half')

__init__(layout, lattice, direction, target, name='square_winding_sector', flux_normalization='spin_half')

class qlinks.constraints.TotalValueSector(layout, target, variable_indices=None, coefficients=None, name='total_value_sector')

Bases: BaseSectorCondition

Fix the total signed value over selected variables.

Examples

total particle number total magnetization total electric flux on selected links

layout: VariableLayout

target: int

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

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

name: str

affected_variables()

value(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

__init__(layout, target, variable_indices=None, coefficients=None, name='total_value_sector')

class qlinks.constraints.TriangularZ2WindingSector(layout, lattice, direction, target, value_convention='binary', name='triangular_z2_winding_sector')

Bases: BaseSectorCondition

Z2 topological winding sector for triangular-lattice QDM/QLM on a torus.

The sector is the parity of occupied/electric-positive links crossing a non-contractible cut. The labels direction="a" and direction="b" refer to the two independent periodic cell directions of the triangular torus, not to filtering links by link.kind.

The cut is constructed from the periodic image shift of each link. This is important because triangular c links can also cross the primitive seams. Counting only wrapping links of kind "a" or "b" is not invariant under all triangular QDM rhombus flips.

layout: VariableLayout

lattice: TriangularLattice

direction: Literal['a', 'b']

target: int

value_convention: Literal['binary', 'flux_pm']

name: str

classmethod cut_data(*, layout, lattice, direction)

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

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

affected_variables()

value(config)

is_satisfied(config)

partial_check(config, assigned_mask)

propagate(config, assigned_mask)

classmethod allowed_targets(*, layout, lattice, direction, value_convention='binary')

Return all allowed target quantum numbers for this sector condition.

Subclasses should override this when the allowed labels can be determined from the lattice/layout.

classmethod validate_target(*, target, layout, lattice, direction, value_convention='binary')

__init__(layout, lattice, direction, target, value_convention='binary', name='triangular_z2_winding_sector')

class qlinks.constraints.WindingCutData(link_ids, signs, variable_indices)

Bases: object

Cached data defining one winding cut.

link_ids:

Physical lattice links participating in the winding cut.

signs:

Integer covector signs used in the winding value.

variable_indices:

VariableLayout indices corresponding to link_ids.

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

signs: ndarray[tuple[Any, ...], dtype[int64]]

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

__init__(link_ids, signs, variable_indices)

class qlinks.constraints.Z2CutData(link_ids, variable_indices)

Bases: object

Cached link and variable indices for one Z2 winding cut.

link_ids

Physical link ids crossing the cut.

Type:

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

variable_indices

Layout variable indices associated with link_ids.

Type:

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

link_ids: ndarray[tuple[Any, ...], dtype[int64]]

variable_indices: ndarray[tuple[Any, ...], dtype[int64]]

__init__(link_ids, variable_indices)

qlinks.constraints.all_satisfied(config, constraints=(), sectors=())

Convenience helper used by simple solvers.

qlinks.constraints.allowed_signed_sum_targets(*, layout, variable_indices, signs, value_transform=None)

Return all possible raw signed-sum sector values.

Computes all values of sum_i signs[i] * f(x_i) over the local spaces of the selected variables.

Parameters:

• layout (VariableLayout) – Variable layout.

• variable_indices (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Variables included in the diagonal quantum number.

• signs (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Integer signs/covector coefficients.

• value_transform – Optional function mapping local-space values to the internal values used by the sector. If None, values are used directly.

Returns:

Sorted tuple of possible raw signed-sum targets.

Return type:

tuple[int, …]

qlinks.constraints.internal_charge_value(charge, *, charge_normalization)

Convert user-facing charge into the raw integer target used by configs.

integer_flux:

config values are interpreted as physical E_l = ±1. charge target is used directly.

spin_half:

config values are stored as s_l = ±1, but physical E_l = s_l / 2. user-facing charge q is converted to raw target 2q.

qlinks.constraints.internal_flux_winding_value(winding, *, flux_normalization)

Convert user-facing winding target into raw integer flux target.

integer_flux:

stored flux s_l ∈ {-1,+1} is the physical electric field. raw_target = winding

spin_half:

stored flux s_l ∈ {-1,+1} represents twice the physical spin-half electric field, E_l = s_l / 2. raw_target = 2 * winding

qlinks.constraints.normalize_winding_target(target)

Normalize a user-facing winding target.

Accepts:

1 Fraction(3, 2) “3/2”

Avoid floats to prevent precision ambiguity.

qlinks.constraints.raw_targets_from_user_targets(user_targets, *, flux_normalization)

Convert user-facing winding labels to internal raw targets.

Parameters:

• user_targets (tuple[int, ...]) – Winding labels in the requested normalization.

• flux_normalization (Literal['integer_flux', 'spin_half']) – Normalization convention used by the user labels.

Returns:

Raw integer winding targets used internally by sector conditions.

Return type:

tuple[int, …]

qlinks.constraints.square_disk_line_label_for_cell(cell, lattice, *, family)

Return the diagonal-line label for one square-lattice cell/site.

qlinks.constraints.square_disk_line_labels(lattice, *, family)

Return stable labels for square-lattice disk diagonal lines.

family='x_plus_y' labels anti-diagonals with constant x + y; family='x_minus_y' labels diagonals with constant x - y. Periodic lattices use labels modulo the corresponding linear size, so these are the line sums conserved by diagonal hopping on a torus.

qlinks.constraints.user_targets_from_raw_flux_targets(raw_targets, *, flux_normalization)

Convert raw stored-flux winding values into user-facing winding labels.

integer_flux:

raw target equals user target.

spin_half:

stored flux s_l in {-1,+1} represents twice the physical spin-half electric field, so raw target = 2 * user target. Only even raw targets are valid integer user labels under the current API.

qlinks.constraints.user_winding_value_from_internal(raw_target, *, flux_normalization)

Convert raw integer winding value back to the user-facing convention.