quimb.operator.configcore ========================= .. py:module:: quimb.operator.configcore .. autoapi-nested-parse:: Numba accelerated tools for ranking, deranking and coupling 'flat configs', used for constructing sparse matrices in a variety of Hilbert spaces, as well as applying operators to vectors in those spaces. Attributes ---------- .. autoapisummary:: quimb.operator.configcore.nogil quimb.operator.configcore.cache Functions --------- .. autoapisummary:: quimb.operator.configcore._check_next_coupled_term quimb.operator.configcore.flatconfig_coupling_numba quimb.operator.configcore.flatconfig_to_rank_nosymm quimb.operator.configcore.rank_into_flatconfig_nosymm quimb.operator.configcore.rank_to_flatconfig_nosymm quimb.operator.configcore.build_coo_numba_core_nosymm quimb.operator.configcore.matvec_nosymm quimb.operator.configcore.calculate_strides quimb.operator.configcore.flatconfig_to_rank_mixed_radix_nosymm quimb.operator.configcore.rank_into_flatconfig_mixed_radix_nosymm quimb.operator.configcore.rank_to_flatconfig_mixed_radix_nosymm quimb.operator.configcore.flatconfig_to_rank_z2 quimb.operator.configcore.rank_into_flatconfig_z2 quimb.operator.configcore.rank_to_flatconfig_z2 quimb.operator.configcore.build_coo_numba_core_z2 quimb.operator.configcore.matvec_z2 quimb.operator.configcore.build_pascal_table quimb.operator.configcore.flatconfig_to_rank_u1_pascal quimb.operator.configcore.rank_into_flatconfig_u1_pascal quimb.operator.configcore.rank_to_flatconfig_u1_pascal quimb.operator.configcore.build_coo_numba_core_u1 quimb.operator.configcore.matvec_u1 quimb.operator.configcore.flatconfig_to_rank_u1u1_pascal quimb.operator.configcore.rank_into_flatconfig_u1u1_pascal quimb.operator.configcore.rank_to_flatconfig_u1u1_pascal quimb.operator.configcore.build_coo_numba_core_u1u1 quimb.operator.configcore.matvec_u1u1 quimb.operator.configcore.rank_to_flatconfig quimb.operator.configcore.flatconfig_to_rank quimb.operator.configcore.build_coo_numba_core quimb.operator.configcore.matvec_numba Module Contents --------------- .. py:data:: nogil :value: True .. py:data:: cache :value: True .. py:function:: _check_next_coupled_term(a, b, n, bi, bj, size_term, sizes_op, regs, xis, xjs, cijs) Calculate the next coupled config and coeff, or flag as zero if there is no coupled config. Inplace modifies the bj array. :param a: The index into the stacked terms. :type a: uint32 :param b: The index into the stacked operators. :type b: uint32 :param n: The total size of the flat configuration. :type n: int :param bi: The flat configuration to get the coupled configurations for. :type bi: ndarray[uint8] :param bj: The coupled flat configuration to be modified in place. :type bj: ndarray[uint8] :param size_term: The number of operators in this term. :type size_term: uint32 :param sizes_op: Flat array of number of entries for each operator, indexed by `a`. :type sizes_op: ndarray[uint8] :param regs: Flat array of registers in each term, indexed by `a`. :type regs: ndarray[uint32] :param xis: Flat array of input bits for each entry, indexed by `b`. :type xis: ndarray[uint8] :param xjs: Flat array of output bits for each entry, indexed by `b`. :type xjs: ndarray[uint8] :param cijs: Flat array of coefficients for each entry, indexed by `b`. :type cijs: ndarray :returns: * **a** (*int*) -- The updated index into the stacked terms. * **b** (*int*) -- The updated index into the stacked operators. * **valid** (*bool*) -- True if the coupled config is non-zero, False otherwise. * **hij** (*scalar*) -- The coefficient for the coupled config. .. py:function:: flatconfig_coupling_numba(flatconfig, coupling_map, dtype=np.float64) Get the coupled flat configurations for a given flat configuration and coupling map. Like applying the sparse matrix to a basis vector, or retrieving a single row. :param flatconfig: The flat configuration to get the coupled configurations for. :type flatconfig: ndarray[uint8] :param coupling_map: The operator defined as tuple of flat arrays. :type coupling_map: tuple[ndarray] :param dtype: The dtype to use for the coupled coefficients. Default is np.float64. :type dtype: {np.float64, np.complex128, np.float32, np.float64}, optional :returns: * **coupled_flatconfigs** (*ndarray[uint8]*) -- A list of coupled flat configurations, each with the corresponding coefficient. * **coeffs** (*ndarray[dtype]*) -- The coefficients for each coupled flat configuration. .. py:function:: flatconfig_to_rank_nosymm(flatconfig) Convert a flat config array to a rank, i.e. its position in the lexicographic ordering of all bitstrings of that length. :param flatconfig: A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8. :type flatconfig: array_like :rtype: int .. py:function:: rank_into_flatconfig_nosymm(flatconfig, r, n) Inplace conversion of a rank to a flat config array. :param flatconfig: A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten. :type flatconfig: array_like :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int .. py:function:: rank_to_flatconfig_nosymm(r, n) Convert a rank to a flat config array. :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int :returns: **flatconfig** -- A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8. :rtype: array_like .. py:function:: build_coo_numba_core_nosymm(n, coupling_map, dtype=np.float64, world_size=1, world_rank=0) Build sparse coo data in a unconstrained hilbert space. .. py:function:: matvec_nosymm(x, out, n, coupling_map, world_size=1, world_rank=0) .. py:function:: calculate_strides(sizes) .. py:function:: flatconfig_to_rank_mixed_radix_nosymm(flatconfig, strides) Convert a flat config array for a mixed size system to a rank, i.e. its position in the lexicographic ordering of all configurations. :param flatconfig: A flat config array of shape (n,), corresponding to a configuration. The array should be of dtype uint8. :type flatconfig: array_like :param strides: The strides array of shape (n,) The array should be of dtype uint64. :type strides: array_like :rtype: np.uint64 .. py:function:: rank_into_flatconfig_mixed_radix_nosymm(flatconfig, r, sizes, strides) Inplace conversion of a mixed-radix rank to a flat config array. :param flatconfig: A flat config array of shape (n,), corresponding to a configuration. The array should be of dtype uint8. :type flatconfig: array_like :param r: The rank to convert. :type r: np.uint64 :param sizes: The sizes of the configuration dimensions. :type sizes: array_like :param strides: The strides of the configuration dimensions. :type strides: array_like .. py:function:: rank_to_flatconfig_mixed_radix_nosymm(r, sizes, strides) -> numpy.ndarray Convert a mixed-radix rank to a flat config array. :param r: The rank to convert. :type r: np.uint64 :param sizes: The sizes of the configuration dimensions. :type sizes: array_like :param strides: The strides of the configuration dimensions. :type strides: array_like :returns: **flatconfig** -- A flat config array of shape (n,), corresponding to a configuration. The array will be of dtype uint8. :rtype: array_like .. py:function:: flatconfig_to_rank_z2(flatconfig) Convert a flat config array to a z2 rank, i.e. its position in the lexicographic ordering of all bitstrings of even or odd parity. :param flatconfig: A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8. :type flatconfig: array_like :rtype: int .. py:function:: rank_into_flatconfig_z2(flatconfig, r, n, p) Inplace conversion of a z2 rank to a flat config array. :param flatconfig: A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten. :type flatconfig: array_like :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int .. py:function:: rank_to_flatconfig_z2(r, n, p) Convert a z2 rank to a flat config array. :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int :param p: The parity of the flat config array. :type p: int :returns: **flatconfig** -- A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8. :rtype: array_like .. py:function:: build_coo_numba_core_z2(n, p, coupling_map, dtype=np.float64, world_size=1, world_rank=0) Build sparse coo data in a parity conserved hilbert space. .. py:function:: matvec_z2(x, out, n, p, coupling_map, world_size=1, world_rank=0) .. py:function:: build_pascal_table(nmax) Build the Pascal triangle table for the number of ways to choose k elements from n elements, i.e. the binomial coefficients. The table is of shape (nmax+1, nmax+1) and the entry at (n, k) is the number of ways to choose k elements from n elements. :param nmax: The maximum number of particles. :type nmax: int :returns: **pt** -- The Pascal triangle table of shape (nmax+1, nmax+1). :rtype: array_like .. py:function:: flatconfig_to_rank_u1_pascal(flatconfig, n, k, pt) Given a flat config array, return the u1 rank of the config in the lexicographic ordering of all bitstrings of that length with hamming weight k. :param flatconfig: A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8. :type flatconfig: array_like :param n: The total length of the flat config array. :type n: int :param k: The number of particles in the flat config array. :type k: int :param pt: The Pascal triangle table of shape containing at least (n, k). :type pt: array_like :returns: **r** -- The rank of the config in the lexicographic ordering. :rtype: int .. py:function:: rank_into_flatconfig_u1_pascal(flatconfig, r, n, k, pt) Inplace conversion of a rank to a flat config array with hamming weight k. :param flatconfig: A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten. :type flatconfig: array_like :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int :param k: The number of particles in the flat config array. :type k: int :param pt: The Pascal triangle table of shape containing at least (n, k). :type pt: array_like .. py:function:: rank_to_flatconfig_u1_pascal(r, n, k, pt) Convert a rank to a flat config array with hamming weight k. :param r: The rank to convert. :type r: int :param n: The total length of the flat config array. :type n: int :param k: The number of particles in the flat config array. :type k: int :param pt: The Pascal triangle table of shape containing at least (n, k). :type pt: array_like :returns: A flat config array of shape (n,), corresponding to a bitstring. :rtype: array_like .. py:function:: build_coo_numba_core_u1(n, k, coupling_map, dtype=np.float64, world_size=1, world_rank=0) Build sparse coo data in a number conserved hilbert space. .. py:function:: matvec_u1(x, out, n, k, coupling_map, world_size=1, world_rank=0) .. py:function:: flatconfig_to_rank_u1u1_pascal(flatconfig, na, ka, nb, kb, pt) Convert a flat config array to a doubly number conserved rank, i.e. its position in the ordering of all bitstrings of lenght `na + nb` with hamming weight `ka` and `kb` on each section respectively. :param flatconfig: A flat config array of shape (na + nb,), corresponding to a bitstring. The array should be of dtype uint8. :type flatconfig: array_like :param na: The total length of the first section of the flat config array. :type na: int :param ka: The hamming weight of the first section. :type ka: int :param nb: The total length of the second section of the flat config array. :type nb: int :param kb: The hamming weight of the second section. :type kb: int :param pt: The Pascal triangle table of shape containing at least max(na, nb). :type pt: array_like :returns: **r** -- The rank of the config in the lexicographic ordering. :rtype: int .. py:function:: rank_into_flatconfig_u1u1_pascal(flatconfig, r, na, ka, nb, kb, pt) Inplace conversion of a doubly number conserved rank to a flat config array. :param flatconfig: A input flat config array of shape (na + nb,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten. :type flatconfig: array_like :param r: The rank to convert. :type r: int :param na: The total length of the first section of the flat config array. :type na: int :param ka: The hamming weight of the first section. :type ka: int :param nb: The total length of the second section of the flat config array. :type nb: int :param kb: The hamming weight of the second section. :type kb: int :param pt: The Pascal triangle table of shape containing at least max(na, nb). :type pt: array_like .. py:function:: rank_to_flatconfig_u1u1_pascal(r, na, ka, nb, kb, pt) Convert a doubly number conserved rank to a flat config array. :param r: The rank to convert. :type r: int :param na: The total length of the first section of the flat config array. :type na: int :param ka: The hamming weight of the first section. :type ka: int :param nb: The total length of the second section of the flat config array. :type nb: int :param kb: The hamming weight of the second section. :type kb: int :param pt: The Pascal triangle table of shape containing at least max(na, nb). :type pt: array_like :returns: **flatconfig** -- A flat config array of shape (na + nb,), corresponding to a bitstring. The array will be of dtype uint8. :rtype: array_like .. py:function:: build_coo_numba_core_u1u1(na, ka, nb, kb, coupling_map, dtype=np.float64, world_size=1, world_rank=0) .. py:function:: matvec_u1u1(x, out, na, ka, nb, kb, coupling_map, world_size=1, world_rank=0) .. py:function:: rank_to_flatconfig(r, sector, symmetry=0, pt=None) Convert a rank to a flat config array. :param r: The rank to convert. :type r: int :param sector: Specifies the sector to convert. - (n,) for unconstrained hilbert space - (n, parity) for Z2 symmetry - (n, k) for U1 symmetry - (na, ka, nb, kb) for U1U1 symmetry :type sector: tuple[int] :param symmetry: Specifies the symmetry to use. 0 = "None", 1 = "Z2", 2 = "U1", 3 = "U1U1". Default is 0. :type symmetry: {0, 1, 2, 3}, optional :param pt: The Pascal triangle table of shape containing at least max(na, nb). If not provided, it will be built internally. This is only used for U1 and U1U1 hilbert spaces. :type pt: array_like, optional :returns: **flatconfig** -- A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8. :rtype: array_like .. py:function:: flatconfig_to_rank(flatconfig, sector, symmetry=0, pt=None) Convert a flat config array to a rank, i.e. its position in the lexicographic ordering of all bitstrings of that length. :param flatconfig: A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8. :type flatconfig: array_like :param sector: Specifies the sector to convert. - (n,) for unconstrained hilbert space - (n, parity) for Z2 symmetry - (n, k) for U1 symmetry - (na, ka, nb, kb) for U1U1 symmetry :type sector: tuple[int] :param symmetry: Specifies the symmetry to use. 0 = "None", 1 = "Z2", 2 = "U1", 3 = "U1U1". Default is 0. :type symmetry: {0, 1, 2, 3}, optional :param pt: The Pascal triangle table of shape containing at least max(na, nb). If not provided, it will be built internally. This is only used for U1 and U1U1 hilbert spaces. :type pt: array_like, optional :rtype: int .. py:function:: build_coo_numba_core(coupling_map, sector, symmetry=0, dtype=np.float64, world_size=1, world_rank=0) Build the data for a sparse matrix in COO format. :param coupling_map: The operator defined as tuple of flat arrays. :type coupling_map: tuple[ndarray] :param sector: Specifies the sector to convert. - (n,) for unconstrained hilbert space - (n, parity) for Z2 symmetry - (n, k) for U1 symmetry - (na, ka, nb, kb) for U1U1 symmetry :type sector: tuple[int] :param symmetry: Specifies the symmetry to use. 0 = "None", 1 = "Z2", 2 = "U1", 3 = "U1U1". Default is 0. :type symmetry: {0, 1, 2, 3}, optional :param dtype: The dtype to use for the data. Default is np.float64. :type dtype: {np.float64, np.complex128, np.float32, np.float64}, optional :param world_size: The number of processes in the world. Default is 1. Only rows corresponding to range(world_rank, D, world_size) will be computed. This is used for parallelization. :type world_size: int, optional :param world_rank: The rank of the current process. Default is 0. Only rows corresponding to range(world_rank, D, world_size) will be computed. This is used for parallelization. :type world_rank: int, optional :returns: * **data** (*ndarray[float64]*) -- The data for the sparse matrix in COO format. * **rows** (*ndarray[int64]*) -- The row indices for the sparse matrix in COO format. * **cols** (*ndarray[int64]*) -- The column indices for the sparse matrix in COO format. .. py:function:: matvec_numba(x, out, coupling_map, sector, symmetry=0, world_size=1, world_rank=0) Apply the operator defined by the coupling map to the input vector. :param x: The input vector to apply the operator to. :type x: ndarray[float64] :param out: The output vector to store the result. :type out: ndarray[float64] :param coupling_map: The operator defined as tuple of flat arrays. :type coupling_map: tuple[ndarray] :param sector: Specifies the sector to convert. - (n,) for unconstrained hilbert space - (n, parity) for Z2 symmetry - (n, k) for U1 symmetry - (na, ka, nb, kb) for U1U1 symmetry :type sector: tuple[int] :param symmetry: Specifies the symmetry to use. 0 = "None", 1 = "Z2", 2 = "U1", 3 = "U1U1". Default is 0. :type symmetry: {0, 1, 2, 3}, optional :param world_size: The number of processes in the world. Default is 1. Only rows corresponding to range(world_rank, D, world_size) will be computed. This is used for parallelization. :type world_size: int, optional :param world_rank: The rank of the current process. Default is 0. Only rows corresponding to range(world_rank, D, world_size) will be computed. This is used for parallelization. :type world_rank: int, optional