qlinks.basis package

qlinks.basis package#

Subpackages#

qlinks.basis.solvers package

Submodules#

qlinks.basis.basis module#

qlinks.basis.basis.full_basis_from_layout(layout, *, sort=True, max_states=None)[source]#

Generate the full Cartesian-product basis for an unconstrained layout.

This is faster and simpler than DFS when there are no constraints/sectors.

The output states have shape:

(prod_i dim_i, layout.n_variables)

where dim_i is the local-space dimension of variable i.

Parameters:

layout (VariableLayout)
sort (bool)
max_states (int | None)

Return type:

Basis

class qlinks.basis.basis.Basis(layout, states, encoder, index)[source]#

Bases: object

Computational basis represented by explicit configurations.

states:: Integer array of shape (n_states, n_variables).
index:: Map encoded configuration -> basis index.

Parameters:

layout (VariableLayout)
states (ndarray[tuple[Any, ...], dtype[int64]])
encoder (ConfigEncoder)
index (dict[bytes, int])

layout: VariableLayout#

states: ndarray[tuple[Any, ...], dtype[int64]]#

encoder: ConfigEncoder#

index: dict[bytes, int]#

classmethod from_states(layout, states, *, sort=False)[source]#

Parameters:

layout (VariableLayout)
states (ArrayLike)
sort (bool)

Return type:

Basis

classmethod empty(layout)[source]#

Parameters:: layout (VariableLayout)
Return type:: Basis

property n_states: int#

property n_variables: int#

state(basis_index, *, copy=True)[source]#

Parameters:

basis_index (int)
copy (bool)

Return type:

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

get_index(config)[source]#

Parameters:: config (ArrayLike)
Return type:: int | None

require_index(config)[source]#

Parameters:: config (ArrayLike)
Return type:: int

iter_states(*, copy=True)[source]#

Parameters:: copy (bool)
Return type:: Iterable[ndarray[tuple[Any, …], dtype[int64]]]

__init__(layout, states, encoder, index)#

Parameters:

layout (VariableLayout)
states (ndarray[tuple[Any, ...], dtype[int64]])
encoder (ConfigEncoder)
index (dict[bytes, int])

Return type:

None

Module contents#

class qlinks.basis.Basis(layout, states, encoder, index)[source]#

Bases: object

Computational basis represented by explicit configurations.

states:: Integer array of shape (n_states, n_variables).
index:: Map encoded configuration -> basis index.

Parameters:

layout (VariableLayout)
states (ndarray[tuple[Any, ...], dtype[int64]])
encoder (ConfigEncoder)
index (dict[bytes, int])

layout: VariableLayout#

states: ndarray[tuple[Any, ...], dtype[int64]]#

encoder: ConfigEncoder#

index: dict[bytes, int]#

classmethod from_states(layout, states, *, sort=False)[source]#

Parameters:

layout (VariableLayout)
states (ArrayLike)
sort (bool)

Return type:

Basis

classmethod empty(layout)[source]#

Parameters:: layout (VariableLayout)
Return type:: Basis

property n_states: int#

property n_variables: int#

state(basis_index, *, copy=True)[source]#

Parameters:

basis_index (int)
copy (bool)

Return type:

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

get_index(config)[source]#

Parameters:: config (ArrayLike)
Return type:: int | None

require_index(config)[source]#

Parameters:: config (ArrayLike)
Return type:: int

iter_states(*, copy=True)[source]#

Parameters:: copy (bool)
Return type:: Iterable[ndarray[tuple[Any, …], dtype[int64]]]

__init__(layout, states, encoder, index)#

Parameters:

layout (VariableLayout)
states (ndarray[tuple[Any, ...], dtype[int64]])
encoder (ConfigEncoder)
index (dict[bytes, int])

Return type:

None

class qlinks.basis.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.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.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.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.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.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.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.full_basis_from_layout(layout, *, sort=True, max_states=None)[source]#

Generate the full Cartesian-product basis for an unconstrained layout.

This is faster and simpler than DFS when there are no constraints/sectors.

The output states have shape:

(prod_i dim_i, layout.n_variables)

where dim_i is the local-space dimension of variable i.

Parameters:

layout (VariableLayout)
sort (bool)
max_states (int | None)

Return type:

Basis

qlinks.basis.basis_configs_from_basis(basis)[source]#

Return explicit basis configurations for ArrayBasis or BinaryEncodedBasis.

Sparse/array builders usually expose this as basis.states. Bitmask builders may use BinaryEncodedBasis, which stores compact integer codes and exposes to_array_basis().

Parameters:: basis (Any)
Return type:: ndarray[tuple[Any, …], dtype[integer]]

qlinks.basis.basis_configs_from_build_result(build_result)[source]#

Return physical basis configurations from a ModelBuildResult.

Bitmask builders may store basis states as local integer codes, e.g. 0/1 for a two-state local space. The classifier and visualizers need the physical variable values declared by build_result.layout, e.g. -1/+1.

Parameters:: build_result (Any)
Return type:: ndarray[tuple[Any, …], dtype[integer]]

qlinks.basis.decode_basis_configs_with_layout(basis_configs, layout)[source]#

Decode local integer codes into physical values using a VariableLayout.

If the configs already contain valid physical values, they are returned unchanged. Otherwise, values 0, 1, …, d-1 are interpreted as indices into each variable’s local space.

Parameters:

basis_configs (ndarray[tuple[Any, ...], dtype[integer]])
layout (Any)

Return type:

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

qlinks.basis.sector_mask_from_build_result(build_result, sectors=None)[source]#

Return a boolean mask for configs in a build result.

If sectors is provided, use those sectors. Otherwise, try common build-result fields and fall back to selecting all basis states.

Parameters:

build_result (Any)
sectors (Sequence[Any] | None)

Return type:

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

qlinks.basis.sector_mask_from_sectors(basis_configs, sectors)[source]#

Return a boolean mask selecting configs satisfying all sectors.

Parameters:

basis_configs (ndarray[tuple[Any, ...], dtype[integer]])
sectors (Sequence[Any])

Return type:

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

qlinks.basis package

Contents

qlinks.basis package#

Subpackages#

Submodules#

qlinks.basis.basis module#

Module contents#