quimb.operator.hilbertspace

Tools for defining and manipulating Hilbert spaces.

Attributes

ORDER_PRESETS

Classes

HilbertSpace

Take a set of 'sites' (any sequence of sortable, hashable objects), and

Functions

parse_edges_to_unique(edges)	Given a list of edges, return a sorted list of unique sites and edges.
valid_z2_sector(sector)	Check if the given sector is valid for Z2 symmetry.
valid_u1_sector(sector, nsites)	Check if the given sector is valid for U1 symmetry.
parse_u1u1_sector(sector, nsites[, species_regs])	Parse a U1U1 sector into the ((na, ka), (nb, kb)) form, where
parse_species(sites, species)	Group ordered sites by species.
parse_symmetry_and_sector(nsites[, sector, symmetry, ...])
parse_sites_dims(sites, dims)	Parse a site and dimension specification.
parse_order_preset(sites, order)	Get the sorting key for a named ordering preset, checking that the

Module Contents

quimb.operator.hilbertspace.parse_edges_to_unique(edges)

Given a list of edges, return a sorted list of unique sites and edges.

Parameters:

edges (Iterable[tuple[hashable, hashable]]]) – The edges to parse.

Returns:

• sites (list of hashable) – The unique sites in the edges, sorted.

• edges (list of (hashable, hashable)) – The unique edges, sorted.

quimb.operator.hilbertspace.valid_z2_sector(sector)

Check if the given sector is valid for Z2 symmetry.

quimb.operator.hilbertspace.valid_u1_sector(sector, nsites)

Check if the given sector is valid for U1 symmetry.

quimb.operator.hilbertspace.parse_u1u1_sector(sector, nsites, species_regs=None)

Parse a U1U1 sector into the ((na, ka), (nb, kb)) form, where na and nb are the number of sites of each species, and ka and kb their fillings. Three forms are accepted:

• {speciesa: ka, speciesb: kb}: the fillings keyed by species label

• (ka, kb): the fillings alone, paired with the species in sorted label order

• ((na, ka), (nb, kb)): the sizes and fillings given explicitly

The first two require species_regs, since they name no sizes.

Parameters:

• sector (dict, tuple[int] or ((int, int), (int, int))) – The sector to parse.

• nsites (int) – The total number of sites.

• species_regs (dict[hashable, tuple[int]], optional) – The registers of each species, keyed by species label, in sorted label order. If not given, only the explicit form can be parsed.

Returns:

sector – The parsed sector, or None if it is not a valid U1U1 sector.

Return type:

((int, int), (int, int)) or None

quimb.operator.hilbertspace.parse_species(sites, species)

Group ordered sites by species.

Parameters:

• sites (sequence of hashable) – The sites, in register order.

• species (callable or dict[hashable, hashable] or None) – How to get the species label of each site. If None, return None.

Returns:

species_regs – The registers of each species, keyed by species label, in sorted label order.

Return type:

dict[hashable, tuple[int]] or None

quimb.operator.hilbertspace.parse_symmetry_and_sector(nsites, sector=None, symmetry=None, species_regs=None)

quimb.operator.hilbertspace.parse_sites_dims(sites, dims)

Parse a site and dimension specification.

Parameters:

• sites (int, sequence of hashable objects, or dict) – The sites to parse. If an integer, simply use range(sites). If a dict, the keys are the sites and the values are the dimensions.

• dims (int or sequence of int) – The dimensions to parse. If an integer, all sites have the same dim.

Returns:

• parsed_sites (list of hashable) – The parsed list of sites (as yet unsorted).

• parsed_dims (dict[hashable, int]) – A dictionary mapping each site to its dimension.

• dims_used (set[int]) – The set of unique dimensions used.

quimb.operator.hilbertspace.ORDER_PRESETS

quimb.operator.hilbertspace.parse_order_preset(sites, order)

Get the sorting key for a named ordering preset, checking that the sites are labelled in the (species, ...) form the presets require.

Parameters:

• sites (sequence of hashable) – The sites the ordering will be applied to.

• order (str) – The name of the preset, one of ORDER_PRESETS.

Returns:

A sorting key function.

Return type:

callable

class quimb.operator.hilbertspace.HilbertSpace(sites, dims=2, order=None, species=None, sector=None, symmetry=None)

Take a set of ‘sites’ (any sequence of sortable, hashable objects), and map this into a ‘register’ or linearly indexed range, optionally using a particular ordering. A symmetry and sector can also be specified, which will change the size of the Hilbert space and how the valid configurations are enumerated.

Some nomenclature:

• site: a hashable label for a site in the Hilbert space. This can be any python object (e.g. tuple[str | int]).

• register: a linear index for a site in the Hilbert space. This is an integer in the range [0, nsites), and requires an ordering of the sites.

• configuration: a mapping from sites to their occupation number or spin state. This is a dictionary mapping from site to int.

