..
: 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 various :py:class:`~pybest.occ_model.occ_base.OccupationModel` classes. In the current
version, the number of occupied orbitals in atoms and molecules (doubly and singly occupied orbitals) is
assigned using a :py:class:`~pybest.gbasis.pybasis.Basis` instance.
The charge and/or the number of unpaired electrons can be specified separately.
By default PyBEST always assumes a closed-shell system with either doubly occupied or unoccupied
orbitals (restricted orbitals; even number of electrons) or one unpaired electron
(unrestricted orbitals; odd number of electrons), which will be placed in an alpha orbital.
Specifically, there are five different occupation models implemented.
Each occupation model is explained in detail below.
Alternatively, an occupation number instance can be created from a
:py:class:`~pybest.linalg.base.LinalgFactory` instance. In this case,
we need to specify the total number of electrons or occupation pattern explicitly.
This feature has to be chosen for model Hamiltonians or for external Hamiltonians
(that is, one- and two-electron integrals) not generated in PyBEST.
See :ref:`user_occ_examples` for examples.
The input structure for all supported occupation models is similar. To
create an instance, do as follows if a :py:class:`~pybest.gbasis.pybasis.Basis`
instance ``gobasis`` is present,
.. code-block:: python
# assuming a gobasis instance ``gobasis``
# initialize some occupation model ``OccModel`` using default settings
occ_model = OccModel(gobasis)
while, for a :py:class:`~pybest.linalg.base.LinalgFactory` instance ``lf``,
the total number of electrons needs to be specified using the keyword argument
``nel``,
.. code-block:: python
# assuming an lf instance ``lf`` with 10 electrons
# initialize some occupation model ``OccModel`` using default settings
occ_model = OccModel(lf, nel=10)
Note that ``OccModel`` is used as an example and encodes one of the supported occupation model
classes of PyBEST mentioned below. It does not represent any class implementation in PyBEST.
All supported occupation models share some common features and functionality.
For instance, they can be defined for restricted and unrestricted orbitals.
The table below summarizes the most important arguments and keyword arguments
supported in each class.
.. |check| unicode:: u+2705
+-----------------------+----------------------+----------------------------------------------------------+
| | Occupation | Arguments | Keyword Arguments |
| model class +-----------+----------+----------+---------+---------------+---------+-----------+
| | gobasis | lf | charge | alpha | unrestricted | ncore | nel |
+=======================+===========+==========+==========+=========+===============+=========+===========+
| AufbauOccModel | |check| | |check| | |check| | |check| | |check| | |check| | |check| |
+-----------------------+-----------+----------+----------+---------+---------------+---------+-----------+
| FixedOccModel | |check| | |check| | |check| | | |check| | |check| | |
+-----------------------+-----------+----------+----------+---------+---------------+---------+-----------+
| FermiOccModel | |check| | |check| | |check| | |check| | |check| | |check| | |check| |
+-----------------------+-----------+----------+----------+---------+---------------+---------+-----------+
| FractionalOccModel | |check| | |check| | |check| | | |check| | |check| | |
+-----------------------+-----------+----------+----------+---------+---------------+---------+-----------+
| AufbauSpinOccModel | |check| | |check| | |check| | | fixed | |check| | |check| |
+-----------------------+-----------+----------+----------+---------+---------------+---------+-----------+
The keyword argument ``nel`` has to be specified if an ``lf`` instance is passed to
create an occupation number instance. It can only be omitted if the occupation
model uses different keyword arguments to specify the occupation pattern of
orbitals (more details on how to specify occupation patterns are given in
each occupation model subsection).
Below, each argument and keyword argument is explained.
:gobasis: (Basis) an instance of :py:class:`~pybest.gbasis.pybasis.Basis`.
It contains the information on the total number of electrons
:lf: (Linalg) an instance of :py:class:`~pybest.linalg.base.LinalgFactory`.
It does **NOT** contain any information on the total number of electrons.
Thus, ``nel`` (or any other occupation pattern) needs to be specified.
:charge: (int) the total charge of the system
:alpha: (int) number of unpaired electrons
:unrestricted: (boolean) enforce unrestricted occupiations for both
even and odd numbers of electrons
:ncore: (int) the number of frozen core orbitals. The same value for alpha and beta
orbitals is assumed. They are not allowed to differ.
:nel: (int) the total number of electrons. Only mandatory if an ``lf`` instance
is passed and for selected occupation models (if occupations are not
specified otherwise).
.. note::
Currently, post-HF calculations only support the Aufbau occupation model.
All other occupation models are only supported in SCF calculations
(UHF and RHF).
The occupation module not only stores information on the occupation pattern of the orbitals
but also all information concerning active orbital spaces.
The current version of PyBEST only supports frozen core orbitals. By defining a frozen
core using some occupation model, all attributes are set accordingly.
This includes the number of active orbitals ``nact``, the number of active occupied
orbitals ``nacto``, and the number of active virtual orbitals ``nactv``.
All attributes are stored in an instance of some occupation model class.
To specify a frozen core, the ``ncore`` keyword argument has to be set during
initialization,
.. code-block:: python
# assuming a gobasis instance ``gobasis``
# initialize some occupation model ``OccModel`` with three frozen core orbitals
occ_model = OccModel(gobasis, ncore=3)
# assuming an lf instance ``lf`` with 10 electrons
# initialize some occupation model ``OccModel`` with three frozen core orbitals
occ_model = OccModel(lf, nel=10, ncore=3)
.. _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.occ_model.AufbauOccModel` class.
The number of doubly- or singly-occupied orbitals is determined from a
:py:class:`~pybest.gbasis.pybasis.Basis` instance as follows
- Even number of electrons: restricted orbitals
- Odd number of electrons: unrestricted orbitals with 1 electron in an
alpha orbital
.. code-block:: python
# assuming a gobasis instance ``gobasis``
# initialize an instance of the AufbauOccModel using default settings
occ_model = AufbauOccModel(gobasis)
The default assignment of doubly occupied and singly occupied orbitals can
be overwritten using the following keyword arguments
:charge: (int) the total charge of the system
:alpha: (int) number of unpaired electrons
:unrestricted: (boolean) enforce unrestricted occupations even for an
even number of electrons
The examples listed below (see :ref:`user_occ_examples`) demonstrate how
each keyword argument is used to specify the occupation pattern of a
molecule or a model Hamiltonian.
Alternatively, an instance of the :py:class:`~pybest.occ_model.AufbauOccModel`
can be created from a :py:class:`~pybest.linalg.LinalgFactory` instance.
To do so, the :py:class:`~pybest.gbasis.pybasis.Basis` instance ``gobasis`` has
to be replaced by a :py:class:`~pybest.linalg.LinalgFactory` instance ``lf``.
In addition, we have to specify the total number of electrons otherwise,
the initialization of the :py:class:`~pybest.occ_model.AufbauOccModel` will
raise an error.
.. code-block:: python
# defining some LinalgFactory instance with ten orbitals
lf = DenseLinalgFactory(10)
# initialize an instance of the AufbauOccModel using an lf instance
# the total number of electrons is specified using nel
# we assume four electrons
occ_model = AufbauOccModel(lf, nel=4)
Each :py:class:`~pybest.occ_model.occ_base.OccupationModel` offers the feature
to specify the number of frozen core orbitals which are used in post-HF
modules.
:ncore: (int) the number of frozen core orbitals. The same value for alpha and beta
orbitals is assumed. They are not allowed to differ.
.. code-block:: python
# assuming a gobasis instance ``gobasis``
# initialize an instance of the AufbauOccModel using default settings
# enforce four frozen core orbitals
occ_model = AufbauOccModel(gobasis, ncore=4)
.. note::
A frozen core is only supported in post-HF methods. It has no effect in
HF calculations and will be simply ignored.
.. _user_occ_fixed:
The fixed occupation model
==========================
The :py:class:`~pybest.occ_model.FixedOccModel` freezes the occupation numbers
to some pre-defined value.
It features similar functionality as the :py:class:`~pybest.occ_model.AufbauOccModel`
using similar keyword arguments to steer the occupation of the orbitals.
:charge: (int) the total charge of the system
:unrestricted: (boolean) enforce unrestricted occupations even for an
even number of electrons
:ncore: (int) the number of frozen core orbitals. The same number of alpha
and beta orbitals is frozen. They are not allowed to differ.
The occupations have to be passed as a one-dimensional numpy array, where
``occ_a`` assigns an occupation vector to alpha orbitals, while ``occ_b``
(optional) specifies the occupation vector of beta orbitals.
If only ``occ_a`` is given, PyBEST assumes ``occ_b`` = ``occ_a`` and
restricted orbitals.
.. code-block:: python
# assume a gobasis instance ``gobasis`` with eight electrons
# restricted case
occ_model = FixedOccModel(gobasis, occ_a=np.array([1.0, 1.0, 1.0, 0.5, 0.5, 0.0]))
# unrestricted cases
# same occupation number vector for alpha and beta
occ_model = FixedOccModel(
gobasis, unrestricted=True, occ_a=np.array([1.0, 1.0, 1.0, 0.5, 0.5, 0.0])
)
# different occupation number vector for alpha and beta
# defaults to unrestricted orbitals
occ_model = FixedOccModel(
gobasis,
occ_a=np.array([1.0, 1.0, 1.0, 0.5, 0.5, 0.0]),
occ_b=np.array([1.0, 0.7, 1.0, 1.0, 0.0, 0.3])
)
More examples are listed below (see :ref:`user_occ_examples`).
.. note::
The number of electrons stored in ``gobasis`` has to agree with the number
of electrons in the occupation number vectors ``occ_a`` and ``occ_b``.
Otherwise, an error will be raised.
.. _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
# Evoke an instance of the FermiOccModel using default parameters
# (default occupations, T=250K, dT=50K, method=pfon - pseudo fractional occupation numbers)
occ_model = FermiOccModel(gobasis)
In general, the :py:class:`~pybest.occ_model.FermiOccModel` is a child class
of the :py:class:`~pybest.occ_model.AufbauOccModel`. Thus, both
use the same set of keyword arguments ``charge``, ``unrestricted``, ``alpha``,
and ``ncore``.
The convergence of the Fermi-smearing method can be steered using the following
keyword arguments,
:temperature: (float) controls the width of the distribution (derivative).
Default value: 250 K.
:eps: (float) the error on the sum of the occupation number when searching for
the right Fermi level. Only required for the FON method.
Default value: 1e-8.
:method: (str) the method to define fractional occupation numbers FON as
presented in [rabuck1999]_. FON (``"fon"``) and pFON (``"pfon"``) are supported.
Default value: ``"pfon"``
:delta_t: (float) the amount in K by which the temperature is reduced.
Default value: 50 K.
More examples of how to specify different occupation models using Fermi-smearing
are listed below (see :ref:`user_occ_examples`).
Note that at the end of an SCF calculation that exploited Fermi smearing, a
conventional calculation using the Aufbau occupation model should be performed.
.. _user_occ_fractional:
The fractional occupation model
===============================
Fractional occupation numbers can be defined using the :py:class:`~pybest.occ_model.FractionalOccModel`
class.
This occupation model is a child class of the :py:class:`~pybest.occ_model.AufbauOccModel`
class. Thus, the orbitals are occupied in accordance with the Aufbau principle, where the highest-
lying orbitals might have fractional occupation numbers.
In contrast, the :py:class:`~pybest.occ_model.AufbauOccModel` allows for integer occupations
only. These fractional occupation numbers are set during the initialization of the class and are not
updated afterward.
.. note::
The sum of all occupation numbers has to equal the total number of electrons, otherwise
an error will be raised.
The :py:class:`~pybest.occ_model.FractionalOccModel` should NOT be used in combination with
post-Hartree-Fock wave functions as the number of occupied orbitals might be assigned incorrectly.
This occupation model might be useful for single Slater determinant wave
functions in case of convergence difficulties.
Since the occupation model is a child class of :py:class:`~pybest.occ_model.AufbauOccModel`,
it contains similar functionality and supports similar keyword arguments to steer the occupation of
the orbitals.
:charge: (int) the total charge of the system
:unrestricted: (boolean) enforce unrestricted occupations even for an
even number of electrons
:ncore: (int) the number of frozen core orbitals. The same number of alpha
and beta orbitals is frozen. They are not allowed to differ.
The fractional occupation numbers are set using the keyword arguments ``nocc_a`` and ``nocc_b``,
which specify the **total** number of (occupied) alpha and beta orbitals.
Thus, their sum has to equal the total number of electrons.
:nocc_a: (float) the number of alpha electrons
:nocc_b: (float) the number of beta electrons (**optional**). If not provided, we assume
nocc_b = nocc_a.
.. code-block:: python
# Take gobasis information from ``gobasis`` (assuming 10 electrons)
# Enforce 5.5 alpha and 4.5 beta electrons
# defaults to unrestricted orbitals
occ_model = FractionalOccModel(gobasis, nocc_a=5.5, nocc_b=4.5)
More examples of how to specify different fractional occupation patterns
are listed below (see :ref:`user_occ_examples`).
.. _user_occ_spin:
The spin Aufbau occupation model
================================
An Aufbau occupation model for spin orbitals can be defined using the
:py:class:`~pybest.occ_model.AufbauSpinOccModel` class.
This occupation model is a child class of the :py:class:`~pybest.occ_model.AufbauOccModel`
class. Thus, the orbitals are occupied in accordance with the Aufbau principle.
The :py:class:`~pybest.occ_model.AufbauSpinOccModel` always enforces **unrestricted**
orbitals. In contrast to the occupation models mentioned above, which assign
"fixed" occupations to orbitals resulting in a well-defined number of occupied alpha and beta
orbitals, this occupation model assigns the occupations of alpha and beta orbitals
on-the-fly. Meaning that during an SCF optimization step, the energetically
lowest-lying orbitals are occupied, independent of their spin degree of freedom.
Therefore, the number of alpha and beta electrons may change during the optimization.
In contrast to the :py:class:`~pybest.occ_model.AufbauOccModel`, only a subset of
keyword arguments is supported.
:charge: (int) the total charge of the system
:ncore: (int) the number of frozen core orbitals. The same number of alpha
and beta orbitals is frozen. They are not allowed to differ.
To create an instance of the :py:class:`~pybest.occ_model.AufbauSpinOccModel` class,
a similar syntax as for the :py:class:`~pybest.occ_model.AufbauOccModel` is used,
.. code-block:: python
# Take gobasis information from ``gobasis``
# (contains information on the number of electrons)
# defaults to unrestricted orbitals
occ_model = AufbauSpinOccModel(gobasis)
More examples of how to specify different Aufbau occupation patterns for spin
orbitals are listed below (see :ref:`user_occ_examples`).
.. _user_occ_examples:
Example Python scripts
======================
Several complete examples can be found in the directory
``data/examples/occ_model``.
AufbauOccModel
--------------
This is a basic example of how to create an instance of the :py:class:`~pybest.occ_model.AufbauOccModel`
using various settings.
.. literalinclude:: ../src/pybest/data/examples/occ_model/aufbau_model.py
:caption: data/data/examples/occ_model/aufbau_model.py
:lines: 3-
FixedOccModel
-------------
This is a basic example on how to create an instance of the :py:class:`~pybest.occ_model.FixedOccModel`
using various settings.
.. literalinclude:: ../src/pybest/data/examples/occ_model/fixed_model.py
:caption: data/data/examples/occ_model/fixed_model.py
:lines: 3-
FermiOccModel
-------------
This is a basic example on how to create an instance of the :py:class:`~pybest.occ_model.FermiOccModel`
using various settings.
.. literalinclude:: ../src/pybest/data/examples/occ_model/aufbau_fermi.py
:caption: data/data/examples/occ_model/aufbau_fermi.py
:lines: 3-
FractionalOccModel
------------------
This is a basic example on how to create an instance of the :py:class:`~pybest.occ_model.FractionalOccModel`
using various settings.
.. literalinclude:: ../src/pybest/data/examples/occ_model/aufbau_fractional_model.py
:caption: data/data/examples/occ_model/aufbau_fractional_model.py
:lines: 3-
AufbauSpinOccModel
------------------
This is a basic example on how to create an instance of the :py:class:`~pybest.occ_model.AufbauSpinOccModel`
using various settings.
.. literalinclude:: ../src/pybest/data/examples/occ_model/aufbau_spin_model.py
:caption: data/data/examples/occ_model/aufbau_spin_model.py
:lines: 3-