BEBOP - Bond Energy from Bond Order Populations

A unified, optimized package for computing atomization energies and bond energy decompositions using the BEBOP methodology.

Overview

This package provides two complementary methods for calculating atomization energies from Gaussian ROHF/CBSB3 output files:

• BEBOP-1: The original BEBOP methodology using Mulliken bond orders
• BEBOP-2: Enhanced methodology with sigma/pi bond order separation and charge effects (default)

Installation

git clone https://github.com/keithgroup/bebop-qc.git
cd bebop-qc
pip install -e .

Quick Start

from bebop import BEBOP

# Load molecule (model='bebop1' or 'bebop2', default is 'bebop2')
mol = BEBOP('molecule.out', model='bebop1')
energy = mol.total_E()

# Bond energies with sigma/pi decomposition
totals, decomp = mol.bond_E(NetBond=True, GrossBond=True, sig_pi=True)

# Ionic character (BEBOP-2 only)
mol2 = BEBOP('molecule.out', model='bebop2')
mol2.total_E()
mol_ionic, bond_ionic = mol2.ionic_character()

Command Line

bebop -f molecule.out                    # Default (bebop2)
bebop -f molecule.out -model bebop1      # Use BEBOP-1
bebop -f molecule.out --be --sort        # With sorted bond energies
bebop -f molecule.out --ionicity --json  # Ionicity + JSON export

---

Resonance and Strain Energy

Calculate π-electron delocalization (resonance) and geometric distortion (ring strain) energies.

Basic Usage

from bebop import BEBOP

mol = BEBOP('molecule.out', model='bebop1')  # or 'bebop2'
mol.total_E()

# Resonance energy (1-indexed atom pairs)
res_E = mol.resonance_E({
    'C-C': [(1, 2), (3, 4)],
    'C=C': [(2, 3), (4, 5)],
})

# Strain energy
strain_E = mol.strain_E({
    '3-ring': [(1, 2), (2, 3), (3, 1)],
    'normal': [(4, 5)],
})

Custom Reference Bond Orders

Pass custom references directly or add to the global registry:

# Method 1: Pass directly (one-off use)
res_E = mol.resonance_E(bonds, reference_bond_orders={'N-N': 0.522, 'N=N': 0.852})

# Method 2: Add to registry (persistent)
from bebop import BEBOP1_RESONANCE
BEBOP1_RESONANCE.add('N-N', 0.522, 'NN', 'From model compound')

# Method 3: Via molecule object
mol.add_resonance_reference('N-N', 0.522, 'NN', 'Description')
mol.set_resonance_reference('C-C', 0.80)  # Modify existing
mol.reset_references()  # Reset to defaults

Default Reference Values

BEBOP-1 uses single float values (Mulliken bond orders):

Bond Type	Value	Bond Type	Value
C-C	0.7874	C-N*	0.6941
C=C	1.1958	C=N	1.0699

BEBOP-2 uses (σ, π) tuples:

Bond Type	(σ, π)	Bond Type	(σ, π)
C-C	(0.767, 0.024)	C-N*	(0.641, 0.052)
C=C	(0.812, 0.387)	C=N	(0.774, 0.305)

Strain parameters: CC_single and CC_anti (3-ring ref = CC_single + 2×CC_anti)

View/Manage References

from bebop import BEBOP1_RESONANCE, BEBOP2_RESONANCE, BEBOP1_STRAIN, BEBOP2_STRAIN

print(BEBOP1_RESONANCE)              # View all
BEBOP1_RESONANCE.get('C-C')          # Get value
BEBOP1_RESONANCE.list_bond_types()   # List available
BEBOP1_RESONANCE.to_dict()           # Export as dict

---

API Reference

BEBOP Class

BEBOP(name: str, model: str = 'bebop2')
    # model: 'bebop1', 'bebop2', 1, or 2

# Energy methods
total_E() -> float
bond_E(NetBond=True, GrossBond=False, Composite=False, sig_pi=False)
ionic_character() -> tuple  # bebop2 only

# Resonance/strain methods
resonance_E(Atom_Positions: dict, reference_bond_orders: dict = None) -> float
strain_E(Atom_Positions: dict, reference_bond_orders: dict = None) -> float

# Reference management
get_resonance_references() -> ReferenceBondOrders
get_strain_references() -> ReferenceBondOrders
add_resonance_reference(bond_type, value, atom_pair, description="")
set_resonance_reference(bond_type, value)
set_strain_reference(param_name, value)
reset_references(which='all')  # 'resonance', 'strain', or 'all'

ResonanceStrainCalculator (Advanced)

For direct use without loading a Gaussian file:

from bebop import ResonanceStrainCalculator

calc = ResonanceStrainCalculator(
    model='bebop1',      # or 'bebop2', 1, 2
    mulliken=matrix,
    bo_sig=sig_matrix,   # Required for bebop2
    bo_pi=pi_matrix,     # Required for bebop2
)
res_E = calc.resonance_energy(positions, reference_bond_orders=refs)
strain_E = calc.strain_energy(positions)

Key Attributes

Attribute	Description	Models
mol	Element symbols	both
mulliken	Mulliken bond order matrix	both
bo_sig, bo_pi	Sigma/pi bond order matrices	bebop2
charges	Mulliken atomic charges	bebop2
E_net, E_gross	Net/gross bond energy matrices	both (after bond_E())

---

Input Requirements

BEBOP requires Gaussian output files with MinPop analysis:

# SP ROHF/CBSB3 Pop=(Full) IOp(6/27=122,6/12=3)

Supported elements: H, He, Li, Be, B, C, N, O, F

---

License

MIT License - Copyright (c) 2026, Barbaro Zulueta

Citation

BEBOP-1:

Barbaro Zulueta, et al. "Bond Energy from Bond Order Populations." J. Chem. Theory Comput. 2022, 18, 4774-4794. DOI: 10.1021/acs.jctc.2c00334

BEBOP-2:

Barbaro Zulueta, George A. Petersson, and John A. Keith. "Sigma/Pi Bond and Charge Model Contributions to BEBOP Model." 2026 (in preparation).