qlinks.encoded package

Submodules

qlinks.encoded.binary_basis module

qlinks.encoded.binary_basis.encode_binary_config(config)

Encode binary config into a Python int.

bit i stores config[i].

Parameters:

config (ArrayLike)

Return type:

int

qlinks.encoded.binary_basis.decode_binary_code(code, n_variables)

Decode Python int code back to binary config.

Parameters:

• code (int)

• n_variables (int)

Return type:

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

qlinks.encoded.binary_basis.bitmask_from_indices(indices)

Parameters:

indices (Iterable[int])

Return type:

int

class qlinks.encoded.binary_basis.BinaryEncodedBasis(layout, codes, index)

Bases: object

Basis represented by integer bit patterns.

This is the production-oriented binary fast path. It is useful for PXP, QDM, toric-code qubits, and any model whose variables are {0, 1}.

Parameters:

• layout (VariableLayout)

• codes (ndarray[tuple[Any, ...], dtype[object_]])

• index (dict[int, int])

layout: VariableLayout

codes: ndarray[tuple[Any, ...], dtype[object_]]

index: dict[int, int]

classmethod from_codes(layout, codes, *, sort=False)

Parameters:

• layout (VariableLayout)

• codes (Iterable[int])

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod from_configs(layout, configs, *, sort=False)

Parameters:

• layout (VariableLayout)

• configs (ArrayLike)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod from_basis(basis, *, sort=False)

Parameters:

• basis (Basis)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod full(layout, *, sort=True)

Parameters:

• layout (VariableLayout)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod empty(layout)

Parameters:

layout (VariableLayout)

Return type:

BinaryEncodedBasis

property n_states: int

property n_variables: int

code(basis_index)

Parameters:

basis_index (int)

Return type:

int

config(basis_index)

Parameters:

basis_index (int)

Return type:

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

get_index(code)

Parameters:

code (int)

Return type:

int | None

require_index(code)

Parameters:

code (int)

Return type:

int

to_array_basis()

Return type:

Basis

__init__(layout, codes, index)

Parameters:

• layout (VariableLayout)

• codes (ndarray[tuple[Any, ...], dtype[object_]])

• index (dict[int, int])

Return type:

None

qlinks.encoded.bitmask_builder module

class qlinks.encoded.bitmask_builder.BitmaskSparseBuildStats(n_basis: 'int', n_terms: 'int', n_raw_actions: 'int', n_kept_actions: 'int', n_missing_actions: 'int', nnz: 'int')

Bases: object

Parameters:

• n_basis (int)

• n_terms (int)

• n_raw_actions (int)

• n_kept_actions (int)

• n_missing_actions (int)

• nnz (int)

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

Parameters:

• n_basis (int)

• n_terms (int)

• n_raw_actions (int)

• n_kept_actions (int)

• n_missing_actions (int)

• nnz (int)

Return type:

None

class qlinks.encoded.bitmask_builder.BitmaskSparseBuildResult(matrix: 'Any', stats: 'BitmaskSparseBuildStats')

Bases: object

Parameters:

• matrix (Any)

• stats (BitmaskSparseBuildStats)

matrix: Any

stats: BitmaskSparseBuildStats

__init__(matrix, stats)

Parameters:

• matrix (Any)

• stats (BitmaskSparseBuildStats)

Return type:

None

class qlinks.encoded.bitmask_builder.BitmaskSparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Bases: object

Sparse Hamiltonian builder for BinaryEncodedBasis.

This avoids constructing NumPy config arrays during matrix assembly.

Parameters:

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

dtype: DTypeLike

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

Return type:

Any

build_with_stats(basis, operators)

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

Return type:

BitmaskSparseBuildResult

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Parameters:

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

Return type:

None

qlinks.encoded.bitmask_builder.build_bitmask_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

Return type:

Any

qlinks.encoded.bitmask_operators module

class qlinks.encoded.bitmask_operators.BitmaskAction(coefficient: 'complex', code: 'int')

Bases: object

Parameters:

• coefficient (complex)

• code (int)

coefficient: complex

code: int

__init__(coefficient, code)

Parameters:

• coefficient (complex)

• code (int)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskOperator(*args, **kwargs)

Bases: Protocol

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(*args, **kwargs)

class qlinks.encoded.bitmask_operators.BitmaskDiagonalOperator(*args, **kwargs)

