gSOMOs 1.0.0a0

A Python package to analyze magnetic molecular orbitals (SOMOs) from Gaussian outputs

Versions [0.9.0] - [1.0.0a] - 2024-04-27

Changed

• logo is now gSOMOs instead of SOMOs
• in the projection scheme (proj.py), there are now two criteria to identify a SOMO, namely "SOMO P2v?" (formerly SOMO?) and "SOMO dom. β MO?" (see scientific documentation)
  • SOMOs identified according to the P^2_virtual criterion are highlighted in green
  • SOMOs identified only on the basis of a dominant virtual beta MO are highlighted in orange (weaker criterion)
• Scientific documentation renamed gSOMOs.pdf. And content updated
• gSOMOs-v3.pdf scientific document now downloadable in gsomos.readthedocs.io
• Images in README.md now point to their https://raw.githubusercontent.com counterpart
• Update of DOCUMENTATION_setup.md, PUBLISHING.md
• Link toward the Jupyter notebook with examples and a log zip file with two Gaussian logs in DOCUMENTATION_setup.md and in README.md

Added

• new analyzis scheme in proj.py: bases on the diagonalization of projection matrices
• new clean_logfile_name() function in io.py (made to solve a prefix issue for X.log.gz files)
• Short examples in the documentation
• docstring for projection_heatmap_from_df
• docstring of show_alpha_to_homo translated in English
• updated Installation section in README.md

Fixed

• minor fixes
• wrong initialization of visualID_Eng at the beginning of the notebook, and tricky issues

gSOMOs

🔗 Available on PyPI

A Python library to identify and analyze Single Occupied Molecular Orbitals (SOMOs) from Gaussian 09 or Gaussian 16 .log files.

---

🛠️ Installation

⚡ Quickstart

1. Open a terminal:

• On Linux/macOS: open a Terminal (bash)

• On Windows: open PowerShell

2. (Recommended) Set up a local virtual environment inside your project folder using virtualenv.

   # Create, if necessary, a project folder
   mkdir my-project-folder
   
   # Move to your project directory
   cd my-project-folder
   
   # Create the virtual environment
   virtualenv gSOMOS-venv # or any other name that has nothing to do with gSOMOS
   
   # Activate the environment
   source gSOMOS-venv/bin/activate   # On Linux/macOS
   # or
   gSOMOS-venv\Scripts\activate      # On Windows
   

3. Install gSOMOs inside the environment:

   pip install gSOMOs
   

📦 All necessary Python packages will be installed automatically !

---

📋 Requirements

• 🐍 Python ≥ 3.8
• 📦 A working installation of virtualenv
• 🔄 An up-to-date version of pip (python -m pip install --upgrade pip)

---

📝 Notes

• Keeping the virtual environment inside the project folder makes it easier to manage and remove if needed.

• To deactivate the environment at any time, simply type:

  deactivate
  

---

🔎 Capabilities Overview

SOMOs is a Python toolkit for analyzing molecular orbitals (MOs) from Gaussian log files, with a focus on identifying SOMOs (Singly Occupied Molecular Orbitals) in open-shell systems.

---

🚀 Main Features

from somos import io # optional
from somos import cosim, proj

Load Gaussian Log Files

• Parses .log and .log.gz Gaussian output files
• Extracts orbital energies, coefficients, overlap matrices, and spin

Cosine Similarity & SOMO Detection

• Computes cosine similarities between alpha and beta orbitals
• Identifies SOMO candidates from orbital projections

Projection-Based Analysis

• Projects occupied and virtual alpha MOs onto virtual beta MOs
• Decomposes projection matrix to extract leading contributions

---

📊 Visualization Tools

Heatmaps

• Interactive or static heatmaps of MO similarities

t-SNE (Dimensionality Reduction)

• Projects high-dimensional orbital space to 2D for visual exploration
• Enables inspection of orbital families and similarity patterns

---

📁 Output

• .xlsx tables of SOMO similarity and projections
• .png images of heatmaps and projections
• All results saved in the logs/ folder
• well-organized dataframes and printing

=== Summary of SOMO candidates ===

──────────── SOMO Candidate #1 ────────────
  α occupied contributions:
    • α 187 (44.2%)
    • α 164 (27.3%)
  β virtual projections:
    • β 194 (73.3%)
    • β 196 (16.1%)

──────────── SOMO Candidate #2 ────────────
  α occupied contributions:
    • α 169 (41.1%)
    • α 186 (21.6%)
    • α 165 (15.7%)
  β virtual projections:
    • β 192 (53.1%)
    • β 193 (26.9%)

──────────── SOMO Candidate #3 ────────────
  α occupied contributions:
    • α 186 (30.0%)
  β virtual projections:
    • β 198 (73.0%)

──────────── SOMO Candidate #4 ────────────
  α occupied contributions:
    • α 168 (51.8%)
    • α 183 (16.3%)
  β virtual projections:
    • β 193 (41.6%)
    • β 192 (26.7%)

---

🧠 Examples and Documentation

✅ Examples Used in Notebooks (compressed Gaussian files)

• logs/H2CO_T1.log.gz
• logs/FeComplex.log.gz

---

📓 Example Jupyter Notebook

An example notebook demonstrating gSOMOs usage is available at: gSOMOs Examples Notebook on GitHub. Save it in my-project-folder.

Also download the logs/ folder with the two examples. Store it also in my-project-folder.

---

📚 Technical and scientific documentation

This document describes two complementary methods to identify singly occupied molecular orbitals (SOMOs) in open-shell systems:

• Orbital projection analysis, where occupied α orbitals are projected onto the β orbital basis using the AO overlap matrix;
• Cosine similarity mapping, which computes the angular similarity between α and β orbitals and matches them using the Kuhn–Munkres (Hungarian) algorithm.

The two examples, which involve finding the SOMOs of the lowest triplet state (T₁) of formaldehyde (H₂CO) and the lowest quintet state of an iron complex, are discussed in this document.

---