quimb.operator.configcore¶

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¶

`nogil`
`cache`

Functions¶

`_check_next_coupled_term`(a, b, n, bi, bj, size_term, ...)	Calculate the next coupled config and coeff, or flag as zero if
`flatconfig_coupling_numba`(flatconfig, coupling_map[, ...])	Get the coupled flat configurations for a given flat configuration
`flatconfig_to_rank_nosymm`(flatconfig)	Convert a flat config array to a rank, i.e. its position in the
`rank_into_flatconfig_nosymm`(flatconfig, r, n)	Inplace conversion of a rank to a flat config array.
`rank_to_flatconfig_nosymm`(r, n)	Convert a rank to a flat config array.
`build_coo_numba_core_nosymm`(n, coupling_map[, dtype, ...])	Build sparse coo data in a unconstrained hilbert space.
`matvec_nosymm`(x, out, n, coupling_map[, world_size, ...])
`calculate_strides`(sizes)
`flatconfig_to_rank_mixed_radix_nosymm`(flatconfig, strides)	Convert a flat config array for a mixed size system to a rank, i.e. its
`rank_into_flatconfig_mixed_radix_nosymm`(flatconfig, r, ...)	Inplace conversion of a mixed-radix rank to a flat config array.
`rank_to_flatconfig_mixed_radix_nosymm`(→ numpy.ndarray)	Convert a mixed-radix rank to a flat config array.
`flatconfig_to_rank_z2`(flatconfig)	Convert a flat config array to a z2 rank, i.e. its position in the
`rank_into_flatconfig_z2`(flatconfig, r, n, p)	Inplace conversion of a z2 rank to a flat config array.
`rank_to_flatconfig_z2`(r, n, p)	Convert a z2 rank to a flat config array.
`build_coo_numba_core_z2`(n, p, coupling_map[, dtype, ...])	Build sparse coo data in a parity conserved hilbert space.
`matvec_z2`(x, out, n, p, coupling_map[, world_size, ...])
`build_pascal_table`(nmax)	Build the Pascal triangle table for the number of ways to choose k
`flatconfig_to_rank_u1_pascal`(flatconfig, n, k, pt)	Given a flat config array, return the u1 rank of the config in the
`rank_into_flatconfig_u1_pascal`(flatconfig, r, n, k, pt)	Inplace conversion of a rank to a flat config array with hamming weight
`rank_to_flatconfig_u1_pascal`(r, n, k, pt)	Convert a rank to a flat config array with hamming weight k.
`build_coo_numba_core_u1`(n, k, coupling_map[, dtype, ...])	Build sparse coo data in a number conserved hilbert space.
`matvec_u1`(x, out, n, k, coupling_map[, world_size, ...])
`flatconfig_to_rank_u1u1_pascal`(flatconfig, na, ka, nb, ...)	Convert a flat config array to a doubly number conserved rank, i.e.
`rank_into_flatconfig_u1u1_pascal`(flatconfig, r, na, ...)	Inplace conversion of a doubly number conserved rank to a flat config
`rank_to_flatconfig_u1u1_pascal`(r, na, ka, nb, kb, pt)	Convert a doubly number conserved rank to a flat config array.
`build_coo_numba_core_u1u1`(na, ka, nb, kb, coupling_map)
`matvec_u1u1`(x, out, na, ka, nb, kb, coupling_map[, ...])
`rank_to_flatconfig`(r, sector[, symmetry, pt])	Convert a rank to a flat config array.
`flatconfig_to_rank`(flatconfig, sector[, symmetry, pt])	Convert a flat config array to a rank, i.e. its position in the
`build_coo_numba_core`(coupling_map, sector[, symmetry, ...])	Build the data for a sparse matrix in COO format.
`matvec_numba`(x, out, coupling_map, sector[, symmetry, ...])	Apply the operator defined by the coupling map to the input vector.

Module Contents¶

quimb.operator.configcore.nogil = True¶

quimb.operator.configcore.cache = True¶

quimb.operator.configcore._check_next_coupled_term(a, b, n, bi, bj, size_term, sizes_op, regs, xis, xjs, cijs)[source]¶

