<commit_before>.. index::
    module: methods

Calculation methods
===================

The following methods in cclib allow further analysis of calculation output.

.. _`methods in the development version`: methods_dev.html

.. index::
    single: methods; C squared population analysis (CSPA)

C squared population analysis (CSPA)
------------------------------------

**CSPA** can be used to determine and interpret the electron density of a molecule. The contribution of the a-th atomic orbital to the i-th molecular orbital can be written in terms of the molecular orbital coefficients:

.. math:: \Phi_{ai} = \frac{c^2_{ai}}{\sum_k c^2_{ki}}

The CSPA class available from cclib.method performs C-squared population analysis and can be used as follows:

.. code-block:: python

    from cclib.io import ccread
    from cclib.method import CSPA

    data = ccread("mycalc.out")

    m = CSPA(data)
    m.calculate()

After the ``calculate()`` method is called, the following attributes are available:

* ``aoresults`` is a NumPy array[3] with spin, molecular orbital, and atomic/fragment orbitals as the axes (``aoresults[0][45][0]`` gives the contribution of the 1st atomic/fragment orbital to the 46th alpha/restricted molecular orbital)
* ``fragresults`` is a NumPy array[3] with spin, molecular orbital, and atoms as the axes (``atomresults[1][23][4]`` gives the contribution of the 5th atomic/fragment orbital to the 24th beta molecular orbital)
* ``fragcharges`` is a NumPy array[1] with the number of (partial) electrons in each atom (``atomcharges[2]`` gives the number of electrons on the 3rd atom)

Custom fragments
~~~~~~~~~~~~~~~~

Calling the calculate method without an argument treats each atom as a fragment in the population analysis. An optional argument can be passed - a list of lists - containing the atomic orbital numbers to be included in each fragment. Calling with this additional argument is useful if one is more interested in the contributions of certain orbitals, such as metal d, to the molecular orbitals. For example:

.. code-block:: python

    from cclib.io import ccread
    from cclib.method import CSPA

    data = ccread("mycalc.out")

    m = CSPA(data)
    m.calculate([[0, 1, 2, 3, 4], [5, 6], [7, 8, 9]]) # fragment one is made from basis functions 0 - 4
                                                      # fragment two is made from basis functions 5 & 6
                                                      # fragment three is made from basis functions 7 - 9

Custom progress
~~~~~~~~~~~~~~~

The CSPA class also can take a progress class as an argument so that the progress of the calculation can be monitored:

.. code-block:: python

    from cclib.method import CSPA
    from cclib.parser import Gaussian
    from cclib.progress import TextProgress

    import logging

    progress = TextProgress()
    p = Gaussian("mycalc.out", logging.ERROR)
    d = p.parse(progress)

    m = CSPA(d, progress, logging.ERROR)
    m.calculate()

.. index::
    single: methods; Mulliken population analysis (MPA)

Mulliken population analysis (MPA)
----------------------------------

MPA can be used to determine and interpret the electron density of a molecule. The contribution of the a-th atomic orbital to the i-th molecular orbital in this method is written in terms of the molecular orbital coefficients, c, and the overlap matrix, S:

.. math:: \Phi_{ai} = \sum_b c_{ai} c_{bi} S_{ab}

The MPA class available from cclib.method performs Mulliken population analysis and can be used as follows:

.. code-block:: python

    import sys

    from cclib.method import MPA
    from cclib.parser import ccopen

    d = ccopen(sys.argv[1]).parse()
    m = MPA(d)
    m.calculate()

After the calculate() method is called, the following attributes are available:

* ``aoresults``: a three dimensional array with spin, molecular orbital, and atomic orbitals as the axes, so that ``aoresults[0][45][0]`` gives the contribution of the 1st atomic orbital to the 46th alpha/restricted molecular orbital,
* ``fragresults``: a three dimensional array with spin, molecular orbital, and atoms as the axes, so that ``fragresults[1][23][4]`` gives the contribution of the 5th fragment orbitals to the 24th beta molecular orbital)
* ``fragcharges``: a vector with the number of (partial) electrons in each fragment, so that ``fragcharges[2]`` gives the number of electrons in the 3rd fragment.

Custom fragments
~~~~~~~~~~~~~~~~

The calculate method chooses atoms as the fragments by default, and optionally accepts a list of lists containing the atomic orbital numbers (e.g. ``[[0, 1, 2], [3, 4, 5, 6], ...]``) of arbitrary fragments. Calling it in this way is useful if one is more interested in the contributions of groups of atoms or even certain orbitals or orbital groups, such as metal d, to the molecular orbitals. In this case, fragresults and fragcharges reflect the chosen groups of atomic orbitals instead of atoms.

Custom progress
~~~~~~~~~~~~~~~

The Mulliken class also can take a progress class as an argument so that the progress of the calculation can be monitored:

.. code-block:: python

    from cclib.method import MPA
    from cclib.parser import ccopen
    from cclib.progress import TextProgress
    import logging

    progress = TextProgress()
    d = ccopen("mycalc.out", logging.ERROR).parse(progress)

    m = MPA(d, progress, logging.ERROR)
    m.calculate()

.. index::
    single: methods; Löwdin Population Analysis

Löwdin Population Analysis
--------------------------

The LPA class available from cclib.method performs Löwdin population analysis and can be used as follows:

.. code-block:: python

    import sys

    from cclib.method import LPA
    from cclib.parser import ccopen

    d = ccopen(sys.argv[1]).parse()
    m = LPA(d)
    m.calculate()<commit_msg>New: Add documentation for Bickelhaupt class<commit_after>.. index::
    module: methods

Calculation methods
===================

The following methods in cclib allow further analysis of calculation output.

.. _`methods in the development version`: methods_dev.html

.. index::
    single: methods; C squared population analysis (CSPA)

C squared population analysis (CSPA)
------------------------------------

**CSPA** can be used to determine and interpret the electron density of a molecule. The contribution of the a-th atomic orbital to the i-th molecular orbital can be written in terms of the molecular orbital coefficients:

.. math:: \Phi_{ai} = \frac{c^2_{ai}}{\sum_k c^2_{ki}}

The CSPA class available from cclib.method performs C-squared population analysis and can be used as follows:

.. code-block:: python

    from cclib.io import ccread
    from cclib.method import CSPA

    data = ccread("mycalc.out")

    m = CSPA(data)
    m.calculate()

After the ``calculate()`` method is called, the following attributes are available:

* ``aoresults`` is a NumPy array[3] with spin, molecular orbital, and atomic/fragment orbitals as the axes (``aoresults[0][45][0]`` gives the contribution of the 1st atomic/fragment orbital to the 46th alpha/restricted molecular orbital)
* ``fragresults`` is a NumPy array[3] with spin, molecular orbital, and atoms as the axes (``atomresults[1][23][4]`` gives the contribution of the 5th atomic/fragment orbital to the 24th beta molecular orbital)
* ``fragcharges`` is a NumPy array[1] with the number of (partial) electrons in each atom (``atomcharges[2]`` gives the number of electrons on the 3rd atom)

Custom fragments
~~~~~~~~~~~~~~~~

Calling the calculate method without an argument treats each atom as a fragment in the population analysis. An optional argument can be passed - a list of lists - containing the atomic orbital numbers to be included in each fragment. Calling with this additional argument is useful if one is more interested in the contributions of certain orbitals, such as metal d, to the molecular orbitals. For example:

.. code-block:: python

    from cclib.io import ccread
    from cclib.method import CSPA

    data = ccread("mycalc.out")

    m = CSPA(data)
    m.calculate([[0, 1, 2, 3, 4], [5, 6], [7, 8, 9]]) # fragment one is made from basis functions 0 - 4
                                                      # fragment two is made from basis functions 5 & 6
                                                      # fragment three is made from basis functions 7 - 9

Custom progress
~~~~~~~~~~~~~~~

The CSPA class also can take a progress class as an argument so that the progress of the calculation can be monitored:

.. code-block:: python

    from cclib.method import CSPA
    from cclib.parser import Gaussian
    from cclib.progress import TextProgress

    import logging

    progress = TextProgress()
    p = Gaussian("mycalc.out", logging.ERROR)
    d = p.parse(progress)

    m = CSPA(d, progress, logging.ERROR)
    m.calculate()

.. index::
    single: methods; Mulliken population analysis (MPA)

Mulliken population analysis (MPA)
----------------------------------

MPA can be used to determine and interpret the electron density of a molecule. The contribution of the a-th atomic orbital to the i-th molecular orbital in this method is written in terms of the molecular orbital coefficients, c, and the overlap matrix, S:

.. math:: \Phi_{ai} = \sum_b c_{ai} c_{bi} S_{ab}

The MPA class available from cclib.method performs Mulliken population analysis and can be used as follows:

.. code-block:: python

    import sys

    from cclib.method import MPA
    from cclib.parser import ccopen

    d = ccopen(sys.argv[1]).parse()
    m = MPA(d)
    m.calculate()

After the calculate() method is called, the following attributes are available:

* ``aoresults``: a three dimensional array with spin, molecular orbital, and atomic orbitals as the axes, so that ``aoresults[0][45][0]`` gives the contribution of the 1st atomic orbital to the 46th alpha/restricted molecular orbital,
* ``fragresults``: a three dimensional array with spin, molecular orbital, and atoms as the axes, so that ``fragresults[1][23][4]`` gives the contribution of the 5th fragment orbitals to the 24th beta molecular orbital)
* ``fragcharges``: a vector with the number of (partial) electrons in each fragment, so that ``fragcharges[2]`` gives the number of electrons in the 3rd fragment.

