qlinks.variables package

Submodules

qlinks.variables.config module

class qlinks.variables.config.ConfigView(layout, array)

Bases: object

Lightweight read/write wrapper around a NumPy configuration array.

This is useful for readable operator code:

cfg.link(3) cfg.set_link(3, -cfg.link(3))

The underlying array is still a normal NumPy array.

Parameters:

• layout (VariableLayout)

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

layout: VariableLayout

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

classmethod from_array(layout, array)

Parameters:

• layout (VariableLayout)

• array (ArrayLike)

Return type:

ConfigView

classmethod default(layout)

Parameters:

layout (VariableLayout)

Return type:

ConfigView

copy()

Return type:

ConfigView

value(variable_index)

Parameters:

variable_index (int)

Return type:

int

set_value(variable_index, value)

Parameters:

• variable_index (int)

• value (int)

Return type:

None

site(site_index)

Parameters:

site_index (int)

Return type:

int

link(link_index)

Parameters:

link_index (int)

Return type:

int

set_site(site_index, value)

Parameters:

• site_index (int)

• value (int)

Return type:

None

set_link(link_index, value)

Parameters:

• link_index (int)

• value (int)

Return type:

None

flipped(variable_index)

Return a new config with a binary variable flipped.

This only works for variables with local values {0, 1}. For QLM flux variables {-1, +1}, use negated().

Parameters:

variable_index (int)

Return type:

ConfigView

negated(variable_index)

Return a new config with one variable multiplied by -1.

This is useful for spin-1/2 QLM flux variables {-1, +1}.

Parameters:

variable_index (int)

Return type:

ConfigView

as_array(copy=True)

Parameters:

copy (bool)

Return type:

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

__init__(layout, array)

Parameters:

• layout (VariableLayout)

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

Return type:

None

qlinks.variables.encoding module

class qlinks.variables.encoding.ConfigEncoder(layout)

Bases: object

Encode configurations into hashable keys for basis lookup.

The default key is bytes from a canonical int64 representation. This is not always the most compressed representation, but it is robust for mixed site/link variables and arbitrary integer local values.

Later, for spin-1/2-only models, this can be supplemented by a bit-packed encoder.

Parameters:

layout (VariableLayout)

layout: VariableLayout

encode(config, *, validate=True)

Parameters:

• config (ArrayLike)

• validate (bool)

Return type:

bytes

decode(key, *, validate=True)

Parameters:

• key (bytes)

• validate (bool)

Return type:

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

build_index(configs, *, validate=True)

Parameters:

• configs (Iterable[ArrayLike])

• validate (bool)

Return type:

dict[bytes, int]

__init__(layout)

Parameters:

layout (VariableLayout)

Return type:

None

class qlinks.variables.encoding.BitPackedBinaryEncoder(layout)

Bases: object

Compact encoder for pure binary layouts with local values {0, 1}.

This is useful for PXP, toric-code qubits, or dimer occupation variables.

It intentionally does not support {-1, +1} directly. For QLM flux variables, either use ConfigEncoder or convert values to binary codes first.

Parameters:

layout (VariableLayout)

layout: VariableLayout

encode(config, *, validate=True)

Parameters:

• config (ArrayLike)

• validate (bool)

Return type:

bytes

decode(key, *, validate=True)

Parameters:

• key (bytes)

• validate (bool)

Return type:

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

__init__(layout)

Parameters:

layout (VariableLayout)

Return type:

None

qlinks.variables.layout module

class qlinks.variables.layout.VariableKind(*values)

Bases: StrEnum

SITE = 'site'

LINK = 'link'

class qlinks.variables.layout.HasSiteLinkCounts(*args, **kwargs)

Bases: Protocol

Minimal protocol expected from the future lattice layer.

A concrete lattice does not need to inherit from this protocol. It only needs to expose num_sites and/or num_links.

num_sites: int

num_links: int

__init__(*args, **kwargs)

class qlinks.variables.layout.VariableSpec(kind, geometry_index, local_space)

Bases: object

One variable in the flattened configuration array.

kind:

Whether this variable lives on a site or link.

