Fermion (qiskit_addon_sqd.fermion)

Functions for the study of fermionic systems.

class SCIState(amplitudes, ci_strs_a, ci_strs_b)[source]

The amplitudes and determinants describing a quantum state.

Parameters:
amplitudes: ndarray

An \(M \times N\) array where \(M =\) len(ci_strs_a) and \(N\) = len(ci_strs_b). amplitudes[i][j] is the amplitude of the determinant pair (ci_strs_a[i], ci_strs_b[j]).

ci_strs_a: ndarray

The alpha determinants.

ci_strs_b: ndarray

The beta determinants.

classmethod load(filename)[source]

Load an SCIState object from an .npz file.

save(filename)[source]

Save the SCIState object to an .npz file.

bitstring_matrix_to_ci_strs(bitstring_matrix, open_shell=False)[source]

Convert bitstrings (rows) in a bitstring_matrix into integer representations of determinants.

This function separates each bitstring in bitstring_matrix in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function.

Parameters:

  • bitstring_matrix (ndarray) – A 2D array of bool representations of bit values such that each row represents a single bitstring

  • open_shell (bool) – A flag specifying whether unique configurations from the left and right halves of the bitstrings should be kept separate. If False, configurations from the left and right halves of the bitstrings are combined into a single set of unique configurations. That combined set will be returned for both the left and right bitstrings.

Returns:

A length-2 tuple of determinant lists representing the right (spin-up) and left (spin-down) halves of the bitstrings, respectively.

Return type:

tuple[ndarray, ndarray]

enlarge_batch_from_transitions(bitstring_matrix, transition_operators)[source]

Apply the set of transition operators to the configurations represented in bitstring_matrix.

Parameters:

  • bitstring_matrix (ndarray) – A 2D array of bool representations of bit values such that each row represents a single bitstring.

  • transition_operators (ndarray) – A 1D or 2D array I, +, -, and n strings representing the action of the identity, creation, annihilation, or number operators. Each row represents a transition operator.

Returns:

Bitstring matrix representing the augmented set of electronic configurations after applying the excitation operators.

Return type:

ndarray

flip_orbital_occupancies(occupancies)[source]

Flip an orbital occupancy array to match the indexing of a bitstring.

This function reformats a 1D array of spin-orbital occupancies formatted like:

[occ_a_1, occ_a_2, ..., occ_a_N, occ_b_1, ..., occ_b_N]

To an array formatted like:

[occ_a_N, ..., occ_a_1, occ_b_N, ..., occ_b_1]

where N is the number of spatial orbitals.

Parameters:

occupancies (ndarray)

Return type:

ndarray

solve_fermion(bitstring_matrix, /, hcore, eri, *, open_shell=False, spin_sq=None, max_davidson=100, verbose=None)[source]

Approximate the ground state given molecular integrals and a set of electronic configurations.

Parameters:

  • bitstring_matrix (tuple[ndarray, ndarray] | ndarray) –

    A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of bool representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range (N, N/2], and the spin-down configurations should be specified by column indices in range (N/2, 0], where N is the number of qubits.

    (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively.

  • hcore (ndarray) – Core Hamiltonian matrix representing single-electron integrals

  • eri (ndarray) – Electronic repulsion integrals representing two-electron integrals

  • open_shell (bool) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If False, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces.

  • spin_sq (int | None) – Target value for the total spin squared for the ground state. If None, no spin will be imposed.

  • max_davidson (int) – The maximum number of cycles of Davidson’s algorithm

  • verbose (int | None) – A verbosity level between 0 and 10

Returns:

  • Minimum energy from SCI calculation

  • The SCI ground state

  • Average occupancy of the alpha and beta orbitals, respectively

  • Expectation value of spin-squared

Return type:

tuple[float, SCIState, list[ndarray], float]

optimize_orbitals(bitstring_matrix, /, hcore, eri, k_flat, *, open_shell=False, spin_sq=0.0, num_iters=10, num_steps_grad=10000, learning_rate=0.01, max_davidson=100)[source]

Optimize orbitals to produce a minimal ground state.

The process involves iterating over 3 steps:

For num_iters iterations:

  • Rotate the integrals with respect to the parameters, k_flat

  • Diagonalize and approximate the groundstate energy and wavefunction amplitudes

  • Optimize k_flat using gradient descent and the wavefunction amplitudes found in Step 2

Refer to Sec. II A 4 for more detailed discussion on this orbital optimization technique.

Parameters:

  • bitstring_matrix (tuple[ndarray, ndarray] | ndarray) –

    A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of bool representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range (N, N/2], and the spin-down configurations should be specified by column indices in range (N/2, 0], where N is the number of qubits.

    (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively.

  • hcore (ndarray) – Core Hamiltonian matrix representing single-electron integrals

  • eri (ndarray) – Electronic repulsion integrals representing two-electron integrals

  • k_flat (ndarray) – 1D array defining the orbital transform. This array will be reshaped to be of shape (# orbitals, # orbitals) before being used as a similarity transform operator on the orbitals. Thus len(k_flat)=# orbitals**2.

  • open_shell (bool) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If False, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces.

  • spin_sq (float) – Target value for the total spin squared for the ground state

  • num_iters (int) – The number of iterations of orbital optimization to perform

  • max_davidson (int) – The maximum number of cycles of Davidson’s algorithm to perform during diagonalization.

  • num_steps_grad (int) – The number of steps of gradient descent to perform during each optimization iteration

  • learning_rate (float) – The learning rate to use during gradient descent

Returns:

  • The groundstate energy found during the last optimization iteration

  • An optimized 1D array defining the orbital transform

  • Average orbital occupancy

Return type:

tuple[float, ndarray, list[ndarray]]

rotate_integrals(hcore, eri, k_flat)[source]

Perform a similarity transform on the integrals.

The transformation is described as:

\[\hat{\widetilde{H}} = \hat{U^{\dagger}}(k)\hat{H}\hat{U}(k)\]

For more information on how \(\hat{U}\) and \(\hat{U^{\dagger}}\) are generated from k_flat and applied to the one- and two-body integrals, refer to Sec. II A 4.

Parameters:

  • hcore (ndarray) – Core Hamiltonian matrix representing single-electron integrals

  • eri (ndarray) – Electronic repulsion integrals representing two-electron integrals

  • k_flat (ndarray) –

    1D array defining the orbital transform. Refer to Sec. II A 4 for more information on how these values are used to generate the transform operator.

Returns:

  • The rotated core Hamiltonian matrix

  • The rotated ERI matrix

Return type:

tuple[ndarray, ndarray]

bitstring_matrix_to_sorted_addresses(bitstring_matrix, open_shell=False)[source]

Convert a bitstring matrix into a sorted array of unique, unsigned integers.

This function separates each bitstring in bitstring_matrix in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function.

Deprecated since version 0.6.0: The function qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses() is deprecated as of qiskit-addon-sqd 0.6.0. It will be removed no sooner than qiskit-addon-sqd 0.9.0. Use the bitstring_matrix_to_ci_strs function.

Parameters:

  • bitstring_matrix (ndarray) – A 2D array of bool representations of bit values such that each row represents a single bitstring

  • open_shell (bool) – A flag specifying whether unique addresses from the left and right halves of the bitstrings should be kept separate. If False, addresses from the left and right halves of the bitstrings are combined into a single set of unique addresses. That combined set will be returned for both the left and right bitstrings.

Returns:

A length-2 tuple of sorted, unique determinants representing the left (spin-down) and right (spin-up) halves of the bitstrings, respectively.

Return type:

tuple[ndarray, ndarray]