Basis input documentation
=========================

Initialize plane-wave basis with `ke_cutoff`.


Used to initialize class :class:`qimpy.dft.electrons.Basis`.

YAML template:
--------------

.. parsed-literal::

   :yamlparam:`qimpy.dft.electrons.Basis:ke-cutoff`: 20.0         :yamlcomment:`# Wavefunction kinetic energy cutoff in Hartrees.`
   :yamlparam:`qimpy.dft.electrons.Basis:real-wavefunctions`: :yamlkey:`no`  :yamlcomment:`# Whether to use real wavefunctions (instead of complex).`
   :yamlparam:`qimpy.dft.electrons.Basis:grid`:                   :yamlcomment:`# Override parameters of grid for wavefunction operations:`
     :yamlparam:`qimpy.grid.Grid:ke-cutoff`: :yamlkey:`null`       :yamlcomment:`# Kinetic-energy cutoff for grid in Hartrees.`
     :yamlparam:`qimpy.grid.Grid:shape`: :yamlkey:`null`           :yamlcomment:`# Explicit grid dimensions [Nx, Ny, Nz].`
                          
   :yamlparam:`qimpy.dft.electrons.Basis:fft-block-size`: 0       :yamlcomment:`# Number of wavefunction bands to FFT simultaneously.`
   :yamlparam:`qimpy.dft.electrons.Basis:mpi-block-size`: 0       :yamlcomment:`# Number of wavefunction bands to MPI transfer simultaneously.`

Component classes:
------------------

.. toctree::
    :maxdepth: 1

    Grid <qimpy.grid.Grid>

Parameters:
-----------

ke-cutoff
+++++++++

*Type:* :yamltype:`float`, *Default:*  20.0

Wavefunction kinetic energy cutoff in Hartrees.

real-wavefunctions
++++++++++++++++++

*Type:* :yamltype:`bool`, *Default:*  :yamlkey:`no`

Whether to use real wavefunctions (instead of complex).
This is only supported for non-spinorial, Gamma-point-only
calculations, where conjugate symmetry allows real wavefunctions.

grid
++++

*Type:* :doc:`Grid <qimpy.grid.Grid>`, *Default:*  :yamlkey:`null`

Override parameters of grid for wavefunction operations.

fft-block-size
++++++++++++++

*Type:* :yamltype:`int`, *Default:*  0

Number of wavefunction bands to FFT simultaneously.
Higher numbers require more memory, but can achieve
better occupancy of GPUs or high-core-count CPUs.
The default of 0 auto-selects the block size based on the number
of bands and k-points being processed by each process.

mpi-block-size
++++++++++++++

*Type:* :yamltype:`int`, *Default:*  0

Number of wavefunction bands to MPI transfer simultaneously.
Lower numbers may allow better overlap between computation and transfers,
which is beneficial if MPI implementation supports asynchronous progress
and/or CUDA streams are used to compute asynrchronously.
Higher numbers mitigate MPI latency, but may require more memory.
This number is automatically rounded up to nearest multiple of
`fft_block_size * comm.size`. The default of 0 selects the block size
based on the number of bands and k-points being processed by each process.