qlinks.operators package

Submodules

qlinks.operators.base module

class qlinks.operators.base.OperatorAction(coefficient, config)

Bases: object

One operator action on one computational configuration.

coefficient:

Matrix element contributed by this action.

config:

Resulting configuration after the operator acts. For diagonal operators, this is usually a copy of the input config.

Parameters:

• coefficient (complex)

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

coefficient: complex

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

__init__(coefficient, config)

Parameters:

• coefficient (complex)

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

Return type:

None

class qlinks.operators.base.LocalOperator(*args, **kwargs)

Bases: Protocol

Interface for all configuration-space operators.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(*args, **kwargs)

class qlinks.operators.base.DiagonalLocalOperator(*args, **kwargs)

Bases: LocalOperator, Protocol

Configuration-space diagonal operator.

Returning None means the operator gives no action on this config. Returning a complex number means the operator contributes that diagonal matrix element.

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

class qlinks.operators.base.BaseLocalOperator

Bases: object

Convenience base class for configuration-space local operators.

Design rule

Concrete operators should precompute all geometry/layout-dependent data in __post_init__(), so apply() only performs cheap indexed array operations.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

class qlinks.operators.base.OperatorSum(terms, name='operator_sum')

Bases: object

Formal sum of local operators.

This is still only an action-level object. Sparse matrix construction is handled by the next layer.

Parameters:

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

• name (str)

terms: tuple[LocalOperator, ...]

name: str

classmethod from_terms(terms, name='operator_sum')

Parameters:

• terms (Sequence[LocalOperator])

• name (str)

Return type:

OperatorSum

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(terms, name='operator_sum')

Parameters:

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

• name (str)

Return type:

None

qlinks.operators.base.combine_duplicate_actions(actions, *, atol=0.0)

Combine actions that produce the same output configuration.

This is useful before sparse assembly when two terms lead to the same row/column matrix element.

Parameters:

• actions (Sequence[OperatorAction])

• atol (float)

Return type:

tuple[OperatorAction, …]

qlinks.operators.diagonal module

class qlinks.operators.diagonal.ConstantDiagonalOperator(layout, coefficient, name='constant_diagonal')

Bases: BaseLocalOperator

Diagonal operator c * I.

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

layout: VariableLayout

coefficient: complex

name: str

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.diagonal.LocalValueDiagonalOperator(layout, variable_index, coefficient=1.0, name='local_value_diagonal')

Bases: BaseLocalOperator

Diagonal operator proportional to one variable value.

coefficient * config[variable_index]

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.diagonal.LocalSquareValueDiagonalOperator(layout, variable_index, coefficient=1.0, name='local_square_value_diagonal')

Bases: BaseLocalOperator

Diagonal operator proportional to one squared variable value.

coefficient * config[variable_index] ** 2

For spin-1 variables m in {-1, 0, +1}, this represents coefficient * (S^z)^2 in the S^z product basis.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.diagonal.LocalSumDiagonalOperator(layout, variable_indices, weights=None, coefficient=1.0, name='local_sum_diagonal')

Bases: BaseLocalOperator

Diagonal operator

coefficient * sum_i weights[i] * config[variable_indices[i]]

Parameters:

• layout (VariableLayout)

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

• weights (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficient (complex)

• name (str)

layout: VariableLayout

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

weights: ndarray[tuple[Any, ...], dtype[int64]] | None

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, weights=None, coefficient=1.0, name='local_sum_diagonal')

Parameters:

• layout (VariableLayout)

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

