forte2.orbitals.cube_generator
==============================

.. py:module:: forte2.orbitals.cube_generator






Module Contents
---------------

.. py:function:: write_orbital_cubes(system, C, indices=None, prefix='orbital', filepath='.', format=('cube', ), spacing=0.2, padding=4.0)

   
   A convenience function to write cube files for molecular orbitals.


   :Parameters:

       **system** : forte2.system.System
           The system object containing the molecular information.

       **C** : NDArray
           The molecular orbital coefficients matrix.

       **indices** : List[int], optional, default=None
           The indices (zero-based) of the orbitals to generate cube files for.
           By default all orbitals are generated.

       **prefix** : str, optional, default="orbital"
           The prefix for the cube file names.

       **filepath** : str, optional, default="."
           The directory to save the cube files in.

       **format** : Tuple[str, ...] or str, optional, default=("cube",)
           Output formats to generate. Supported values:
             - "cube": standard CUBE files. For two-component systems, writes
               separate alpha and beta magnitude files ("_a.cube" and "_b.cube").
             - "2ccube": two-component cube files (".2ccube"). For two-component
               systems only, writes four datasets consecutively per orbital in the
               order: alpha real, alpha imag, beta real, beta imag.
           Multiple formats can be requested at once, e.g., formats=("cube","2ccube").

       **spacing** : float, optional, default=0.2
           The spacing between grid points in the cube file (in bohr).

       **padding** : float, optional, default=4.0
           The extra space (in bohr) added in all directions around the atoms when generating the grid.














   ..
       !! processed by numpydoc !!

.. py:function:: simple_grid(atoms, spacing: tuple[float, float, float], padding: tuple[float, float, float])

   
   Create a simple cubic grid around the given atoms.


   :Parameters:

       **atoms** : List[Tuple[int, Tuple[float, float, float]]]
           List of atoms, each represented as a tuple (Z, (x, y, z)).

       **spacing** : Tuple[float, float, float]
           The spacing between grid points in the x, y, and z directions.

       **padding** : Tuple[float, float, float]
           The amount of padding (extra space) to add to the grid in the x, y, and z directions around the atoms when generating the grid.



   :Returns:

       **grid_origin** : Tuple[float, float, float]
           The origin of the grid.

       **npoints** : Tuple[int, int, int]
           The number of grid points in the x, y, and z directions.

       **scaled_axes** : List[Tuple[float, float, float]]
           The scaled axes for the grid.











   ..
       !! processed by numpydoc !!

.. py:class:: CubeGenerator(spacing=0.2, padding=4.0)

   
   Class to generate cube files from a given set of molecular orbitals.


   :Parameters:

       **spacing** : float, optional, default=0.2
           The spacing between grid points in the cube file (in bohr).

       **padding** : float, optional, default=4.0
           The extra space (in bohr) added in all directions around the atoms when generating the grid.














   ..
       !! processed by numpydoc !!

   .. py:attribute:: spacing


   .. py:attribute:: padding


   .. py:method:: write_cubes(system, C, indices=None, prefix='orbital', filepath='.', formats=('cube', )) -> None

      
      Generate cube files for the given orbitals.

      This method generates cube files for the specified molecular orbitals
      represented by the coefficient matrix `C`. The cube files are saved in the
      specified directory with the given prefix. The files are named as:

          {prefix}_{index:0{number_of_digits}d}.cube

      where `index` is the zero-based index of the orbital and `number_of_digits` is
      determined by the maximum index to ensure proper zero-padding.

      :Parameters:

          **system** : forte2.system.System
              The system object containing the molecular information.

          **C** : NDArray
              The molecular orbital coefficients matrix.

          **indices** : List[int], optional, default=None
              The indices (zero-based) of the orbitals to generate cube files for.
              By default all orbitals are generated.

          **prefix** : str, optional, default="orbital"
              The prefix for the cube file names.

          **filepath** : str, optional, default="."
              The directory to save the cube files in.

          **formats** : Tuple[str, ...], optional, default=("cube",)
              Output formats to generate. Supported values:
                - "cube": standard CUBE files. For two-component systems, writes
                  separate alpha and beta magnitude files ("_a.cube" and "_b.cube").
                - "2ccube": two-component cube files (".2ccube"). For two-component
                  systems only, writes four datasets consecutively per orbital in the
                  order: alpha real, alpha imag, beta real, beta imag.
              Multiple formats can be requested at once, e.g., formats=("cube","2ccube").














      ..
          !! processed by numpydoc !!