quimb.operator.hilbertspace =========================== .. py:module:: quimb.operator.hilbertspace .. autoapi-nested-parse:: Tools for defining and manipulating Hilbert spaces. Classes ------- .. autoapisummary:: quimb.operator.hilbertspace.HilbertSpace Functions --------- .. autoapisummary:: quimb.operator.hilbertspace.parse_edges_to_unique quimb.operator.hilbertspace.valid_z2_sector quimb.operator.hilbertspace.valid_u1_sector quimb.operator.hilbertspace.valid_u1u1_sector quimb.operator.hilbertspace.parse_symmetry_and_sector quimb.operator.hilbertspace.parse_sites_dims Module Contents --------------- .. py:function:: parse_edges_to_unique(edges) Given a list of edges, return a sorted list of unique sites and edges. :param edges: The edges to parse. :type edges: Iterable[tuple[hashable, hashable]]] :returns: * **sites** (*list of hashable*) -- The unique sites in the edges, sorted. * **edges** (*list of (hashable, hashable)*) -- The unique edges, sorted. .. py:function:: valid_z2_sector(sector) Check if the given sector is valid for Z2 symmetry. .. py:function:: valid_u1_sector(sector, nsites) Check if the given sector is valid for U1 symmetry. .. py:function:: valid_u1u1_sector(sector, nsites) Check if the given sector is valid for U1U1 symmetry. .. py:function:: parse_symmetry_and_sector(nsites, sector=None, symmetry=None) .. py:function:: parse_sites_dims(sites, dims) Parse a site and dimension specification. :param sites: 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. :type sites: int, sequence of hashable objects, or dict :param dims: The dimensions to parse. If an integer, all sites have the same dim. :type dims: int or sequence of int :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. .. py:class:: HilbertSpace(sites, dims=2, order=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. :param sites: 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. :type sites: int, sequence of hashable objects, or dict :param dims: 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. :type dims: int or sequence of int, optional :param order: 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. :type order: bool, sequence[hashable] or callable, optional :param sector: The sector of the Hilbert space. If None, no sector is assumed. :type sector: {None, str, int, ((int, int), (int, int))}, optional :param symmetry: 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. :type symmetry: {None, "Z2", "U1", "U1U1"}, optional .. py:attribute:: _size :value: None .. py:attribute:: _sizes :value: None .. py:attribute:: _strides :value: None .. py:attribute:: _pt :value: None .. py:method:: set_ordering(order) Set the ordering of the sites in this Hilbert space. :param order: 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. :type order: bool, sequence[hashable] or callable, optional .. py:method:: from_edges(edges, order=None) :classmethod: Construct a HilbertSpace from a set of edges, which are pairs of sites. :param edges: The edges to parse. :type edges: Iterable[tuple[hashable, hashable]]] :param order: 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. :type order: bool, sequence[hashable] or callable, optional .. py:property:: sites The ordered tuple of all sites in the Hilbert space. .. py:property:: sector The sector of the Hilbert space. .. py:method:: 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. :param sector: The sector of the Hilbert space. If None, the default sector is used. :type sector: {None, str, int, ((int, int), (int, int))}, optional :param symmetry: The symmetry of the Hilbert space. If None, the default symmetry is used, or inferred from the supplied sector if possible. :type symmetry: {None, "Z2", "U1", "U1U1"}, optional :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". .. py:property:: symmetry The symmetry of the Hilbert space. .. py:property:: nsites The total number of sites in the Hilbert space. .. py:method:: get_sizes() Get a numpy array of the ordered sizes of each site in the Hilbert space. .. py:property:: sizes Get a numpy array of the ordered sizes of each site in the Hilbert space. .. py:method:: get_strides() Get the strides for each site in the Hilbert space. .. py:property:: strides Get the strides for each site in the Hilbert space. .. py:method:: get_pascal_table() Get a sufficiently large pascal table for this Hilbert space. .. py:method:: get_size(sector=None, symmetry=None) Get the size of the Hilbert space, optionally given a non-default symmetry and sector. :param sector: The sector of the Hilbert space. If None, the default sector is used. :type sector: {None, str, int, ((int, int), (int, int))}, optional :param symmetry: The symmetry of the Hilbert space. If None, the default symmetry is used, or inferred from the supplied sector if possible. :type symmetry: {None, "Z2", "U1", "U1U1"}, optional .. py:property:: size Get the size of this Hilbert space, taking into account the default symmetry and sector. .. py:method:: site_size(site) Get the local dimension of a given site. .. py:method:: site_to_reg(site) Convert a site to a linear register index. .. py:method:: reg_to_site(reg) Convert a linear register index back to a site. .. py:method:: has_site(site) Check if this HilbertSpace contains a given site. .. py:method:: rank_to_flatconfig(rank) Convert a rank (linear index) into a flat configuration. :param rank: The rank (linear index) to convert. :type rank: int :returns: **flatconfig** -- A flat configuration, with the occupation number or spin state of each site in the order given by this ``HilbertSpace``. :rtype: ndarray[uint8] .. py:method:: flatconfig_to_rank(flatconfig) Convert a flat configuration into a rank (linear index). :param flatconfig: A flat configuration, with the occupation number or spin state of each site in the order given by this ``HilbertSpace``. :type flatconfig: ndarray[uint8] :returns: **rank** -- The rank (linear index) of the flat configuration in the Hilbert space. :rtype: int .. py:method:: config_to_flatconfig(config) Turn a configuration into a flat configuration, assuming the order given by this ``HilbertSpace``. :param config: A dictionary mapping sites to their occupation number / spin. :type config: dict[hashable, int] :returns: **flatconfig** -- A flat configuration, with the occupation number or spin state of each site in the order given by this ``HilbertSpace``. :rtype: ndarray[uint8] .. py:method:: flatconfig_to_config(flatconfig) Turn a flat configuration into a configuration, assuming the order given by this ``HilbertSpace``. :param flatconfig: A flat configuration, with the occupation number or spin state of each site in the order given by this ``HilbertSpace``. :type flatconfig: ndarray[uint8] :returns: **config** -- A dictionary mapping sites to their occupation number / spin state. :rtype: dict[hashable, int] .. py:method:: rank_to_config(rank) Convert a rank (linear index) into a configuration. :param rank: The rank (linear index) to convert. :type rank: int :returns: **config** -- A dictionary mapping sites to their occupation number / spin state. :rtype: dict[hashable, int] .. py:method:: config_to_rank(config) Convert a configuration into a rank (linear index). :param config: A dictionary mapping sites to their occupation number / spin state. :type config: dict[hashable, int] :returns: **rank** -- The rank (linear index) of the configuration in the Hilbert space. :rtype: int .. py:method:: rand_rank(seed=None) Get a random rank (linear index) in the Hilbert space. :param seed: The random seed or generator to use. If None, a new generator will be created with default settings. :type seed: None, int or numpy.random.Generator, optional :returns: **rank** -- A random rank in the Hilbert space. :rtype: int64 .. py:method:: rand_flatconfig(seed=None) Get a random flat configuration. :param seed: The random seed or generator to use. If None, a new generator will be created with default settings. :type seed: None, int or numpy.random.Generator, optional :returns: **flatconfig** -- A flat configuration, with the occupation number or spin state of each site in the order given by this ``HilbertSpace``. :rtype: ndarray[uint8] .. py:method:: rand_config(seed=None) Get a random configuration. :param seed: The random seed or generator to use. If None, a new generator will be created with default settings. :type seed: None, int or numpy.random.Generator, optional :returns: **config** -- A dictionary mapping sites to their occupation number / spin state. :rtype: dict[hashable, np.uint8] .. py:method:: __repr__()