pseudopotential
===============

This option defines the pseudopotentials used for quantum chemistry calculations. You can define pseudopotentials in several flexible ways.

.. contents::
   :local:

.. WARNING::
   ``pseudopotential`` **only** contains pseudopotential and does not contain any valence electron basis set information. You must assign basis sets in ``basis``. The valence basis and core pseudopotential **must match**. 

Below is a typical example. H is represented by a def2-TZVP basis set. For Au, the valence electrons are represented by a def2-TZVP basis set, and core electrons are repesented by def2-ecp, i.e. Stuggart-Cologne pseudopotential.

.. code-block:: bash
     :linenos:

     basis
       def2-TZVP
     end
     pseudopotential
       def2-ecp
     end
     # The Karlsruhe basis sets for Au was developed with Stuggart-Cologne pseudopotential. 
     mol
         Au 0. 0. 0.  # SDD+def2-TZVP
         H  0. 0. 1.  # def2-TZVP
     end

If you write it in this way:

.. code-block:: bash
     :linenos:
     
     # A wrong input!
     basis
       def2-TZVP
     end
     mol
         Au 0. 0. 0.
         H  0. 0. 1.
     end

Then, **no** pseudopotential is applied for any element!

Also, keep in mind that the valence basis and core pseudopotential **must match**. The following combinations are usually accepted:

.. list-table::
   :widths: 8 8
   :header-rows: 1
   
   * - Valence Basis Set
     - Pseudopotential
   * - def2-X
     - def2-ecp
   * - (aug-)cc-X-pp
     - cc-ecp
   * - lanlX
     - lanl-ecp

Using Built-in Pseudopotentials
--------------------------------

A lot of important pseudopotentials have been provided in a folder ``pseudopotential`` in the same path of Qbics. The files are named after their names well-known in computational chemistry community. For example, ``pseudopotential/def2-ecp`` contains the Stuggart-Cologne pseudopotentials. 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-ecp:

.. code-block:: bash
    :linenos:

    pseudopotential
      def2-ecp
    end

Qbics will extract pseudopotential information from ``pseudopotential/def2-ecp`` for all atoms that **have pseudopotentials**. For example, you molecule contains only C, H, N, Ce, and F. Since in ``pseudopotential/sdd``, there is only pseudopotential for Ce, then for C, H, N, and F, no pseudopotentials are applied.

Explicit Pseudopotential Definitions
-------------------------------------

You can also explicitly define your pseudopotentials. For example, you want to apply pseudopotentials for Rb and Sr, then their pseudopotentials can be defined in this way:

.. code-block:: bash
    :linenos:

    pseudopotential 
      RB     0
      RB-ECP     3     28
      f POTENTIAL
            1
      2      3.84311400          -12.31690000
      s-f POTENTIAL
            3
      2      5.03655100           89.50019800
      2      1.97084900            0.49376100
      2      3.84311400           12.31690000
      p-f POTENTIAL
            3
      2      4.25834100           58.56897400
      2      1.47070900            0.43179100
      2      3.84311400           12.31690000
      d-f POTENTIAL
            3
      2      3.02312700           26.22489800
      2      0.65038300            0.96283900
      2      3.84311400           12.31690000
      ****
      SR     0
      SR-ECP     3     28
      f POTENTIAL
            1
      2      4.63397500          -15.80599200
      s-f POTENTIAL
            3
      2      7.40007400          135.47943000
      2      3.60637900           17.53446300
      2      4.63397500           15.80599200
      p-f POTENTIAL
            3
      2      6.48486800           88.35970900
      2      3.28805300           15.39437200
      2      4.63397500           15.80599200
      d-f POTENTIAL
            3
      2      4.62284100           29.88898700
      2      2.24690400            6.65941400
      2      4.63397500           15.80599200
      ****
    end

The pseudopotential definition is of standard Gaussian94 format:

- The definition of the pseudopotential for each atom ends with 4 asterisks, i.e.  ``****``.
- The definition starts with the element name like ``Rb`` and a ``0``. Currently ``0`` has no meaning.
- Then, three parameters are given: pseudopotential name, maximum angular momentum, and number of core electrons.
- Then, the semi-local pseudopotential and local ones are listed. Each pseudopotential has the form :math:`\sum_{k=1}^{K}d_{kl}r^{n_{kl}}e^{-\xi_{kl}r^2}`:
  
  * The first line is a comment.
  * The contraction degree :math:`K`.
  * Then, each line defines the power :math:`n_{kl}` , the exponent :math:`\xi_{kl}`, and the contraction coefficient :math:`d_{kl}`. They are 3 real numbers.

.. hint:: 
    Note that many pseudopotentials in Gaussian94 format can be obtained from https://www.basissetexchange.org/. But, remember to replace ``D`` to ``E`` since the former is not recognized by Qbics. Also, add ``****`` between elements.

Using Self-defined Pseudopotential Files
------------------------------------------

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

.. code-block:: bash
     :linenos:

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