geometry_index:

Site index or link index in the lattice layer.

local_space:

Allowed values for this variable.

Parameters:

• kind (VariableKind)

• geometry_index (int)

• local_space (LocalSpace)

kind: VariableKind

geometry_index: int

local_space: LocalSpace

__init__(kind, geometry_index, local_space)

Parameters:

• kind (VariableKind)

• geometry_index (int)

• local_space (LocalSpace)

Return type:

None

class qlinks.variables.layout.VariableLayout(specs)

Bases: object

Map physical site/link variables to positions in a compact NumPy config array.

The computational basis state is represented as

config[var_index]

This class tells us which var_index corresponds to which site/link variable.

Parameters:

specs (tuple[VariableSpec, ...])

specs: tuple[VariableSpec, ...]

classmethod from_sites(num_sites, local_space)

Parameters:

• num_sites (int)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_links(num_links, local_space)

Parameters:

• num_links (int)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_sites_and_links(num_sites, site_space, num_links, link_space)

Parameters:

• num_sites (int)

• site_space (LocalSpace)

• num_links (int)

• link_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_sites(lattice, local_space)

Parameters:

• lattice (HasSiteLinkCounts)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_links(lattice, local_space)

Parameters:

• lattice (HasSiteLinkCounts)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_sites_and_links(lattice, site_space, link_space)

Parameters:

• lattice (HasSiteLinkCounts)

• site_space (LocalSpace)

• link_space (LocalSpace)

Return type:

VariableLayout

property n_variables: int

property shape: tuple[int]

spec(variable_index)

Parameters:

variable_index (int)

Return type:

VariableSpec

local_space(variable_index)

Parameters:

variable_index (int)

Return type:

LocalSpace

variable_index(kind, geometry_index)

Parameters:

• kind (VariableKind | str)

• geometry_index (int)

Return type:

int

site_variable_index(site_index)

Parameters:

site_index (int)

Return type:

int

link_variable_index(link_index)

Parameters:

link_index (int)

Return type:

int

site_variable_indices()

Return type:

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

link_variable_indices()

Return type:

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

empty_config(fill_value=0)

Parameters:

fill_value (int)

Return type:

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

default_config()

Return a valid default configuration.

For each variable, choose the first value in its local space.

Return type:

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

validate_config(config)

Parameters:

config (ArrayLike)

Return type:

None

validate_batch(configs)

Parameters:

configs (ArrayLike)

Return type:

None

as_metadata()

Small serializable summary useful for debugging or future IO.

Return type:

dict[str, Any]

__init__(specs)

Parameters:

specs (tuple[VariableSpec, ...])

Return type:

None

qlinks.variables.local_space module

class qlinks.variables.local_space.LocalSpace(values)

Bases: object

Finite local Hilbert/configuration space for one physical variable.

Examples

Spin-1/2 site:

values = [0, 1]

QLM spin-1/2 electric field:

values = [-1, 1]

Dimer occupation:

values = [0, 1]

Parameters:

values (ndarray[tuple[Any, ...], dtype[integer]])

values: ndarray[tuple[Any, ...], dtype[integer]]

classmethod from_values(values)

Parameters:

values (Iterable[int])

Return type:

LocalSpace

classmethod binary()

Local two-state variable with values {0, 1}.

Return type:

LocalSpace

classmethod spin_half_flux()

Spin-1/2 QLM-like electric flux variable.

This uses integer values {-1, +1}; if you prefer physical values {-1/2, +1/2}, keep this integer representation internally and divide by 2 only when evaluating physical observables.

Return type:

LocalSpace

classmethod spin_one()

Spin-1 local variable with S^z values {-1, 0, +1}.

Return type:

LocalSpace

property dim: int

property dtype: dtype

contains(value)

Parameters:

value (int)

Return type:

bool

validate_value(value)

Parameters:

value (int)

Return type:

None

validate_array(array)

Parameters:

array (ArrayLike)

Return type:

None

value_to_code(value)

Convert a physical local value to a dense integer code 0, …, dim - 1.

Parameters:

value (int)

Return type:

int

code_to_value(code)