• flat configuration: a flat array of the occupation number or spin state of each site in the order given by this Hilbert space (i.e. a mapping of register to int). This is a 1D array of length nsites with dtype np.uint8, for efficient manipulation with numba and numpy.

• rank: a linear index for a configuration in the Hilbert space, taking into account any symmetries and sectors. This is an integer in the range [0, size), where size is the size of the Hilbert space given the symmetry and sector.

Parameters:

• sites (int, sequence of hashable objects, or dict) – The sites to map into a linear register. If an integer, simply use range(sites). If a dict, the keys are the sites and the values are the dimensions, in which case the dims argument is ignored.

• dims (int or sequence of int, optional) – The local dimensions of each site. If an integer, all sites have the same dimension. If a sequence, it should be the same length as sites. You can also provide the dimensions as part of the sites argument by passing a dict, in which case this argument is ignored.

• order (bool, str, sequence[hashable] or callable, optional) – How to order the sites. If None or False (default), the sites are kept in the order supplied. If True, the sites are sorted. If a string, it should name one of ORDER_PRESETS: “blocked” groups the sites into a contiguous block per species, “interleaved” alternates the species at each position. Both require sites labelled as (species, ...) tuples, and take the species blocks in sorted order. If a sequence, it should be a permutation of the sites, and this will be used to order them. If a callable, it should be a sorting key function which will be used to order the sites.

• species (callable or dict[hashable, hashable], optional) – The species of each site, i.e. which conserved charge its occupation counts towards, given either as a function of the site or a mapping from site to species label. Required for the {species: filling} and (ka, kb) forms of a U1U1 sector.

• sector ({None, str, int, dict, (int, int), ((int, int), (int, int))}, optional) – The sector of the Hilbert space. If None, no sector is assumed. For U1U1 the filling of each species can be given as {species: filling} or, in sorted species label order, as (ka, kb), both of which need species. The explicit ((na, ka), (nb, kb)) form does not, but assumes the species occupy contiguous blocks of registers.

• symmetry ({None, "Z2", "U1", "U1U1"}, optional) – The symmetry of the Hilbert space if any. If None and a sector is provided, the symmetry will be inferred from the sector if possible.

_species = None

_species_regs = None

_size = None

_sizes = None

_strides = None

_pt = None

_build_blocked_perm()

Build the permutation between the register ordering and the blocked ordering, which groups each species into a contiguous block, and is what U1U1 enumerates configurations in. The two coincide unless the species are interleaved among the registers. This depends on the ordering and species alone, not the symmetry, since a sector can be supplied per call, and the coupling map is built once for all of them.

property needs_blocking

Whether the species are interleaved among the registers, so that the blocked ordering differs from the register ordering.

_flatconfig_to_blocked(flatconfig)

Permute a flat configuration from register order into the blocked ordering, along the last axis. Only the default sector’s mappings are permuted, so this is a no-op unless that sector is U1U1.

_flatconfig_from_blocked(flatconfig)

Permute a flat configuration from the blocked ordering back into register order. The inverse of _flatconfig_to_blocked.

site_to_blocked_reg(site)

Convert a site to its index in the blocked ordering, which matches its register unless the species are interleaved.

_build_config_maps()

Build the rank <-> flat configuration mappings. These depend on the ordering, so are only built once it is fixed.

_set_ordering(order)

Set the ordering of the sites in this Hilbert space. Only called at construction, since the ordering is immutable thereafter.

Parameters:

order (bool, str, sequence[hashable] or callable, optional) – How to order the sites. If None or False (default), the sites are kept in the order supplied. If True, the sites are sorted. If a string, it should name one of ORDER_PRESETS. If a sequence, it should be a permutation of the sites, and this will be used to order them. If a callable, it should be a sorting key function which will be used to order the sites.

set_ordering(order)

Deprecated: the ordering of a HilbertSpace is immutable.

with_ordering(order)

Get a new HilbertSpace with the same sites, dimensions, symmetry and sector, but a different ordering.

Parameters:

order (bool, str, sequence[hashable] or callable, optional) – How to order the sites. If None or False, the sites are kept in the current order. If True, the sites are sorted. If a string, it should be one of the ordering presets, “blocked” or “interleaved”. If a sequence, it should be a permutation of the sites, and this will be used to order them. If a callable, it should be a sorting key function which will be used to order the sites.

Return type:

HilbertSpace

classmethod from_edges(edges, order=None)

Construct a HilbertSpace from a set of edges, which are pairs of sites.

Parameters:

• edges (Iterable[tuple[hashable, hashable]]]) – The edges to parse.

• order (bool, sequence[hashable] or callable, optional) – How to order the sites. If None or False (default), the sites are kept in the order supplied. If True, the sites are sorted. If a sequence, it should be a permutation of the sites, and this will be used to order them. If a callable, it should be a sorting key function which will be used to order the sites.

property sites

The ordered tuple of all sites in the Hilbert space.

property sector