• weights (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.diagonal.PatternDiagonalOperator(layout, variable_indices, pattern, coefficient=1.0, name='pattern_diagonal')

Bases: BaseLocalOperator

Diagonal projector-like operator.

If selected variables match pattern, return coefficient * config. Otherwise return no action.

Example

A flippability counter for a plaquette can be represented as a sum of pattern diagonal operators.

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

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, pattern, coefficient=1.0, name='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.operators.plaquette module

class qlinks.operators.plaquette.PlaquettePatternTransition(initial, final, coefficient=1.0)

Bases: object

One allowed plaquette pattern transition.

initial:

Values on plaquette links before the operator acts.

final:

Values on plaquette links after the operator acts.

coefficient:

Matrix element for this transition.

Parameters:

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

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

• coefficient (complex)

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

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

coefficient: complex

__init__(initial, final, coefficient=1.0)

Parameters:

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

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

• coefficient (complex)

Return type:

None

class qlinks.operators.plaquette.PlaquettePatternOperator(layout, lattice, plaquette_id, transitions, name='plaquette_pattern')

Bases: BaseLocalOperator

General plaquette transition operator.

It reads the plaquette’s link variables in the lattice plaquette order. If the current values match one of the allowed transition patterns, it returns the corresponding new configuration.

This is suitable for QDM plaquette flips, constrained ring exchanges, and other local loop moves.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[PlaquettePatternTransition, ...])

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

transitions: tuple[PlaquettePatternTransition, ...]

name: str

classmethod qdm_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Standard binary dimer plaquette flip:

1010 <-> 0101

The order is the plaquette link order supplied by the lattice.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

PlaquettePatternOperator

classmethod alternating_binary_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

PlaquettePatternOperator

classmethod alternating_flux_flip(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

PlaquettePatternOperator

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, plaquette_id, transitions, name='plaquette_pattern')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[PlaquettePatternTransition, ...])

• name (str)

Return type:

None

qlinks.operators.plaquette.qdm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Return diagonal projectors onto the two flippable QDM plaquette patterns:

1010 and 0101

The potential term V * P_p^2 in a QDM-like model can be represented using these diagonal projectors.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.plaquette.alternating_binary_patterns(length)

Parameters:

length (int)

Return type:

tuple[ndarray, ndarray]

qlinks.operators.plaquette.alternating_flux_patterns(length)

Parameters:

length (int)

Return type:

tuple[ndarray, ndarray]

qlinks.operators.plaquette.alternating_binary_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.plaquette.alternating_flux_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.pxp module

class qlinks.operators.pxp.PXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='pxp_spin_flip')

Bases: BaseLocalOperator

Constrained spin flip for PXP/Rydberg-blockade models.

The spin at site_id is flipped only if all neighboring sites are not occupied.

With binary variables:

0 <-> 1

and usually:

occupied_value = 1

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

occupied_value: int

name: str

property site_variable: int

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

Return type:

None

qlinks.operators.transitions module

class qlinks.operators.transitions.SetVariablesOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='set_variables')

Bases: BaseLocalOperator

General local transition operator.

If

config[variable_indices] == initial_values

then produce a new config with

new_config[variable_indices] = final_values

Otherwise return no action.

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

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.operators.transitions.BinaryFlipOperator(layout, variable_index, coefficient=1.0, name='binary_flip')

Bases: BaseLocalOperator

Flip one binary variable 0 <-> 1.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_site(layout, site_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• site_id (int)

• coefficient (complex)

Return type:

BinaryFlipOperator

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

BinaryFlipOperator

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.transitions.NegationFlipOperator(layout, variable_index, coefficient=1.0, name='negation_flip')

Bases: BaseLocalOperator

Flip one sign variable v -> -v.

Useful for internal integer representation of spin-1/2 flux variables with values {-1, +1}.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

NegationFlipOperator

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.transitions.MultiNegationFlipOperator(layout, variable_indices, coefficient=1.0, name='multi_negation_flip')

Bases: BaseLocalOperator

Simultaneously apply v -> -v to several variables.

Useful as a simple QLM-like plaquette flip when the link variables are represented as {-1, +1}.

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

coefficient: complex

name: str

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, coefficient=1.0, name='multi_negation_flip')

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

Return type:

None

qlinks.operators.updates module

class qlinks.operators.updates.LocalUpdateAction(coefficient, variable_indices, new_values)

Bases: object

Compact operator action.

Instead of storing the full output configuration, store only

variable_indices new_values

The optimized sparse builder will reuse a scratch array:

