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.

Parameters:

• satisfied (bool)

• name (str)

• residual (object | None)

• message (str)

satisfied: bool

name: str

residual: object | None

message: str

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

Parameters:

• satisfied (bool)

• name (str)

• residual (object | None)

• message (str)

Return type:

None

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.

Parameters:

• consistent (bool)

• forced_assignments (tuple[tuple[int, int], ...])

consistent: bool

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

classmethod contradiction()

Return type:

ConstraintPropagation

classmethod no_change()

Return type:

ConstraintPropagation

__init__(consistent=True, forced_assignments=())

Parameters:

• consistent (bool)

• forced_assignments (tuple[tuple[int, int], ...])

Return type:

None

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

Bases: Protocol

General constraint interface.

A constraint decides whether a raw configuration is allowed.

Performance contract

affected_variables() must return the variable indices that can affect the result of partial_check() or check().

DFSBasisSolver uses this support to decide when to call partial_check(). If a constraint does not override affected_variables(), BaseConstraint conservatively returns all variables, which is correct but slower.

name: str

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

__init__(*args, **kwargs)

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

Bases: Protocol

Diagonal symmetry-sector filter.

Performance contract

affected_variables() must return the variable indices that can affect the result of partial_check() or check().

DFSBasisSolver uses this support to decide when to call partial_check(). If a constraint does not override affected_variables(), BaseConstraint conservatively returns all variables, which is correct but slower.

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

object

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

object

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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.

Return type:

tuple[int, …]

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

Parameters:

target (int)

Return type:

None

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

Convenience helper used by simple solvers.

Parameters:

• config (ArrayLike)

• constraints (Sequence[Constraint])

• sectors (Sequence[SectorCondition])

Return type:

bool

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.

Parameters:

• layout (VariableLayout)

• site_i (int)

• site_j (int)

• occupied_value (int)

• name (str)

layout: VariableLayout

site_i: int

site_j: int

occupied_value: int

name: str

classmethod from_lattice(lattice, layout, occupied_value=1)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• occupied_value (int)

Return type:

tuple[NearestNeighborBlockadeConstraint, …]

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Parameters:

• layout (VariableLayout)

• site_i (int)

• site_j (int)

• occupied_value (int)

• name (str)

Return type:

None

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.

Parameters:

• constraints (tuple[Constraint, ...])

• sectors (tuple[SectorCondition, ...])

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

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

Parameters:

• constraints (Sequence[Constraint])

• sectors (Sequence[SectorCondition])

Return type:

ConstraintCollection

check_constraints(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

check_sectors(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

check_all(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

first_failure(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult | None

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

Parameters:

• constraints (tuple[Constraint, ...])

• sectors (tuple[SectorCondition, ...])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• site_id (int)

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• required_count (int)

• name (str)

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)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• site_id (int)

• required_count (int)

Return type:

DimerCoveringConstraint

classmethod all_sites(lattice, layout, required_counts=1)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• required_counts (int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]])

Return type:

tuple[DimerCoveringConstraint, …]

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• site_id (int)

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• required_count (int)

• name (str)

Return type:

None

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.

Parameters:

• charge (int)

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

int

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.

Parameters:

• 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'])

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

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• site_id (int)

• charge (int)

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

GaussLawConstraint

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

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• charges (int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]])

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[GaussLawConstraint, …]

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• 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'])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• min_count (int | None)

• max_count (int)

• name (str)

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

Parameters:

• layout (VariableLayout)

• variable_indices (ArrayLike)

• count (int)

• name (str)

Return type:

BoundedLocalCountConstraint

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

Parameters:

• layout (VariableLayout)

• variable_indices (ArrayLike)

• max_count (int)

• name (str)

Return type:

BoundedLocalCountConstraint

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• min_count (int | None)

• max_count (int)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• values (ndarray[tuple[Any, ...], dtype[int64]])

• name (str)

layout: VariableLayout

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

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

name: str

classmethod single(layout, variable_index, value)

Parameters:

• layout (VariableLayout)

• variable_index (int)

