adsorpqc 1.0.0__tar.gz

adsorpqc-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.

adsorpqc-1.0.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: adsorpqc
+Version: 1.0.0
+Summary: Automated Quality-Control, GCMC Burn-in Detection, Isotherm Fitting, and Reproducibility Toolkit for Adsorption Simulations in Nanoporous Materials
+Author-email: Andre Monreal-Hernández <amonreal@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sircalch/adsorpqc
+Project-URL: Documentation, https://github.com/sircalch/adsorpqc#readme
+Project-URL: Repository, https://github.com/sircalch/adsorpqc.git
+Project-URL: Bug Tracker, https://github.com/sircalch/adsorpqc/issues
+Project-URL: Changelog, https://github.com/sircalch/adsorpqc/blob/main/CHANGELOG.md
+Keywords: adsorption,gcmc,raspa,mofs,cofs,zeolites,isotherms,langmuir,iast,isosteric-heat,henry-coefficient,reproducibility,computational-materials
+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
+
+# AdsorpQC
+
+[![CI](https://github.com/sircalch/adsorpqc/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/adsorpqc/actions)
+[![PyPI version](https://img.shields.io/pypi/v/adsorpqc.svg?color=blue)](https://pypi.org/project/adsorpqc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/adsorpqc.svg)](https://pypi.org/project/adsorpqc/)
+[![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.1234570.svg)](https://doi.org/10.5281/zenodo.1234570)
+
+> **Automated Quality-Control, GCMC Burn-in Detection, Isotherm Model Fitting, and Reproducibility Toolkit for Adsorption Simulations in Nanoporous Materials.**
+
+---
+
+## Overview
+
+**AdsorpQC** is an open-source scientific software toolkit tailored for the rigorous validation and certification of molecular adsorption simulations (**Grand Canonical Monte Carlo, GCMC**, RASPA, LAMMPS) and experimental gas isotherms in **MOFs, COFs, Zeolites, and Porous Carbons**.
+
+In GCMC simulations, reporting average loadings before reaching true thermodynamic equilibrium (*under-equilibrated burn-in*) or during unresolved systematic drift leads to invalid capacities. `adsorpqc` addresses this with an automated quality-control pipeline in a single command:
+
+- ⏳ **Automated GCMC Burn-in Detection**:
+  - Maximizes the number of statistically independent production samples ($N_{\text{eff}}$).
+  - Automatically identifies and truncates un-equilibrated initialization cycles.
+- 📉 **Loading Drift & Stationarity Audit**:
+  - Evaluates percentage loading drift $\Delta_{\text{drift}}$ across the production phase.
+  - Generates clear safety alerts: `"DO NOT REPORT PRODUCTION AVERAGE"` if $\Delta_{\text{drift}} > 8.0\%$.
+- 🧪 **Non-Linear Isotherm Fitting & Model Selection**:
+  - Fits **Langmuir**, **Dual-Site Langmuir (DSLG)**, **Sips (Langmuir-Freundlich)**, **Toth**, **Freundlich**, and **BET** models.
+  - Automatically ranks models and selects the optimal description using **Akaike Information Criterion (AIC)** and $R^2$.
+- ⚡ **Thermodynamic Energetics & Selectivity**:
+  - **Henry coefficient ($K_H$)** via low-pressure linear regression.
+  - **Isosteric heat of adsorption ($q_{\text{st}}$)** via particle-energy fluctuation formulas in $\mu VT$ ensemble.
+  - **Ideal Adsorbed Solution Theory (IAST)** binary mixture selectivity ($S_{A/B}$) with **95% Bootstrap Confidence Intervals**.
+- 📑 **Publication Deliverables**:
+  - Interactive self-contained `report.html` dashboard.
+  - Vector publication plots (Isotherm fit curves, GCMC burn-in shaded trajectory) in SVG, PDF, PNG (300 DPI).
+  - Ready-to-compile LaTeX summary tables (`.tex`).
+  - Draft **Methods** text paragraph and BibTeX citation (`citation.bib`).
+
+```
+    GCMC Simulation (RASPA) / Isotherm CSV
+                      │
+                      ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                         AdsorpQC                          │
+  │  ├── Automated GCMC Burn-in / Equilibration Cutoff        │
+  │  ├── Production Loading Drift & Stationarity Audit        │
+  │  ├── Non-Linear Isotherm Fitting (Langmuir, Sips, Toth)   │
+  │  ├── Henry Constant (K_H) & Isosteric Heat (q_st)        │
+  │  └── IAST Selectivity (S_A/B) with Bootstrap 95% CI       │
+  └───────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── adsorpqc_isotherm_fit.pdf/svg/png                    │
+  │  ├── adsorpqc_gcmc_burnin_trajectory.pdf/svg/png         │
+  │  ├── adsorpqc_summary_table.tex / .csv                    │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install adsorpqc
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/adsorpqc.git
+cd adsorpqc
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Benchmark Demo (Instant GCMC + Isotherm Simulation)
+```bash
+adsorpqc demo -o my_adsorption_audit/
+```
+Open `my_adsorption_audit/report.html` in your browser to explore the interactive dashboard!
+
+### 2. Assess Isotherm CSV File
+```bash
+adsorpqc assess -i my_isotherm.csv --framework "Mg-MOF-74" --adsorbate "CO2" --temp 298.15 -o output_report/
+```
+
+### 3. Assess RASPA Simulation Output
+```bash
+adsorpqc assess -i output_Mg-MOF-74_298.000000_100000.data -o raspa_audit/
+```
+
+---
+
+## Python API Usage
+
+```python
+import numpy as np
+from adsorpqc import assess_adsorption_quality
+from adsorpqc.parsers import parse_isotherm_csv
+from adsorpqc.reporters import generate_adsorption_figures, generate_adsorption_manuscript_assets, generate_adsorption_html_report
+
+# 1. Parse isotherm data
+data = parse_isotherm_csv("co2_isotherm.csv")
+
+# 2. Assess quality and fit models
+report = assess_adsorption_quality(
+    metadata={"framework": "HKUST-1", "adsorbate": "CO2", "temperature_k": 298.15},
+    pressure_isotherm=data["pressure"],
+    loading_isotherm=data["loading"],
+    temperature_k=298.15
+)
+
+print(f"Overall Certification: {report.overall_status}")
+print(f"Optimal Model: {report.isotherm_fits['best_model_name']} (R^2 = {report.isotherm_fits['best_r_squared']:.4f})")
+
+# 3. Export all publication assets
+generate_adsorption_figures(report, "output_dir/", pressure_raw=data["pressure"], loading_raw=data["loading"])
+generate_adsorption_manuscript_assets(report, "output_dir/")
+generate_adsorption_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use AdsorpQC in your publications, please cite:
+
+```bibtex
+@software{monreal2026adsorpqc,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{AdsorpQC: An Open-Source Toolkit for Quality-Control, GCMC Burn-in Detection, Isotherm Fitting, and Reproducibility Assessment of Adsorption Simulations}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/adsorpqc}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

adsorpqc-1.0.0/README.md

@@ -0,0 +1,151 @@
+# AdsorpQC
+
+[![CI](https://github.com/sircalch/adsorpqc/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/adsorpqc/actions)
+[![PyPI version](https://img.shields.io/pypi/v/adsorpqc.svg?color=blue)](https://pypi.org/project/adsorpqc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/adsorpqc.svg)](https://pypi.org/project/adsorpqc/)
+[![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.1234570.svg)](https://doi.org/10.5281/zenodo.1234570)
+
+> **Automated Quality-Control, GCMC Burn-in Detection, Isotherm Model Fitting, and Reproducibility Toolkit for Adsorption Simulations in Nanoporous Materials.**
+
+---
+
+## Overview
+
+**AdsorpQC** is an open-source scientific software toolkit tailored for the rigorous validation and certification of molecular adsorption simulations (**Grand Canonical Monte Carlo, GCMC**, RASPA, LAMMPS) and experimental gas isotherms in **MOFs, COFs, Zeolites, and Porous Carbons**.
+
+In GCMC simulations, reporting average loadings before reaching true thermodynamic equilibrium (*under-equilibrated burn-in*) or during unresolved systematic drift leads to invalid capacities. `adsorpqc` addresses this with an automated quality-control pipeline in a single command:
+
+- ⏳ **Automated GCMC Burn-in Detection**:
+  - Maximizes the number of statistically independent production samples ($N_{\text{eff}}$).
+  - Automatically identifies and truncates un-equilibrated initialization cycles.
+- 📉 **Loading Drift & Stationarity Audit**:
+  - Evaluates percentage loading drift $\Delta_{\text{drift}}$ across the production phase.
+  - Generates clear safety alerts: `"DO NOT REPORT PRODUCTION AVERAGE"` if $\Delta_{\text{drift}} > 8.0\%$.
+- 🧪 **Non-Linear Isotherm Fitting & Model Selection**:
+  - Fits **Langmuir**, **Dual-Site Langmuir (DSLG)**, **Sips (Langmuir-Freundlich)**, **Toth**, **Freundlich**, and **BET** models.
+  - Automatically ranks models and selects the optimal description using **Akaike Information Criterion (AIC)** and $R^2$.
+- ⚡ **Thermodynamic Energetics & Selectivity**:
+  - **Henry coefficient ($K_H$)** via low-pressure linear regression.
+  - **Isosteric heat of adsorption ($q_{\text{st}}$)** via particle-energy fluctuation formulas in $\mu VT$ ensemble.
+  - **Ideal Adsorbed Solution Theory (IAST)** binary mixture selectivity ($S_{A/B}$) with **95% Bootstrap Confidence Intervals**.
+- 📑 **Publication Deliverables**:
+  - Interactive self-contained `report.html` dashboard.
+  - Vector publication plots (Isotherm fit curves, GCMC burn-in shaded trajectory) in SVG, PDF, PNG (300 DPI).
+  - Ready-to-compile LaTeX summary tables (`.tex`).
+  - Draft **Methods** text paragraph and BibTeX citation (`citation.bib`).
+
+```
+    GCMC Simulation (RASPA) / Isotherm CSV
+                      │
+                      ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                         AdsorpQC                          │
+  │  ├── Automated GCMC Burn-in / Equilibration Cutoff        │
+  │  ├── Production Loading Drift & Stationarity Audit        │
+  │  ├── Non-Linear Isotherm Fitting (Langmuir, Sips, Toth)   │
+  │  ├── Henry Constant (K_H) & Isosteric Heat (q_st)        │
+  │  └── IAST Selectivity (S_A/B) with Bootstrap 95% CI       │
+  └───────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── adsorpqc_isotherm_fit.pdf/svg/png                    │
+  │  ├── adsorpqc_gcmc_burnin_trajectory.pdf/svg/png         │
+  │  ├── adsorpqc_summary_table.tex / .csv                    │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install adsorpqc
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/adsorpqc.git
+cd adsorpqc
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Benchmark Demo (Instant GCMC + Isotherm Simulation)
+```bash
+adsorpqc demo -o my_adsorption_audit/
+```
+Open `my_adsorption_audit/report.html` in your browser to explore the interactive dashboard!
+
+### 2. Assess Isotherm CSV File
+```bash
+adsorpqc assess -i my_isotherm.csv --framework "Mg-MOF-74" --adsorbate "CO2" --temp 298.15 -o output_report/
+```
+
+### 3. Assess RASPA Simulation Output
+```bash
+adsorpqc assess -i output_Mg-MOF-74_298.000000_100000.data -o raspa_audit/
+```
+
+---
+
+## Python API Usage
+
+```python
+import numpy as np
+from adsorpqc import assess_adsorption_quality
+from adsorpqc.parsers import parse_isotherm_csv
+from adsorpqc.reporters import generate_adsorption_figures, generate_adsorption_manuscript_assets, generate_adsorption_html_report
+
+# 1. Parse isotherm data
+data = parse_isotherm_csv("co2_isotherm.csv")
+
+# 2. Assess quality and fit models
+report = assess_adsorption_quality(
+    metadata={"framework": "HKUST-1", "adsorbate": "CO2", "temperature_k": 298.15},
+    pressure_isotherm=data["pressure"],
+    loading_isotherm=data["loading"],
+    temperature_k=298.15
+)
+
+print(f"Overall Certification: {report.overall_status}")
+print(f"Optimal Model: {report.isotherm_fits['best_model_name']} (R^2 = {report.isotherm_fits['best_r_squared']:.4f})")
+
+# 3. Export all publication assets
+generate_adsorption_figures(report, "output_dir/", pressure_raw=data["pressure"], loading_raw=data["loading"])
+generate_adsorption_manuscript_assets(report, "output_dir/")
+generate_adsorption_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use AdsorpQC in your publications, please cite:
+
+```bibtex
+@software{monreal2026adsorpqc,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{AdsorpQC: An Open-Source Toolkit for Quality-Control, GCMC Burn-in Detection, Isotherm Fitting, and Reproducibility Assessment of Adsorption Simulations}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/adsorpqc}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

adsorpqc-1.0.0/adsorpqc/__init__.py

@@ -0,0 +1,46 @@
+"""
+AdsorpQC: Automated Quality-Control, GCMC Burn-in Detection, Isotherm Fitting, and
+Reproducibility Assessment for Adsorption Simulations.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Andre Monreal-Hernández"
+__license__ = "MIT"
+
+from adsorpqc.core.burnin import (
+    detect_gcmc_burnin,
+    assess_loading_drift,
+    GCMCBurninResult
+)
+from adsorpqc.core.isotherms import (
+    fit_all_isotherm_models,
+    fit_langmuir,
+    fit_dual_site_langmuir,
+    fit_sips,
+    fit_toth,
+    IsothermFitResult
+)
+from adsorpqc.core.energetics import (
+    calculate_henry_constant,
+    calculate_isosteric_heat
+)
+from adsorpqc.core.iast import calculate_iast_selectivity
+from adsorpqc.core.scoring import assess_adsorption_quality, AdsorptionValidationReport
+
+__all__ = [
+    "__version__",
+    "detect_gcmc_burnin",
+    "assess_loading_drift",
+    "GCMCBurninResult",
+    "fit_all_isotherm_models",
+    "fit_langmuir",
+    "fit_dual_site_langmuir",
+    "fit_sips",
+    "fit_toth",
+    "IsothermFitResult",
+    "calculate_henry_constant",
+    "calculate_isosteric_heat",
+    "calculate_iast_selectivity",
+    "assess_adsorption_quality",
+    "AdsorptionValidationReport"
+]