Bases: BitmaskOperator, Protocol

Configuration-space diagonal operator in binary bitmask encoding.

Returning None means the operator gives no diagonal contribution for this code. Returning a complex number means the operator contributes that diagonal matrix element.

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

class qlinks.encoded.bitmask_operators.BitmaskSingleActionOperator(*args, **kwargs)

Bases: BitmaskOperator, Protocol

Operator that produces at most one non-diagonal action per input code.

Returning None means the operator has no action on this code. Returning (coefficient, new_code) means the operator contributes one matrix element without allocating a BitmaskAction.

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

class qlinks.encoded.bitmask_operators.BitmaskOperatorSum(terms: 'tuple[BitmaskOperator, ...]', name: 'str' = 'bitmask_operator_sum')

Bases: object

Parameters:

• terms (tuple[BitmaskOperator, ...])

• name (str)

terms: tuple[BitmaskOperator, ...]

name: str

classmethod from_terms(terms, name='bitmask_operator_sum')

Parameters:

• terms (Sequence[BitmaskOperator])

• name (str)

Return type:

BitmaskOperatorSum

affected_variables()

Return type:

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

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(terms, name='bitmask_operator_sum')

Parameters:

• terms (tuple[BitmaskOperator, ...])

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskConstantDiagonalOperator(layout: 'VariableLayout', coefficient: 'complex', name: 'str' = 'bitmask_constant_diagonal')

Bases: object

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

layout: VariableLayout

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, coefficient, name='bitmask_constant_diagonal')

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskBinaryFlipOperator(layout, variable_index, coefficient=1.0, name='bitmask_binary_flip')

Bases: object

Flip one binary variable using XOR:

code -> code ^ (1 << variable_index)

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

property flip_mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_index, coefficient=1.0, name='bitmask_binary_flip')

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskPXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, name='bitmask_pxp_spin_flip')

Bases: object

PXP constrained spin flip.

Flip site_id only when all neighboring sites are zero.

Since the encoded basis is binary, occupied_value is fixed to 1.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

name: str

property site_variable: int

property neighbor_mask: int

property flip_mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, name='bitmask_pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskPatternFlipOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='bitmask_pattern_flip')

Bases: object

General bitmask pattern transition.

If

code & mask == initial_bits

then replace the masked region with final_bits:

new_code = (code & ~mask) | final_bits

Parameters:

• layout (VariableLayout)

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

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

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

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

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

coefficient: complex

name: str

property mask: int

property initial_bits: int

property final_bits: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='bitmask_pattern_flip')

Parameters:

• layout (VariableLayout)

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

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

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

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskQDMFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qdm_flip')

Bases: object

Binary QDM plaquette flip:

1010 <-> 0101

The pattern order is the lattice plaquette link order.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qdm_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

class qlinks.encoded.bitmask_operators.BitmaskPatternDiagonalOperator(layout, variable_indices, pattern, coefficient=1.0, name='bitmask_pattern_diagonal')

Bases: object

Diagonal projector onto a local binary pattern.

If

code & mask == pattern_bits

then return

coefficient * |code>

Otherwise return no action.

This is useful for QDM/QLM flippability potentials.

Parameters:

• layout (VariableLayout)

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

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

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

coefficient: complex

name: str

property mask: int

property pattern_bits: int

affected_variables()

Return type:

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

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_indices, pattern, coefficient=1.0, name='bitmask_pattern_diagonal')

Parameters:

• layout (VariableLayout)

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

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

• coefficient (complex)

• name (str)

Return type:

None

qlinks.encoded.bitmask_operators.bitmask_qdm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Bitmask projectors onto QDM flippable plaquette patterns:

1010 and 0101

in the lattice plaquette link order.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

qlinks.encoded.bitmask_operators.binary_pattern_from_flux_pattern(flux_pattern)

Convert physical QLM flux values {-1, +1} to binary values {0, 1}.

Parameters:

flux_pattern (ndarray[tuple[Any, ...], dtype[int64]])

Return type:

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

qlinks.encoded.bitmask_operators.bitmask_qlm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Bitmask projectors for spin-1/2 QLM flippable flux plaquettes.

The physical QLM flippable flux patterns are the oriented plaquette boundary pattern and its negative. With binary convention

-1 -> 0 +1 -> 1

these become binary_pattern and 1 - binary_pattern.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