scratch[:] = config scratch[variable_indices] = new_values

Parameters:

• coefficient (complex)

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

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

coefficient: complex

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

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

__init__(coefficient, variable_indices, new_values)

Parameters:

• coefficient (complex)

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

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

Return type:

None

class qlinks.operators.updates.LocalUpdateOperator(*args, **kwargs)

Bases: Protocol

Optimized local-operator protocol.

This protocol does not return a full new configuration. It returns only local updates.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(*args, **kwargs)

class qlinks.operators.updates.SingleLocalUpdateOperator(*args, **kwargs)

Bases: LocalUpdateOperator, Protocol

Local update operator with at most one action per input config.

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

class qlinks.operators.updates.BaseLocalUpdateOperator

Bases: object

layout: VariableLayout

name: str

affected_variables()

Return type:

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

class qlinks.operators.updates.UpdateOperatorSum(terms, name='update_operator_sum')

Bases: object

Sum of update-level local operators.

Parameters:

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

• name (str)

terms: tuple[LocalUpdateOperator, ...]

name: str

classmethod from_terms(terms, name='update_operator_sum')

Parameters:

• terms (Sequence[LocalUpdateOperator])

• name (str)

Return type:

UpdateOperatorSum

affected_variables()

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(terms, name='update_operator_sum')

Parameters:

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

• name (str)

Return type:

None

class qlinks.operators.updates.UpdateSetVariablesOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='update_set_variables')

Bases: BaseLocalUpdateOperator

Optimized version of SetVariablesOperator.

If config[variable_indices] == initial_values, return a local update setting those variables to final_values.

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

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

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.operators.updates.UpdateBinaryFlipOperator(layout, variable_index, coefficient=1.0, name='update_binary_flip')

Bases: BaseLocalUpdateOperator

Optimized binary flip 0 <-> 1.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_site(layout, site_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• site_id (int)

• coefficient (complex)

Return type:

UpdateBinaryFlipOperator

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

UpdateBinaryFlipOperator

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.updates.UpdateNegationFlipOperator(layout, variable_index, coefficient=1.0, name='update_negation_flip')

Bases: BaseLocalUpdateOperator

Optimized sign flip v -> -v.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

UpdateNegationFlipOperator

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.updates.UpdateMultiNegationFlipOperator(layout, variable_indices, coefficient=1.0, name='update_multi_negation_flip')

Bases: BaseLocalUpdateOperator

Optimized simultaneous sign flip on several variables.

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

coefficient: complex

name: str

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, variable_indices, coefficient=1.0, name='update_multi_negation_flip')

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.updates.UpdatePlaquettePatternTransition(initial: 'npt.NDArray[np.int64]', final: 'npt.NDArray[np.int64]', coefficient: 'complex' = 1.0)

Bases: object

Parameters:

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

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

• coefficient (complex)

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

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

coefficient: complex

__init__(initial, final, coefficient=1.0)

Parameters:

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

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

• coefficient (complex)

Return type:

None

class qlinks.operators.updates.UpdatePlaquettePatternOperator(layout, lattice, plaquette_id, transitions, name='update_plaquette_pattern')

Bases: BaseLocalUpdateOperator

Optimized plaquette-pattern transition operator.

This is the update-action version of PlaquettePatternOperator.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[UpdatePlaquettePatternTransition, ...])

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

transitions: tuple[UpdatePlaquettePatternTransition, ...]

name: str

classmethod qdm_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

UpdatePlaquettePatternOperator

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

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

affected_variables()

Return type:

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

property supports_single_update: bool

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, lattice, plaquette_id, transitions, name='update_plaquette_pattern')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[UpdatePlaquettePatternTransition, ...])

• name (str)

Return type:

None

class qlinks.operators.updates.UpdatePXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='update_pxp_spin_flip')

Bases: BaseLocalUpdateOperator

Optimized PXP constrained spin flip.

Flip site_id only if all neighbors are not occupied.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

occupied_value: int

name: str

property site_variable: int

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

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

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='update_pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

