solve_hci

solve_hci(hcore, eri, *, norb, nelec, ci_strs=None, spin_sq=0.0, select_cutoff=0.0005, energy_tol=1e-10, max_iter=10, mpirun_options=None, temp_dir=None, clean_temp_dir=True)[source]

Approximate the ground state of a molecular Hamiltonian using the heat bath configuration interaction method.

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, sci_strings, avg_occs = solve_hci(..., 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:

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

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

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

  • nelec (tuple[int, int]) – The numbers of spin up and spin down electrons.

  • ci_strs (tuple[Sequence[int], Sequence[int]] | None) – CI strings specifying the subspace to use at the beginning of the first HCI iteration. Should be specified as a pair of lists, with the first list containing the alpha strings and the second list containing the beta strings. If not specified, only the Hartree-Fock string will be used. A CI string is specified as an integer whose binary expansion encodes the string. For example, the Hartree-Fock string with 3 electrons in 5 orbitals is 0b00111.

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

  • select_cutoff (float) – Cutoff threshold for retaining state vector coefficients.

  • energy_tol (float) – Energy floating point tolerance.

  • max_iter (int) – The maximum number of HCI iterations to perform.

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