class qlinks.encoded.bitmask_operators.BitmaskQLMFluxFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qlm_flux_flip')

Bases: object

Spin-1/2 QLM plaquette ring exchange in binary flux encoding.

Physical convention:

-1 -> 0 +1 -> 1

The flippable QLM flux patterns are given by the plaquette orientation signs and their negatives.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qlm_flux_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

qlinks.encoded.bitmask_operators.bitmask_alternating_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

class qlinks.encoded.bitmask_operators.BitmaskAlternatingPlaquetteFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_alternating_plaquette_flip')

Bases: object

Generic binary alternating plaquette flip:

1010… <-> 0101…

Works for any even-length plaquette.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_alternating_plaquette_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

qlinks.encoded.flux module

qlinks.encoded.flux.flux_to_bit(value)

Encode spin-1/2 flux value as a bit.

-1 -> 0 +1 -> 1

Parameters:

value (int)

Return type:

int

qlinks.encoded.flux.bit_to_flux(value)

Decode bit as spin-1/2 flux.

0 -> -1 1 -> +1

Parameters:

value (int)

Return type:

int

qlinks.encoded.flux.flux_config_to_binary(config)

Parameters:

config (ArrayLike)

Return type:

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

qlinks.encoded.flux.binary_config_to_flux(config)

Parameters:

config (ArrayLike)

Return type:

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

qlinks.encoded.flux.flux_configs_to_binary(configs)

Parameters:

configs (ArrayLike)

Return type:

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

qlinks.encoded.flux.binary_layout_like_flux_layout(flux_layout)

Create a binary link-variable layout with the same number/order of link variables as a spin-half-flux layout.

This assumes the QLM layout is link-only and ordered by link id.

Parameters:

flux_layout (VariableLayout)

Return type:

VariableLayout

qlinks.encoded.flux.binary_encoded_basis_from_flux_basis(flux_basis, *, sort=False)

Convert a {-1,+1} flux Basis into a BinaryEncodedBasis using

-1 -> 0 +1 -> 1

Parameters:

• flux_basis (Basis)

• sort (bool)

Return type:

BinaryEncodedBasis

Module contents

class qlinks.encoded.BinaryEncodedBasis(layout, codes, index)

Bases: object

Basis represented by integer bit patterns.

This is the production-oriented binary fast path. It is useful for PXP, QDM, toric-code qubits, and any model whose variables are {0, 1}.

Parameters:

• layout (VariableLayout)

• codes (ndarray[tuple[Any, ...], dtype[object_]])

• index (dict[int, int])

layout: VariableLayout

codes: ndarray[tuple[Any, ...], dtype[object_]]

index: dict[int, int]

classmethod from_codes(layout, codes, *, sort=False)

Parameters:

• layout (VariableLayout)

• codes (Iterable[int])

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod from_configs(layout, configs, *, sort=False)

Parameters:

• layout (VariableLayout)

• configs (ArrayLike)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod from_basis(basis, *, sort=False)

Parameters:

• basis (Basis)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod full(layout, *, sort=True)

Parameters:

• layout (VariableLayout)

• sort (bool)

Return type:

BinaryEncodedBasis

classmethod empty(layout)

Parameters:

layout (VariableLayout)

Return type:

BinaryEncodedBasis

property n_states: int

property n_variables: int

code(basis_index)

Parameters:

basis_index (int)

Return type:

int

config(basis_index)

Parameters:

basis_index (int)

Return type:

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

get_index(code)

Parameters:

code (int)

Return type:

int | None

require_index(code)

Parameters:

code (int)

Return type:

int

to_array_basis()

Return type:

Basis

__init__(layout, codes, index)

Parameters:

• layout (VariableLayout)

• codes (ndarray[tuple[Any, ...], dtype[object_]])

• index (dict[int, int])

Return type:

None

class qlinks.encoded.BitmaskAction(coefficient: 'complex', code: 'int')

Bases: object

Parameters:

• coefficient (complex)

• code (int)

coefficient: complex

code: int

__init__(coefficient, code)

Parameters:

• coefficient (complex)

• code (int)

Return type:

None

class qlinks.encoded.BitmaskBinaryFlipOperator(layout, variable_index, coefficient=1.0, name='bitmask_binary_flip')

Bases: object

Flip one binary variable using XOR:

code -> code ^ (1 << variable_index)

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