Return type:

None

Module contents

class qlinks.operators.BaseLocalOperator

Bases: object

Convenience base class for configuration-space local operators.

Design rule

Concrete operators should precompute all geometry/layout-dependent data in __post_init__(), so apply() only performs cheap indexed array operations.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

class qlinks.operators.BasisOperator(basis, operators, combine_duplicates=True, drop_zero_atol=0.0, dtype=<class 'numpy.complex128'>)

Bases: object

Matrix-like wrapper around configuration-space LocalOperator objects.

This object does not explicitly build the sparse matrix. Instead, it applies the local operators directly by looping over the basis states.

Examples

>>> O = BasisOperator(basis, operators)
>>> y = O @ v
>>> value = v.T @ O @ v
>>> value_complex = v.conj() @ O @ v
>>> y_t = O.T @ v
>>> y_h = O.H @ v

Parameters:

• basis (Basis)

• operators (tuple[LocalOperator, ...])

• combine_duplicates (bool)

• drop_zero_atol (float)

• dtype (DTypeLike)

basis: Basis

operators: tuple[LocalOperator, ...]

combine_duplicates: bool = True

drop_zero_atol: float = 0.0

dtype

alias of complex128

classmethod from_operator(basis, operator, **kwargs)

Parameters:

• basis (Basis)

• operator (LocalOperator)

Return type:

BasisOperator

property shape: tuple[int, int]

property T: TransposedBasisOperator

property H: TransposedBasisOperator

Hermitian adjoint view.

matvec(vector)

Compute self @ vector.

Parameters:

vector (ArrayLike)

Return type:

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

matmat(matrix)

Compute self @ matrix, where matrix has shape (n_basis, n_vecs).

Parameters:

matrix (ArrayLike)

Return type:

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

rmatvec(vector)

Compute vector @ self.

Parameters:

vector (ArrayLike)

Return type:

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

rmatmat(matrix)

Compute matrix @ self, where matrix has shape (n_vecs, n_basis).

Parameters:

matrix (ArrayLike)

Return type:

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

expectation(vector, *, conjugate=True)

Compute <v|O|v> by default.

If conjugate=False, compute v.T @ O @ v.

Parameters:

• vector (ArrayLike)

• conjugate (bool)

Return type:

complex

__init__(basis, operators, combine_duplicates=True, drop_zero_atol=0.0, dtype=<class 'numpy.complex128'>)

Parameters:

• basis (Basis)

• operators (tuple[LocalOperator, ...])

• combine_duplicates (bool)

• drop_zero_atol (float)

• dtype (DTypeLike)

Return type:

None

class qlinks.operators.BinaryFlipOperator(layout, variable_index, coefficient=1.0, name='binary_flip')

Bases: BaseLocalOperator

