symmray.spin_local_operators

Helper functions for building local spin-1/2 operators from a symbolic description, without any external dependencies. Unlike the fermionic case there are no ‘internal’ signs to compute, so each named operator is simply given its 2x2 matrix representation and terms are combined via tensor (Kronecker) products.

Functions

_spin_matrices()

The 2x2 matrix representations of the supported single-site spin-1/2

get_spin_operator(label[, like])

Get the 2x2 matrix representation of a single-site spin-1/2 operator.

get_spinhalf_charge_indexmap(symmetry)

Get a mapping of linear index to charge sector for a spin-1/2 site.

_spinhalf_index_maps(symmetry, nsites)

Per-site spin-1/2 index maps, or None when symmetry is None.

build_local_spin_dense(terms[, like])

Compute the dense matrix of a local spin-1/2 operator from a symbolic

build_local_spin_array(terms, symmetry[, index_maps, ...])

Compute a local spin-1/2 operator as an AbelianArray.

tfim_local_array(symmetry[, jx, hz, coordinations, ...])

Build an abelian symmetric local operator for the transverse field

heisenberg_local_array(symmetry[, j, b, ...])

Build an abelian symmetric local operator for the Heisenberg model:

spin_operator_local_array(symmetry[, op, like, flat])

Build a single-site abelian symmetric spin-1/2 operator.

Module Contents

symmray.spin_local_operators._spin_matrices()[source]

The 2x2 matrix representations of the supported single-site spin-1/2 operators, as a dict of numpy arrays. Cached so they are built only once.

symmray.spin_local_operators.get_spin_operator(label, like='numpy')[source]

Get the 2x2 matrix representation of a single-site spin-1/2 operator.

Parameters:

  • label (str) – The operator to get, one of “I”, “x”, “y”, “z”, “sx”, “sy”, “sz”, “+” or “-“.

  • like (str, optional) – The backend to use, by default “numpy”.

Returns:

The 2x2 matrix representation.

Return type:

array

symmray.spin_local_operators.get_spinhalf_charge_indexmap(symmetry)[source]

Get a mapping of linear index to charge sector for a spin-1/2 site.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, a “ZN” group, or “U1”.

Return type:

list[hashable]

symmray.spin_local_operators._spinhalf_index_maps(symmetry, nsites)[source]

Per-site spin-1/2 index maps, or None when symmetry is None.

symmray.spin_local_operators.build_local_spin_dense(terms, like='numpy')[source]

Compute the dense matrix of a local spin-1/2 operator from a symbolic description.

Parameters:

  • terms (Sequence[tuple[float, tuple[str, ...]]]) – The terms in the operator, each a tuple of a coefficient and a tuple of single-site operator labels (see get_spin_operator), one per site. All terms should act on the same number of sites.

  • like (str, optional) – The backend to use, by default “numpy”.

Returns:

The dense operator, of shape (2,) * (2 * nsites) with axes ordered as (ket_0, ..., ket_{n-1}, bra_0, ..., bra_{n-1}).

Return type:

array

Examples

The transverse field Ising local term:

build_local_spin_dense(
    [(-1.0, ("x", "x")), (-3.0, ("z", "I")), (-3.0, ("I", "z"))]
)
symmray.spin_local_operators.build_local_spin_array(terms, symmetry, index_maps=None, charge=None, like='numpy', flat=False)[source]

Compute a local spin-1/2 operator as an AbelianArray.

Parameters:

  • terms (Sequence[tuple[float, tuple[str, ...]]]) – The terms in the operator, each a tuple of a coefficient and a tuple of single-site operator labels (see get_spin_operator), one per site.

  • symmetry (str or None) – The symmetry of the operator. Either “Z2”, a “ZN” group, or “U1”. If None, the raw dense array is returned instead of a symmetric array.

  • index_maps (Sequence[Sequence[hashable]], optional) – For each site, the sequence mapping linear index to charge sector. Required unless symmetry is None.

  • charge (hashable, optional) – The total charge of the array. If not given it is taken as the identity / zero element, suitable for charge-conserving operators.

  • like (str, optional) – The backend to use, by default “numpy”.

  • flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator, as a dense array if symmetry is None.

Return type:

AbelianArray or AbelianArrayFlat or array

symmray.spin_local_operators.tfim_local_array(symmetry, jx=-1.0, hz=-3.0, coordinations=(1, 1), like='numpy', flat=False)[source]

Build an abelian symmetric local operator for the transverse field Ising model:

H = jx * sum_ij X_i X_j + hz * sum_i Z_i

Note that its rotated into the x-basis so that the Z2 symmetry is manifest.

Parameters:

  • symmetry (str or None) – The symmetry of the model. Should be “Z2”, or None to return the raw dense array.

  • jx (float) – The coupling strength for the X-X interactions, by default -1.0.

  • hz (float or tuple[float, float]) – The coupling strength for the Z interactions, by default -3.0. If a tuple is given it should contain the fields for the two sites.

  • coordinations (tuple[int, int], optional) – The coordinations of the two sites, by default (1, 1). The fields are divided by these values to account for double counting.

  • like (str, optional) – The backend to use, by default “numpy”.

  • flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local Hamiltonian term, dense if symmetry is None.

Return type:

Z2Array or Z2ArrayFlat or array

symmray.spin_local_operators.heisenberg_local_array(symmetry, j=1.0, b=0.0, coordinations=(1, 1), like='numpy', flat=False)[source]

Build an abelian symmetric local operator for the Heisenberg model:

H = sum_ij (jx Sx_i Sx_j + jy Sy_i Sy_j + jz Sz_i Sz_j)
    - sum_i bz Sz_i

where the spin operators are the spin-1/2 operators (eigenvalues +/- 1/2).

Parameters:

  • symmetry (str or None) – The symmetry of the model. Either “Z2” or “U1”, or None to return the raw dense array. Note “U1” requires the XY couplings to be equal (jx == jy), so that total magnetization is conserved.

  • j (float or tuple[float, float, float], optional) – The coupling strength, by default 1.0. If a tuple is given it should contain the (jx, jy, jz) couplings.

  • b (float or tuple[float, float], optional) – The magnetic field along the z-axis, by default 0.0. A scalar is applied uniformly to both sites, while a pair (ba, bb) sets the two sites’ fields independently. Only z-fields are supported as transverse fields would not conserve the symmetry.

  • coordinations (tuple[int, int], optional) – The coordinations of the two sites, by default (1, 1). The fields are divided by these values to account for double counting.

  • like (str, optional) – The backend to use, by default “numpy”.

  • flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local Hamiltonian term, dense if symmetry is None.

Return type:

AbelianArray or AbelianArrayFlat or array

symmray.spin_local_operators.spin_operator_local_array(symmetry, op='z', like='numpy', flat=False)[source]

Build a single-site abelian symmetric spin-1/2 operator.

Parameters:

  • symmetry (str or None) – The symmetry of the model. Either “Z2”, a “ZN” group, or “U1”, or None to return the raw dense array.

  • op (str, optional) – The operator to build, by default “z”. One of “I”, “x”, “y”, “z”, “sx”, “sy”, “sz”, “+” or “-”. Note charge-changing operators (“+”, “-”, and for “U1” also “x”, “y”) yield an array with non-identity total charge.

  • like (str, optional) – The backend to use, by default “numpy”.

  • flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The single-site operator, dense if symmetry is None.

Return type:

AbelianArray or AbelianArrayFlat or array