..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    :
    : --

.. _user_occupation_model:

The Occupation Model in PyBEST
###############################

In PyBEST, the number of occupied orbitals (for the restricted and unrestricted case) is
specified using the :py:class:`~pybest.scf.occ.OccModel` class. In the current
version, the charge of a molecule is defined by the difference between the
number of electrons in (singly or doubly occupied) orbitals and the sum of the
atomic numbers of all atoms in the molecule.
Specifically, there are three different occupation models implemented.

.. _user_occ_aufbau:

The Aufbau occupation model
===========================

In most electronic structure calculations, this occupation model will be first
and most decent choice. The orbitals are occupied according to the Aufbau
principle, that is, the energetically lowest-lying orbitals become occupied.
To initialize the occupation model, create an instance of the 
:py:class:`~pybest.scf.occ.AufbauOccModel` class.
The number of doubly- or singly-occupied orbitals is passed as an argument,

.. code-block:: python

    # restricted case (six alpha and six beta electrons)
    occ_model = AufbauOccModel(6)
    # unrestricted case (four alpha and three beta electrons)
    occ_model = AufbauOccModel(4, 3)


.. _user_occ_fixed:

The fixed occupation model
==========================

The :py:class:`~pybest.scf.occ.FixedOccModel` freezes the occupation numbers
to some pre-defined value.
The occupations are passed as a one-dimensional numpy array,

.. code-block:: python

    # restricted case
    occ_model = FixedOccModel(np.array([1.0, 1.0, 1.0, 0.5, 0.5, 0.0]))
    # unrestricted case
    occ_model = FixedOccModel(np.array([1.0, 1.0, 1.0, 0.5, 0.5, 0.0]), np.array([1.0, 0.7, 1.0, 0.0, 0.0, 0.3]))


.. _user_occ_fermi:

The Fermi occupation model
==========================

In case of convergence difficulties in HF calculations, the Fermi-smearing
method can be applied to fill up the orbitals [rabuck1999]_.

.. code-block:: python

    # restricted case (six alpha and six beta electrons, 300K)
    occ_model = FermiOccModel(6, temperature=300)
    # unrestricted case (four alpha and three beta electrons, 500K)
    occ_model = FermiOccModel(4, 3, temperature=500)

Note that at the end of an SCF calculation that exploited Fermi smearing, a
conventional calculation using the Aufbau occupation model should be performed.

.. note::

    Currently, post-HF calculations only support the Aufbau occupation model.
    The fixed and Fermi occupation models are only supported in SCF calculations
    (UHF and RHF).