Flip one binary variable 0 <-> 1.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_site(layout, site_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• site_id (int)

• coefficient (complex)

Return type:

BinaryFlipOperator

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

BinaryFlipOperator

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.ConstantDiagonalOperator(layout, coefficient, name='constant_diagonal')

Bases: BaseLocalOperator

Diagonal operator c * I.

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

layout: VariableLayout

coefficient: complex

name: str

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.DiagonalLocalOperator(*args, **kwargs)

Bases: LocalOperator, Protocol

Configuration-space diagonal operator.

Returning None means the operator gives no action on this config. Returning a complex number means the operator contributes that diagonal matrix element.

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

class qlinks.operators.LocalOperator(*args, **kwargs)

Bases: Protocol

Interface for all configuration-space operators.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(*args, **kwargs)

class qlinks.operators.LocalSquareValueDiagonalOperator(layout, variable_index, coefficient=1.0, name='local_square_value_diagonal')

Bases: BaseLocalOperator

Diagonal operator proportional to one squared variable value.

coefficient * config[variable_index] ** 2

For spin-1 variables m in {-1, 0, +1}, this represents coefficient * (S^z)^2 in the S^z product basis.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.LocalSumDiagonalOperator(layout, variable_indices, weights=None, coefficient=1.0, name='local_sum_diagonal')

Bases: BaseLocalOperator

Diagonal operator

coefficient * sum_i weights[i] * config[variable_indices[i]]

Parameters:

• layout (VariableLayout)

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

• weights (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficient (complex)

• name (str)

layout: VariableLayout

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

weights: ndarray[tuple[Any, ...], dtype[int64]] | None

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, weights=None, coefficient=1.0, name='local_sum_diagonal')

Parameters:

• layout (VariableLayout)

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

• weights (ndarray[tuple[Any, ...], dtype[int64]] | None)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.LocalValueDiagonalOperator(layout, variable_index, coefficient=1.0, name='local_value_diagonal')

Bases: BaseLocalOperator

Diagonal operator proportional to one variable value.

coefficient * config[variable_index]

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.MultiNegationFlipOperator(layout, variable_indices, coefficient=1.0, name='multi_negation_flip')

Bases: BaseLocalOperator

Simultaneously apply v -> -v to several variables.

Useful as a simple QLM-like plaquette flip when the link variables are represented as {-1, +1}.

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

coefficient: complex

name: str

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, coefficient=1.0, name='multi_negation_flip')

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.NegationFlipOperator(layout, variable_index, coefficient=1.0, name='negation_flip')

Bases: BaseLocalOperator

Flip one sign variable v -> -v.

Useful for internal integer representation of spin-1/2 flux variables with values {-1, +1}.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

NegationFlipOperator

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.OperatorAction(coefficient, config)

Bases: object

One operator action on one computational configuration.

coefficient:

Matrix element contributed by this action.

config:

Resulting configuration after the operator acts. For diagonal operators, this is usually a copy of the input config.

Parameters:

• coefficient (complex)

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

coefficient: complex

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

__init__(coefficient, config)

Parameters:

• coefficient (complex)

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

Return type:

None

class qlinks.operators.OperatorSum(terms, name='operator_sum')

Bases: object

Formal sum of local operators.

This is still only an action-level object. Sparse matrix construction is handled by the next layer.

Parameters:

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

• name (str)

terms: tuple[LocalOperator, ...]

name: str

classmethod from_terms(terms, name='operator_sum')

Parameters:

• terms (Sequence[LocalOperator])

• name (str)

Return type:

OperatorSum

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(terms, name='operator_sum')

Parameters:

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

• name (str)

Return type:

None

class qlinks.operators.PXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='pxp_spin_flip')

Bases: BaseLocalOperator

Constrained spin flip for PXP/Rydberg-blockade models.

The spin at site_id is flipped only if all neighboring sites are not occupied.

With binary variables:

0 <-> 1

and usually:

occupied_value = 1

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

occupied_value: int

name: str

property site_variable: int

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

Return type:

None

class qlinks.operators.PatternDiagonalOperator(layout, variable_indices, pattern, coefficient=1.0, name='pattern_diagonal')

Bases: BaseLocalOperator

Diagonal projector-like operator.

If selected variables match pattern, return coefficient * config. Otherwise return no action.

Example

A flippability counter for a plaquette can be represented as a sum of pattern diagonal operators.

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

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex | None

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, variable_indices, pattern, coefficient=1.0, name='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

class qlinks.operators.PlaquettePatternOperator(layout, lattice, plaquette_id, transitions, name='plaquette_pattern')

Bases: BaseLocalOperator

General plaquette transition operator.

It reads the plaquette’s link variables in the lattice plaquette order. If the current values match one of the allowed transition patterns, it returns the corresponding new configuration.

This is suitable for QDM plaquette flips, constrained ring exchanges, and other local loop moves.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[PlaquettePatternTransition, ...])

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

transitions: tuple[PlaquettePatternTransition, ...]

name: str

classmethod qdm_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Standard binary dimer plaquette flip:

1010 <-> 0101

The order is the plaquette link order supplied by the lattice.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

PlaquettePatternOperator

classmethod alternating_binary_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

PlaquettePatternOperator

