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.

layout: VariableLayout

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

classmethod from_array(layout, array)

classmethod default(layout)

copy()

value(variable_index)

set_value(variable_index, value)

site(site_index)

link(link_index)

set_site(site_index, value)

set_link(link_index, value)

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

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

as_array(copy=True)

__init__(layout, array)

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.

layout: VariableLayout

encode(config, *, validate=True)

decode(key, *, validate=True)

build_index(configs, *, validate=True)

__init__(layout)

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.

layout: VariableLayout

encode(config, *, validate=True)

decode(key, *, validate=True)

__init__(layout)

qlinks.variables.layout module

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

Bases: StrEnum

Kind of physical variable represented in a layout.

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.

kind: VariableKind

geometry_index: int

local_space: LocalSpace

__init__(kind, geometry_index, local_space)

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.

specs: tuple[VariableSpec, ...]

classmethod from_sites(num_sites, local_space)

classmethod from_links(num_links, local_space)

classmethod from_sites_and_links(num_sites, site_space, num_links, link_space)

classmethod from_lattice_sites(lattice, local_space)

classmethod from_lattice_links(lattice, local_space)

classmethod from_lattice_sites_and_links(lattice, site_space, link_space)

property n_variables: int

property shape: tuple[int]

spec(variable_index)

local_space(variable_index)

variable_index(kind, geometry_index)

site_variable_index(site_index)

link_variable_index(link_index)

site_variable_indices()

link_variable_indices()

empty_config(fill_value=0)

default_config()

Return a valid default configuration.

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

validate_config(config)

validate_batch(configs)

as_metadata()

Small serializable summary useful for debugging or future IO.

__init__(specs)

qlinks.variables.local_space module

class qlinks.variables.local_space.LocalSpace(values)

Bases: object

Finite local Hilbert/configuration space for one variable.

values

Allowed integer values for the variable.

Type:

numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.integer]]

Examples

Spin-1/2 site or dimer occupation uses [0, 1]. A spin-half QLM electric field uses [-1, 1].

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

classmethod from_values(values)

classmethod binary()

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

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.

classmethod spin_one()

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

property dim: int

property dtype: dtype

contains(value)

validate_value(value)

validate_array(array)

value_to_code(value)

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

code_to_value(code)

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

__init__(values)

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.

layout: VariableLayout

encode(config, *, validate=True)

decode(key, *, validate=True)

__init__(layout)

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.

layout: VariableLayout

encode(config, *, validate=True)

decode(key, *, validate=True)

build_index(configs, *, validate=True)

__init__(layout)

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.

layout: VariableLayout

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

classmethod from_array(layout, array)

classmethod default(layout)

copy()

value(variable_index)

set_value(variable_index, value)

site(site_index)

link(link_index)

set_site(site_index, value)

set_link(link_index, value)

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

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

as_array(copy=True)

__init__(layout, array)

class qlinks.variables.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.LocalSpace(values)

Bases: object

Finite local Hilbert/configuration space for one variable.

values

Allowed integer values for the variable.

Type:

numpy.ndarray[tuple[Any, …], numpy.dtype[numpy.integer]]

Examples

Spin-1/2 site or dimer occupation uses [0, 1]. A spin-half QLM electric field uses [-1, 1].

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

classmethod from_values(values)

classmethod binary()

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

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.

classmethod spin_one()

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

property dim: int

property dtype: dtype

contains(value)

validate_value(value)

validate_array(array)

value_to_code(value)

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

code_to_value(code)

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

__init__(values)

class qlinks.variables.VariableKind(*values)

Bases: StrEnum

Kind of physical variable represented in a layout.

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.

specs: tuple[VariableSpec, ...]

classmethod from_sites(num_sites, local_space)

classmethod from_links(num_links, local_space)

classmethod from_sites_and_links(num_sites, site_space, num_links, link_space)

classmethod from_lattice_sites(lattice, local_space)

classmethod from_lattice_links(lattice, local_space)

classmethod from_lattice_sites_and_links(lattice, site_space, link_space)

property n_variables: int

property shape: tuple[int]

spec(variable_index)

local_space(variable_index)

variable_index(kind, geometry_index)

site_variable_index(site_index)

link_variable_index(link_index)

site_variable_indices()

link_variable_indices()

empty_config(fill_value=0)

default_config()

Return a valid default configuration.

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

validate_config(config)

validate_batch(configs)

as_metadata()

Small serializable summary useful for debugging or future IO.

__init__(specs)

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.

kind: VariableKind

geometry_index: int

local_space: LocalSpace

__init__(kind, geometry_index, local_space)