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].

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

Decode Python int code back to binary config.

qlinks.encoded.binary_basis.bitmask_from_indices(indices)

Return an integer mask with bits set at the requested indices.

Parameters:

indices (Iterable[int]) – Nonnegative bit positions.

Returns:

Integer bitmask.

Raises:

ValueError – If any bit index is negative.

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}.

layout: VariableLayout

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

index: dict[int, int]

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

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

classmethod from_basis(basis, *, sort=False)

classmethod full(layout, *, sort=True)

classmethod empty(layout)

property n_states: int

property n_variables: int

code(basis_index)

config(basis_index)

get_index(code)

require_index(code)

to_array_basis()

__init__(layout, codes, index)

qlinks.encoded.bitmask_builder module

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

Bases: object

Counters collected by BitmaskSparseHamiltonianBuilder.

n_basis

Number of encoded basis states.

Type:

int

n_terms

Number of bitmask operators.

Type:

int

n_raw_actions

Number of raw bitmask actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target code was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after sparse assembly.

Type:

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)

class qlinks.encoded.bitmask_builder.BitmaskSparseBuildResult(matrix, stats)

Bases: object

Bitmask sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the bitmask build.

Type:

qlinks.encoded.bitmask_builder.BitmaskSparseBuildStats

matrix: Any

stats: BitmaskSparseBuildStats

__init__(matrix, stats)

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

Bases: object

Sparse builder for BinaryEncodedBasis.

Bitmask operators act directly on integer-encoded configurations, avoiding NumPy configuration arrays in the matrix-assembly hot loop.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the encoded basis.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

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

drop_zero_atol: float

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

build(basis, operators)

build_with_stats(basis, operators)

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

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

Build a sparse Hamiltonian from bitmask operators.

Parameters:

• basis (BinaryEncodedBasis) – Encoded basis that fixes matrix row/column order.

• operators (Sequence[BitmaskOperator]) – Bitmask operators to sum.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the encoded basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.encoded.bitmask_operators module

class qlinks.encoded.bitmask_operators.BitmaskAction(coefficient, code)

Bases: object

One encoded-basis matrix action.

coefficient

Matrix element coefficient.

Type:

complex

code

Target encoded configuration.

Type:

int

coefficient: complex

code: int

__init__(coefficient, code)

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

Bases: Protocol

Protocol for operators acting on integer-encoded binary states.

layout: VariableLayout

name: str

affected_variables()

apply_code(code)

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

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)

class qlinks.encoded.bitmask_operators.BitmaskOperatorSum(terms, name='bitmask_operator_sum')

Bases: object

Sum of bitmask operators presented as one operator.

terms

Bitmask operators to apply and concatenate.

Type:

tuple[qlinks.encoded.bitmask_operators.BitmaskOperator, …]

name

Human-readable operator name.

Type:

str

terms: tuple[BitmaskOperator, ...]

name: str

classmethod from_terms(terms, name='bitmask_operator_sum')

affected_variables()

apply_code(code)

__init__(terms, name='bitmask_operator_sum')

class qlinks.encoded.bitmask_operators.BitmaskConstantDiagonalOperator(layout, coefficient, name='bitmask_constant_diagonal')

Bases: object

Constant diagonal operator in bitmask representation.

layout

Binary variable layout.

Type:

qlinks.variables.layout.VariableLayout

coefficient

Constant diagonal matrix element.

Type:

complex

name

Human-readable operator name.

Type:

str

layout: VariableLayout

coefficient: complex

name: str

affected_variables()

diagonal_value_code(code)

apply_code(code)

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

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)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

property flip_mask: int

affected_variables()

single_action_code(code)

apply_code(code)

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

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.

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

single_action_code(code)

apply_code(code)

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

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

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

single_action_code(code)

apply_code(code)

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

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.

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

single_action_code(code)

apply_code(code)

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

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.

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

diagonal_value_code(code)

apply_code(code)

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

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.

qlinks.encoded.bitmask_operators.binary_pattern_from_flux_pattern(flux_pattern)

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

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.

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.

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

single_action_code(code)

apply_code(code)

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

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

Return the two alternating-pattern projectors for a binary plaquette.

Parameters:

• layout (VariableLayout) – Binary variable layout.

• lattice (LatticeGraph) – Lattice containing the plaquette.

• plaquette_id (int) – Plaquette id.

• coefficient (complex) – Diagonal coefficient for each projector.

Returns:

Pair of bitmask diagonal projectors onto the two alternating patterns.

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.

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

single_action_code(code)

apply_code(code)

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

qlinks.encoded.flux module

qlinks.encoded.flux.flux_to_bit(value)

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

-1 -> 0 +1 -> 1

qlinks.encoded.flux.bit_to_flux(value)

Decode bit as spin-1/2 flux.

0 -> -1 1 -> +1

qlinks.encoded.flux.flux_config_to_binary(config)

Convert a {-1, +1} flux configuration to binary {0, 1}.

Parameters:

config (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Flux configuration.

Returns:

Binary configuration with -1 -> 0 and +1 -> 1.

Return type:

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

qlinks.encoded.flux.binary_config_to_flux(config)

Convert a binary {0, 1} configuration to flux {-1, +1}.

Parameters:

config (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Binary configuration.

Returns:

Flux configuration with 0 -> -1 and 1 -> +1.

Return type:

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

qlinks.encoded.flux.flux_configs_to_binary(configs)

Convert a stack of flux configurations to binary configurations.

Parameters:

configs (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Array whose final axis contains flux values {-1, +1}.

Returns:

Array of the same shape with binary values {0, 1}.

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.

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

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}.

layout: VariableLayout

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

index: dict[int, int]

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

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

classmethod from_basis(basis, *, sort=False)

classmethod full(layout, *, sort=True)

classmethod empty(layout)

property n_states: int

property n_variables: int

code(basis_index)

config(basis_index)

get_index(code)

require_index(code)

to_array_basis()

__init__(layout, codes, index)

class qlinks.encoded.BitmaskAction(coefficient, code)

Bases: object

One encoded-basis matrix action.

coefficient

Matrix element coefficient.

Type:

complex

code

Target encoded configuration.

Type:

int

coefficient: complex

code: int

__init__(coefficient, code)

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.

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

single_action_code(code)

apply_code(code)

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

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)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

property flip_mask: int

affected_variables()

single_action_code(code)

apply_code(code)

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

class qlinks.encoded.BitmaskConstantDiagonalOperator(layout, coefficient, name='bitmask_constant_diagonal')

Bases: object

Constant diagonal operator in bitmask representation.

layout

Binary variable layout.

Type:

qlinks.variables.layout.VariableLayout

coefficient

Constant diagonal matrix element.

Type:

complex

name

Human-readable operator name.

Type:

str

layout: VariableLayout

coefficient: complex

name: str

affected_variables()

diagonal_value_code(code)

apply_code(code)

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

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)

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

Bases: Protocol

Protocol for operators acting on integer-encoded binary states.

layout: VariableLayout

name: str

affected_variables()

apply_code(code)

__init__(*args, **kwargs)

class qlinks.encoded.BitmaskOperatorSum(terms, name='bitmask_operator_sum')

Bases: object

Sum of bitmask operators presented as one operator.

terms

Bitmask operators to apply and concatenate.

Type:

tuple[qlinks.encoded.bitmask_operators.BitmaskOperator, …]

name

Human-readable operator name.

Type:

str

terms: tuple[BitmaskOperator, ...]

name: str

classmethod from_terms(terms, name='bitmask_operator_sum')

affected_variables()

apply_code(code)

__init__(terms, name='bitmask_operator_sum')

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.

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

single_action_code(code)

apply_code(code)

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

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.

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

diagonal_value_code(code)

apply_code(code)

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

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

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

single_action_code(code)

apply_code(code)

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

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.

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

single_action_code(code)

apply_code(code)

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

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.

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

single_action_code(code)

apply_code(code)

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

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)

class qlinks.encoded.BitmaskSparseBuildResult(matrix, stats)

Bases: object

Bitmask sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the bitmask build.

Type:

qlinks.encoded.bitmask_builder.BitmaskSparseBuildStats

matrix: Any

stats: BitmaskSparseBuildStats

__init__(matrix, stats)

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

Bases: object

Counters collected by BitmaskSparseHamiltonianBuilder.

n_basis

Number of encoded basis states.

Type:

int

n_terms

Number of bitmask operators.

Type:

int

n_raw_actions

Number of raw bitmask actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target code was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after sparse assembly.

Type:

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)

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

Bases: object

Sparse builder for BinaryEncodedBasis.

Bitmask operators act directly on integer-encoded configurations, avoiding NumPy configuration arrays in the matrix-assembly hot loop.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the encoded basis.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

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

drop_zero_atol: float

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

build(basis, operators)

build_with_stats(basis, operators)

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

qlinks.encoded.binary_config_to_flux(config)

Convert a binary {0, 1} configuration to flux {-1, +1}.

Parameters:

config (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Binary configuration.

Returns:

Flux configuration with 0 -> -1 and 1 -> +1.

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

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.

qlinks.encoded.binary_pattern_from_flux_pattern(flux_pattern)

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

qlinks.encoded.bit_to_flux(value)

Decode bit as spin-1/2 flux.

0 -> -1 1 -> +1

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

Return the two alternating-pattern projectors for a binary plaquette.

Parameters:

• layout (VariableLayout) – Binary variable layout.

• lattice (LatticeGraph) – Lattice containing the plaquette.

• plaquette_id (int) – Plaquette id.

• coefficient (complex) – Diagonal coefficient for each projector.

Returns:

Pair of bitmask diagonal projectors onto the two alternating patterns.

Return type:

tuple[BitmaskPatternDiagonalOperator, BitmaskPatternDiagonalOperator]

qlinks.encoded.bitmask_from_indices(indices)

Return an integer mask with bits set at the requested indices.

Parameters:

indices (Iterable[int]) – Nonnegative bit positions.

Returns:

Integer bitmask.

Raises:

ValueError – If any bit index is negative.

Return type:

int

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.

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.

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

Build a sparse Hamiltonian from bitmask operators.

Parameters:

• basis (BinaryEncodedBasis) – Encoded basis that fixes matrix row/column order.

• operators (Sequence[BitmaskOperator]) – Bitmask operators to sum.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the encoded basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.encoded.decode_binary_code(code, n_variables)

Decode Python int code back to binary config.

qlinks.encoded.encode_binary_config(config)

Encode binary config into a Python int.

bit i stores config[i].

qlinks.encoded.flux_config_to_binary(config)

Convert a {-1, +1} flux configuration to binary {0, 1}.

Parameters:

config (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Flux configuration.

Returns:

Binary configuration with -1 -> 0 and +1 -> 1.

Return type:

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

qlinks.encoded.flux_configs_to_binary(configs)

Convert a stack of flux configurations to binary configurations.

Parameters:

configs (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Array whose final axis contains flux values {-1, +1}.

Returns:

Array of the same shape with binary values {0, 1}.

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