qlinks.basis package

Subpackages

• 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

Submodules

qlinks.basis.basis module

qlinks.basis.basis.full_basis_from_layout(layout, *, sort=True, max_states=None)

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.

class qlinks.basis.basis.Basis(layout, states, encoder, index)

Bases: object

Computational basis represented by explicit configurations.

states:

Integer array of shape (n_states, n_variables).

index:

Map encoded configuration -> basis index.

layout: VariableLayout

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

encoder: ConfigEncoder

index: dict[bytes, int]

classmethod from_states(layout, states, *, sort=False)

classmethod empty(layout)

property n_states: int

property n_variables: int

state(basis_index, *, copy=True)

get_index(config)

require_index(config)

iter_states(*, copy=True)

__init__(layout, states, encoder, index)

qlinks.basis.configs module

qlinks.basis.configs.basis_configs_from_basis(basis)

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

qlinks.basis.configs.basis_configs_from_build_result(build_result)

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.

qlinks.basis.configs.decode_basis_configs_with_layout(basis_configs, layout)

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.

qlinks.basis.sectors module

qlinks.basis.sectors.sector_mask_from_sectors(basis_configs, sectors)

Return a boolean mask selecting configs satisfying all sectors.

qlinks.basis.sectors.sector_mask_from_build_result(build_result, sectors=None)

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.

Module contents

class qlinks.basis.Basis(layout, states, encoder, index)

Bases: object

Computational basis represented by explicit configurations.

states:

Integer array of shape (n_states, n_variables).

index:

Map encoded configuration -> basis index.

layout: VariableLayout

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

encoder: ConfigEncoder

index: dict[bytes, int]

classmethod from_states(layout, states, *, sort=False)

classmethod empty(layout)

property n_states: int

property n_variables: int

state(basis_index, *, copy=True)

get_index(config)

require_index(config)

iter_states(*, copy=True)

__init__(layout, states, encoder, index)

class qlinks.basis.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.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.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.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.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.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.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.basis_configs_from_basis(basis)

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

qlinks.basis.basis_configs_from_build_result(build_result)

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.

qlinks.basis.decode_basis_configs_with_layout(basis_configs, layout)

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.

qlinks.basis.full_basis_from_layout(layout, *, sort=True, max_states=None)

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.

qlinks.basis.sector_mask_from_build_result(build_result, sectors=None)

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.

qlinks.basis.sector_mask_from_sectors(basis_configs, sectors)

Return a boolean mask selecting configs satisfying all sectors.