classmethod alternating_flux_flip(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

PlaquettePatternOperator

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, plaquette_id, transitions, name='plaquette_pattern')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[PlaquettePatternTransition, ...])

• name (str)

Return type:

None

class qlinks.operators.PlaquettePatternTransition(initial, final, coefficient=1.0)

Bases: object

One allowed plaquette pattern transition.

initial:

Values on plaquette links before the operator acts.

final:

Values on plaquette links after the operator acts.

coefficient:

Matrix element for this transition.

Parameters:

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

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

• coefficient (complex)

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

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

coefficient: complex

__init__(initial, final, coefficient=1.0)

Parameters:

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

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

• coefficient (complex)

Return type:

None

class qlinks.operators.SetVariablesOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='set_variables')

Bases: BaseLocalOperator

General local transition operator.

If

config[variable_indices] == initial_values

then produce a new config with

new_config[variable_indices] = final_values

Otherwise return no action.

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

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.operators.SpinOneXYBondOperator(layout, lattice, link_id, coefficient=1.0, name='spin_one_xy_bond')

Bases: BaseLocalOperator

Spin-1 XY bond operator on sites i,j.

H_ij = J_xy * (S^x_i S^x_j + S^y_i S^y_j)

= J_xy/2 * (S^+_i S^-_j + S^-_i S^+_j)

The computational basis is the S^z product basis with values:

m_i in {-1, 0, +1}

Parameters:

• layout (VariableLayout)

• lattice (ChainLattice)

• link_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: ChainLattice

link_id: int

coefficient: complex

name: str

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, link_id, coefficient=1.0, name='spin_one_xy_bond')

Parameters:

• layout (VariableLayout)

• lattice (ChainLattice)

• link_id (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.UpdateSpinOneXYBondOperator(layout, lattice, link_id, coefficient=1.0, name='update_spin_one_xy_bond')

Bases: BaseLocalUpdateOperator

Update-action version of SpinOneXYBondOperator.

The operator returns only local two-site updates instead of allocating full output configurations. It is intended for OptimizedSparseHamiltonianBuilder.

Parameters:

• layout (VariableLayout)

• lattice (ChainLattice)

• link_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: ChainLattice

link_id: int

coefficient: complex

name: str

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

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

affected_variables()

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, lattice, link_id, coefficient=1.0, name='update_spin_one_xy_bond')

Parameters:

• layout (VariableLayout)

• lattice (ChainLattice)