Calculate the next coupled config and coeff, or flag as zero if there is no coupled config. Inplace modifies the bj array.

Parameters:

a (uint32) – The index into the stacked terms.
b (uint32) – The index into the stacked operators.
n (int) – The total size of the flat configuration.
bi (ndarray[uint8]) – The flat configuration to get the coupled configurations for.
bj (ndarray[uint8]) – The coupled flat configuration to be modified in place.
size_term (uint32) – The number of operators in this term.
sizes_op (ndarray[uint8]) – Flat array of number of entries for each operator, indexed by a.
regs (ndarray[uint32]) – Flat array of registers in each term, indexed by a.
xis (ndarray[uint8]) – Flat array of input bits for each entry, indexed by b.
xjs (ndarray[uint8]) – Flat array of output bits for each entry, indexed by b.
cijs (ndarray) – Flat array of coefficients for each entry, indexed by b.

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.

quimb.operator.configcore.flatconfig_coupling_numba(flatconfig, coupling_map, dtype=np.float64)[source]¶

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.

Parameters:

flatconfig (ndarray[uint8]) – The flat configuration to get the coupled configurations for.
coupling_map (tuple[ndarray]) – The operator defined as tuple of flat arrays.
dtype ({np.float64, np.complex128, np.float32, np.float64}, optional) – The dtype to use for the coupled coefficients. Default is np.float64.

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.

quimb.operator.configcore.flatconfig_to_rank_nosymm(flatconfig)[source]¶

Convert a flat config array to a rank, i.e. its position in the lexicographic ordering of all bitstrings of that length.

Parameters:: flatconfig (array_like) – A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8.
Return type:: int

quimb.operator.configcore.rank_into_flatconfig_nosymm(flatconfig, r, n)[source]¶

Inplace conversion of a rank to a flat config array.

Parameters:

flatconfig (array_like) – A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten.
r (int) – The rank to convert.
n (int) – The total length of the flat config array.

quimb.operator.configcore.rank_to_flatconfig_nosymm(r, n)[source]¶

Convert a rank to a flat config array.

Parameters:

r (int) – The rank to convert.
n (int) – The total length of the flat config array.

Returns:

flatconfig – A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8.

Return type:

array_like

quimb.operator.configcore.build_coo_numba_core_nosymm(n, coupling_map, dtype=np.float64, world_size=1, world_rank=0)[source]¶: Build sparse coo data in a unconstrained hilbert space.

quimb.operator.configcore.matvec_nosymm(x, out, n, coupling_map, world_size=1, world_rank=0)[source]¶

quimb.operator.configcore.calculate_strides(sizes)[source]¶

quimb.operator.configcore.flatconfig_to_rank_mixed_radix_nosymm(flatconfig, strides)[source]¶

Convert a flat config array for a mixed size system to a rank, i.e. its position in the lexicographic ordering of all configurations.

Parameters:

flatconfig (array_like) – A flat config array of shape (n,), corresponding to a configuration. The array should be of dtype uint8.
strides (array_like) – The strides array of shape (n,) The array should be of dtype uint64.

Return type:

np.uint64

quimb.operator.configcore.rank_into_flatconfig_mixed_radix_nosymm(flatconfig, r, sizes, strides)[source]¶

Inplace conversion of a mixed-radix rank to a flat config array.

Parameters:

flatconfig (array_like) – A flat config array of shape (n,), corresponding to a configuration. The array should be of dtype uint8.
r (np.uint64) – The rank to convert.
sizes (array_like) – The sizes of the configuration dimensions.
strides (array_like) – The strides of the configuration dimensions.

quimb.operator.configcore.rank_to_flatconfig_mixed_radix_nosymm(r, sizes, strides) → numpy.ndarray[source]¶

Convert a mixed-radix rank to a flat config array.

Parameters:

r (np.uint64) – The rank to convert.
sizes (array_like) – The sizes of the configuration dimensions.
strides (array_like) – The strides of the configuration dimensions.

Returns:

flatconfig – A flat config array of shape (n,), corresponding to a configuration. The array will be of dtype uint8.

