mbd-framework 1.0.2

A formal validation toolkit calculating Many-Body Dispersion bounds connecting geometric theorems derived in Lean.

MBD Framework: Many-Body Dispersion Computations

mbd-framework is a computational toolkit that calculates precise Many-Body Dispersion (MBD) scaling bounds and Tkatchenko-Scheffler (TS) screening parameters. It acts as the numerical bridge between formal mathematical proofs (derived in Lean 4) and first-principles quantum chemistry computations (powered by PySCF).

---

🚀 Installation

Install the framework globally via PyPI:

pip install mbd-framework

---

💻 Quick Start & Command Line Tools

Once installed, the framework provides three native command-line tools to instantly run calculations on your molecular targets:

1. Extract Atomic Density Bounds (mbd-compute)

Run background PySCF calculations to extract absolute finite-field Cartesian dipole tensors, compute precise atomic polarizabilities ($\alpha$), and map them to the universal TS scaling parameter $x = V_{\text{Bohr}} / \alpha$. The results are safely checkpointed into a local database.json.

# Example: Extract the bounds for Benzene using the aug-cc-pVDZ basis set
mbd-compute --molecule Benzene --basis aug-cc-pVDZ

Supported molecules: Benzene, Naphthalene, Ice, He, Ne, Xe

2. Simulate Crystal Dispersion (mbd-crystal)

Generate a structurally symmetric 7x7x7 Cartesian atomic lattice array (thousands of interacting pairs) to compute the macroscopic isotropic dispersion grid ($C_{6} \cdot \varepsilon^{-x} / R^{6}$) against your extracted bounds, yielding total empirical lattice energies in kJ/mol.

# Example: Simulate Benzene dispersion scaling in a vacuum (epsilon = 1.0)
mbd-crystal --target Benzene --epsilon 1.0

3. SERS Mathematical Equivalence (mbd-sers)

A strict numerical checking endpoint that compares the macroscopic structural Surface-Enhanced Raman Scattering (SERS) exponential quenching envelope ($\exp(-\rho)$) against the framework's intrinsic MBD interacting boundaries ($\varepsilon^{-x}$).

# Example: Test SERS equivalence for Benzene
mbd-sers --target Benzene --epsilon 2.0

---

🛠 Features at a Glance

• Strictly Typed Physics: The extraction pipeline explicitly intercepts non-converged PySCF Hartree-Fock instabilities, ensuring only physically valid, positive $\alpha$ states pass through.
• Automated Checkpointing: Computations automatically stack results into a local database.json to prevent losing time-intensive finite-field SCF runs.
• Seamless Academic Pipeline: Numerically validates mathematical limit theorems bounding dispersion properties for large-scale Molecular Crystals.

---

For detailed physics explanations, API structures, and Lean 4 formal mathematical proofs, please visit the main academic repository at GitHub: MBD-Theoretical-Framework.