qdk_chemistry.utils.cubegen module

Generate cube files for molecular orbitals and electron densities.

qdk_chemistry.utils.cubegen.generate_cubefiles_from_orbitals(orbitals, output_folder=None, indices=None, grid_size=(40, 40, 40), margin=3.0, label_maker=None, backend='native')[source]

Generate volumetric cube data for molecular orbitals.

This method creates cube files containing the spatial distribution of molecular orbitals on a 3D grid. It supports both canonical and localized orbitals.

Parameters:

  • orbitals (Orbitals) – The orbitals object containing the molecular orbital coefficients and basis set

  • output_folder (str | Path | None) –

    The folder where the cube files will be saved.

    If None, files are not saved to temporary storage.

  • indices (list[int] | None) – Specific molecular orbital indices to generate cube files for. If None, all orbitals are processed.

  • grid_size (tuple) – The size of the grid in each dimension (nx, ny, nz). Default is (40, 40, 40).

  • margin (float) – The margin (in Bohr radii) to extend around molecule. Default is 3.

  • label_maker (Callable[[int], str] | None) –

    A function that takes an orbital index and returns a base label without the .cube extension.

    If None, files are labeled with the zero-based orbital index; orbital 0 generates orbital_0000.cube.

  • backend (str) –

    Which evaluator to use, either "native" (default) or "pyscf".

    The native backend evaluates the orbitals in process with gauXC and needs no third-party quantum chemistry package. The "pyscf" backend delegates to pyscf.tools.cubegen and is kept for comparison and for falling back if a difference is ever suspected. PySCF is not installed on Windows, so the "pyscf" backend is unavailable there and raises ImportError. PySCF conversion currently supports only spherical bases. Cartesian bases must use the native backend.

    Both backends place grid points identically: the origin is the nuclear bounding box corner minus margin, and the step is the padded extent divided by n - 1 along each axis. They also share the same atomic orbital ordering, so the same coefficient vector means the same thing to both.

Returns:

Paths or contents of the generated cube files.

Return type:

list[str] | dict[str, str]

Raises:

ValueError – If backend is not "native" or "pyscf", or if backend="pyscf" is requested for a Cartesian basis.