Convert a dense integer code 0, …, dim - 1 back to the physical value.

Parameters:

code (int)

Return type:

int

__init__(values)

Parameters:

values (ndarray[tuple[Any, ...], dtype[integer]])

Return type:

None

Module contents

class qlinks.variables.BitPackedBinaryEncoder(layout)

Bases: object

Compact encoder for pure binary layouts with local values {0, 1}.

This is useful for PXP, toric-code qubits, or dimer occupation variables.

It intentionally does not support {-1, +1} directly. For QLM flux variables, either use ConfigEncoder or convert values to binary codes first.

Parameters:

layout (VariableLayout)

layout: VariableLayout

encode(config, *, validate=True)

Parameters:

• config (ArrayLike)

• validate (bool)

Return type:

bytes

decode(key, *, validate=True)

Parameters:

• key (bytes)

• validate (bool)

Return type:

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

__init__(layout)

Parameters:

layout (VariableLayout)

Return type:

None

class qlinks.variables.ConfigEncoder(layout)

Bases: object

Encode configurations into hashable keys for basis lookup.

The default key is bytes from a canonical int64 representation. This is not always the most compressed representation, but it is robust for mixed site/link variables and arbitrary integer local values.

Later, for spin-1/2-only models, this can be supplemented by a bit-packed encoder.

Parameters:

layout (VariableLayout)

layout: VariableLayout

encode(config, *, validate=True)

Parameters:

• config (ArrayLike)

• validate (bool)

Return type:

bytes

decode(key, *, validate=True)

Parameters:

• key (bytes)

• validate (bool)

Return type:

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

build_index(configs, *, validate=True)

Parameters:

• configs (Iterable[ArrayLike])

• validate (bool)

Return type:

dict[bytes, int]

__init__(layout)

Parameters:

layout (VariableLayout)

Return type:

None

class qlinks.variables.ConfigView(layout, array)

Bases: object

Lightweight read/write wrapper around a NumPy configuration array.

This is useful for readable operator code:

cfg.link(3) cfg.set_link(3, -cfg.link(3))

The underlying array is still a normal NumPy array.

Parameters:

• layout (VariableLayout)

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

layout: VariableLayout

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

classmethod from_array(layout, array)

Parameters:

• layout (VariableLayout)

• array (ArrayLike)

Return type:

ConfigView

classmethod default(layout)

Parameters:

layout (VariableLayout)

Return type:

ConfigView

copy()

Return type:

ConfigView

value(variable_index)

Parameters:

variable_index (int)

Return type:

int

set_value(variable_index, value)

Parameters:

• variable_index (int)

• value (int)

Return type:

None

site(site_index)

Parameters:

site_index (int)

Return type:

int

link(link_index)

Parameters:

link_index (int)

Return type:

int

set_site(site_index, value)

Parameters:

• site_index (int)

• value (int)

Return type:

None

set_link(link_index, value)

Parameters:

• link_index (int)

• value (int)

Return type:

None

flipped(variable_index)

Return a new config with a binary variable flipped.

This only works for variables with local values {0, 1}. For QLM flux variables {-1, +1}, use negated().

Parameters:

variable_index (int)

Return type:

ConfigView

negated(variable_index)

Return a new config with one variable multiplied by -1.

This is useful for spin-1/2 QLM flux variables {-1, +1}.

Parameters:

variable_index (int)

Return type:

ConfigView

as_array(copy=True)

Parameters:

copy (bool)

Return type:

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

__init__(layout, array)

Parameters:

• layout (VariableLayout)

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

Return type:

None

class qlinks.variables.LocalSpace(values)

Bases: object

Finite local Hilbert/configuration space for one physical variable.

Examples

Spin-1/2 site:

values = [0, 1]

QLM spin-1/2 electric field:

values = [-1, 1]

Dimer occupation:

values = [0, 1]

Parameters:

values (ndarray[tuple[Any, ...], dtype[integer]])

values: ndarray[tuple[Any, ...], dtype[integer]]

classmethod from_values(values)

Parameters:

values (Iterable[int])

Return type:

LocalSpace

classmethod binary()

