qlinks.basis.solvers package

Submodules

qlinks.basis.solvers.base module

class qlinks.basis.solvers.base.BasisSolver(*args, **kwargs)

Bases: Protocol

Protocol implemented by constrained-basis solvers.

Solvers enumerate configurations from a VariableLayout subject to constraints and sector filters, then return a Basis.

solve(layout, constraints=(), sectors=())

__init__(*args, **kwargs)

class qlinks.basis.solvers.base.SolverInput(layout, constraints, sectors)

Bases: object

Immutable bundle of inputs shared by basis solvers.

layout

Variable layout defining local spaces.

Type:

qlinks.variables.layout.VariableLayout

constraints

Constraints all states must satisfy.

Type:

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

sectors

Sector filters all states must satisfy.

Type:

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

layout: VariableLayout

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

classmethod from_parts(layout, constraints=(), sectors=())

classmethod from_collection(layout, collection)

__init__(layout, constraints, sectors)

qlinks.basis.solvers.brute_force module

class qlinks.basis.solvers.brute_force.BruteForceBasisSolver(sort=False)

Bases: object

Exhaustive product-space basis solver.

This is simple and useful for tests, but it scales as

prod_i dim(local_space_i)

so it should only be used for small systems.

sort: bool

solve(layout, constraints=(), sectors=(), *, max_states=None)

__init__(sort=False)

qlinks.basis.solvers.cpsat module

class qlinks.basis.solvers.cpsat.CPSATBasisSolver(max_solutions=None, num_workers=1, log_search_progress=False, sort=False)

Bases: object

OR-Tools CP-SAT basis solver.

This solver is useful when the constraints are naturally integer/Boolean constraints. It currently supports:

FixedValueConstraint LocalSumConstraint GaussLawConstraint DimerCoveringConstraint NearestNeighborBlockadeConstraint TotalValueSector ParitySector SquareWindingSector

Unsupported custom constraints raise NotImplementedError.

OR-Tools is imported lazily so qlinks can still be installed without it.

max_solutions: int | None

num_workers: int

log_search_progress: bool

sort: bool

solve(layout, constraints=(), sectors=(), *, max_states=None)

__init__(max_solutions=None, num_workers=1, log_search_progress=False, sort=False)

qlinks.basis.solvers.dfs module

class qlinks.basis.solvers.dfs.DFSSearchObserver(*args, **kwargs)

Bases: Protocol

Read-only branch/solution observer for DFSBasisSolver.

Observers are intended for search-specific pruning that is not naturally a model constraint. They may inspect the mutable DFS arrays but must not mutate them. Returning False from can_continue prunes the current partial branch; returning False from accept_solution filters the complete configuration.

Stateful observers may additionally implement any of these optional methods, which DFSBasisSolver discovers with getattr so existing read-only observers remain valid:

reset(config, assigned_mask)
on_assignments(config, assigned_mask, changed_variables)
on_unassignments(config, assigned_mask, changed_variables)
on_assign(config, assigned_mask, variable_index, value, forced_assignment)
on_unassign(config, assigned_mask, variable_index, value)

Assignment callbacks run after the DFS arrays have been updated; unassign callbacks run just before assigned_mask[variable_index] is cleared. Batched callbacks are preferred for observers that maintain incremental state over many variables.

name: str

can_continue(config, assigned_mask, changed_variables)

accept_solution(config)

__init__(*args, **kwargs)

class qlinks.basis.solvers.dfs.DFSStatistics(branch_count=0, solution_count=0, contradiction_count=0, propagated_assignment_count=0, skipped_forced_variable_count=0, partial_check_count=0, propagation_round_count=0, propagator_call_count=0, dynamic_variable_selection_count=0, dynamic_value_ordering_count=0, observer_call_count=0, observer_update_count=0, observer_prune_count=0, observer_solution_reject_count=0, max_depth=0)

Bases: object

Execution counters for DFSBasisSolver.

The counters are intentionally lightweight and solver-centric. They are meant for comparing pruning/order heuristics, not for proving exact search tree identities across implementation changes.

branch_count: int

