qlinks.basis.solvers package

qlinks.basis.solvers package#

Submodules#

qlinks.basis.solvers.base module#

class qlinks.basis.solvers.base.BasisSolver(*args, **kwargs)[source]#

Bases: Protocol

solve(layout, constraints=(), sectors=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])

Return type:

Basis

__init__(*args, **kwargs)#

class qlinks.basis.solvers.base.SolverInput(layout: 'VariableLayout', constraints: 'tuple[Constraint, ...]', sectors: 'tuple[SectorCondition, ...]')[source]#

Bases: object

Parameters:

layout (VariableLayout)
constraints (tuple[Constraint, ...])
sectors (tuple[SectorCondition, ...])

layout: VariableLayout#

constraints: tuple[Constraint, ...]#

sectors: tuple[SectorCondition, ...]#

classmethod from_parts(layout, constraints=(), sectors=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])

Return type:

SolverInput

classmethod from_collection(layout, collection)[source]#

Parameters:

layout (VariableLayout)
collection (ConstraintCollection)

Return type:

SolverInput

__init__(layout, constraints, sectors)#

Parameters:

layout (VariableLayout)
constraints (tuple[Constraint, ...])
sectors (tuple[SectorCondition, ...])

Return type:

None

qlinks.basis.solvers.brute_force module#

class qlinks.basis.solvers.brute_force.BruteForceBasisSolver(sort=False)[source]#

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.

Parameters:: sort (bool)

sort: bool#

solve(layout, constraints=(), sectors=(), *, max_states=None)[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)

Return type:

Basis

__init__(sort=False)#

Parameters:: sort (bool)
Return type:: None

qlinks.basis.solvers.cpsat module#

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

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.

Parameters:

max_solutions (int | None)
num_workers (int)
log_search_progress (bool)
sort (bool)

max_solutions: int | None#

num_workers: int#

log_search_progress: bool#

sort: bool#

solve(layout, constraints=(), sectors=(), *, max_states=None)[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)

Return type:

Basis

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

Parameters:

max_solutions (int | None)
num_workers (int)
log_search_progress (bool)
sort (bool)

Return type:

None

qlinks.basis.solvers.dfs module#

class qlinks.basis.solvers.dfs.DFSSearchObserver(*args, **kwargs)[source]#

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)[source]#

Parameters:

config (ndarray[tuple[Any, ...], dtype[int64]])
assigned_mask (ndarray[tuple[Any, ...], dtype[bool]])
changed_variables (Sequence[int])

Return type:

bool

accept_solution(config)[source]#

Parameters:: config (ndarray[tuple[Any, ...], dtype[int64]])
Return type:: bool

__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)[source]#

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.

Parameters:

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)

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

Parameters:

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)

Return type:

None

class qlinks.basis.solvers.dfs.DFSBasisSolver(sort: 'bool' = True, variable_order: 'npt.ArrayLike | None' = None, variable_order_strategy: 'VariableOrderStrategy' = 'auto', value_order_strategy: 'ValueOrderStrategy' = 'layout')[source]#

Bases: object

Parameters:

sort (bool)
variable_order (ArrayLike | None)
variable_order_strategy (Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic'])
value_order_strategy (Literal['layout', 'propagation'])

sort: bool#

variable_order: ArrayLike | 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=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)
observers (Sequence[DFSSearchObserver])

Return type:

Basis

solve_with_statistics(layout, constraints=(), sectors=(), *, max_states=None, observers=())[source]#

Solve and return lightweight DFS execution statistics.

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)
observers (Sequence[DFSSearchObserver])

Return type:

tuple[Basis, DFSStatistics]

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

Parameters:

sort (bool)
variable_order (ArrayLike | None)
variable_order_strategy (Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic'])
value_order_strategy (Literal['layout', 'propagation'])

Return type:

None

Module contents#

class qlinks.basis.solvers.BasisSolver(*args, **kwargs)[source]#

Bases: Protocol

solve(layout, constraints=(), sectors=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])

Return type:

Basis

