.. tip::
    All input files can be downloaded: :download:`Files <https://zhjun-sci.com/qbics/input_library/keywords-basis.tar.gz>`.

basis
=================

.. contents::
   :local:

This keyword defines the basis functions used for quantum chemical calculations. You can define basis sets in several flexible ways.

Using Built-in Basis Sets
-------------------------

A lot of important basis sets have been provided in a directory ``basis`` in the same path of Qbics. The files are named after their names well-known in computational chemistry community. For example, ``basis/cc-pvdz`` contains the cc-pVDZ basis. All files are named in small cases.

To use them, simple write down the basis set name. It is **case-insensitive.** For example, to use def2-TZVP for all atoms:

.. code-block:: bash
    :linenos:

    basis
      def2-TZVP
    end

Qbics will extract basis set information from ``basis/def2-tzvp``.

Explicit Basis Set Definitions
------------------------------

You can also explicitly define your own basis sets. For example, your system contains two elements, H and Li, then their basis sets can be defined in this way:

.. code-block:: bash
    :linenos:

    basis 
      H     0
      S   3   1.00
            13.0107010             0.19682158E-01
            1.9622572              0.13796524
            0.4445379              0.47831935
      S   1   1.00
            0.12194962             1.0000000
      P   1   1.00
            0.8000000              1.0000000
      ****
      Li     0
      S   5   1.00
            266.27785516           0.64920150325E-02
            40.069783447           0.47747863215E-01
            9.0559944389           0.20268796111
            2.4503009051           0.48606574817
            0.72209571855          0.43626977955
      S   1   1.00
            0.52810884721E-01      1.0000000
      S   1   1.00
            0.20960948798E-01      1.0000000
      P   2   1.00
            1.4500000              0.2586000
            0.3000000              1.0000000
      P   1   1.00
            0.0820000              1.0000000
      ****
    end
    
The analyitcal expression of Gaussian basis function is: 

.. math::
  
  \chi(\mathbf{r}) = A_{L}(\mathbf{r})\sum_{k=1}^{K} C_k e^{-\alpha_k r_A^2}

Here, :math:`A_{L}(\mathbf{r})` is the angular part with angular momentum quantum number :math:`L`, :math:`K` is the contraction degree, :math:`\alpha_k` is the exponent, :math:`C_k` is the contraction coefficient, and :math:`\mathbf{A}` is the atom position.

The basis set definition is of standard Gaussian94 format:

- The definition of the basis set for each atom ends with 4 asterisks, i.e.  ``****``.
- The definition starts with the element name like ``Li`` and a ``0``. Currently ``0`` has no meaning.
- Then, each GTO shell is defined. The shell definition starts with three parameters:  

  * Angular momentum :math:`L`. It can be any nonnegative numbers like ``0``, ``5``, or one of ``S``, ``P``, ``D``, ``F``, ``G``, ``H``, and ``I``.
  * Contraction degree :math:`K`. It must be a positive integer.
  * A real number. Currently it has no meaning.
  * Then, each line defines the exponent :math:`\alpha_k` and contraction coefficient :math:`C_k` of the primitive GTO to be contracted. They are 2 real numbers.

For more about basis function expressions, please refer to :doc:`basinfo`.

.. hint:: 
    Basis sets in Gaussian94 format can be obtained from several websites. But, remember to replace ``D`` to ``E`` since the former is not recognized by Qbics.

    - https://www.basissetexchange.org/
    - https://www.cosmologic-services.de/basis-sets/basissets.php
    - https://comp.chem.umn.edu/basissets/basis.cgi
    - http://www.grant-hill.group.shef.ac.uk/ccrepo/index.html

Using Self-defined Basis Set Files
----------------------------------

You can also put your explicit basis set definitions into some files, say ``/home/zhang/userdef/my-own-basis``. Qbics will automatically read it if you give explicit file name including path.

.. code-block:: bash
     :linenos:

     basis
       /home/zhang/userdef/my-own-basis
     end 

The format can be found in ``basis`` directory.

Define Different Basis Sets for Different Elements
---------------------------------------------------

If you want to use different basis set s for different elements, then you can write ``element`` in the first line, then write element and basis set file name line by line. For example:

.. code-block:: bash
     :linenos:

      basis
        element # This indicates that Qbics will assign basis set element by element.
        O aug-cc-pvtz
        C cc-pvtz
        N /home/zhang/userdef/my-own-basis
      end