• value (int)

Return type:

FixedValueConstraint

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• values (ndarray[tuple[Any, ...], dtype[int64]])

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• coefficients (ndarray[tuple[Any, ...], dtype[int64]])

• target (int)

• name (str)

layout: VariableLayout

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

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

target: int

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• coefficients (ndarray[tuple[Any, ...], dtype[int64]])

• target (int)

• name (str)

Return type:

None

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficients (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

layout: VariableLayout

target: int

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

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

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficients (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

layout: VariableLayout

target: int

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

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

Return type:

None

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.

Parameters:

target (int | Fraction | str)

Return type:

Fraction

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

Parameters:

• winding (int | Fraction | str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

int

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

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

Parameters:

• raw_target (int)

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

Fraction

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

Return all possible raw values of sum_i signs[i] * f(x_i).

Parameters:

• layout (VariableLayout) – Variable layout.

• variable_indices (ArrayLike) – Variables included in the diagonal quantum number.

• signs (ArrayLike) – Integer signs/covector coefficients.

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

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.

Parameters:

• raw_targets (tuple[int, ...])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[int, …]

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

Parameters:

• user_targets (tuple[int, ...])

• flux_normalization (Literal['integer_flux', 'spin_half'])

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.

Parameters:

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• signs (ndarray[tuple[Any, ...], dtype[int64]])

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

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)

Parameters:

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• signs (ndarray[tuple[Any, ...], dtype[int64]])

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

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)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

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

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

internal_target()

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

classmethod allowed_internal_targets(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

tuple[int, …]

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[Fraction, …]

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

Parameters:

• target (int | Fraction | str)

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

layout: VariableLayout

lattice: SquareLattice

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

target: int | Fraction | str

name: str

classmethod cut_data(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

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

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

affected_variables()

Return type:

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

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

value(configuration)

Parameters:

configuration (ndarray)

Return type:

int

internal_target()

Return type:

int

check(configuration)

Parameters:

configuration (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

Return type:

None

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 defined as the signed electric flux through a non-contractible cut of the periodic lattice. The signs are determined by the oriented-link convention of the lattice, so the sector is invariant under local plaquette flips.

Notes

The direction argument 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.

Parameters:

• layout (qlinks.variables.layout.VariableLayout) – Variable layout whose link variables represent spin-half electric fluxes.

• lattice (qlinks.lattice.honeycomb.HoneycombLattice) – Periodic honeycomb lattice.

• direction (Literal['x', 'y']) – Either "x" or "y". These refer to the two unit-cell periodic directions, not Cartesian plot axes.

• target (int | fractions.Fraction | str) – Target winding value in the chosen direction.

• flux_normalization (Literal['integer_flux', 'spin_half']) – Normalization convention for the electric flux variables. For example, "spin_half" corresponds to link values {-1, +1} representing twice the physical spin-half electric field.

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

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)

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

internal_target()

Return type:

int

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

static electric_values_from_convention(values, *, value_convention)

Parameters:

• values (ndarray[tuple[Any, ...], dtype[int64]])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

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

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

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

tuple[int, …]

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.

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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

Parameters:

• 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'])

Return type:

None

qlinks.constraints.z2_winding module

class qlinks.constraints.z2_winding.Z2CutData(link_ids: 'npt.NDArray[np.int64]', variable_indices: 'npt.NDArray[np.int64]')

Bases: object

Parameters:

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

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

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

__init__(link_ids, variable_indices)

Parameters:

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• target (int)

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

layout: VariableLayout

lattice: TriangularLattice

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

target: int

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

name: str

classmethod cut_data(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

Return type:

Z2CutData

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

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

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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.

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• target (int)

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

Return type:

None

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

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

object

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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.

Return type:

tuple[int, …]

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

Parameters:

target (int)

Return type:

None

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

Bases: Protocol

General constraint interface.

A constraint decides whether a raw configuration is allowed.

Performance contract

affected_variables() must return the variable indices that can affect the result of partial_check() or check().

DFSBasisSolver uses this support to decide when to call partial_check(). If a constraint does not override affected_variables(), BaseConstraint conservatively returns all variables, which is correct but slower.

name: str

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Parameters:

• constraints (tuple[Constraint, ...])

• sectors (tuple[SectorCondition, ...])

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

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

Parameters:

• constraints (Sequence[Constraint])

• sectors (Sequence[SectorCondition])

Return type:

ConstraintCollection

check_constraints(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

check_sectors(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

check_all(config)

Parameters:

config (ArrayLike)

Return type:

tuple[ConstraintResult, …]

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

first_failure(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult | None

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

Parameters:

• constraints (tuple[Constraint, ...])

• sectors (tuple[SectorCondition, ...])

Return type:

None

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.

Parameters:

• consistent (bool)

• forced_assignments (tuple[tuple[int, int], ...])

consistent: bool

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

classmethod contradiction()

Return type:

ConstraintPropagation

classmethod no_change()

Return type:

ConstraintPropagation

__init__(consistent=True, forced_assignments=())

Parameters:

• consistent (bool)

• forced_assignments (tuple[tuple[int, int], ...])

Return type:

None

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

Bases: object

Result of checking one constraint or sector condition.

Parameters:

• satisfied (bool)

• name (str)

• residual (object | None)

• message (str)

satisfied: bool

name: str

residual: object | None

message: str

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

Parameters:

• satisfied (bool)

• name (str)

• residual (object | None)

• message (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• site_id (int)

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• required_count (int)

• name (str)

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)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• site_id (int)

• required_count (int)

Return type:

DimerCoveringConstraint

classmethod all_sites(lattice, layout, required_counts=1)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• required_counts (int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]])

Return type:

tuple[DimerCoveringConstraint, …]

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• site_id (int)

• link_ids (ndarray[tuple[Any, ...], dtype[int64]])

• required_count (int)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• min_count (int | None)

• max_count (int)

• name (str)

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

Parameters:

• layout (VariableLayout)

• variable_indices (ArrayLike)

• count (int)

• name (str)

Return type:

BoundedLocalCountConstraint

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

Parameters:

• layout (VariableLayout)

• variable_indices (ArrayLike)

• max_count (int)

• name (str)

Return type:

BoundedLocalCountConstraint

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• min_count (int | None)

• max_count (int)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• values (ndarray[tuple[Any, ...], dtype[int64]])

• name (str)

layout: VariableLayout

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

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

name: str

classmethod single(layout, variable_index, value)

Parameters:

• layout (VariableLayout)

• variable_index (int)

• value (int)

Return type:

FixedValueConstraint

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• values (ndarray[tuple[Any, ...], dtype[int64]])

• name (str)

Return type:

None

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.

Parameters:

• 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'])

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

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• site_id (int)

• charge (int)

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

GaussLawConstraint

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

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• charges (int | Sequence[int] | ndarray[tuple[Any, ...], dtype[int64]])

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[GaussLawConstraint, …]

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• 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'])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• coefficients (ndarray[tuple[Any, ...], dtype[int64]])

• target (int)

• name (str)

layout: VariableLayout

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

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

target: int

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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

Parameters:

• layout (VariableLayout)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]])

• coefficients (ndarray[tuple[Any, ...], dtype[int64]])

• target (int)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• site_i (int)

• site_j (int)

• occupied_value (int)

• name (str)

layout: VariableLayout

site_i: int

site_j: int

occupied_value: int

name: str

classmethod from_lattice(lattice, layout, occupied_value=1)

Parameters:

• lattice (LatticeGraph)

• layout (VariableLayout)

• occupied_value (int)

Return type:

tuple[NearestNeighborBlockadeConstraint, …]

affected_variables()

Return type:

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

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

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.

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

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

Parameters:

• layout (VariableLayout)

• site_i (int)

• site_j (int)

• occupied_value (int)

• name (str)

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

layout: VariableLayout

target: int

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

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

Return type:

None

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

Bases: Protocol

Diagonal symmetry-sector filter.

Performance contract

affected_variables() must return the variable indices that can affect the result of partial_check() or check().

DFSBasisSolver uses this support to decide when to call partial_check(). If a constraint does not override affected_variables(), BaseConstraint conservatively returns all variables, which is correct but slower.

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

object

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

__init__(*args, **kwargs)

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

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)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

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

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

internal_target()

Return type:

int

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

classmethod allowed_internal_targets(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

tuple[int, …]

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[Fraction, …]

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

Parameters:

• target (int | Fraction | str)

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

layout: VariableLayout

lattice: SquareLattice

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

target: int | Fraction | str

name: str

classmethod cut_data(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

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

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

affected_variables()

Return type:

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

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

value(configuration)

Parameters:

configuration (ndarray)

Return type:

int

internal_target()

Return type:

int

check(configuration)

Parameters:

configuration (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• direction (Literal['x', 'y'])

• target (int | Fraction | str)

• name (str)

Return type:

None

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficients (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

layout: VariableLayout

target: int

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

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

name: str

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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

Parameters:

• layout (VariableLayout)

• target (int)

• variable_indices (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficients (ndarray[tuple[Any, ...], dtype[int64]] | None)

• name (str)

Return type:

None

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

Convenience helper used by simple solvers.

Parameters:

• config (ArrayLike)

• constraints (Sequence[Constraint])

• sectors (Sequence[SectorCondition])

Return type:

bool

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.

Parameters:

• charge (int)

• charge_normalization (Literal['integer_flux', 'spin_half'])

Return type:

int

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

Parameters:

• winding (int | Fraction | str)

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

int

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 defined as the signed electric flux through a non-contractible cut of the periodic lattice. The signs are determined by the oriented-link convention of the lattice, so the sector is invariant under local plaquette flips.

Notes

The direction argument 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.

Parameters:

• layout (qlinks.variables.layout.VariableLayout) – Variable layout whose link variables represent spin-half electric fluxes.

• lattice (qlinks.lattice.honeycomb.HoneycombLattice) – Periodic honeycomb lattice.

• direction (Literal['x', 'y']) – Either "x" or "y". These refer to the two unit-cell periodic directions, not Cartesian plot axes.

• target (int | fractions.Fraction | str) – Target winding value in the chosen direction.

• flux_normalization (Literal['integer_flux', 'spin_half']) – Normalization convention for the electric flux variables. For example, "spin_half" corresponds to link values {-1, +1} representing twice the physical spin-half electric field.

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

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)

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

Return type:

WindingCutData

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

internal_target()

Return type:

int

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

check(config)

Parameters:

config (ArrayLike)

Return type:

ConstraintResult

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

static electric_values_from_convention(values, *, value_convention)

Parameters:

• values (ndarray[tuple[Any, ...], dtype[int64]])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

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

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

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

tuple[int, …]

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.

Parameters:

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (HoneycombLattice)

• direction (Literal['x', 'y'])

• value_convention (Literal['binary', 'flux_pm'])

• flux_normalization (Literal['integer_flux', 'spin_half'])

Return type:

None

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

Parameters:

• 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'])

Return type:

None

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.

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• target (int)

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

layout: VariableLayout

lattice: TriangularLattice

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

target: int

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

name: str

classmethod cut_data(*, layout, lattice, direction)

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

Return type:

Z2CutData

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

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

affected_variables()

Return type:

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

value(config)

Parameters:

config (ArrayLike)

Return type:

int

is_satisfied(config)

Parameters:

config (ArrayLike)

Return type:

bool

partial_check(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

bool

propagate(config, assigned_mask)

Parameters:

• config (ArrayLike)

• assigned_mask (ArrayLike)

Return type:

ConstraintPropagation

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.

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

tuple[int, …]

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

Parameters:

• target (int)

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• value_convention (Literal['binary', 'flux_pm'])

Return type:

None

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

Parameters:

• layout (VariableLayout)

• lattice (TriangularLattice)

• direction (Literal['a', 'b'])

• target (int)

• value_convention (Literal['binary', 'flux_pm'])

• name (str)

Return type:

None