Custom fragments
~~~~~~~~~~~~~~~~

The calculate method chooses atoms as the fragments by default, and optionally accepts a list of lists containing the atomic orbital numbers (e.g. ``[[0, 1, 2], [3, 4, 5, 6], ...]``) of arbitrary fragments. Calling it in this way is useful if one is more interested in the contributions of groups of atoms or even certain orbitals or orbital groups, such as metal d, to the molecular orbitals. In this case, fragresults and fragcharges reflect the chosen groups of atomic orbitals instead of atoms.

Custom progress
~~~~~~~~~~~~~~~

The Mulliken class also can take a progress class as an argument so that the progress of the calculation can be monitored:

.. code-block:: python

    from cclib.method import MPA
    from cclib.parser import ccopen
    from cclib.progress import TextProgress
    import logging

    progress = TextProgress()
    d = ccopen("mycalc.out", logging.ERROR).parse(progress)

    m = MPA(d, progress, logging.ERROR)
    m.calculate()

.. index::
    single: methods; Löwdin Population Analysis

Löwdin Population Analysis
--------------------------

The LPA class available from cclib.method performs Löwdin population analysis and can be used as follows:

.. code-block:: python

    import sys

    from cclib.method import LPA
    from cclib.parser import ccopen

    d = ccopen(sys.argv[1]).parse()
    m = LPA(d)
    m.calculate()

.. index::
    single: methods; Bickelhaupt Population Analysis

Bickelhaupt Population Analysis
-------------------------------

The Bickelhaupt class available from cclib.method performs Bickelhaupt population analysis that has been proposed in *Organometallics* 1996, 15, 13, 2923–2931. `doi:10.1021/om950966x <https://pubs.acs.org/doi/abs/10.1021/om950966x>`_

The contribution of the a-th atomic orbital to the i-th molecular orbital in this method is written in terms of the molecular orbital coefficients, c, and the overlap matrix, S:

.. math:: \Phi_{ai} = \sum_b w_{ab} c_{ai} c_{bi} S_{ab}

where the weights :math:`w_{ab}` that are applied on the Mulliken atomic orbital contributions are defined as:

.. math:: w_{ab} = 2 \frac{\sum_k c_{ak}^2}{\sum_i c_{ai}^2 + \sum_j c_{bj}^2}

The weights are introduced to replace the somewhat arbitrary partitioning of off-diagonal charges in the Mulliken population analysis, which divides the off-diagonal charges identically to both atoms. Bickelhaupt population analysis instead divides the off-diagonal elements based on the relative magnitude of diagonal elements.

.. code-block:: python

    import sys

    from cclib.method import Bickelhaupt
    from cclib.parser import ccopen

    d = ccopen(sys.argv[1]).parse()
    m = Bickelhaupt(d)
    m.calculate()

After the calculate() method is called, the following attributes are available:

* ``aoresults``: a three dimensional array with spin, molecular orbital, and atomic orbitals as the axes, so that ``aoresults[0][45][0]`` gives the contribution of the 1st atomic orbital to the 46th alpha/restricted molecular orbital,
* ``fragresults``: a three dimensional array with spin, molecular orbital, and atoms as the axes, so that ``fragresults[1][23][4]`` gives the contribution of the 5th fragment orbitals to the 24th beta molecular orbital)
* ``fragcharges``: a vector with the number of (partial) electrons in each fragment, so that ``fragcharges[2]`` gives the number of electrons in the 3rd fragment.

Custom fragments
~~~~~~~~~~~~~~~~

The calculate method chooses atoms as the fragments by default, and optionally accepts a list of lists containing the atomic orbital numbers (e.g. ``[[0, 1, 2], [3, 4, 5, 6], ...]``) of arbitrary fragments. Calling it in this way is useful if one is more interested in the contributions of groups of atoms or even certain orbitals or orbital groups, such as metal d, to the molecular orbitals. In this case, fragresults and fragcharges reflect the chosen groups of atomic orbitals instead of atoms.

Custom progress
~~~~~~~~~~~~~~~

The Bickelhaupt class also can take a progress class as an argument so that the progress of the calculation can be monitored:

.. code-block:: python

    from cclib.method import Bickelhaupt
    from cclib.parser import ccopen
    from cclib.progress import TextProgress
    import logging

    progress = TextProgress()
    d = ccopen("mycalc.out", logging.ERROR).parse(progress)

    m = Bickelhaupt(d, progress, logging.ERROR)
    m.calculate()
{'fraction_non_alphanumeric': 0.10393925011865211, 'fraction_numerical': 0.01301783171740457, 'mean_word_length': 3.5595054095826892, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '199226', 'n_tokens_mistral': 4166, 'n_tokens_neox': 3865, 'n_words': 1871}