Theoretical Background
-------------------------

.. hint:: 
    To determine what basis set you should use, the following guidelines are recommended:
    
    - Nowadays, nobody uses STO-nG or basis sets without polarization functions like ``6-31g``, unless you really know what you are doing.
    - For systems with strongly delocalized electrons, use diffuse basis sets, like ``6-31+g(d)`` or ``aug-cc-pvDZ``.
    - To consider core-excitations or strong core-valence interactions, use (aug-)cc-p(W)CVnZ.
    - To get accurate energies, use triple-zeta basis sets or better, like ``6-311g(d)``, ``def2-TZVP`` or ``cc-pVTZ``.
    - For non-relativistic calculations, use basis set with pseudopotentials instead of all-electron ones. For example, it is better to use cc-pVDZ-PP for Cu than using cc-pVDZ.

Karlsruhe Basis Sets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Karlsruhe family (def2-) is a versatile and widely used series of basis sets in quantum chemistry, particularly effective for calculations involving heavy elements and systems requiring efficient computational performance. **For elements ≥ Rb,** def2- basis sets incorporate **pseudopotentials** to reduce computational cost while maintaining high accuracy for valence electron properties.

.. attention::
   
   These basis sets for **elements ≥ Rb** must be used together with corresponding ``def2-ECP`` pseudopotentials! See :ref:`example` below.