property flip_mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_index, coefficient=1.0, name='bitmask_binary_flip')

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.BitmaskConstantDiagonalOperator(layout: 'VariableLayout', coefficient: 'complex', name: 'str' = 'bitmask_constant_diagonal')

Bases: object

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

layout: VariableLayout

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, coefficient, name='bitmask_constant_diagonal')

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.BitmaskDiagonalOperator(*args, **kwargs)

Bases: BitmaskOperator, Protocol

Configuration-space diagonal operator in binary bitmask encoding.

Returning None means the operator gives no diagonal contribution for this code. Returning a complex number means the operator contributes that diagonal matrix element.

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

class qlinks.encoded.BitmaskOperator(*args, **kwargs)

Bases: Protocol

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(*args, **kwargs)

class qlinks.encoded.BitmaskOperatorSum(terms: 'tuple[BitmaskOperator, ...]', name: 'str' = 'bitmask_operator_sum')

Bases: object

Parameters:

• terms (tuple[BitmaskOperator, ...])

• name (str)

terms: tuple[BitmaskOperator, ...]

name: str

classmethod from_terms(terms, name='bitmask_operator_sum')

Parameters:

• terms (Sequence[BitmaskOperator])

• name (str)

Return type:

BitmaskOperatorSum

affected_variables()

Return type:

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

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(terms, name='bitmask_operator_sum')

Parameters:

• terms (tuple[BitmaskOperator, ...])

• name (str)

Return type:

None

class qlinks.encoded.BitmaskSingleActionOperator(*args, **kwargs)

Bases: BitmaskOperator, Protocol

Operator that produces at most one non-diagonal action per input code.

Returning None means the operator has no action on this code. Returning (coefficient, new_code) means the operator contributes one matrix element without allocating a BitmaskAction.

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

class qlinks.encoded.BitmaskPatternFlipOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='bitmask_pattern_flip')

Bases: object

General bitmask pattern transition.

If

code & mask == initial_bits

then replace the masked region with final_bits:

new_code = (code & ~mask) | final_bits

Parameters:

• layout (VariableLayout)

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

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

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

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

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

coefficient: complex

name: str

property mask: int

property initial_bits: int

property final_bits: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='bitmask_pattern_flip')

Parameters:

• layout (VariableLayout)

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

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

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

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.BitmaskPXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, name='bitmask_pxp_spin_flip')

Bases: object

PXP constrained spin flip.

Flip site_id only when all neighboring sites are zero.

Since the encoded basis is binary, occupied_value is fixed to 1.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

name: str

property site_variable: int

property neighbor_mask: int

property flip_mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, name='bitmask_pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.encoded.BitmaskQDMFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qdm_flip')

Bases: object

Binary QDM plaquette flip:

1010 <-> 0101

The pattern order is the lattice plaquette link order.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qdm_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

class qlinks.encoded.BitmaskSparseBuildResult(matrix: 'Any', stats: 'BitmaskSparseBuildStats')

Bases: object

Parameters:

• matrix (Any)

• stats (BitmaskSparseBuildStats)

matrix: Any

stats: BitmaskSparseBuildStats

__init__(matrix, stats)

Parameters:

• matrix (Any)

• stats (BitmaskSparseBuildStats)

Return type:

None

class qlinks.encoded.BitmaskSparseBuildStats(n_basis: 'int', n_terms: 'int', n_raw_actions: 'int', n_kept_actions: 'int', n_missing_actions: 'int', nnz: 'int')

Bases: object

Parameters:

• n_basis (int)

• n_terms (int)

• n_raw_actions (int)

• n_kept_actions (int)

• n_missing_actions (int)

• nnz (int)

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

Parameters:

• n_basis (int)

• n_terms (int)

• n_raw_actions (int)

• n_kept_actions (int)

• n_missing_actions (int)

• nnz (int)

Return type:

None

class qlinks.encoded.BitmaskSparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Bases: object

Sparse Hamiltonian builder for BinaryEncodedBasis.

This avoids constructing NumPy config arrays during matrix assembly.

Parameters:

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

dtype: DTypeLike

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

Return type:

Any

build_with_stats(basis, operators)

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

Return type:

BitmaskSparseBuildResult

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Parameters:

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

Return type:

None

qlinks.encoded.bitmask_from_indices(indices)

Parameters:

indices (Iterable[int])