__init__(*args, **kwargs)#

class qlinks.basis.solvers.BruteForceBasisSolver(sort=False)[source]#

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.

Parameters:: sort (bool)

sort: bool#

solve(layout, constraints=(), sectors=(), *, max_states=None)[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)

Return type:

Basis

__init__(sort=False)#

Parameters:: sort (bool)
Return type:: None

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

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.

Parameters:

max_solutions (int | None)
num_workers (int)
log_search_progress (bool)
sort (bool)

max_solutions: int | None#

num_workers: int#

log_search_progress: bool#

sort: bool#

solve(layout, constraints=(), sectors=(), *, max_states=None)[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)

Return type:

Basis

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

Parameters:

max_solutions (int | None)
num_workers (int)
log_search_progress (bool)
sort (bool)

Return type:

None

class qlinks.basis.solvers.DFSBasisSolver(sort: 'bool' = True, variable_order: 'npt.ArrayLike | None' = None, variable_order_strategy: 'VariableOrderStrategy' = 'auto', value_order_strategy: 'ValueOrderStrategy' = 'layout')[source]#

Bases: object

Parameters:

sort (bool)
variable_order (ArrayLike | None)
variable_order_strategy (Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic'])
value_order_strategy (Literal['layout', 'propagation'])

sort: bool#

variable_order: ArrayLike | 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=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)
observers (Sequence[DFSSearchObserver])

Return type:

Basis

solve_with_statistics(layout, constraints=(), sectors=(), *, max_states=None, observers=())[source]#

Solve and return lightweight DFS execution statistics.

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])
max_states (int | None)
observers (Sequence[DFSSearchObserver])

Return type:

tuple[Basis, DFSStatistics]

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

Parameters:

sort (bool)
variable_order (ArrayLike | None)
variable_order_strategy (Literal['auto', 'layout', 'degree', 'weighted_degree', 'constraint_closure', 'dynamic'])
value_order_strategy (Literal['layout', 'propagation'])

Return type:

None

class qlinks.basis.solvers.DFSSearchObserver(*args, **kwargs)[source]#

Bases: Protocol

Read-only branch/solution observer for DFSBasisSolver.

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)

name: str#

can_continue(config, assigned_mask, changed_variables)[source]#

Parameters:

config (ndarray[tuple[Any, ...], dtype[int64]])
assigned_mask (ndarray[tuple[Any, ...], dtype[bool]])
changed_variables (Sequence[int])

Return type:

bool

accept_solution(config)[source]#

Parameters:: config (ndarray[tuple[Any, ...], dtype[int64]])
Return type:: bool

__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)[source]#

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.

Parameters:

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)

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#

Parameters:

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)

Return type:

None

class qlinks.basis.solvers.SolverInput(layout: 'VariableLayout', constraints: 'tuple[Constraint, ...]', sectors: 'tuple[SectorCondition, ...]')[source]#

Bases: object

Parameters:

layout (VariableLayout)
constraints (tuple[Constraint, ...])
sectors (tuple[SectorCondition, ...])

layout: VariableLayout#

constraints: tuple[Constraint, ...]#

sectors: tuple[SectorCondition, ...]#

classmethod from_parts(layout, constraints=(), sectors=())[source]#

Parameters:

layout (VariableLayout)
constraints (Sequence[Constraint])
sectors (Sequence[SectorCondition])

Return type:

SolverInput

classmethod from_collection(layout, collection)[source]#

Parameters:

layout (VariableLayout)
collection (ConstraintCollection)

Return type:

SolverInput

__init__(layout, constraints, sectors)#

Parameters:

layout (VariableLayout)
constraints (tuple[Constraint, ...])
sectors (tuple[SectorCondition, ...])

Return type:

None

qlinks.basis.solvers package

Contents

qlinks.basis.solvers package#

Submodules#

qlinks.basis.solvers.base module#

qlinks.basis.solvers.brute_force module#

qlinks.basis.solvers.cpsat module#

qlinks.basis.solvers.dfs module#

Module contents#