In Qbics, the following Karlsruhe basis sets are available:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to
   * - ``def2-svp`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La-Lu
   * - ``def2-tzvp`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La-Lu
   * - ``def2-tzvpp`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La-Lu
   * - ``def2-qzvp`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La-Lu
   * - ``def2-qzvpp`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La-Lu
   * - ``def2-svpd`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La
   * - ``def2-tzvpd`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La
   * - ``def2-tzvppd`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La
   * - ``def2-qzvpd`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La
   * - ``def2-qzvppd`` 
     -  H-Xe, Cs-Ba, Hf-Rn, La
   
Here:

  - ``pp``: Adds additional polarization functions on both heavy and hydrogen atoms.
  - ``pd``: Adds diffuse functions on both heavy and hydrogen atoms.
  - ``ppd``: Adds diffuse functions and additional polarization functions on both heavy and hydrogen atoms.

Dunning Correlation-Consistent Basis Sets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Dunning correlation-consistent basis sets are high-precision basis sets widely used in quantum chemistry, particularly for systems with significant electron correlation. These basis sets aim to ensure consistent treatment of electron correlation across different levels of precision, offering **reliable and accurate** results. They are recommended for **high-precision calculations** and **excitated states**.

In Qbics, the following Dunning correlation-consistent basis sets are available:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to   
   * - ``cc-pVDZ``
     - H-He, Li-Ne, Na-Ar, Ca-Kr
   * - ``cc-pVTZ``
     - H-He, Li-Ne, Na-Ar, Ca-Kr
   * - ``cc-pVQZ``       
     - H-He, Li-Ne, Na-Ar, Ca-Kr
   * - ``cc-pCVDZ``      
     - Li-Ne, Na-Ar, Ca
   * - ``cc-pCVTZ``      
     - Li-Ne, Na-Ar, Ca
   * - ``cc-pCVQZ``      
     - Li-Ne, Na-Ar, Ca
   * - ``cc-pwCVDZ``     
     - B-Ne, Al-Ar
   * - ``cc-pWCVTZ``     
     - B-Ne, Al-Ar, Sc-Zn
   * - ``cc-pWCVQZ``     
     - B-Ne, Al-Ar, Sc-Zn, Br
   * - ``aug-cc-pVDZ``   
     - H-Ar, Sc-Kr
   * - ``aug-cc-pVTZ``   
     - H-Ar, Sc-Kr
   * - ``aug-cc-pVQZ``   
     - H-Ar, Sc-Kr
   * - ``aug-cc-pCVDZ``  
     - Li-Ne, Na-Ar
   * - ``aug-cc-pCVTZ``  
     - Li-Ne, Na-Ar
   * - ``aug-cc-pCVQZ``  
     - Li-Ne, Na-Ar
   * - ``aug-cc-pWCVDZ`` 
     - B-Ne, Al-Ar
   * - ``aug-cc-pWCVTZ`` 
     - B-Ne, Al-Ar
   * - ``aug-cc-pWCVQZ`` 
     - B-Ne, Al-Ar

Here:

  - ``aug``: Adds diffuse functions on heavy and hydrogen atoms.
  - ``c``: Adds tight basis functions for core electrons.
  - ``wc``: Adds tighter basis functions for core electrons. 

Dunning Correlation-Consistent Basis Sets with Pseudopotentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Dunning correlation-consistent basis sets with pseudopotentials simplify calculations for heavy elements by replacing core electrons with pseudopotentials. This reduces computational costs while retaining high accuracy for valence electron interactions.

.. attention::
   
   These basis sets must be used together with corresponding ``cc-ECP`` pseudopotentials! See :ref:`example` below.

In Qbics, the following Dunning correlation-consistent basis sets with pseudopotentials are available:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to   
   * - ``cc-pVDZ-PP``       
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``cc-pVTZ-PP``       
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``cc-pVQZ-PP``       
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``cc-pWCVDZ-PP``     
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``cc-pWCVTZ-PP``     
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``cc-pWCVQZ-PP``     
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pVDZ-PP``   
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pVTZ-PP``   
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pVQZ-PP``   
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pWCVDZ-PP`` 
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pWCVTZ-PP`` 
     - Cu-Kr, Y-Xe, Hf-Rn
   * - ``aug-cc-pWCVQZ-PP`` 
     - Cu-Kr, Y-Xe, Hf-Rn

Pople Basis Sets
^^^^^^^^^^^^^^^^^^^^^^

Pople basis sets are widely used in quantum chemical calculations to describe the electronic structure of molecules. These basis sets provide an effective balance between computational efficiency and accuracy for molecules containing H-Ca.

In Qbics, the following Pople basis sets are available:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to
   * - ``3-21G``
     - H-Xe, Cs             
   * - ``4-31G``
     - H-He, B-Ne, P-Cl     
   * - ``6-31G``
     - H-Zn
   * - ``6-31G(d)``, ``6-31G(d,p)``
     - H-Kr                      
   * - ``6-31G(2df,p)``, ``6-31G(3df,3pd)``                             
     - H-Ar                 
   * - ``6-31+G``, ``6-31+G(d)``, ``6-31+G(d,p)``
     - H-Ar                 
   * - ``6-31++G``, ``6-31++G(d)``, ``6-31++G(d,p)``
     - H-Ar                 
   * - ``6-311G``, ``6-311G(d)``, ``6-311G(d,p)``
     - H-Ar, K-Ca, Ga-Kr, I 
   * - ``6-311G(2df,2pd)``
     - H-Ne, K-Ca           
   * - ``6-311+G``, ``6-311+G(d)``, ``6-311+G(d,p)``, ``6-311+G(2d,p)``
     - H-Ar, K-Ca           
   * - ``6-311++G``, ``6-311++G(d)``, ``6-311++G(d,p)``, ``6-311++G(2d,2p)``
     - H, Li-Ar, K-Ca       
   * - ``6-311++G(3df,3pd)``
     - H, Li-Ar             

Here:

  - ``(d)``: Adds 1 set of *d* functions on heavy atoms.
  - ``(d,p)``: Adds 1 set of *d* functions on heavy atoms and 1 set of *p* functions on hydrogens.
  - ``+``: Adds *s* and *p* diffuse functions on heavy atoms.
  - ``++``: Adds *s* and *p* diffuse functions on heavy atoms and *s* diffuse functions on hydrogens.
  - ``(2df,p)``: Adds 2 sets of *d* functions and 1 set of *f* functions on heavy atoms, and 2 sets of *p* functions on hydrogens.

STO-nG Basis Sets
^^^^^^^^^^^^^^^^^^^^^^

In STO-nG basis sets, each atomic orbital is described by a single-Zeta basis set, where *n* Gaussian functions are used to approximate a Slater orbital. This design provides a compact and efficient representation of atomic wavefunctions.

In Qbics, the following STO-nG basis sets are available:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to
   * - ``sto-2g``, ``sto-3g``, ``sto-4g``, ``sto-5g``, ``sto-6g``
     - H-Xe

Los Alamos National Laboratory Pseudopotentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Los Alamos National Laboratory (LANL) basis sets are tailored for simplifying quantum chemistry calculations involving heavy elements. For all **elements ≥ Na,** pseudopotentials are used.

.. attention::
   
   These basis sets for elements ≥ Na must be used together with corresponding ``lanl-ECP`` pseudopotentials! See :ref:`example` below.

In Qbics, the following LANL basis sets are available, listed below:

.. list-table::  
   :header-rows: 1

   * - Basis set
     - Applied to
   * - ``LANL2DZ``
     - H, Li-Xe, Cs-Bi, La, U-Pu
   * - ``LANL2DZdp``
     - H, C-F, Si-Cl, Ge-Br, Sn-I, Pb-Bi
   * - ``LANL08``
     - Na-Xe, Cs-Bi, La
   * - ``LANL08+``
     - Sc-Zn
   * - ``LANL08(d)``
     - Si-Cl, Ge-Br, Sn-I, Pb-Bi
   * - ``LANL08(f)``
     - Sc-Cu, Y-Ag, Hf-Au, La
   * - ``LANL2TZ``
     - Sc-Zn, Y-Cd, Hf-Hg, La
   * - ``LANL2TZ+``
     - Sc-Zn
   
Here:

  - ``+``: Adds *d* diffuse functions.
  - ``d`` or ``f``: Adds *d* or *f* polarization functions.

.. _example:

Input Examples
-------------------------

Some examples are also given in :doc:`pseudopotential`.

Example: CuH with cc-pvDZ and cc-pvDZ-PP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Below we show a calculation for CuH with all-electron correlation-consistent basis set and correlation-consistent basis set with pseudopotential. The first is an all-electron one:

.. code-block:: bash
    :linenos:
    :caption: basis-1.inp

    # All electrons for CuH.
    basis
        cc-pvdz
    end
    
    mol
       Cu     -0.00000000     -0.00000000     -0.23939021
        H      0.00000000      0.00000000      1.23939021
    end
    
    task
        opt b3lyp
    end

We can see output:

.. code-block:: bash
    :linenos:
    :caption: basis-1.out 

    SCF Structure:
     # of electrons:       30
     # of alpha electrons: 15
     # of beta electrons:  15

The number of electrons is 30. The optimized structure has a bond length of 1.48 Angstrom.
   
Now we use pseudopotential:

.. code-block:: bash
    :linenos:
    :caption: basis-2.inp

    # Pseudopotentials for Cu, all-electrons for H.
    basis
        element
        Cu cc-pvdz-pp
        H  cc-pvdz
    end
    
    pseudopotential
       cc-ecp
    end
    
    mol
       Cu     -0.00000000     -0.00000000     -0.23939021
        H      0.00000000      0.00000000      1.23939021
    end
    
    task
        opt b3lyp
    end
    
We can see output:

.. code-block:: bash
    :linenos:
    :caption: basis-2.out 

    SCF Structure:
     # of electrons:       20
     # of alpha electrons: 10
     # of beta electrons:  10

The number of electrons is 20, 10 electrons of Cu (Ne core) were replaced by pseudopotential. The optimized structure has a bond length of 1.46 Angstrom.

Example: AuH with Karlsruhe Basis Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Calculate AuH with Karlsruhe basis set:

.. code-block:: bash
    :linenos:
    :caption: basis-3.inp
    
    basis
        def2-TZVP
    end
    
    pseudopotential
       def2-ecp # If there are elements >= Rb, this must be used!
    end
    
    mol
       Au     0. 0. 0.
        H     0. 0. 1.5
    end
    
    task
        opt b3lyp
    end

Example: AgI with LANL Basis Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Optimize the structure of AgI with LANL basis set:

.. code-block:: bash
    :linenos:
    :caption: basis-4.inp
    
    basis
       lanl2dz 
    end
        
    pseudopotential
        lanl-ecp # For LANL basis set, this should always be set.
    end
        
    mol
       Ag     0. 0. 0.
        I     0. 0. 1.5
    end
      
    task
        opt b3lyp
    end

See the output:

.. code-block:: bash
    :linenos:
    :caption: basis-4.out 
    
    SCF Structure:
     # of electrons:       26
     # of alpha electrons: 13
     # of beta electrons:  13

The number of electrons is 26, so 74 electrons were replaced by pseudopotential. The optimized structure has a bond length of 2.65 Angstrom.