solve_fermion

solve_fermion(bitstring_matrix, /, hcore, eri, *, open_shell=False, mpirun_options=None, temp_dir=None, clean_temp_dir=True)[source]

Approximate the ground state of a molecular Hamiltonian given a bitstring matrix defining the Hilbert subspace.

This solver is designed for compatibility with qiskit-addon-sqd workflows.

In order to leverage the multi-processing nature of this tool, the user must specify the CPU resources to use via the mpirun_options argument.

For example, to use 8 CPU slots in parallel in quiet mode:

# Run 8 parallel slots in quiet mode
mpirun_opts = "-quiet -n 8"
# OR
mpirun_opts = ["-quiet", "-n", "8"]

energy, sci_coeffs, avg_occs = solve_fermion(..., mpirun_options=mpirun_opts)

For more information on the mpirun command line options, refer to the man page.

Note

Determinants are interpreted by the Dice command line application as 16-byte unsigned integers; therefore, only systems of 128 or fewer orbitals are supported.

Parameters:

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

    A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized.

    This may be specified in two ways:

    A bitstring matrix: A 2D numpy.ndarray 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.

    CI strings: A length-2 tuple of sequences containing integer representations of the spin-up and spin-down determinants, respectively.

    The expected ordering is ([a_str_0, ..., a_str_N], [b_str_0, ..., b_str_M]).

  • 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.

  • mpirun_options (Sequence[str] | str | None) –

    Options controlling the CPU resource allocation for the Dice command line application. These command-line options will be passed directly to the mpirun command line application during invocation of Dice. These may be formatted as a Sequence of strings or a single string. If a Sequence, the elements will be combined into a single, space-delimited string and passed to mpirun. If the input is a single string, it will be passed to mpirun as-is. If no mpirun_options are provided by the user, Dice will run on a single MPI slot. For more information on the mpirun command line options, refer to the man page.

  • temp_dir (str | Path | None) – An absolute path to a directory for storing temporary files. If not provided, the system temporary files directory will be used.

  • clean_temp_dir (bool) – Whether to delete intermediate files generated by the Dice command line application. These files will be stored in a directory created inside temp_dir. If False, then this directory will be preserved.

Returns:

  • Minimum energy from SCI calculation

  • Approximate ground state from SCI

  • Average orbital occupancy

Return type:

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