solve_dice

solve_dice(addresses, active_space_path, working_dir, spin_sq=0.0, max_davidson=100, clean_working_dir=True, mpirun_options=None)[source]

Approximate the ground state given an active space and Slater determinant addresses.

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_dice(..., mpirun_options=mpirun_opts)

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

Note

Only closed-shell systems are currently supported. The particle number for both spin-up and spin-down determinants is expected to be equal.

Note

Determinant addresses are interpreted by the Dice command line application as 5-byte unsigned integers; therefore, only systems of 40 or fewer orbitals are supported.

Parameters:

  • addresses (tuple[Sequence[int], Sequence[int]]) – A length-2 tuple of Sequence containing base-10, unsigned integer representations of bitstrings. The first Sequence represents configurations of the alpha particles, and the second Sequence represents that of the beta particles.

  • active_space_path (str | Path) – An absolute path to an FCI dump – a format partially defined in Knowles and Handy 1989.

  • working_dir (str | Path) – An absolute path to a directory in which intermediate files can be written to and read from.

  • spin_sq (float) – 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 method to perform.

  • clean_working_dir (bool) – A flag indicating whether to remove the intermediate files used by the Dice command line application. If False, the intermediate files will be left in a temporary directory in the working_dir.

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

Returns:

Minimum energy from SCI calculation, SCI coefficients, and average orbital occupancy for spin-up and spin-down orbitals

Return type:

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