Return type:

int

qlinks.encoded.build_bitmask_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Parameters:

• basis (BinaryEncodedBasis)

• operators (Sequence[BitmaskOperator])

• dtype (DTypeLike)

• on_missing (Literal['skip', 'raise'])

• drop_zero_atol (float)

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend)

Return type:

Any

qlinks.encoded.decode_binary_code(code, n_variables)

Decode Python int code back to binary config.

Parameters:

• code (int)

• n_variables (int)

Return type:

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

qlinks.encoded.encode_binary_config(config)

Encode binary config into a Python int.

bit i stores config[i].

Parameters:

config (ArrayLike)

Return type:

int

class qlinks.encoded.BitmaskPatternDiagonalOperator(layout, variable_indices, pattern, coefficient=1.0, name='bitmask_pattern_diagonal')

Bases: object

Diagonal projector onto a local binary pattern.

If

code & mask == pattern_bits

then return

coefficient * |code>

Otherwise return no action.

This is useful for QDM/QLM flippability potentials.

Parameters:

• layout (VariableLayout)

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

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

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

coefficient: complex

name: str

property mask: int

property pattern_bits: int

affected_variables()

Return type:

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

diagonal_value_code(code)

Parameters:

code (int)

Return type:

complex | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, variable_indices, pattern, coefficient=1.0, name='bitmask_pattern_diagonal')

Parameters:

• layout (VariableLayout)

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

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

• coefficient (complex)

• name (str)

Return type:

None

qlinks.encoded.bitmask_qdm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Bitmask projectors onto QDM flippable plaquette patterns:

1010 and 0101

in the lattice plaquette link order.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

class qlinks.encoded.BitmaskQLMFluxFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qlm_flux_flip')

Bases: object

Spin-1/2 QLM plaquette ring exchange in binary flux encoding.

Physical convention:

-1 -> 0 +1 -> 1

The flippable QLM flux patterns are given by the plaquette orientation signs and their negatives.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_qlm_flux_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

qlinks.encoded.bitmask_qlm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Bitmask projectors for spin-1/2 QLM flippable flux plaquettes.

The physical QLM flippable flux patterns are the oriented plaquette boundary pattern and its negative. With binary convention

-1 -> 0 +1 -> 1

these become binary_pattern and 1 - binary_pattern.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

qlinks.encoded.bitmask_alternating_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

class qlinks.encoded.BitmaskAlternatingPlaquetteFlipOperator(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_alternating_plaquette_flip')

Bases: object

Generic binary alternating plaquette flip:

1010… <-> 0101…

Works for any even-length plaquette.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

coefficient: complex

reverse_coefficient: complex | None

name: str

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

property mask: int

affected_variables()

Return type:

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

single_action_code(code)

Parameters:

code (int)

Return type:

tuple[complex, int] | None

apply_code(code)

Parameters:

code (int)

Return type:

tuple[BitmaskAction, …]

__init__(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None, name='bitmask_alternating_plaquette_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

• name (str)

Return type:

None

qlinks.encoded.binary_config_to_flux(config)

Parameters:

config (ArrayLike)

Return type:

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

qlinks.encoded.binary_encoded_basis_from_flux_basis(flux_basis, *, sort=False)

Convert a {-1,+1} flux Basis into a BinaryEncodedBasis using

-1 -> 0 +1 -> 1

Parameters:

• flux_basis (Basis)

• sort (bool)

Return type:

BinaryEncodedBasis

qlinks.encoded.binary_layout_like_flux_layout(flux_layout)

Create a binary link-variable layout with the same number/order of link variables as a spin-half-flux layout.

This assumes the QLM layout is link-only and ordered by link id.

Parameters:

flux_layout (VariableLayout)

Return type:

VariableLayout

qlinks.encoded.bit_to_flux(value)

Decode bit as spin-1/2 flux.

0 -> -1 1 -> +1

Parameters:

value (int)

Return type:

int

qlinks.encoded.flux_config_to_binary(config)

Parameters:

config (ArrayLike)

Return type:

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

qlinks.encoded.flux_configs_to_binary(configs)

Parameters:

configs (ArrayLike)

Return type:

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

qlinks.encoded.flux_to_bit(value)

Encode spin-1/2 flux value as a bit.

-1 -> 0 +1 -> 1

Parameters:

value (int)

Return type:

int