bitbasis
========

.. py:module:: bitbasis


Functions
---------

.. autoapisummary::

   bitbasis.get_local_size
   bitbasis.get_local_range
   bitbasis.get_nth_bit
   bitbasis.flip_nth_bit
   bitbasis._recursively_fill_flatconfigs
   bitbasis.get_all_equal_weight_flatconfigs
   bitbasis.flatconfig_to_bit
   bitbasis.comb
   bitbasis.get_all_equal_weight_bits
   bitbasis.bit_to_rank
   bitbasis.rank_to_bit
   bitbasis.product_of_bits
   bitbasis.get_number_bitbasis
   bitbasis.build_bitmap
   bitbasis.coupled_bits_numba
   bitbasis._build_coo_numba_core
   bitbasis.build_coo_numba
   bitbasis.config_to_bit
   bitbasis.bit_to_config


Module Contents
---------------

.. py:function:: get_local_size(n, rank, world_size)

   Given global size n, and a rank in [0, world_size), return the size of
   the portion assigned to this rank.


.. py:function:: get_local_range(n, rank, world_size)

   Given global size n, and a rank in [0, world_size), return the range of
   indices assigned to this rank.


.. py:function:: get_nth_bit(val, n)

   Get the nth bit of val.

   .. rubric:: Examples

   >>> get_nth_bit(0b101, 1)
   0


.. py:function:: flip_nth_bit(val, n)

   Flip the nth bit of val.

   .. rubric:: Examples

   >>> bin(flip_nth_bit(0b101, 1))
   0b111


.. py:function:: _recursively_fill_flatconfigs(flatconfigs, n, k, c, r)

.. py:function:: get_all_equal_weight_flatconfigs(n, k)

   Get every flat configuration of length n with k bits set.


.. py:function:: flatconfig_to_bit(flatconfig)

   Given a flat configuration, return the corresponding bitstring.


.. py:function:: comb(n, k)

   Compute the binomial coefficient n choose k.


.. py:function:: get_all_equal_weight_bits(n, k, dtype=np.int64)

   Get an array of all 'bits' (integers), with n bits, and k of them set.


.. py:function:: bit_to_rank(b, n, k)

   Given a bitstring b, return the rank of the bitstring in the
   basis of all bitstrings of length n with k bits set. Adapted from
   https://dlbeer.co.nz/articles/kwbs.html.


.. py:function:: rank_to_bit(r, n, k)

   Given a rank r, return the bitstring of length n with k bits set
   that has rank r in the basis of all bitstrings of length n with k
   bits set. Adapted from https://dlbeer.co.nz/articles/kwbs.html.


.. py:function:: product_of_bits(b1, b2, n2, dtype=np.int64)

   Get the outer product of two bit arrays.

   :param b1: The bit arrays to take the outer product of.
   :type b1: array
   :param b2: The bit arrays to take the outer product of.
   :type b2: array
   :param n2: The number of bits in ``b2``
   :type n2: int


.. py:function:: get_number_bitbasis(*nk_pairs, dtype=np.int64)

   Create a bit basis with number conservation.

   :param nk_pairs: Each element is a pair (n, k) where n is the number of bits, and k is
                    the number of bits that are set. The basis will be the product of all
                    supplied pairs.
   :type nk_pairs: sequence of (int, int)

   :returns: **basis** -- An array of integers, each representing a bit string. The size will be
             ``prod(comb(n, k) for n, k in nk_pairs)``.
   :rtype: ndarray

   .. rubric:: Examples

   A single number conserving basis:

       >>> for i, b in enumerate(get_number_bitbasis((4, 2))):
       >>>    print(f"{i}: {b:0>4b}")
       0: 0011
       1: 0101
       2: 0110
       3: 1001
       4: 1010
       5: 1100

   A product of two number conserving bases, e.g. n_up and n_down:

       >>> for b in get_number_bitbasis((3, 2), (3, 1)):
       >>>     print(f"{b:0>6b}")
       011001
       011010
       011100
       101001
       101010
       101100
       110001
       110010
       110100


.. py:function:: build_bitmap(configs)

   Build of map of bits to linear indices, suitable for use with numba.


.. py:function:: coupled_bits_numba(bi, coupling_map)

.. py:function:: _build_coo_numba_core(bits, coupling_map, bitmap=None, dtype=np.float64)

.. py:function:: build_coo_numba(bits, coupling_map, dtype=None, parallel=False)

   Build an operator in COO form, using the basis ``bits`` and the
    ``coupling_map``, optionally multithreaded.

   :param bits: An array of integers, each representing a bit string.
   :type bits: array
   :param coupling_map: A nested numba dictionary of couplings. The outermost key is the term
                        index, the next key is the register, and the innermost key is the bit
                        index. The value is a tuple of (coupled bit index, coupling
                        coefficient).
   :type coupling_map: Dict[int, Dict[int, Dict[int, Tuple[int, float]]]]
   :param parallel: Whether to parallelize the computation. If an integer is given, it
                    specifies the number of threads to use.
   :type parallel: bool or int, optional

   :returns: * **data** (*array*) -- The non-zero elements of the operator.
             * **cis** (*array*) -- The row indices of the non-zero elements.
             * **cjs** (*array*) -- The column indices of the non-zero elements.


.. py:function:: config_to_bit(self, config)

   Encode a 'configuration' as a bit.

   :param config: A dictionary mapping sites to their occupation number / spin.
   :type config: dict[hashable, int]

   :returns: **bit** -- The bit corresponding to this configuration.
   :rtype: int


.. py:function:: bit_to_config(self, bit)

   Decode a bit to a configuration.

   :param bit: The bit to decode.
   :type bit: int

   :returns: **config** -- A dictionary mapping sites to their occupation number / spin.
   :rtype: dict[hashable, int]