solution_count: int

contradiction_count: int

propagated_assignment_count: int

skipped_forced_variable_count: int

partial_check_count: int

propagation_round_count: int

propagator_call_count: int

dynamic_variable_selection_count: int

dynamic_value_ordering_count: int

observer_call_count: int

observer_update_count: int

observer_prune_count: int

observer_solution_reject_count: int

max_depth: int

__init__(branch_count=0, solution_count=0, contradiction_count=0, propagated_assignment_count=0, skipped_forced_variable_count=0, partial_check_count=0, propagation_round_count=0, propagator_call_count=0, dynamic_variable_selection_count=0, dynamic_value_ordering_count=0, observer_call_count=0, observer_update_count=0, observer_prune_count=0, observer_solution_reject_count=0, max_depth=0)

class qlinks.basis.solvers.dfs.DFSBasisSolver(sort=True, variable_order=None, variable_order_strategy='auto', value_order_strategy='layout')

Bases: object

Depth-first constrained-basis enumerator.

The solver incrementally assigns variables, runs partial checks and propagators, and optionally notifies search observers. It is the default basis solver for model builds because it supports early stopping, dynamic ordering, propagation, and model-specific observer hooks.

sort

Whether to lexicographically sort the returned basis.

Type:

bool

variable_order

Optional explicit variable order.

Type:

collections.abc.Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str] | None

variable_order_strategy

Heuristic used when variable_order is not supplied.

Type:

Literal[‘auto’, ‘layout’, ‘degree’, ‘weighted_degree’, ‘constraint_closure’, ‘dynamic’]

value_order_strategy

Heuristic used to order trial local values.

Type:

Literal[‘layout’, ‘propagation’]

sort: bool

variable_order: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None

variable_order_strategy: Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic']

value_order_strategy: Literal['layout', 'propagation']

solve(layout, constraints=(), sectors=(), *, max_states=None, observers=())

solve_with_statistics(layout, constraints=(), sectors=(), *, max_states=None, observers=())

Solve and return lightweight DFS execution statistics.

__init__(sort=True, variable_order=None, variable_order_strategy='auto', value_order_strategy='layout')

Module contents

class qlinks.basis.solvers.BasisSolver(*args, **kwargs)

Bases: Protocol

Protocol implemented by constrained-basis solvers.

Solvers enumerate configurations from a VariableLayout subject to constraints and sector filters, then return a Basis.

solve(layout, constraints=(), sectors=())

__init__(*args, **kwargs)

class qlinks.basis.solvers.BruteForceBasisSolver(sort=False)

Bases: object

Exhaustive product-space basis solver.

This is simple and useful for tests, but it scales as

prod_i dim(local_space_i)

so it should only be used for small systems.

sort: bool

solve(layout, constraints=(), sectors=(), *, max_states=None)

__init__(sort=False)

class qlinks.basis.solvers.CPSATBasisSolver(max_solutions=None, num_workers=1, log_search_progress=False, sort=False)

Bases: object

OR-Tools CP-SAT basis solver.

This solver is useful when the constraints are naturally integer/Boolean constraints. It currently supports:

FixedValueConstraint LocalSumConstraint GaussLawConstraint DimerCoveringConstraint NearestNeighborBlockadeConstraint TotalValueSector ParitySector SquareWindingSector

Unsupported custom constraints raise NotImplementedError.

OR-Tools is imported lazily so qlinks can still be installed without it.

max_solutions: int | None

num_workers: int

log_search_progress: bool

sort: bool

solve(layout, constraints=(), sectors=(), *, max_states=None)

__init__(max_solutions=None, num_workers=1, log_search_progress=False, sort=False)

class qlinks.basis.solvers.DFSBasisSolver(sort=True, variable_order=None, variable_order_strategy='auto', value_order_strategy='layout')

Bases: object

Depth-first constrained-basis enumerator.

The solver incrementally assigns variables, runs partial checks and propagators, and optionally notifies search observers. It is the default basis solver for model builds because it supports early stopping, dynamic ordering, propagation, and model-specific observer hooks.

sort

