fulqrum.core.Subspace

class Subspace

Hashmap representation of a quantum subspace over bit-strings obtained from sampling on a quantum computer (or simulator).

Parameters:

• subspace_strs –

  Input bitstrings as either length-1 or length-2 tuple (or list of list(s)).

  Two modes of input to subspace is supported: 1. Half-string mode: In this mode, the input subspace_strs to the Subspace() is a length-2 tuple[list[str], list[str]], where the first element represents _alpha_ strings, and the second one represents _beta_ strings. Internally, fulqrum will sort each list and perform a Cartesian product between the two lists to construct the full subspace. A full bitstring will be represented by beta half str + alpha half str, and the final length of subspace bitstring will be len(beta half string) + len(alpha half string). For example, [[‘100’, ‘001, ‘010’], [‘110’, ‘000’]] is a valid input subspace_strs in half-string mode. The final subspace size will be 2 * 3 = 6, with each bitstrings with 3 + 3 = 6 characters/bits. This mode is useful for chemistry applications.

  2. Full-string mode: In this mode, subspace_strs has to be length-1 tuple[list[str]]. In this mode, no Cartesian product is taken internally, and the supplied _full_ bitstrings are used as is after sorting.

• reserve_multiplier (float) – We reserve a capacity for the Hash table that stores the subspace bit-strings, typically equal to the number of bit-strings. This argument allows a user to reserve more capacity than needed. While it consumes, more memory, it reduces collision during Hash table look-up leading to minor speed-up. Default: 2.

• use_all_bitset_blocks (bool) – If use_all_bitset_blocks=False, only first block of a bitset is used in hashing. If your bitsets are long and rarely share common prefixes, setting it to False speeds up execution. However, it likely that bitsets for practical cases will share common patterns. In that case, set use_all_bitset_blocks to True so that the whole bitset is used in the hash function. Although hashing n (> 1) blocks is slower than hashing a single block, full hashing usually leads to fewer collisions during Hash table look-up. Default: True.

Example:

import fulqrum as fq

num_qubits = 5
bitstrings = []
for val in range(2**num_qubits):
    bitstrings.append(bin(val)[2:].zfill(num_qubits))

fq.Subspace([bitstrings])

<Subspace: size=32, width=5, num_buckets=128, use_all_bitset_blocks=True>

Methods

copy(self)	Return a copy of subspace
get_bitset_index(self, Bitset bitset)	Return the index of the given Bitset.
get_bitstring_index(self, str bitstring)	Return the index of the given bitstring.
get_n_th_bitstring(self, size_t n)	Return n-th bitstring in the Subspace
get_orbital_occupancies(self, double[, int norb)	Computes orbital occupancies of electrons.
size(self)	Size (dimensionality) of subspace
to_dict(self, str key_type=)	Converts Subspace to a dictionary

Attributes

interpret_vector

Convert solution vector into dict of counts and complex amplitudes

copy(self)

Return a copy of subspace

Returns:

Subspace

get_bitset_index(self, Bitset bitset)

Return the index of the given Bitset.

Return value is max(size_t) if bitset not in subspace

Returns:

Index

Return type:

size_t

get_bitstring_index(self, str bitstring)

Return the index of the given bitstring.

Return value is max(size_t) if bitset not in subspace

Parameters:

bitstring (str) – The bitstring as Python str type.

Returns:

Index if the bitstring is found. None: If the bitstring is not found.

Return type:

size_t

get_n_th_bitstring(self, size_t n)

Return n-th bitstring in the Subspace

Parameters:

n (size_t) – Index of the expected bitstring.

Returns:

N-th bitstring in the subspace. Note that, both Python

dictionary and emhash8::HashMap retains the insertion order.

Return type:

str

get_orbital_occupancies(self, double[::1] probs, int norb)

Computes orbital occupancies of electrons.

Parameters:

• probs (np.ndarray) – Probabilities of each basis vector of a wavefunction. It must be the absolute value squared of an eigenvector, which represents amplitudes of each basis vector (Slated determinant) in a wavefunction.

• norb (int) – The number of spatial orbitals.

Returns:

Orbital occupanies as a length-2 tuple of 1D np.ndarrays. It is formatted as ([a0, ..., aN], [b0, ..., bN]).

interpret_vector

Convert solution vector into dict of counts and complex amplitudes

Parameters:

• vec (ndarray) – Complex solution vector

• atol (double) – Absolute tolerance for truncation, default=1e-12

• sort (int) – Sort output dict by integer representation.

• renormalize (bool) – Renormalize values such that probabilities sum to one, default = True

Returns:

Dictionary with bit-string keys and complex values

Return type:

dict

Notes

Truncation can be disabled by calling atol=0

size(self)

Size (dimensionality) of subspace

Returns:

int

to_dict(self, str key_type='bitset')

Converts Subspace to a dictionary

Parameters:

key_type (str) – Type of key data to return, default=’bitset’

Returns:

dict