• link_id (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.TransposedBasisOperator(parent, conjugate=False)

Bases: object

Transpose or adjoint view of BasisOperator.

Parameters:

• parent (BasisOperator)

• conjugate (bool)

parent: BasisOperator

conjugate: bool = False

property shape: tuple[int, int]

property T: BasisOperator | TransposedBasisOperator

property H: BasisOperator

matvec(vector)

Compute A.T @ vector or A.H @ vector.

Parameters:

vector (ArrayLike)

Return type:

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

rmatvec(vector)

Compute vector @ A.T or vector @ A.H.

Parameters:

vector (ArrayLike)

Return type:

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

__init__(parent, conjugate=False)

Parameters:

• parent (BasisOperator)

• conjugate (bool)

Return type:

None

qlinks.operators.spin_one_lower_amplitude(m)

Spin-1 S^- amplitude.

S^- |m> = sqrt(S(S+1) - m(m-1)) |m-1>

for S=1 and m in {-1, 0, 1}.

Parameters:

m (int)

Return type:

float

qlinks.operators.spin_one_raise_amplitude(m)

Spin-1 S^+ amplitude.

S^+ |m> = sqrt(S(S+1) - m(m+1)) |m+1>

for S=1 and m in {-1, 0, 1}.

Parameters:

m (int)

Return type:

float

class qlinks.operators.ToricCodePlaquetteFluxOperator(layout, lattice, plaquette_id, coefficient=-1.0, name='toric_code_plaquette_flux')

Bases: BaseLocalOperator

Toric-code plaquette operator B_p in the Z basis.

It is diagonal:

B_p |z> = prod_{l in boundary(p)} z_l |z>

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• plaquette_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: SquareLattice

plaquette_id: int

coefficient: complex

name: str

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

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

affected_variables()

Return type:

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

diagonal_value(config)

Parameters:

config (ArrayLike)

Return type:

complex

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

__init__(layout, lattice, plaquette_id, coefficient=-1.0, name='toric_code_plaquette_flux')

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• plaquette_id (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.ToricCodeStarFlipOperator(layout, lattice, site_id, coefficient=-1.0, name='toric_code_star_flip')

Bases: BaseLocalOperator

Toric-code star operator A_v in the Z basis.

It flips all links incident on site v.

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• site_id (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

lattice: SquareLattice

site_id: int

coefficient: complex

name: str

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

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

affected_variables()

Return type:

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

apply(config)

Parameters:

config (ArrayLike)

Return type:

tuple[OperatorAction, …]

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

Parameters:

• layout (VariableLayout)

• lattice (SquareLattice)

• site_id (int)

• coefficient (complex)

• name (str)

Return type:

None

qlinks.operators.combine_duplicate_actions(actions, *, atol=0.0)

Combine actions that produce the same output configuration.

This is useful before sparse assembly when two terms lead to the same row/column matrix element.

Parameters:

• actions (Sequence[OperatorAction])

• atol (float)

Return type:

tuple[OperatorAction, …]

qlinks.operators.qdm_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Return diagonal projectors onto the two flippable QDM plaquette patterns:

1010 and 0101

The potential term V * P_p^2 in a QDM-like model can be represented using these diagonal projectors.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.as_basis_operator(basis, operators, **kwargs)

Convenience constructor.

Parameters:

• basis (Basis)

• operators (LocalOperator | Sequence[LocalOperator])

Return type:

BasisOperator

qlinks.operators.alternating_binary_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.alternating_binary_patterns(length)

Parameters:

length (int)

Return type:

tuple[ndarray, ndarray]

qlinks.operators.alternating_flux_flippability_projectors(layout, lattice, plaquette_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

Return type:

tuple[PatternDiagonalOperator, PatternDiagonalOperator]

qlinks.operators.alternating_flux_patterns(length)

Parameters:

length (int)

Return type:

tuple[ndarray, ndarray]

class qlinks.operators.BaseLocalUpdateOperator

Bases: object

layout: VariableLayout

name: str

affected_variables()

Return type:

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

class qlinks.operators.LocalUpdateAction(coefficient, variable_indices, new_values)

Bases: object

Compact operator action.

Instead of storing the full output configuration, store only

variable_indices new_values

The optimized sparse builder will reuse a scratch array:

scratch[:] = config scratch[variable_indices] = new_values

Parameters:

• coefficient (complex)

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

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

coefficient: complex

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

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

__init__(coefficient, variable_indices, new_values)

Parameters:

• coefficient (complex)

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

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

Return type:

None

class qlinks.operators.LocalUpdateOperator(*args, **kwargs)

Bases: Protocol

Optimized local-operator protocol.

This protocol does not return a full new configuration. It returns only local updates.

layout: VariableLayout

name: str

affected_variables()

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(*args, **kwargs)

class qlinks.operators.SingleLocalUpdateOperator(*args, **kwargs)

Bases: LocalUpdateOperator, Protocol

Local update operator with at most one action per input config.

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

class qlinks.operators.UpdateBinaryFlipOperator(layout, variable_index, coefficient=1.0, name='update_binary_flip')

Bases: BaseLocalUpdateOperator

Optimized binary flip 0 <-> 1.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_site(layout, site_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• site_id (int)

• coefficient (complex)

Return type:

UpdateBinaryFlipOperator

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

UpdateBinaryFlipOperator

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.UpdateMultiNegationFlipOperator(layout, variable_indices, coefficient=1.0, name='update_multi_negation_flip')

Bases: BaseLocalUpdateOperator

Optimized simultaneous sign flip on several variables.

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

layout: VariableLayout

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

coefficient: complex

name: str

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, variable_indices, coefficient=1.0, name='update_multi_negation_flip')

Parameters:

• layout (VariableLayout)

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

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.UpdateNegationFlipOperator(layout, variable_index, coefficient=1.0, name='update_negation_flip')

Bases: BaseLocalUpdateOperator

Optimized sign flip v -> -v.

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

layout: VariableLayout

variable_index: int

coefficient: complex

name: str

classmethod on_link(layout, link_id, coefficient=1.0)

Parameters:

• layout (VariableLayout)

• link_id (int)

• coefficient (complex)

Return type:

UpdateNegationFlipOperator

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

Parameters:

• layout (VariableLayout)

• variable_index (int)

• coefficient (complex)

• name (str)

Return type:

None

class qlinks.operators.UpdateOperatorSum(terms, name='update_operator_sum')

Bases: object

Sum of update-level local operators.

Parameters:

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

• name (str)

terms: tuple[LocalUpdateOperator, ...]

name: str

classmethod from_terms(terms, name='update_operator_sum')

Parameters:

• terms (Sequence[LocalUpdateOperator])

• name (str)

Return type:

UpdateOperatorSum

affected_variables()

Return type:

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

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(terms, name='update_operator_sum')

Parameters:

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

• name (str)

Return type:

None

class qlinks.operators.UpdatePXPSpinFlipOperator(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='update_pxp_spin_flip')

Bases: BaseLocalUpdateOperator

Optimized PXP constrained spin flip.

Flip site_id only if all neighbors are not occupied.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

layout: VariableLayout

lattice: LatticeGraph

site_id: int

coefficient: complex

occupied_value: int

name: str

property site_variable: int

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

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

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, lattice, site_id, coefficient=1.0, occupied_value=1, name='update_pxp_spin_flip')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• site_id (int)

• coefficient (complex)

• occupied_value (int)

• name (str)

Return type:

None

class qlinks.operators.UpdatePlaquettePatternOperator(layout, lattice, plaquette_id, transitions, name='update_plaquette_pattern')

Bases: BaseLocalUpdateOperator

Optimized plaquette-pattern transition operator.

This is the update-action version of PlaquettePatternOperator.

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[UpdatePlaquettePatternTransition, ...])

• name (str)

layout: VariableLayout

lattice: LatticeGraph

plaquette_id: int

transitions: tuple[UpdatePlaquettePatternTransition, ...]

name: str

classmethod qdm_flip(layout, lattice, plaquette_id, coefficient=1.0, reverse_coefficient=None)

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• coefficient (complex)

• reverse_coefficient (complex | None)

Return type:

UpdatePlaquettePatternOperator

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

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

affected_variables()

Return type:

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

property supports_single_update: bool

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

__init__(layout, lattice, plaquette_id, transitions, name='update_plaquette_pattern')

Parameters:

• layout (VariableLayout)

• lattice (LatticeGraph)

• plaquette_id (int)

• transitions (tuple[UpdatePlaquettePatternTransition, ...])

• name (str)

Return type:

None

class qlinks.operators.UpdatePlaquettePatternTransition(initial: 'npt.NDArray[np.int64]', final: 'npt.NDArray[np.int64]', coefficient: 'complex' = 1.0)

Bases: object

Parameters:

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

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

• coefficient (complex)

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

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

coefficient: complex

__init__(initial, final, coefficient=1.0)

Parameters:

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

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

• coefficient (complex)

Return type:

None

class qlinks.operators.UpdateSetVariablesOperator(layout, variable_indices, initial_values, final_values, coefficient=1.0, name='update_set_variables')

Bases: BaseLocalUpdateOperator

Optimized version of SetVariablesOperator.

If config[variable_indices] == initial_values, return a local update setting those variables to final_values.

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

affected_variables()

Return type:

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

single_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[complex, ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]] | None

apply_update(config)

Parameters:

config (ArrayLike)

Return type:

tuple[LocalUpdateAction, …]

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

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