qmcert 1.0.0__tar.gz

qmcert-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Monreal-Hernández
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qmcert-1.0.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: qmcert
+Version: 1.0.0
+Summary: Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations
+Author-email: Andre Monreal-Hernández <amonreal@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sircalch/qmcert
+Project-URL: Documentation, https://github.com/sircalch/qmcert#readme
+Project-URL: Repository, https://github.com/sircalch/qmcert.git
+Project-URL: Bug Tracker, https://github.com/sircalch/qmcert/issues
+Project-URL: Changelog, https://github.com/sircalch/qmcert/blob/main/CHANGELOG.md
+Keywords: quantum-chemistry,dft,orca,gaussian,q-chem,scf-convergence,imaginary-frequencies,transition-state,spin-contamination,thermochemistry,reproducibility,computational-chemistry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: jinja2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# QMCert
+
+[![CI](https://github.com/sircalch/qmcert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/qmcert/actions)
+[![PyPI version](https://img.shields.io/pypi/v/qmcert.svg?color=blue)](https://pypi.org/project/qmcert/)
+[![Python versions](https://img.shields.io/pypi/pyversions/qmcert.svg)](https://pypi.org/project/qmcert/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1234569.svg)](https://doi.org/10.5281/zenodo.1234569)
+
+> **Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations.**
+
+---
+
+## Overview
+
+**QMCert** is an open-source scientific toolkit designed to systematically audit, validate, and certify electronic structure calculations (**DFT, HF, post-HF, semiempirical**) from **ORCA**, **Gaussian**, **Q-Chem**, and **NWChem**.
+
+Instead of manually inspecting log files to ensure calculations are publication-ready, `qmcert` performs a comprehensive automated audit with a single command:
+
+- 🎯 **Stationary Point Certification**:
+  - Automatically identifies imaginary frequencies ($\nu < 0\text{ cm}^{-1}$).
+  - Validates **Local Minima** (0 imaginary modes) vs **Transition States** (exactly 1 imaginary mode).
+  - Flags unphysical saddle points with clear diagnostic messages.
+- 🔄 **Wavefunction & Spin Contamination ($\langle S^2 \rangle$)**:
+  - Audits expectation values $\langle S^2 \rangle_{\text{calc}}$ vs exact theoretical $S(S+1)$.
+  - Calculates spin contamination percentage and triggers alerts if $> 5.0\%$.
+- ⚡ **SCF & Geometry Convergence Verification**:
+  - Checks 4 standard convergence thresholds (Energy change, Max/RMS gradients, Max/RMS displacements).
+- 🌡️ **Advanced Thermochemistry & Quasi-Harmonic Corrections**:
+  - Extracts ZPVE, thermal enthalpy $H(T)$, Gibbs free energy $G(T)$, and entropy $S(T)$.
+  - Applies **Grimme's quasi-RRHO harmonic entropy correction** to prevent rotational/vibrational divergence for low-frequency modes ($\nu < 100\text{ cm}^{-1}$).
+- 🌈 **Simulated IR Vibrational Spectra**:
+  - Lorentzian line-broadening with peak identification.
+- 🚦 **Quantum Chemistry Validation Score (`PASS` / `WARNING` / `FAIL`)**.
+- 📑 **Publication Deliverables**: Interactive self-contained `report.html`, publication vector plots (SVG/PDF/PNG 300 DPI), LaTeX summary tables (`.tex`), and a draft **Computational Details** Methods paragraph with automated **BibTeX citations**.
+
+```
+  Quantum Chemical Output (.out, .log)
+                    │
+                    ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                          QMCert                           │
+  │  ├── Stationary Point Certification (0 or 1 Imag Freq)    │
+  │  ├── Spin Contamination Audit (<S^2> vs S(S+1))           │
+  │  ├── SCF & Geometry Optimization Convergence              │
+  │  ├── Grimme Quasi-RRHO Thermochemistry Corrections        │
+  │  └── Frontier Orbital Gap & Simulated IR Spectrum         │
+  └───────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── qmcert_simulated_ir_spectrum.pdf/svg/png             │
+  │  ├── qmcert_summary_table.tex / .csv                      │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install qmcert
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/qmcert.git
+cd qmcert
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Demonstration Mode (Instant Benchmark DFT Calculation)
+```bash
+qmcert demo -o my_qm_validation/
+```
+Open `my_qm_validation/report.html` in any browser to inspect the report and simulated IR spectrum!
+
+### 2. Assess ORCA / Gaussian Output File
+```bash
+qmcert assess -i calculation.out -o qm_quality_report/
+```
+
+### 3. Certify a Transition State (TS) Calculation
+```bash
+qmcert assess -i ts_optimization.out --ts -o ts_report/
+```
+
+---
+
+## Python API Usage
+
+```python
+from qmcert import assess_qm_quality
+from qmcert.parsers import parse_qm_output
+from qmcert.reporters import generate_qm_figures, generate_qm_manuscript_assets, generate_qm_html_report
+
+# 1. Parse quantum chemistry output (ORCA / Gaussian)
+parsed_data = parse_qm_output("my_dft_calc.out")
+
+# 2. Assess calculation quality
+report = assess_qm_quality(
+    metadata=parsed_data["metadata"],
+    scf_converged=parsed_data["scf_converged"],
+    frequencies=parsed_data["frequencies"],
+    intensities=parsed_data["intensities"],
+    expected_point_type="MINIMUM",
+    s2_calculated=parsed_data["s2_calculated"],
+    thermochemistry=parsed_data["thermochemistry"]
+)
+
+print(f"Overall Certification: {report.overall_status}")
+print(f"Stationary Point: {report.frequency_result.point_type}")
+
+# 3. Export all publication assets
+generate_qm_figures(report, "output_dir/")
+generate_qm_manuscript_assets(report, "output_dir/")
+generate_qm_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use QMCert to validate quantum-chemical calculations, certify stationary points, or calculate quasi-RRHO corrections, please cite:
+
+```bibtex
+@software{monreal2026qmcert,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{QMCert: Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/qmcert}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

qmcert-1.0.0/README.md

@@ -0,0 +1,150 @@
+# QMCert
+
+[![CI](https://github.com/sircalch/qmcert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/qmcert/actions)
+[![PyPI version](https://img.shields.io/pypi/v/qmcert.svg?color=blue)](https://pypi.org/project/qmcert/)
+[![Python versions](https://img.shields.io/pypi/pyversions/qmcert.svg)](https://pypi.org/project/qmcert/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1234569.svg)](https://doi.org/10.5281/zenodo.1234569)
+
+> **Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations.**
+
+---
+
+## Overview
+
+**QMCert** is an open-source scientific toolkit designed to systematically audit, validate, and certify electronic structure calculations (**DFT, HF, post-HF, semiempirical**) from **ORCA**, **Gaussian**, **Q-Chem**, and **NWChem**.
+
+Instead of manually inspecting log files to ensure calculations are publication-ready, `qmcert` performs a comprehensive automated audit with a single command:
+
+- 🎯 **Stationary Point Certification**:
+  - Automatically identifies imaginary frequencies ($\nu < 0\text{ cm}^{-1}$).
+  - Validates **Local Minima** (0 imaginary modes) vs **Transition States** (exactly 1 imaginary mode).
+  - Flags unphysical saddle points with clear diagnostic messages.
+- 🔄 **Wavefunction & Spin Contamination ($\langle S^2 \rangle$)**:
+  - Audits expectation values $\langle S^2 \rangle_{\text{calc}}$ vs exact theoretical $S(S+1)$.
+  - Calculates spin contamination percentage and triggers alerts if $> 5.0\%$.
+- ⚡ **SCF & Geometry Convergence Verification**:
+  - Checks 4 standard convergence thresholds (Energy change, Max/RMS gradients, Max/RMS displacements).
+- 🌡️ **Advanced Thermochemistry & Quasi-Harmonic Corrections**:
+  - Extracts ZPVE, thermal enthalpy $H(T)$, Gibbs free energy $G(T)$, and entropy $S(T)$.
+  - Applies **Grimme's quasi-RRHO harmonic entropy correction** to prevent rotational/vibrational divergence for low-frequency modes ($\nu < 100\text{ cm}^{-1}$).
+- 🌈 **Simulated IR Vibrational Spectra**:
+  - Lorentzian line-broadening with peak identification.
+- 🚦 **Quantum Chemistry Validation Score (`PASS` / `WARNING` / `FAIL`)**.
+- 📑 **Publication Deliverables**: Interactive self-contained `report.html`, publication vector plots (SVG/PDF/PNG 300 DPI), LaTeX summary tables (`.tex`), and a draft **Computational Details** Methods paragraph with automated **BibTeX citations**.
+
+```
+  Quantum Chemical Output (.out, .log)
+                    │
+                    ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                          QMCert                           │
+  │  ├── Stationary Point Certification (0 or 1 Imag Freq)    │
+  │  ├── Spin Contamination Audit (<S^2> vs S(S+1))           │
+  │  ├── SCF & Geometry Optimization Convergence              │
+  │  ├── Grimme Quasi-RRHO Thermochemistry Corrections        │
+  │  └── Frontier Orbital Gap & Simulated IR Spectrum         │
+  └───────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── qmcert_simulated_ir_spectrum.pdf/svg/png             │
+  │  ├── qmcert_summary_table.tex / .csv                      │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install qmcert
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/qmcert.git
+cd qmcert
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Demonstration Mode (Instant Benchmark DFT Calculation)
+```bash
+qmcert demo -o my_qm_validation/
+```
+Open `my_qm_validation/report.html` in any browser to inspect the report and simulated IR spectrum!
+
+### 2. Assess ORCA / Gaussian Output File
+```bash
+qmcert assess -i calculation.out -o qm_quality_report/
+```
+
+### 3. Certify a Transition State (TS) Calculation
+```bash
+qmcert assess -i ts_optimization.out --ts -o ts_report/
+```
+
+---
+
+## Python API Usage
+
+```python
+from qmcert import assess_qm_quality
+from qmcert.parsers import parse_qm_output
+from qmcert.reporters import generate_qm_figures, generate_qm_manuscript_assets, generate_qm_html_report
+
+# 1. Parse quantum chemistry output (ORCA / Gaussian)
+parsed_data = parse_qm_output("my_dft_calc.out")
+
+# 2. Assess calculation quality
+report = assess_qm_quality(
+    metadata=parsed_data["metadata"],
+    scf_converged=parsed_data["scf_converged"],
+    frequencies=parsed_data["frequencies"],
+    intensities=parsed_data["intensities"],
+    expected_point_type="MINIMUM",
+    s2_calculated=parsed_data["s2_calculated"],
+    thermochemistry=parsed_data["thermochemistry"]
+)
+
+print(f"Overall Certification: {report.overall_status}")
+print(f"Stationary Point: {report.frequency_result.point_type}")
+
+# 3. Export all publication assets
+generate_qm_figures(report, "output_dir/")
+generate_qm_manuscript_assets(report, "output_dir/")
+generate_qm_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use QMCert to validate quantum-chemical calculations, certify stationary points, or calculate quasi-RRHO corrections, please cite:
+
+```bibtex
+@software{monreal2026qmcert,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{QMCert: Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/qmcert}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

qmcert-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qmcert"
+version = "1.0.0"
+description = "Automated Quality-Control, Stationary Point Certification, and Reproducibility Assessment for Quantum-Chemical Calculations"
+readme = "README.md"
+authors = [
+    { name = "Andre Monreal-Hernández", email = "amonreal@example.com" }
+]
+license = { text = "MIT" }
+keywords = [
+    "quantum-chemistry",
+    "dft",
+    "orca",
+    "gaussian",
+    "q-chem",
+    "scf-convergence",
+    "imaginary-frequencies",
+    "transition-state",
+    "spin-contamination",
+    "thermochemistry",
+    "reproducibility",
+    "computational-chemistry"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent"
+]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.20.0",
+    "scipy>=1.7.0",
+    "pandas>=1.3.0",
+    "matplotlib>=3.5.0",
+    "jinja2>=3.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "flake8>=6.0.0",
+    "build>=0.10.0",
+    "twine>=4.0.0"
+]
+
+[project.scripts]
+qmcert = "qmcert.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sircalch/qmcert"
+Documentation = "https://github.com/sircalch/qmcert#readme"
+Repository = "https://github.com/sircalch/qmcert.git"
+"Bug Tracker" = "https://github.com/sircalch/qmcert/issues"
+Changelog = "https://github.com/sircalch/qmcert/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["qmcert*"]
+
+

qmcert-1.0.0/qmcert/__init__.py

@@ -0,0 +1,46 @@
+"""
+QMCert: Automated Quality-Control, Stationary Point Certification, and Reproducibility
+Assessment for Quantum-Chemical Calculations.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Andre Monreal-Hernández"
+__license__ = "MIT"
+
+from qmcert.core.frequencies import (
+    classify_stationary_point,
+    simulate_ir_spectrum,
+    FrequencyAnalysisResult
+)
+from qmcert.core.scf_opt import (
+    evaluate_scf_convergence,
+    evaluate_geometry_optimization,
+    ConvergenceCriteria
+)
+from qmcert.core.wavefunction import (
+    evaluate_spin_contamination,
+    evaluate_orbital_gap,
+    SpinAnalysisResult
+)
+from qmcert.core.thermo import (
+    calculate_quasi_rrho_corrections,
+    ThermochemistryData
+)
+from qmcert.core.scoring import assess_qm_quality, QMCertValidationReport
+
+__all__ = [
+    "__version__",
+    "classify_stationary_point",
+    "simulate_ir_spectrum",
+    "FrequencyAnalysisResult",
+    "evaluate_scf_convergence",
+    "evaluate_geometry_optimization",
+    "ConvergenceCriteria",
+    "evaluate_spin_contamination",
+    "evaluate_orbital_gap",
+    "SpinAnalysisResult",
+    "calculate_quasi_rrho_corrections",
+    "ThermochemistryData",
+    "assess_qm_quality",
+    "QMCertValidationReport"
+]