ffsim.sample_state_vector

ffsim.sample_state_vector(vec, *, norb=None, nelec=None, orbs=None, shots=1, concatenate=True, bitstring_type=BitstringType.STRING, seed=None)[source]

Sample bitstrings from a state vector.

Parameters:

  • vec (ndarray | StateVector) – The state vector to sample from.

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

  • nelec (int | tuple[int, int] | None) – Either a single integer representing the number of fermions for a spinless system, or a pair of integers storing the numbers of spin alpha and spin beta fermions.

  • orbs (Sequence[int] | tuple[Sequence[int], Sequence[int]] | None) – The spin-orbitals to sample. In the spinless case (when nelec is an integer), this is a list of integers ranging from 0 to norb. In the spinful case, this is a pair of lists of such integers, with the first list storing the spin-alpha orbitals and the second list storing the spin-beta orbitals. If not specified, then all spin-orbitals are sampled.

  • shots (int) – The number of bitstrings to sample.

  • concatenate (bool) – Whether to concatenate the spin-alpha and spin-beta parts of the bitstrings. If True, then a single list of concatenated bitstrings is returned. The strings are concatenated in the order \(s_b s_a\), that is, the alpha string appears on the right. If False, then two lists are returned, (strings_a, strings_b). Note that the list of alpha strings appears first, that is, on the left. In the spinless case (when nelec is an integer), this argument is ignored.

  • bitstring_type (BitstringType) – The desired type of bitstring output.

  • seed (Generator | int | None) – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Returns:

The sampled bitstrings, as a list of strings of length shots.

Raises:

  • TypeError – When passing vec as a Numpy array, norb and nelec must be specified.

  • TypeError – When passing vec as a StateVector, norb and nelec must both be None.