scfguess
========

This option defines the initial guess of SCF calculations.

.. contents::
   :local:

.. option:: type

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - ``hcore`` Will use the eigenvectors of the core matrix as initial guess. Usually, its performance is very bad
      * -  
        - ``atmden`` Will use the superposition of converged densities of all atoms in the system as initial guess. It is recommended for most cases
      * -
        - ``fragden`` Will use the superposition of converged densities of fragments assigned by you as initial guess. This can be used for TSO or treating symmetry-broken systems
      * - 
        - ``mwfn`` Will read a wave function from a MWFN file as initial guess
      * - 
        - ``tso`` Will use a reference state (assigned with ``frag``) to perform TSO calculation (assigned with ``orb``). This is only used for TSO calculations
      * - Default
        - ``atmden``

   Define the type of initial guess. In most cases, ``atmden`` is recommended. ``mwfn`` which reads a guess from a converged SCF is also a good choice.

   For target state optimization (TSO), symmetry-broken, or other special calculations, ``fragden`` can be used.

.. option:: file

   .. list-table::
      :stub-columns: 1
      :widths: 5 20
   
      * - Value
        - A file name
      * - Default
        - job name + ``.mwfn``

   When ``type`` is ``mwfn``,  Qbics will read wave function with using mwfn file name.
   
   When ``type`` is ``tso``, Qbics will save reference wave function using this mwfn file name.

.. option:: frag

  This defines atomic fragments for initial guess. The format is: 
  
  ``frag num_electrons spin_multiplicity atom_range``
  
  There can be arbitrary number of fragments, but all atoms must be included once and only once. They are only activated when ``type`` is ``fragden``.
  
  For example:
  
  .. code-block:: bash
    :linenos:

    scfguess
       type fragden
       frag 0 1 1-9
       frag 0 -3 10-15 18
       frag -1 3 16 17
    end
  
  In this case, the molecule is decomposed into 3 fragments: (1) atom 1,2,3,4,5,6,7,8,9, with charge 0 and spin multiplicity 1; (2) atom 10,11,12,13,14,15,18, with charge 0 and spin multiplicity 3 (beta orbitals occupied first); (3) atom 16,17, with charge -1 and spin multiplicity 3.

  For this guess, Qbics will perform 3 SCF calculations for all fragments, then superpose them as the initial guess for the SCF of the whole molecule. This can be used for ordinary, symmetry-broken, or TSO SCF. 

  .. HINT::
    The total charge of fragments does not have to be the same as the total system.


  .. HINT::
    Please refer to the keyword ``do_tso`` in :doc:`scf` for more details about TSO, when you want to use ``frag``.


.. option:: orb

  This defines the orbitals for initial guess. The format is:
  
  ``orb num_electrons spin_multiplicity  alpha_MO_indices : beta_MO_indices``
  
  There can be arbitrary number of orbital spaces, but all orbitals must be included once and only once. They are only activated when ``type`` is ``mwfn``.

  For example:
  
  .. code-block:: bash
    :linenos:

    scfguess
       type mwfn
       file x.mwfn
       orb 12 1 1-6 : 1-6
       orb 2 1 7 : 8
       orb 0 1 8 : 7
    end
  
  In this case, the orbitals will be read from ``x.mwfn`` and 3 orbital spaces are defined: (1) alpha orbital 1,2,3,4,5,6 and beta orbital 1,2,3,4,5,6, with 12 electron and spin multiplicity 1; (2) alpha orbital 7 and beta orbital 8, with 2 electrons and spin multiplicity 1; (3) alpha orbital 8 and beta orbital 7 with 0 electron and spin multiplicity 1 (since no electrons in this orbital space, actually spin multiplicity can be arbitrary).

  For this guess, Qbics will read orbitals from ``x.mwfn`` and assign occupation according to ``orb``, then do the following ordinary or TSO SCF calculations.
  
  Also, note that in this keyword, orbital order **matters**. For example,

  .. code-block:: bash
    :linenos:

    scfguess
       type mwfn
       file x.mwfn
       orb 14 1 1-6 9 7 8 10-25 : 1-6 9 7 8 10-25
    end
  
  In this case, the 7 alpha and 7 beta electrons will occupy orbital 1,2,3,4,5,6,9.


  .. HINT::
    Please refer to the keyword ``do_tso`` in :doc:`scf` for more details about TSO, when you want to use ``orb``.