Whether to lexicographically sort the returned basis.

Type:

bool

variable_order

Optional explicit variable order.

Type:

collections.abc.Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str] | None

variable_order_strategy

Heuristic used when variable_order is not supplied.

Type:

Literal[‘auto’, ‘layout’, ‘degree’, ‘weighted_degree’, ‘constraint_closure’, ‘dynamic’]

value_order_strategy

Heuristic used to order trial local values.

Type:

Literal[‘layout’, ‘propagation’]

sort: bool

variable_order: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None

variable_order_strategy: Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic']

value_order_strategy: Literal['layout', 'propagation']

solve(layout, constraints=(), sectors=(), *, max_states=None, observers=())

solve_with_statistics(layout, constraints=(), sectors=(), *, max_states=None, observers=())

Solve and return lightweight DFS execution statistics.

__init__(sort=True, variable_order=None, variable_order_strategy='auto', value_order_strategy='layout')

class qlinks.basis.solvers.DFSSearchObserver(*args, **kwargs)

Bases: Protocol

Read-only branch/solution observer for DFSBasisSolver.

Observers are intended for search-specific pruning that is not naturally a model constraint. They may inspect the mutable DFS arrays but must not mutate them. Returning False from can_continue prunes the current partial branch; returning False from accept_solution filters the complete configuration.

Stateful observers may additionally implement any of these optional methods, which DFSBasisSolver discovers with getattr so existing read-only observers remain valid:

reset(config, assigned_mask)
on_assignments(config, assigned_mask, changed_variables)
on_unassignments(config, assigned_mask, changed_variables)
on_assign(config, assigned_mask, variable_index, value, forced_assignment)
on_unassign(config, assigned_mask, variable_index, value)

Assignment callbacks run after the DFS arrays have been updated; unassign callbacks run just before assigned_mask[variable_index] is cleared. Batched callbacks are preferred for observers that maintain incremental state over many variables.

name: str

can_continue(config, assigned_mask, changed_variables)

accept_solution(config)

__init__(*args, **kwargs)

class qlinks.basis.solvers.DFSStatistics(branch_count=0, solution_count=0, contradiction_count=0, propagated_assignment_count=0, skipped_forced_variable_count=0, partial_check_count=0, propagation_round_count=0, propagator_call_count=0, dynamic_variable_selection_count=0, dynamic_value_ordering_count=0, observer_call_count=0, observer_update_count=0, observer_prune_count=0, observer_solution_reject_count=0, max_depth=0)

Bases: object

Execution counters for DFSBasisSolver.

The counters are intentionally lightweight and solver-centric. They are meant for comparing pruning/order heuristics, not for proving exact search tree identities across implementation changes.

branch_count: int

solution_count: int

contradiction_count: int

propagated_assignment_count: int

skipped_forced_variable_count: int

partial_check_count: int

propagation_round_count: int

propagator_call_count: int

dynamic_variable_selection_count: int

dynamic_value_ordering_count: int

observer_call_count: int

observer_update_count: int

observer_prune_count: int

observer_solution_reject_count: int

max_depth: int

__init__(branch_count=0, solution_count=0, contradiction_count=0, propagated_assignment_count=0, skipped_forced_variable_count=0, partial_check_count=0, propagation_round_count=0, propagator_call_count=0, dynamic_variable_selection_count=0, dynamic_value_ordering_count=0, observer_call_count=0, observer_update_count=0, observer_prune_count=0, observer_solution_reject_count=0, max_depth=0)

class qlinks.basis.solvers.SolverInput(layout, constraints, sectors)

Bases: object

Immutable bundle of inputs shared by basis solvers.

layout

Variable layout defining local spaces.

Type:

qlinks.variables.layout.VariableLayout

constraints

Constraints all states must satisfy.

Type:

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

sectors

Sector filters all states must satisfy.

Type:

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

layout: VariableLayout

constraints: tuple[Constraint, ...]

sectors: tuple[SectorCondition, ...]

classmethod from_parts(layout, constraints=(), sectors=())

classmethod from_collection(layout, collection)

__init__(layout, constraints, sectors)