avo_ibo

avo_ibo is a plugin for Avogadro 2 (and standalone CLI) that computes and visualizes Intrinsic Bond Orbitals (IBOs) using Psi4 for SCF and wavefunction generation, then performs post-SCF IAO/2014 orbital construction (Knizia, J. Chem. Theory Comput. 2013, 9, 4834) and Pipek-Mezey localization directly in the plugin.

Capabilities

• Occupied and valence-virtual IBOs — Pipek-Mezey localization (p=2 warmup + p=4 refinement, conv 1e-12)
• On-atom degeneracy resolution via post-PM Fock diagonalization
• Bond-flat degeneracy resolution — flat {σ, π} planes of symmetric bonds are Fock-diagonalised so distorted geometries yield σ+π (not banana bonds) deterministically
• Valence-virtual IBOs via singular value decomposition projection of canonical virtual MOs onto IAO space
• IAO-basis Molden export with Fock-diagonal energies for Avogadro rendering
• Analysis table (ibos.txt) — occupancy, energy, bond type, atomic composition, s/p/d hybridization, partial charges, bond orders (density Wiberg decomposed into σ and π, σ+π = total exactly)
• Standalone CLI (python -m avogadro_ibo molecule.xyz) and Avogadro in-app mode
• Full mathematical derivation in mathematics/mathematics.md with paper equation references

Project notebooks: NOTES.md (open items, design decisions), AGENTS.md (development context and gotchas). Release history: CHANGELOG.md.

Quick Start

Avogadro Plugin (easiest)

Requires pixi.

git clone https://github.com/exergonic/avo_ibo.git
cd avo_ibo
pixi install

Then create a symlink so Avogadro finds the plugin (run PowerShell as Administrator):

New-Item -ItemType SymbolicLink -Path "$env:LOCALAPPDATA\OpenChemistry\Avogadro\plugins\avo_ibo" -Target "C:\path\to\avo_ibo"

Restart Avogadro. Go to Extensions → Intrinsic Bond Orbitals → Compute IBOs.

Orbitals appear in the Molecular Orbitals panel.

Development Setup

Requires pixi.

git clone https://github.com/exergonic/avo_ibo.git
cd avo_ibo
pixi install
pixi run test

Standalone CLI

pixi run python -m avogadro_ibo molecule.xyz

Writes to calcs/ (ibo.molden, canonical.molden, ibos.txt, psi4.log).

pip (no pixi)

pip install git+https://github.com/exergonic/avo_ibo.git

Psi4 must be installed separately via conda.

Data location

Calculations are run in calcs/ in the current working directory:

• input.xyz - the input molecule used for calculations
• ibos.txt — analysis table with per-orbital data
• ibo.molden — IAO-basis orbitals for visualization
• canonical.molden — canonical MOs for reference visualization
• psi4.log — Psi4 SCF output

Limitations and Considerations

• Closed-shell only. The IAO/IBO pipeline treats all occupied orbitals as doubly occupied (RHF-style). Open-shell systems (radicals, triplet states, broken-symmetry calculations) are not supported. The SCF will still run, but the orbital construction, analysis, and Molden output will be invalid.

• Symmetric molecules. Pipek-Mezey localization uses fixed sequential Jacobi sweeps. For highly symmetric molecules, symmetry-equivalent orbitals may show small (sub-milliHartree) energy splittings (a known consequence of the orthogonality constraint — see Knizia JCTC 2013 and mathematics.md).

• Analysis Table vs. Isosurface Tails The IBO analysis table (ibos.txt) reports orbital compositions in the IAO basis, where populations are clean and bond assignments are crisp. The Molden isosurfaces are rendered in the full SCF basis via the projection C_AO = C_IAO @ C_IAO_all, which correctly includes the IAO repolarization components.

  These two representations are slightly inconsistent by construction: small density tails visible on non-dominant atoms in the isosurface are physically real repolarization contributions, not rendering artifacts or bugs. The analysis table intentionally omits these for clarity of chemical interpretation. This discrepancy is mathematically unavoidable and is present in all IAO-based implementations.

  These small tails represent the repolarization of each intrinsic atomic orbital in response to the molecular environment. It is the same physics that makes bonds polar and atoms non-spherical in molecules. The analysis table reports populations in the compressed IAO basis for chemical clarity; the isosurface renders the full physical wavefunction including these repolarization contributions.

Learning the output

The examples/ directory (local companion, not shipped) holds a section-by-section guide to reading ibos.txt plus worked molecule spotlights — carbocations, aromaticity, bent bonds, hyperconjugation, hydrogen bonding — each with run commands, verified numbers, and orbital images. Start there before the mathematics.

License

BSD 3-Clause. See LICENSE.