The sector of the Hilbert space.

get_sector_numba(sector=None, symmetry=None)

The sector of the Hilbert space, in ‘numba form’. A non-default symmetry and sector can be provided.

Parameters:

• sector ({None, str, int, ((int, int), (int, int))}, optional) – The sector of the Hilbert space. If None, the default sector is used.

• symmetry ({None, "Z2", "U1", "U1U1"}, optional) – The symmetry of the Hilbert space. If None, the default symmetry is used, or inferred from the supplied sector if possible.

Returns:

• sector (ndarray[int64]) – The sector of the Hilbert space, in ‘numba form’. This is a 1D array of length 1, 2 or 4, depending on the symmetry.

• symmetry (str) – The symmetry of the Hilbert space. This is one of “None”, “Z2”, “U1”, or “U1U1”.

property symmetry

The symmetry of the Hilbert space.

property nsites

The total number of sites in the Hilbert space.

get_sizes()

Get a numpy array of the ordered sizes of each site in the Hilbert space.

property sizes

Get a numpy array of the ordered sizes of each site in the Hilbert space.

get_strides()

Get the strides for each site in the Hilbert space.

property strides

Get the strides for each site in the Hilbert space.

get_pascal_table()

Get a sufficiently large pascal table for this Hilbert space.

get_size(sector=None, symmetry=None)

Get the size of the Hilbert space, optionally given a non-default symmetry and sector.

Parameters:

• sector ({None, str, int, ((int, int), (int, int))}, optional) – The sector of the Hilbert space. If None, the default sector is used.

• symmetry ({None, "Z2", "U1", "U1U1"}, optional) – The symmetry of the Hilbert space. If None, the default symmetry is used, or inferred from the supplied sector if possible.

property size

Get the size of this Hilbert space, taking into account the default symmetry and sector.

site_size(site)

Get the local dimension of a given site.

site_to_reg(site)

Convert a site to a linear register index.

reg_to_site(reg)

Convert a linear register index back to a site.

has_site(site)

Check if this HilbertSpace contains a given site.

rank_to_flatconfig(rank)

Convert a rank (linear index) into a flat configuration.

Parameters:

rank (int) – The rank (linear index) to convert.

Returns:

flatconfig – A flat configuration, with the occupation number or spin state of each site in the order given by this HilbertSpace.

Return type:

ndarray[uint8]

flatconfig_to_rank(flatconfig)

Convert a flat configuration into a rank (linear index).

Parameters:

flatconfig (ndarray[uint8]) – A flat configuration, with the occupation number or spin state of each site in the order given by this HilbertSpace.

Returns:

rank – The rank (linear index) of the flat configuration in the Hilbert space.

Return type:

int

config_to_flatconfig(config)

Turn a configuration into a flat configuration, assuming the order given by this HilbertSpace.

Parameters:

config (dict[hashable, int]) – A dictionary mapping sites to their occupation number / spin.

Returns:

flatconfig – A flat configuration, with the occupation number or spin state of each site in the order given by this HilbertSpace.

Return type:

ndarray[uint8]

flatconfig_to_config(flatconfig)

Turn a flat configuration into a configuration, assuming the order given by this HilbertSpace.

Parameters:

flatconfig (ndarray[uint8]) – A flat configuration, with the occupation number or spin state of each site in the order given by this HilbertSpace.

Returns:

config – A dictionary mapping sites to their occupation number / spin state.

Return type:

dict[hashable, int]

rank_to_config(rank)

Convert a rank (linear index) into a configuration.

Parameters:

rank (int) – The rank (linear index) to convert.

Returns:

config – A dictionary mapping sites to their occupation number / spin state.

Return type:

dict[hashable, int]

config_to_rank(config)

Convert a configuration into a rank (linear index).

Parameters:

config (dict[hashable, int]) – A dictionary mapping sites to their occupation number / spin state.

Returns:

rank – The rank (linear index) of the configuration in the Hilbert space.

Return type:

int

rand_rank(seed=None)

Get a random rank (linear index) in the Hilbert space.

Parameters:

seed (None, int or numpy.random.Generator, optional) – The random seed or generator to use. If None, a new generator will be created with default settings.

Returns:

rank – A random rank in the Hilbert space.

Return type:

int64

rand_flatconfig(seed=None)

Get a random flat configuration.

Parameters:

seed (None, int or numpy.random.Generator, optional) – The random seed or generator to use. If None, a new generator will be created with default settings.

Returns:

flatconfig – A flat configuration, with the occupation number or spin state of each site in the order given by this HilbertSpace.

Return type:

ndarray[uint8]

rand_config(seed=None)

Get a random configuration.

Parameters:

seed (None, int or numpy.random.Generator, optional) – The random seed or generator to use. If None, a new generator will be created with default settings.

Returns:

config – A dictionary mapping sites to their occupation number / spin state.

Return type:

dict[hashable, np.uint8]

__repr__()