Patch v1.3.0

README.md

@@ -1,6 +1,7 @@
 # PyQInt
 
 [![status](https://jose.theoj.org/papers/2a73fa24200e8c1ec47fc6e37f818a54/status.svg)](https://jose.theoj.org/papers/2a73fa24200e8c1ec47fc6e37f818a54)
+![Version](https://img.shields.io/github/v/tag/ifilot/pyqint?label=version)
 [![PyPI pkg](https://github.com/ifilot/pyqint/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/ifilot/pyqint/actions/workflows/build_wheels.yml)
 [![PyPI](https://img.shields.io/pypi/v/pyqint?style=flat-square)](https://pypi.org/project/pyqint/)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
@@ -65,12 +66,15 @@ as well as the following geometric derivatives
 PyQInt offers additional features such as
 * Performing [restricted
   Hartree-Fock](https://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method)
-  calculations using [DIIS](https://en.wikipedia.org/wiki/DIIS)
-* Calculation of [Crystal Orbital Hamilton Population](http://www.cohp.de/)
-  coefficients
+  calculations using [DIIS](https://en.wikipedia.org/wiki/DIIS) 
+* Population and bonding analysis methods, including:
+    - Mulliken and Löwdin atomic charge analysis  
+    - Molecular Orbital Hamilton Population (MOHP)  
+    - Molecular Orbital Overlap Population (MOOP)  
+    - Molecular Orbital Bond Index (MOBI)  
 * Construction of localized orbitals using the [Foster-Boys
   method](https://en.wikipedia.org/wiki/Localized_molecular_orbitals#Foster-Boys)
-* Geometry optimization using Conjugate Gradient
+* Geometry optimization using the Conjugate Gradient algorithm  
 * Visualization of molecular orbitals
 
 All routines are (automatically) tested and verified against several open-source
@@ -81,7 +85,14 @@ Nevertheless, if you spot any mistake, please kindly open an
 In the image below, the (canonical) molecular orbitals as found using a
 restricted Hartree-Fock calculation for the CO molecule are shown.
 
-![Molecular orbitals of CO](img/co.jpg)
+![Contour plots of CO](img/co.jpg)
+Contour plots of the CO molecule
+
+![Isosurfaces of CO](docs/_static/img/co_canonical_isosurfaces.jpg)
+Isosurfaces of the canonical molecular orbitals of CO
+
+![Isosurfaces of CO](docs/_static/img/co_fosterboys_isosurfaces.jpg)
+Isosurfaces of the localized molecular orbitals of CO
 
 ## Community guidelines
 

docs/_static/img/.gitignore

@@ -0,0 +1,3 @@
+!*.png
+!*.jpg
+!*.svg

docs/basis_sets_and_molecules.rst

@@ -95,6 +95,9 @@ that are supported are given:
 * :code:`sto6g` (H-Kr)
 * :code:`p321` (H-Cs)
 * :code:`p631` (H-Zn)
+* :code:`aug-cc-pVDZ` (H-Kr, excl. K and Ca)
+* :code:`aug-cc-pVTZ` (H-Kr, excl. K and Ca)
+* :code:`aug-cc-pVQZ` (H-Kr, excl. K and Ca)
 
 The example code below builds the basis functions for the H\ :sub:`2` molecule:
 

docs/electronic_structure_calculations.rst

@@ -6,12 +6,20 @@ Electronic structure calculations
 .. contents:: Table of Contents
     :depth: 3
 
-Hartree-Fock
-------------
+The :program:`PyQInt` package provides two flavors of Hartree-Fock electronic
+structure calculations: **restricted Hartree-Fock (RHF)** and
+**unrestricted Hartree-Fock (UHF)**. The restricted formulation is suitable for
+closed-shell systems, whereas the unrestricted formulation allows for the
+treatment of open-shell systems with unpaired electrons.
 
-The Hartree-Fock procedure is readily available as a separate class in the
-:program:`PyQInt` package. It gives rich output allowing the user to investigate
-the Hartree-Fock coefficient optimization procedure in detail.
+Both approaches expose detailed intermediate results, allowing the user to
+inspect orbital coefficients, density matrices, Fock matrices, and energy
+contributions throughout the self-consistent field (SCF) procedure.
+
+Restricted Hartree-Fock
+-----------------------
+
+Below, an example of an **restricted** Hartree-Fock calculation is given.
 
 .. code-block:: python
 
@@ -83,8 +91,8 @@ the Hartree-Fock coefficient optimization procedure in detail.
    rapid generation of grids of molecular orbital contour plots with minimal
    boilerplate code.
 
-Result dictionary
------------------
+Result dictionary (RHF)
+***********************
 
 The result of a Hartree-Fock calculation is captured inside a dictionary
 object. This dictionary objects contains the following keys
@@ -187,6 +195,148 @@ The output of the above script yields::
     Total energy:  -39.72630504189621
     Sum of the individual terms:  -39.726305041896055
 
+Unrestricted Hartree-Fock (UHF)
+-------------------------------
+
+For systems containing unpaired electrons, such as radicals or atoms with open
+shells, the restricted Hartree-Fock approximation is no longer appropriate.
+In such cases, :program:`PyQInt` provides an **unrestricted Hartree-Fock (UHF)**
+implementation via the :code:`uhf()` method.
+
+In UHF, separate spatial orbitals are used for spin-up (:math:`\alpha`) and
+spin-down (:math:`\beta`) electrons. This leads to distinct α and β density
+matrices and Fock matrices, allowing the electronic structure to exhibit spin
+polarization.
+
+As a representative example, consider the methyl radical (CH₃), which has one
+unpaired electron and therefore requires an unrestricted treatment. The geometry
+used below places the carbon atom at the origin, with three hydrogen atoms
+arranged in a planar configuration with H-C-H angles of 120 degrees and a C-H
+bond length of 2.039 Bohr.
+
+.. code-block:: python
+
+    from pyqint import Molecule, HF
+    import numpy as np
+
+    R = 2.039
+    sqrt3 = np.sqrt(3.0)
+
+    mol = Molecule()
+    mol.add_atom('C', 0.0, 0.0, 0.0)
+    mol.add_atom('H',  R, 0.0, 0.0)
+    mol.add_atom('H', -0.5 * R,  0.5 * sqrt3 * R, 0.0)
+    mol.add_atom('H', -0.5 * R, -0.5 * sqrt3 * R, 0.0)
+
+    # CH3 is a doublet (multiplicity = 2)
+    res = HF(mol, 'sto3g').uhf(multiplicity=2)
+
+    print('Total energy:', res['energy'])
+
+Result dictionary (UHF)
+***********************
+
+The result of an unrestricted Hartree-Fock (UHF) calculation is likewise captured
+inside a dictionary object. Compared to restricted Hartree-Fock, the UHF result
+dictionary contains **spin-resolved quantities**, reflecting the fact that
+different spatial orbitals are used for spin-up (:math:`\alpha`) and spin-down
+(:math:`\beta`) electrons.
+
+Below, the most important entries of the UHF result dictionary are listed.
+
+.. list-table:: Description of the data contained in the UHF result dictionary
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - :code:`energy`
+     - Final total electronic energy
+   * - :code:`nuclei`
+     - List of elements and their position in Bohr units
+   * - :code:`cgfs`
+     - List of contracted Gaussian functional objects
+   * - :code:`energies`
+     - List of total energies during the SCF convergence procedure
+   * - :code:`orbe_alpha`
+     - Converged orbital energies for spin-up (:math:`\alpha`) electrons
+   * - :code:`orbe_beta`
+     - Converged orbital energies for spin-down (:math:`\beta`) electrons
+   * - :code:`orbc_alpha`
+     - Orbital coefficient matrix for :math:`\alpha` electrons
+   * - :code:`orbc_beta`
+     - Orbital coefficient matrix for :math:`\beta` electrons
+   * - :code:`density_alpha`
+     - Density matrix :math:`\mathbf{P}^{\alpha}` for spin-up electrons
+   * - :code:`density_beta`
+     - Density matrix :math:`\mathbf{P}^{\beta}` for spin-down electrons
+   * - :code:`density`
+     - Total density matrix :math:`\mathbf{P} = \mathbf{P}^{\alpha} + \mathbf{P}^{\beta}`
+   * - :code:`fock_alpha`
+     - Fock matrix for :math:`\alpha` electrons
+   * - :code:`fock_beta`
+     - Fock matrix for :math:`\beta` electrons
+   * - :code:`transform`
+     - Unitary transformation matrix :math:`\mathbf{X}`
+   * - :code:`overlap`
+     - Overlap matrix :math:`\mathbf{S}`
+   * - :code:`kinetic`
+     - Kinetic energy matrix :math:`\mathbf{T}`
+   * - :code:`nuclear`
+     - Nuclear attraction matrix :math:`\mathbf{V}`
+   * - :code:`hcore`
+     - Core Hamiltonian matrix :math:`\mathbf{H_{\textrm{core}}}`
+   * - :code:`tetensor`
+     - Two-electron integral tensor :math:`(i,j,k,l)`
+   * - :code:`time_stats`
+     - Time statistics object
+
+In unrestricted Hartree-Fock, the exchange contribution is spin-dependent.
+Accordingly, the exchange energy is split into separate :math:`\alpha` and
+:math:`\beta` components.
+
+.. list-table:: UHF energy contributions
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - :code:`ecore`
+     - Sum of kinetic and nuclear attraction energy
+   * - :code:`ej`
+     - Coulomb (Hartree) energy
+   * - :code:`ex_alpha`
+     - Exchange energy contribution from :math:`\alpha` electrons
+   * - :code:`ex_beta`
+     - Exchange energy contribution from :math:`\beta` electrons
+   * - :code:`enucrep`
+     - Electrostatic repulsion energy of the nuclei
+
+In addition to the electronic structure data, the UHF result dictionary contains
+explicit information about the spin state of the system.
+
+.. list-table:: Spin-related quantities
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - :code:`nelec`
+     - Total number of electrons
+   * - :code:`nalpha`
+     - Number of spin-up (:math:`\alpha`) electrons
+   * - :code:`nbeta`
+     - Number of spin-down (:math:`\beta`) electrons
+   * - :code:`multiplicity`
+     - Spin multiplicity :math:`(2S + 1)`
+
+.. note::
+
+   Unlike restricted Hartree-Fock, unrestricted Hartree-Fock allows for spin
+   polarization. As a consequence, the resulting wavefunction is generally not
+   an exact eigenfunction of the total spin operator, which may lead to spin
+   contamination.
+
 Custom basis sets
 -----------------
 

docs/molecular_orbital_diagrams.rst

@@ -12,6 +12,10 @@ PyMoDia package is documented separately at: https://ifilot.github.io/pymodia
 In this section, we demonstrate how results obtained from :program:`PyQInt` can be
 exported and visualized using PyMoDia.
 
+.. warning::
+
+    PyMoDia currently only support **restricted** Hartree-Fock calculations.
+
 Overview
 --------
 

docs/orbital_localization.rst

@@ -6,6 +6,11 @@ Orbital localization: Foster-Boys
 .. contents:: Table of Contents
     :depth: 3
 
+.. warning::
+
+    Orbital Localization methods currently only support **restricted**
+    Hartree-Fock calculations.
+
 Background of FB
 ----------------
 
@@ -46,7 +51,8 @@ as its input.
 .. note::
     The code below uses the PyTessel package for constructing the isosurfaces.
     PyTessel is an external package for easy construction of isosurfaces from
-    scalar fields. More information is given `in the corresponding section <#constructing-isosurfaces>`_.
+    scalar fields. More information is given 
+    `in the corresponding section <#constructing-isosurfaces>`_.
 
 .. code-block:: python
 

docs/orbital_visualization.rst

@@ -66,6 +66,11 @@ generating grids of contour plots for molecular orbitals obtained from a
 Hartree-Fock calculation. The class itself is intentionally stateless: all
 required information is passed explicitly via the Hartree-Fock results object.
 
+.. warning::
+
+    ContourPlotter methods currently only support **restricted**
+    Hartree-Fock calculations.
+
 Cartesian-aligned contour plots
 *******************************
 
@@ -85,7 +90,7 @@ The following example visualizes the molecular orbitals of carbon monoxide
 
     ContourPlotter.build_contourplot(
         res,
-        'co.png',
+        'co_contour.png',
         plane='yz',
         sz=3.0,
         npts=101,
@@ -106,7 +111,7 @@ orbitals in a :math:`2 \times 5` grid.
 
         ContourPlotter.build_contourplot(
             res,
-            'co.png',
+            'co_contour_level15.png',
             plane='yz',
             sz=3.0,
             npts=101,
@@ -153,7 +158,7 @@ the up direction:
     up = [0, 0, 1]
     ContourPlotter.build_contourplot(
         res,
-        'ch4.png',
+        'ch4_contour.png',
         plane=[0, 1, 2, up],
         sz=3.0,
         npts=101,