scf
=====

This option defines how to perform an SCF calculation

.. option:: charge

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - An integer
      * - Default
        - ``0``
      
   Define the total charge of the system.

.. option:: spin2p1

   .. list-table::
      :stub-columns: 1
      :widths: 5 20

      * - Value
        - An integer
      * - Default
        - ``1`` for even number of electrons
      * - 
        - ``2`` for odd number of electrons

   Define the spin multiplicity of the system, i.e., :math:`2S+1`, where :math:`S` is the spin of the system. For example, to consider the singlet and triplet state, one should set :option:`spin2p1` to ``1`` and ``3``, respectively.

   Note that :option:`spin2p1` can be either positive or **negative.** Both positive and negative :option:`spin2p1` represent the same spin multiplicity, but for a SCF wave function, alpha and beta orbitals will be occupied first, respectively. For example, for 11 electrons with :option:`spin2p1` being ``1``, there will be 6 alpha electrons and 5 beta electrons, like most quantum chemistry software does; but when :option:`spin2p1` is ``-1``, there will be 5 alpha electrons and 6 beta electrons.

   For odd number of electrons, a positive ``spin2p1`` will first occupy alpha orbitals. If you want the beta orbitals to be occupied first, use a negative ``spin2p1``. For example:

   .. code-block:: bash
    :linenos:

    scf
      charge  0
      spin2p1 3
    end
    mol
      H 0. 0. 0.
      H 0. 0. 1.
    end

   In this case, the molecule will have 2 alpha electrons and 0 beta ones. For another input:

   .. code-block:: bash
    :linenos:

    scf
      charge  0
      spin2p1 -3
    end
    mol
      H 0. 0. 0.
      H 0. 0. 1.
    end

   The molecule will have 2 beta electrons and 0 alpha ones.

.. option:: type

   .. list-table::
      :stub-columns: 1
      :widths: 5 20

      * - Value
        - ``R`` for restricted SCF (alpha and beta orbitals are restricted to be identical)
      * - 
        - ``U`` for unrestricted SCF (alpha and beta orbitals are not necessarily identical)
      * - Default
        - ``R`` for singlet state
      * - 
        - ``U`` for other states

   For singlet states, both restricted and unrestricted SCF are available. Unrestricted SCF is very useful in treating spin polarized systems. For non-singlet states, only the unrestricted one can be used.

.. option:: max_it

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - A non-negative integer
      * - Default
        - ``128``
      
   Define the maximum number of SCF iteration.

   .. HINT::
     You can set ``max_it`` to ``0`` to do a non-iterative calculation.

.. option:: energy_cov

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - A real number
      * - Default
        - ``1.E-6``
      
   The energy convergence threshold for SCF calculations. 

.. option:: density_cov

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - A real number
      * - Default
        - ``1.E-8``
      
   The density matrix convergence threshold for SCF calculations.

   .. HINT::
     The SCF calculation is determined to be convergent when both the energy and density convergence conditions are satisfied.

.. option:: nodiis
   
   Do not use direct inversion of the iterative subspace (DIIS) convergence acceleration algorithm. 

.. option:: print_MO
  
   Print molecular orbital coefficients. Without this, only molecular orbital energies and occupancies are printed.

.. option:: schwarz

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - A real number
      * - Default
        - ``1.E-10``
       
   Define the Schwarz screening tolerance. All two-electron integral contributions below this tolerance will be discarded to speed up calculations. A positive real number is needed. 

   .. WARNING::
     Do **not** set a too large value (like ``1.E-5``). It may leads to wrong results.

.. option::  do_tso
   
   Instead of doing ordinary SCF, do target state optimization (TSO) SCF. This is a powerful method for calculating excited and diabatic states. For theoretical details, please refer to:

   - `J. Chem. Theory Comput. 2023, 19, 6, 1777-1789 <https://pubs.acs.org/doi/10.1021/acs.jctc.2c01317>`_

   Tutorials of using TSO-DFT can be found here:

   - `TSO-DFT for Excited State Energies <http://qbics.info/tutorial/tsobasic.html>`_




.. ``temp``
   Default: ``0``.
   Define the electron temperature in Kelvin. A positive real number is needed.
   When non-zero temperature is given, the orbital occupation numbers may be fractional. It is useful for some open-shell systems whose SCF calculations are difficult to converge.