Local two-state variable with values {0, 1}.

Return type:

LocalSpace

classmethod spin_half_flux()

Spin-1/2 QLM-like electric flux variable.

This uses integer values {-1, +1}; if you prefer physical values {-1/2, +1/2}, keep this integer representation internally and divide by 2 only when evaluating physical observables.

Return type:

LocalSpace

classmethod spin_one()

Spin-1 local variable with S^z values {-1, 0, +1}.

Return type:

LocalSpace

property dim: int

property dtype: dtype

contains(value)

Parameters:

value (int)

Return type:

bool

validate_value(value)

Parameters:

value (int)

Return type:

None

validate_array(array)

Parameters:

array (ArrayLike)

Return type:

None

value_to_code(value)

Convert a physical local value to a dense integer code 0, …, dim - 1.

Parameters:

value (int)

Return type:

int

code_to_value(code)

Convert a dense integer code 0, …, dim - 1 back to the physical value.

Parameters:

code (int)

Return type:

int

__init__(values)

Parameters:

values (ndarray[tuple[Any, ...], dtype[integer]])

Return type:

None

class qlinks.variables.VariableKind(*values)

Bases: StrEnum

SITE = 'site'

LINK = 'link'

class qlinks.variables.VariableLayout(specs)

Bases: object

Map physical site/link variables to positions in a compact NumPy config array.

The computational basis state is represented as

config[var_index]

This class tells us which var_index corresponds to which site/link variable.

Parameters:

specs (tuple[VariableSpec, ...])

specs: tuple[VariableSpec, ...]

classmethod from_sites(num_sites, local_space)

Parameters:

• num_sites (int)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_links(num_links, local_space)

Parameters:

• num_links (int)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_sites_and_links(num_sites, site_space, num_links, link_space)

Parameters:

• num_sites (int)

• site_space (LocalSpace)

• num_links (int)

• link_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_sites(lattice, local_space)

Parameters:

• lattice (HasSiteLinkCounts)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_links(lattice, local_space)

Parameters:

• lattice (HasSiteLinkCounts)

• local_space (LocalSpace)

Return type:

VariableLayout

classmethod from_lattice_sites_and_links(lattice, site_space, link_space)

Parameters:

• lattice (HasSiteLinkCounts)

• site_space (LocalSpace)

• link_space (LocalSpace)

Return type:

VariableLayout

property n_variables: int

property shape: tuple[int]

spec(variable_index)

Parameters:

variable_index (int)

Return type:

VariableSpec

local_space(variable_index)

Parameters:

variable_index (int)

Return type:

LocalSpace

variable_index(kind, geometry_index)

Parameters:

• kind (VariableKind | str)

• geometry_index (int)

Return type:

int

site_variable_index(site_index)

Parameters:

site_index (int)

Return type:

int

link_variable_index(link_index)

Parameters:

link_index (int)

Return type:

int

site_variable_indices()

Return type:

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

link_variable_indices()

Return type:

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

empty_config(fill_value=0)

Parameters:

fill_value (int)

Return type:

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

default_config()

Return a valid default configuration.

For each variable, choose the first value in its local space.

Return type:

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

validate_config(config)

Parameters:

config (ArrayLike)

Return type:

None

validate_batch(configs)

Parameters:

configs (ArrayLike)

Return type:

None

as_metadata()

Small serializable summary useful for debugging or future IO.

Return type:

dict[str, Any]

__init__(specs)

Parameters:

specs (tuple[VariableSpec, ...])

Return type:

None

class qlinks.variables.VariableSpec(kind, geometry_index, local_space)

Bases: object

One variable in the flattened configuration array.

kind:

Whether this variable lives on a site or link.

geometry_index:

Site index or link index in the lattice layer.

local_space:

Allowed values for this variable.

Parameters:

• kind (VariableKind)

• geometry_index (int)

• local_space (LocalSpace)

kind: VariableKind

geometry_index: int

local_space: LocalSpace

__init__(kind, geometry_index, local_space)

Parameters:

• kind (VariableKind)

• geometry_index (int)

• local_space (LocalSpace)

Return type:

None