Return type:

array_like

quimb.operator.configcore.flatconfig_to_rank_z2(flatconfig)[source]¶

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.

Parameters:: flatconfig (array_like) – A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8.
Return type:: int

quimb.operator.configcore.rank_into_flatconfig_z2(flatconfig, r, n, p)[source]¶

Inplace conversion of a z2 rank to a flat config array.

Parameters:

flatconfig (array_like) – A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten.
r (int) – The rank to convert.
n (int) – The total length of the flat config array.

quimb.operator.configcore.rank_to_flatconfig_z2(r, n, p)[source]¶

Convert a z2 rank to a flat config array.

Parameters:

r (int) – The rank to convert.
n (int) – The total length of the flat config array.
p (int) – The parity of the flat config array.

Returns:

flatconfig – A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8.

Return type:

array_like

quimb.operator.configcore.build_coo_numba_core_z2(n, p, coupling_map, dtype=np.float64, world_size=1, world_rank=0)[source]¶: Build sparse coo data in a parity conserved hilbert space.

quimb.operator.configcore.matvec_z2(x, out, n, p, coupling_map, world_size=1, world_rank=0)[source]¶

quimb.operator.configcore.build_pascal_table(nmax)[source]¶

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.

Parameters:: nmax (int) – The maximum number of particles.
Returns:: pt – The Pascal triangle table of shape (nmax+1, nmax+1).
Return type:: array_like

quimb.operator.configcore.flatconfig_to_rank_u1_pascal(flatconfig, n, k, pt)[source]¶

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.

Parameters:

flatconfig (array_like) – A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8.
n (int) – The total length of the flat config array.
k (int) – The number of particles in the flat config array.
pt (array_like) – The Pascal triangle table of shape containing at least (n, k).

Returns:

r – The rank of the config in the lexicographic ordering.

Return type:

int

quimb.operator.configcore.rank_into_flatconfig_u1_pascal(flatconfig, r, n, k, pt)[source]¶

Inplace conversion of a rank to a flat config array with hamming weight k.

Parameters:

flatconfig (array_like) – A input flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten.
r (int) – The rank to convert.
n (int) – The total length of the flat config array.
k (int) – The number of particles in the flat config array.
pt (array_like) – The Pascal triangle table of shape containing at least (n, k).

quimb.operator.configcore.rank_to_flatconfig_u1_pascal(r, n, k, pt)[source]¶

Convert a rank to a flat config array with hamming weight k.

Parameters:

r (int) – The rank to convert.
n (int) – The total length of the flat config array.
k (int) – The number of particles in the flat config array.
pt (array_like) – The Pascal triangle table of shape containing at least (n, k).

Returns:

A flat config array of shape (n,), corresponding to a bitstring.

Return type:

array_like

quimb.operator.configcore.build_coo_numba_core_u1(n, k, coupling_map, dtype=np.float64, world_size=1, world_rank=0)[source]¶: Build sparse coo data in a number conserved hilbert space.

quimb.operator.configcore.matvec_u1(x, out, n, k, coupling_map, world_size=1, world_rank=0)[source]¶

quimb.operator.configcore.flatconfig_to_rank_u1u1_pascal(flatconfig, na, ka, nb, kb, pt)[source]¶

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.

Parameters:

flatconfig (array_like) – A flat config array of shape (na + nb,), corresponding to a bitstring. The array should be of dtype uint8.
na (int) – The total length of the first section of the flat config array.
ka (int) – The hamming weight of the first section.
nb (int) – The total length of the second section of the flat config array.
kb (int) – The hamming weight of the second section.
pt (array_like) – The Pascal triangle table of shape containing at least max(na, nb).

Returns:

r – The rank of the config in the lexicographic ordering.

Return type:

int

quimb.operator.configcore.rank_into_flatconfig_u1u1_pascal(flatconfig, r, na, ka, nb, kb, pt)[source]¶

Inplace conversion of a doubly number conserved rank to a flat config array.

Parameters:

flatconfig (array_like) – A input flat config array of shape (na + nb,), corresponding to a bitstring. The array should be of dtype uint8, it will be overwritten.
r (int) – The rank to convert.
na (int) – The total length of the first section of the flat config array.
ka (int) – The hamming weight of the first section.
nb (int) – The total length of the second section of the flat config array.
kb (int) – The hamming weight of the second section.
pt (array_like) – The Pascal triangle table of shape containing at least max(na, nb).

quimb.operator.configcore.rank_to_flatconfig_u1u1_pascal(r, na, ka, nb, kb, pt)[source]¶

Convert a doubly number conserved rank to a flat config array.

Parameters:

r (int) – The rank to convert.
na (int) – The total length of the first section of the flat config array.
ka (int) – The hamming weight of the first section.
nb (int) – The total length of the second section of the flat config array.
kb (int) – The hamming weight of the second section.
pt (array_like) – The Pascal triangle table of shape containing at least max(na, nb).

Returns:

flatconfig – A flat config array of shape (na + nb,), corresponding to a bitstring. The array will be of dtype uint8.

Return type:

array_like

quimb.operator.configcore.build_coo_numba_core_u1u1(na, ka, nb, kb, coupling_map, dtype=np.float64, world_size=1, world_rank=0)[source]¶

quimb.operator.configcore.matvec_u1u1(x, out, na, ka, nb, kb, coupling_map, world_size=1, world_rank=0)[source]¶

quimb.operator.configcore.rank_to_flatconfig(r, sector, symmetry=0, pt=None)[source]¶

Convert a rank to a flat config array.

Parameters:

r (int) – The rank to convert.
sector (tuple[int]) –
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
symmetry ({0, 1, 2, 3}, optional) – Specifies the symmetry to use. 0 = “None”, 1 = “Z2”, 2 = “U1”, 3 = “U1U1”. Default is 0.
pt (array_like, optional) – 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.

Returns:

flatconfig – A flat config array of shape (n,), corresponding to a bitstring. The array will be of dtype uint8.

Return type:

array_like

quimb.operator.configcore.flatconfig_to_rank(flatconfig, sector, symmetry=0, pt=None)[source]¶

Convert a flat config array to a rank, i.e. its position in the lexicographic ordering of all bitstrings of that length.

Parameters:

flatconfig (array_like) – A flat config array of shape (n,), corresponding to a bitstring. The array should be of dtype uint8.
sector (tuple[int]) –
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
symmetry ({0, 1, 2, 3}, optional) – Specifies the symmetry to use. 0 = “None”, 1 = “Z2”, 2 = “U1”, 3 = “U1U1”. Default is 0.
pt (array_like, optional) – 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.

Return type:

int

quimb.operator.configcore.build_coo_numba_core(coupling_map, sector, symmetry=0, dtype=np.float64, world_size=1, world_rank=0)[source]¶

Build the data for a sparse matrix in COO format.

Parameters:

coupling_map (tuple[ndarray]) – The operator defined as tuple of flat arrays.
sector (tuple[int]) –
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
symmetry ({0, 1, 2, 3}, optional) – Specifies the symmetry to use. 0 = “None”, 1 = “Z2”, 2 = “U1”, 3 = “U1U1”. Default is 0.
dtype ({np.float64, np.complex128, np.float32, np.float64}, optional) – The dtype to use for the data. Default is np.float64.
world_size (int, optional) – 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.
world_rank (int, optional) – 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.

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.

quimb.operator.configcore.matvec_numba(x, out, coupling_map, sector, symmetry=0, world_size=1, world_rank=0)[source]¶

Apply the operator defined by the coupling map to the input vector.

Parameters:

x (ndarray[float64]) – The input vector to apply the operator to.
out (ndarray[float64]) – The output vector to store the result.
coupling_map (tuple[ndarray]) – The operator defined as tuple of flat arrays.
sector (tuple[int]) –
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
symmetry ({0, 1, 2, 3}, optional) – Specifies the symmetry to use. 0 = “None”, 1 = “Z2”, 2 = “U1”, 3 = “U1U1”. Default is 0.
world_size (int, optional) – 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.
world_rank (int, optional) – 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.