avogadro-vbvis

Bridging molecular geometry with qualitative chemical intuition. avogadro-vbvis is a modern Python-driven plugin for Avogadro 2 designed to algorithmically determine and visualize valence bond orbitals (hybridization, localized lone pairs, and orbital overlap lobes) typically taught in undergraduate general and organic chemistry courses.

🎯 Scope & Intent

This plugin is designed for educational and qualitative visualization using VSEPR rules and geometric algorithms to render textbook-style hybrid ($$sp$$, $$sp^2$$, $$sp^3$$) and unhybridized ($p$) orbitals.

What It Is	What It Is NOT
📐 Geometric & Algorithmic: Infers orbital orientations from local coordination numbers and atomic positions.	🧮 Quantum Mechanical: Does not perform ab initio Valence Bond (VB) wavefunction or resonance calculations.
📚 Pedagogical: Ideal for illustrating undergraduate general/organic chemistry bonding concepts.	🔬 Electronic Structure Tool: Does not compute molecular orbitals (MOs) or electron density matrices.

---

⚠️ Project Status: Work in Progress > This project is under active foundational development. The core framework, Avogadro UI menu hooks, isolated Pixi environment management, and CJSON data-logging pipelines are completely functional. Local coordinate vector math and orbital mesh rendering algorithms are currently being prototyped.

---

🧪 The Vision

While standard computational chemistry software excels at calculating highly delocalized Molecular Orbitals (MOs) via quantum mechanics, students and researchers often reason using the localized framework of Valence Bond (VB) Theory and VSEPR.

This plugin aims to:

• Automatically analyze local coordination environments of central atoms.
• Determine hybridization states ($$sp$$, $$sp^2$$, $$sp^3$$, $sp^3d$, etc.) based on geometric configurations.
• Direct and render 3D geometric meshes representing localized bonding pairs and lone pair lobes directly in the Avogadro 2 viewport.

---

🛠️ Architecture & Tech Stack

The plugin leverages a modern, ultra-fast Python stack isolated entirely from global system variables:

• Avogadro 2 Plugin API: Utilizes the external script plugin framework to communicate via standard I/O streams using Chemical JSON (CJSON) payloads.
• Pixi: A rapid, Rust-powered package management tool used to handle binary dependencies and lock environments deterministically.
• uv_build: A blazing-fast backend to manage python package metadata and project scripts.
• NumPy & SciPy: Vectorized math structures optimized for rapid spatial neighbor lookups, coordinate translation, and angular evaluations.

---

🚀 Quick Start for Developers

Prerequisites

Ensure you have Pixi installed on your machine.

Installation

1. Clone the repository into your local Avogadro 2 plugins directory:

   git clone https://github.com/exergonic/avo_vbvis.git
   cd avo_vbvis

2. Initialize and lock the isolated environment:

   pixi run python -m pip install -e .

   Note: This performs an editable install, creating the executable shortcuts required by Avogadro 2 while linking directly to your active development files.

Debugging & Prototyping

To view real-time plugin diagnostics and execution logs without launching the full Avogadro GUI, pipe a mock CJSON structure directly into the CLI tool:

pixi run avogadro-vbvis display-valence-orbitals < tests/mock_molecule.json

---

🗺️ Roadmap

• Establish Avogadro 2 GUI Extension menu handshake.

• Configure robust pyproject.toml and Pixi task tracking environment.

• Implement structured file logging via sys.stderr.

• Build standalone CJSON parsing utility for atomic coordinates and indices.

• Implement VSEPR coordination number and vector math evaluation.

• Generate 3D grid/cube mappings for orbital lobe orientations.

• Render meshes back into the Avogadro viewport.