gSOMOs 0.9.8

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

Versions [0.9.0] - [0.9.8] - 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

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

pip install gSOMOs

---

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 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 Used in Notebooks (compressed Gaussian files)

• H2CO_T1.log.gz
• FeComplex.log.gz

---

📓 Example Jupyter Notebook

An example notebook demonstrating gSOMOs usage is available: gSOMOs Examples Notebook on GitHub

Also download a log folder with the two examples describied in the documentation.

---

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.

Two examples based on the triplet state (T₁) of formaldehyde (H₂CO) and on the lowest quintet state of an iron complex are commented in this document.

---