chemistrykit 0.1.0__tar.gz

chemistrykit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chemistrykit contributors
+
+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.

chemistrykit-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: chemistrykit
+Version: 0.1.0
+Summary: Unified numerical toolkit for computational chemistry: reaction kinetics, thermodynamics, quantum chemistry, electrochemistry, spectroscopy, and more, sharing common ODE integrators and chemical constants.
+Author-email: Charles Poli <cpoli374@gmail.com>
+Maintainer-email: Charles Poli <cpoli374@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cpoli/chemistrykit
+Project-URL: Issues, https://github.com/cpoli/chemistrykit/issues
+Project-URL: Changelog, https://github.com/cpoli/chemistrykit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cpoli.github.io/chemistrykit/
+Keywords: chemistry,computational-chemistry,reaction-kinetics,thermodynamics,quantum-chemistry,electrochemistry,spectroscopy,physical-chemistry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numba>=0.58
+Requires-Dist: plotly>=5.15
+Requires-Dist: sympy>=1.11
+Requires-Dist: tqdm>=4.65
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: hypothesis>=6.90; extra == "test"
+Requires-Dist: pillow>=9.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: chemistrykit[docs,test]; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Dynamic: license-file
+
+# chemistrykit
+
+| | |
+|:--|:-:|
+| Package | [![PyPI version](https://img.shields.io/pypi/v/chemistrykit)](https://pypi.org/project/chemistrykit/) [![Python versions](https://img.shields.io/pypi/pyversions/chemistrykit)](https://pypi.org/project/chemistrykit/) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/blob/main/LICENSE) [![CI](https://github.com/cpoli/chemistrykit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/chemistrykit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/cpoli/chemistrykit)](https://codecov.io/gh/cpoli/chemistrykit) [![Coverage (manual)](https://img.shields.io/badge/coverage-96%25-brightgreen)](#coverage) |
+| Documentation | [![Docs](https://img.shields.io/badge/docs-cpoli.github.io%2Fchemistrykit-blue)](https://cpoli.github.io/chemistrykit/) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Downloads | [![Downloads](https://static.pepy.tech/badge/chemistrykit)](https://pepy.tech/project/chemistrykit) [![Downloads/Month](https://static.pepy.tech/badge/chemistrykit/month)](https://pepy.tech/project/chemistrykit) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/chemistrykit?style=social)](https://github.com/cpoli/chemistrykit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/chemistrykit?style=social)](https://github.com/cpoli/chemistrykit) [![Contributors](https://img.shields.io/github/contributors/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/commits/main) |
+
+A unified numerical toolkit for computational chemistry, spanning the
+field end to end: Arrhenius kinetics and oscillating reaction networks,
+Huckel aromaticity and variational quantum chemistry, Nernst cells and
+Butler-Volmer electrochemistry, NMR multiplets and Franck-Condon
+spectra, crystal lattice energies and powder XRD, polymer chain
+statistics and photochemical quenching -- with each domain's docs
+tracing the field's own foundational breakthroughs in chronological,
+pedagogical order, every historical milestone linked directly to the
+runnable code that reproduces it. Pure-numerical throughout -- no
+cheminformatics dependencies (no RDKit/ASE/PySCF/OpenMM) -- sharing
+common ODE integrators, chemical constants, and a consistent NumPy-based
+API. Conventionally imported as `ck`. chemistrykit clones the
+architecture and engineering conventions of the sibling project
+[physicskit](https://github.com/physicskit/physicskit) (`pk`).
+
+All 14 domains from `chemistrykit-spec.md`'s build plan are implemented
+-- see [Subpackages](#subpackages) for the full list, or browse the docs
+at <https://chemistrykit.readthedocs.io>.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import chemistrykit as ck
+import numpy as np
+
+# Closed-form first-order decay and its half-life
+rate_law = ck.kinetics.FirstOrder(k=0.1, C0=1.0)
+print(rate_law.half_life())  # ln(2) / k
+
+# A general stoichiometric reaction network: A -> B -> C
+network = ck.kinetics.StoichiometricNetwork.consecutive(k1=1.0, k2=0.3, A0=1.0)
+result = network.integrate((0.0, 10.0), dt=1e-3, method="rk4")
+print(result.concentration("B")[-1])
+```
+
+## Subpackages
+
+Domain subpackages, each with runnable examples linked below:
+
+- [`chemistrykit.kinetics`](https://chemistrykit.readthedocs.io/en/latest/examples/kinetics.html) -- reaction kinetics: integrated rate laws and half-lives, the Arrhenius equation and activation-energy fitting, Michaelis-Menten enzyme kinetics with Lineweaver-Burk linearization and inhibition, a general stoichiometry-matrix reaction-network engine (parallel/consecutive/reversible/steady-state-approximation chains), and the Brusselator oscillating reaction network.
+- [`chemistrykit.thermo`](https://chemistrykit.readthedocs.io/en/latest/examples/thermo.html) -- chemical thermodynamics: equations of state (ideal gas, van der Waals, Redlich-Kwong), Clausius-Clapeyron phase boundaries, reaction equilibrium (Kp/Kc, van't Hoff, and a Gibbs-energy-minimization equilibrium-composition solver), and Raoult's/Henry's law mixtures with colligative properties.
+- [`chemistrykit.solutions`](https://chemistrykit.readthedocs.io/en/latest/examples/solutions.html) -- solution chemistry: pH/pOH and weak acid/base equilibria with Henderson-Hasselbalch buffers, acid-base titration curves, Ksp solubility equilibria and the common-ion effect, and Debye-Huckel activity coefficients.
+- [`chemistrykit.md`](https://chemistrykit.readthedocs.io/en/latest/examples/md.html) -- molecular dynamics and force fields: the Lennard-Jones fluid in reduced units (periodic boundary conditions, a Verlet neighbor list, pressure, g(r)), Morse/Buckingham/harmonic bonded potentials, and velocity-rescaling/Nose-Hoover thermostats.
+- [`chemistrykit.statmech`](https://chemistrykit.readthedocs.io/en/latest/examples/statmech.html) -- statistical mechanics of molecules: translational/rotational/vibrational partition functions and their thermodynamic functions, the Maxwell-Boltzmann speed distribution, and a canonical-ensemble lattice-gas adsorption model.
+- [`chemistrykit.quantum`](https://chemistrykit.readthedocs.io/en/latest/examples/quantum.html) -- quantum chemistry: particle-in-a-box models (with the free-electron model of conjugated-dye color); the quantum harmonic oscillator vs. the exact Morse potential; the rigid rotor; hydrogen-like orbitals; Huckel molecular-orbital theory and its 4n+2 aromaticity rule; a minimal variational treatment of H2+; and Rayleigh-Schrodinger perturbation theory for the anharmonic oscillator.
+- [`chemistrykit.spectro`](https://chemistrykit.readthedocs.io/en/latest/examples/spectro.html) -- spectroscopy: the Beer-Lambert absorbance law and its stray-light deviation from linearity; rigid-rotor rotational spectra with isotope shifts; harmonic vs. Morse vibrational band positions plus a Wilson GF-matrix triatomic normal-mode calculation; Franck-Condon vibronic progressions; and a first-order NMR multiplet simulator.
+- [`chemistrykit.structure`](https://chemistrykit.readthedocs.io/en/latest/examples/structure.html) -- molecular structure and bonding: a lightweight `Molecule` container; VSEPR geometry prediction with real 3D coordinate generation; point-group determination from 3D coordinates and character tables; bond order from the Pauling length correlation and Huckel-theory MO coefficients; and formal-charge/oxidation-state assignment from a Lewis structure.
+- [`chemistrykit.electrochem`](https://chemistrykit.readthedocs.io/en/latest/examples/electrochem.html) -- electrochemistry: the Nernst equation for standard and concentration cells with Debye-Huckel activity corrections; a curated standard-reduction-potential table with redox-couple balancing; Butler-Volmer electrode kinetics and Tafel-plot linearization; galvanic vs. electrolytic cells and Faraday's laws of electrolysis; and a simplified constant-current battery discharge model with Peukert's-law rate dependence.
+- [`chemistrykit.photochem`](https://chemistrykit.readthedocs.io/en/latest/examples/photochem.html) -- photochemistry: Jablonski-diagram excited-state kinetics built on `chemistrykit.kinetics`'s reaction-network engine; fluorescence/phosphorescence quantum yields and the photochemical quantum yield via Beer-Lambert; Stern-Volmer quenching with a static-vs-dynamic diagnostic; and photostationary-state kinetics for a two-state photoswitch.
+- [`chemistrykit.surface`](https://chemistrykit.readthedocs.io/en/latest/examples/surface.html) -- surface chemistry and catalysis: Langmuir, Freundlich, and BET adsorption isotherms with their standard linearizations for fitting parameters from data; Langmuir-Hinshelwood single- and dual-site surface-reaction kinetics; and a turnover-frequency/rate-enhancement catalysis model built on `chemistrykit.kinetics`'s Arrhenius equation.
+- [`chemistrykit.polymer`](https://chemistrykit.readthedocs.io/en/latest/examples/polymer.html) -- polymer chemistry: ideal random-walk chain statistics and the Flory exponent for real chains under theta/good/poor solvent conditions; molecular-weight-distribution statistics and the closed-form Flory-Schulz distribution; step-growth kinetics via the Carothers equation; and chain-growth/free-radical polymerization kinetics built on `chemistrykit.kinetics`'s reaction-network engine.
+- [`chemistrykit.crystal`](https://chemistrykit.readthedocs.io/en/latest/examples/crystal.html) -- crystallography and solid-state chemistry: the 7 crystal systems and general unit-cell volume; hard-sphere packing (packing fraction, coordination number) for SC/BCC/FCC/HCP lattices; ionic-crystal lattice energy via the Born-Lande and Kapustinskii equations, backed by a genuinely converging (Evjen-method) numerical Madelung constant; Bragg's law and powder-XRD peak positions with structure factors and systematic absences; and Schottky/Frenkel point-defect equilibrium.
+- [`chemistrykit.analytical`](https://chemistrykit.readthedocs.io/en/latest/examples/analytical.html) -- analytical chemistry: redox and complexometric (EDTA) titration-curve simulation with equivalence-point detection, alongside `chemistrykit.solutions`'s acid-base titrations; chromatographic plate theory and the van Deemter equation (resolution, selectivity); linear-regression calibration curves with IUPAC-convention limits of detection/quantitation; and propagation-of-uncertainty formulas plus Dixon's Q-test for outlier rejection.
+
+Shared infrastructure, used across the subpackages above rather than
+standalone toolkits:
+
+- `chemistrykit.constants` -- chemical constants (R, NA, k_B, Faraday's
+  constant, ...) from `scipy.constants`, plus a small built-in
+  periodic-table data table and a few well-defined unit conversions.
+- `chemistrykit.integrators` -- shared numerical ODE integrators (RK4,
+  leapfrog, Yoshida4, adaptive Dormand-Prince) used across the other
+  subpackages.
+
+## Test
+
+Tests live alongside each subpackage, at `chemistrykit/<name>/tests/`.
+
+```bash
+pytest                                              # everything
+pytest chemistrykit/kinetics/tests                  # a single subpackage
+
+# docstring examples, across every subpackage:
+MPLBACKEND=Agg pytest --doctest-modules chemistrykit \
+    --ignore-glob="*/tests/*"
+```
+
+Both commands, plus `ruff check`/`ruff format --check`, run in CI on
+every PR (`.github/workflows/ci.yml`) across Python 3.9-3.12 on Linux and
+macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+### Coverage
+
+```bash
+MPLBACKEND=Agg pytest -q --cov=chemistrykit --cov-report=term
+```
+
+774 tests, 96% line coverage overall. Per-subpackage coverage:
+
+| Subpackage | Coverage | | Subpackage | Coverage |
+|:--|--:|---|:--|--:|
+| `analytical` | 99% | | `solutions` | 99% |
+| `crystal` | 99% | | `spectro` | 99% |
+| `electrochem` | 99% | | `statmech` | 99% |
+| `kinetics` | 93% | | `structure` | 98% |
+| `md` | 89% | | `surface` | 99% |
+| `photochem` | 95% | | `thermo` | 99% |
+| `polymer` | 99% | | `integrators` | 47% |
+| `quantum` | 98% | | `constants` | 84% |
+
+`visualizers/` modules are smoke-tested only (correct return type/shape,
+or that `anim.save()` succeeds) rather than covered line-by-line, per the
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` sits lower
+because several of its fixed-step/adaptive methods aren't exercised
+directly by its own tests, only indirectly through the subpackages
+(`kinetics`, `md`) that call into it; `constants` includes a few
+rarely-used unit-conversion helpers not hit by any test.
+
+## Docs
+
+Built docs are hosted at <https://cpoli.github.io/chemistrykit/>, served
+from the `gh-pages` branch. To build
+locally:
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+## Citation
+
+If you use chemistrykit in your research, please cite it — see
+[CITATION.cff](CITATION.cff).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note that this project
+follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

chemistrykit-0.1.0/README.md

@@ -0,0 +1,150 @@
+# chemistrykit
+
+| | |
+|:--|:-:|
+| Package | [![PyPI version](https://img.shields.io/pypi/v/chemistrykit)](https://pypi.org/project/chemistrykit/) [![Python versions](https://img.shields.io/pypi/pyversions/chemistrykit)](https://pypi.org/project/chemistrykit/) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/blob/main/LICENSE) [![CI](https://github.com/cpoli/chemistrykit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/chemistrykit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/cpoli/chemistrykit)](https://codecov.io/gh/cpoli/chemistrykit) [![Coverage (manual)](https://img.shields.io/badge/coverage-96%25-brightgreen)](#coverage) |
+| Documentation | [![Docs](https://img.shields.io/badge/docs-cpoli.github.io%2Fchemistrykit-blue)](https://cpoli.github.io/chemistrykit/) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Downloads | [![Downloads](https://static.pepy.tech/badge/chemistrykit)](https://pepy.tech/project/chemistrykit) [![Downloads/Month](https://static.pepy.tech/badge/chemistrykit/month)](https://pepy.tech/project/chemistrykit) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/chemistrykit?style=social)](https://github.com/cpoli/chemistrykit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/chemistrykit?style=social)](https://github.com/cpoli/chemistrykit) [![Contributors](https://img.shields.io/github/contributors/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/chemistrykit)](https://github.com/cpoli/chemistrykit/commits/main) |
+
+A unified numerical toolkit for computational chemistry, spanning the
+field end to end: Arrhenius kinetics and oscillating reaction networks,
+Huckel aromaticity and variational quantum chemistry, Nernst cells and
+Butler-Volmer electrochemistry, NMR multiplets and Franck-Condon
+spectra, crystal lattice energies and powder XRD, polymer chain
+statistics and photochemical quenching -- with each domain's docs
+tracing the field's own foundational breakthroughs in chronological,
+pedagogical order, every historical milestone linked directly to the
+runnable code that reproduces it. Pure-numerical throughout -- no
+cheminformatics dependencies (no RDKit/ASE/PySCF/OpenMM) -- sharing
+common ODE integrators, chemical constants, and a consistent NumPy-based
+API. Conventionally imported as `ck`. chemistrykit clones the
+architecture and engineering conventions of the sibling project
+[physicskit](https://github.com/physicskit/physicskit) (`pk`).
+
+All 14 domains from `chemistrykit-spec.md`'s build plan are implemented
+-- see [Subpackages](#subpackages) for the full list, or browse the docs
+at <https://chemistrykit.readthedocs.io>.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import chemistrykit as ck
+import numpy as np
+
+# Closed-form first-order decay and its half-life
+rate_law = ck.kinetics.FirstOrder(k=0.1, C0=1.0)
+print(rate_law.half_life())  # ln(2) / k
+
+# A general stoichiometric reaction network: A -> B -> C
+network = ck.kinetics.StoichiometricNetwork.consecutive(k1=1.0, k2=0.3, A0=1.0)
+result = network.integrate((0.0, 10.0), dt=1e-3, method="rk4")
+print(result.concentration("B")[-1])
+```
+
+## Subpackages
+
+Domain subpackages, each with runnable examples linked below:
+
+- [`chemistrykit.kinetics`](https://chemistrykit.readthedocs.io/en/latest/examples/kinetics.html) -- reaction kinetics: integrated rate laws and half-lives, the Arrhenius equation and activation-energy fitting, Michaelis-Menten enzyme kinetics with Lineweaver-Burk linearization and inhibition, a general stoichiometry-matrix reaction-network engine (parallel/consecutive/reversible/steady-state-approximation chains), and the Brusselator oscillating reaction network.
+- [`chemistrykit.thermo`](https://chemistrykit.readthedocs.io/en/latest/examples/thermo.html) -- chemical thermodynamics: equations of state (ideal gas, van der Waals, Redlich-Kwong), Clausius-Clapeyron phase boundaries, reaction equilibrium (Kp/Kc, van't Hoff, and a Gibbs-energy-minimization equilibrium-composition solver), and Raoult's/Henry's law mixtures with colligative properties.
+- [`chemistrykit.solutions`](https://chemistrykit.readthedocs.io/en/latest/examples/solutions.html) -- solution chemistry: pH/pOH and weak acid/base equilibria with Henderson-Hasselbalch buffers, acid-base titration curves, Ksp solubility equilibria and the common-ion effect, and Debye-Huckel activity coefficients.
+- [`chemistrykit.md`](https://chemistrykit.readthedocs.io/en/latest/examples/md.html) -- molecular dynamics and force fields: the Lennard-Jones fluid in reduced units (periodic boundary conditions, a Verlet neighbor list, pressure, g(r)), Morse/Buckingham/harmonic bonded potentials, and velocity-rescaling/Nose-Hoover thermostats.
+- [`chemistrykit.statmech`](https://chemistrykit.readthedocs.io/en/latest/examples/statmech.html) -- statistical mechanics of molecules: translational/rotational/vibrational partition functions and their thermodynamic functions, the Maxwell-Boltzmann speed distribution, and a canonical-ensemble lattice-gas adsorption model.
+- [`chemistrykit.quantum`](https://chemistrykit.readthedocs.io/en/latest/examples/quantum.html) -- quantum chemistry: particle-in-a-box models (with the free-electron model of conjugated-dye color); the quantum harmonic oscillator vs. the exact Morse potential; the rigid rotor; hydrogen-like orbitals; Huckel molecular-orbital theory and its 4n+2 aromaticity rule; a minimal variational treatment of H2+; and Rayleigh-Schrodinger perturbation theory for the anharmonic oscillator.
+- [`chemistrykit.spectro`](https://chemistrykit.readthedocs.io/en/latest/examples/spectro.html) -- spectroscopy: the Beer-Lambert absorbance law and its stray-light deviation from linearity; rigid-rotor rotational spectra with isotope shifts; harmonic vs. Morse vibrational band positions plus a Wilson GF-matrix triatomic normal-mode calculation; Franck-Condon vibronic progressions; and a first-order NMR multiplet simulator.
+- [`chemistrykit.structure`](https://chemistrykit.readthedocs.io/en/latest/examples/structure.html) -- molecular structure and bonding: a lightweight `Molecule` container; VSEPR geometry prediction with real 3D coordinate generation; point-group determination from 3D coordinates and character tables; bond order from the Pauling length correlation and Huckel-theory MO coefficients; and formal-charge/oxidation-state assignment from a Lewis structure.
+- [`chemistrykit.electrochem`](https://chemistrykit.readthedocs.io/en/latest/examples/electrochem.html) -- electrochemistry: the Nernst equation for standard and concentration cells with Debye-Huckel activity corrections; a curated standard-reduction-potential table with redox-couple balancing; Butler-Volmer electrode kinetics and Tafel-plot linearization; galvanic vs. electrolytic cells and Faraday's laws of electrolysis; and a simplified constant-current battery discharge model with Peukert's-law rate dependence.
+- [`chemistrykit.photochem`](https://chemistrykit.readthedocs.io/en/latest/examples/photochem.html) -- photochemistry: Jablonski-diagram excited-state kinetics built on `chemistrykit.kinetics`'s reaction-network engine; fluorescence/phosphorescence quantum yields and the photochemical quantum yield via Beer-Lambert; Stern-Volmer quenching with a static-vs-dynamic diagnostic; and photostationary-state kinetics for a two-state photoswitch.
+- [`chemistrykit.surface`](https://chemistrykit.readthedocs.io/en/latest/examples/surface.html) -- surface chemistry and catalysis: Langmuir, Freundlich, and BET adsorption isotherms with their standard linearizations for fitting parameters from data; Langmuir-Hinshelwood single- and dual-site surface-reaction kinetics; and a turnover-frequency/rate-enhancement catalysis model built on `chemistrykit.kinetics`'s Arrhenius equation.
+- [`chemistrykit.polymer`](https://chemistrykit.readthedocs.io/en/latest/examples/polymer.html) -- polymer chemistry: ideal random-walk chain statistics and the Flory exponent for real chains under theta/good/poor solvent conditions; molecular-weight-distribution statistics and the closed-form Flory-Schulz distribution; step-growth kinetics via the Carothers equation; and chain-growth/free-radical polymerization kinetics built on `chemistrykit.kinetics`'s reaction-network engine.
+- [`chemistrykit.crystal`](https://chemistrykit.readthedocs.io/en/latest/examples/crystal.html) -- crystallography and solid-state chemistry: the 7 crystal systems and general unit-cell volume; hard-sphere packing (packing fraction, coordination number) for SC/BCC/FCC/HCP lattices; ionic-crystal lattice energy via the Born-Lande and Kapustinskii equations, backed by a genuinely converging (Evjen-method) numerical Madelung constant; Bragg's law and powder-XRD peak positions with structure factors and systematic absences; and Schottky/Frenkel point-defect equilibrium.
+- [`chemistrykit.analytical`](https://chemistrykit.readthedocs.io/en/latest/examples/analytical.html) -- analytical chemistry: redox and complexometric (EDTA) titration-curve simulation with equivalence-point detection, alongside `chemistrykit.solutions`'s acid-base titrations; chromatographic plate theory and the van Deemter equation (resolution, selectivity); linear-regression calibration curves with IUPAC-convention limits of detection/quantitation; and propagation-of-uncertainty formulas plus Dixon's Q-test for outlier rejection.
+
+Shared infrastructure, used across the subpackages above rather than
+standalone toolkits:
+
+- `chemistrykit.constants` -- chemical constants (R, NA, k_B, Faraday's
+  constant, ...) from `scipy.constants`, plus a small built-in
+  periodic-table data table and a few well-defined unit conversions.
+- `chemistrykit.integrators` -- shared numerical ODE integrators (RK4,
+  leapfrog, Yoshida4, adaptive Dormand-Prince) used across the other
+  subpackages.
+
+## Test
+
+Tests live alongside each subpackage, at `chemistrykit/<name>/tests/`.
+
+```bash
+pytest                                              # everything
+pytest chemistrykit/kinetics/tests                  # a single subpackage
+
+# docstring examples, across every subpackage:
+MPLBACKEND=Agg pytest --doctest-modules chemistrykit \
+    --ignore-glob="*/tests/*"
+```
+
+Both commands, plus `ruff check`/`ruff format --check`, run in CI on
+every PR (`.github/workflows/ci.yml`) across Python 3.9-3.12 on Linux and
+macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+### Coverage
+
+```bash
+MPLBACKEND=Agg pytest -q --cov=chemistrykit --cov-report=term
+```
+
+774 tests, 96% line coverage overall. Per-subpackage coverage:
+
+| Subpackage | Coverage | | Subpackage | Coverage |
+|:--|--:|---|:--|--:|
+| `analytical` | 99% | | `solutions` | 99% |
+| `crystal` | 99% | | `spectro` | 99% |
+| `electrochem` | 99% | | `statmech` | 99% |
+| `kinetics` | 93% | | `structure` | 98% |
+| `md` | 89% | | `surface` | 99% |
+| `photochem` | 95% | | `thermo` | 99% |
+| `polymer` | 99% | | `integrators` | 47% |
+| `quantum` | 98% | | `constants` | 84% |
+
+`visualizers/` modules are smoke-tested only (correct return type/shape,
+or that `anim.save()` succeeds) rather than covered line-by-line, per the
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` sits lower
+because several of its fixed-step/adaptive methods aren't exercised
+directly by its own tests, only indirectly through the subpackages
+(`kinetics`, `md`) that call into it; `constants` includes a few
+rarely-used unit-conversion helpers not hit by any test.
+
+## Docs
+
+Built docs are hosted at <https://cpoli.github.io/chemistrykit/>, served
+from the `gh-pages` branch. To build
+locally:
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+## Citation
+
+If you use chemistrykit in your research, please cite it — see
+[CITATION.cff](CITATION.cff).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note that this project
+follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

chemistrykit-0.1.0/chemistrykit/__init__.py

@@ -0,0 +1,69 @@
+"""chemistrykit: unified numerical toolkit for computational chemistry.
+
+Import as ``ck`` by convention::
+
+    import chemistrykit as ck
+    ck.kinetics.FirstOrder(k=0.1, C0=1.0)
+    ck.kinetics.StoichiometricNetwork.consecutive(k1=1.0, k2=0.3)
+    ck.thermo.VanDerWaals(a=0.1448, b=3.913e-5)
+    ck.solutions.WeakAcid(Ca=0.1, Ka=1.8e-5).pH()
+    ck.md.LJFluid.from_lattice(n_per_side=4, density=0.6, temperature=1.0)
+    ck.statmech.MaxwellBoltzmannSpeedDistribution(mass=6.63e-26, temperature=298.15)
+    ck.structure.determine_point_group(water_molecule)
+    ck.spectro.rotational_spectrum(rotor, J_max=10, temperature=300.0)
+    ck.electrochem.nernst_potential(E_standard=0.34, n=2, Q=0.01)
+    ck.photochem.jablonski_network(kf=2.0, kic=1.0, kisc=0.5, kp=0.3, kic_T=0.2)
+    ck.surface.LangmuirIsotherm(K=2.0, qmax=5.0).loading(P=1.0)
+    ck.polymer.IdealChain().end_to_end_distance(n=1000, b=0.5)
+    ck.crystal.FaceCenteredCubicPacking().packing_fraction()
+    ck.analytical.fit_calibration([0, 1, 2, 3], [0.1, 1.0, 2.1, 2.9]).lod()
+    ck.constants.R
+    ck.integrators.rk4_integrate(...)
+
+chemistrykit mirrors the architecture of the sibling project physicskit
+(pk): one subpackage per chemistry domain, sharing common ODE integrators
+(:mod:`chemistrykit.integrators`) and physical/chemical constants
+(:mod:`chemistrykit.constants`). All 14 domains from
+``chemistrykit-spec.md``'s build plan are implemented; see ``__all__``
+below for the full list.
+"""
+
+from chemistrykit import (
+    analytical,
+    constants,
+    crystal,
+    electrochem,
+    integrators,
+    kinetics,
+    md,
+    photochem,
+    polymer,
+    quantum,
+    solutions,
+    spectro,
+    statmech,
+    structure,
+    surface,
+    thermo,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "constants",
+    "integrators",
+    "kinetics",
+    "thermo",
+    "solutions",
+    "md",
+    "statmech",
+    "quantum",
+    "spectro",
+    "structure",
+    "electrochem",
+    "photochem",
+    "surface",
+    "polymer",
+    "crystal",
+    "analytical",
+]

chemistrykit-0.1.0/chemistrykit/analytical/__init__.py

@@ -0,0 +1,61 @@
+"""chemistrykit.analytical: analytical chemistry.
+
+Acid-base titration curves are provided by
+:mod:`chemistrykit.solutions.systems.titration`; this subpackage adds
+redox and complexometric (EDTA) titration-curve simulation with
+equivalence-point detection; chromatographic plate theory and the van
+Deemter equation (resolution, selectivity); linear-regression calibration
+curves with IUPAC-convention limits of detection/quantitation; and
+propagation-of-uncertainty formulas plus Dixon's Q-test for outlier
+rejection.
+"""
+
+__version__ = "0.1.0"
+
+from chemistrykit.analytical.core.base_system import TitrationCurve, TitrationCurveResult
+from chemistrykit.analytical.systems.calibration import LinearCalibration, fit_calibration
+from chemistrykit.analytical.systems.chromatography import (
+    minimum_plate_height,
+    optimum_flow_velocity,
+    plate_height,
+    resolution,
+    retention_factor,
+    selectivity_factor,
+    simulate_chromatogram,
+    theoretical_plates,
+    van_deemter_H,
+)
+from chemistrykit.analytical.systems.qtest import Q_CRITICAL_TABLE, QTestResult, dixon_q_test
+from chemistrykit.analytical.systems.titration import EDTATitration, RedoxTitration
+from chemistrykit.analytical.systems.uncertainty import (
+    propagate_power,
+    propagate_product,
+    propagate_sum,
+    propagate_uncertainty,
+)
+
+__all__ = [
+    "__version__",
+    "TitrationCurve",
+    "TitrationCurveResult",
+    "RedoxTitration",
+    "EDTATitration",
+    "theoretical_plates",
+    "plate_height",
+    "van_deemter_H",
+    "optimum_flow_velocity",
+    "minimum_plate_height",
+    "retention_factor",
+    "selectivity_factor",
+    "resolution",
+    "simulate_chromatogram",
+    "LinearCalibration",
+    "fit_calibration",
+    "propagate_sum",
+    "propagate_product",
+    "propagate_power",
+    "propagate_uncertainty",
+    "Q_CRITICAL_TABLE",
+    "QTestResult",
+    "dixon_q_test",
+]

chemistrykit-0.1.0/chemistrykit/analytical/core/base_system.py

@@ -0,0 +1,118 @@
+r"""Abstract base class for potentiometric-style titration-curve models, and a note on scope.
+
+:class:`TitrationCurve` captures the one genuinely polymorphic shape in
+this domain: several titration *types* (redox, complexometric --
+:mod:`chemistrykit.analytical.systems.titration`) that all reduce to
+"compute some scalar response as a function of titrant volume, then find
+the equivalence point as the point of steepest response change" -- the
+same shape that :class:`chemistrykit.solutions.core.base_system.Titration`
+already captures for acid-base titrations (pH vs. volume).
+
+**Why a new ABC here, rather than reusing** :class:`chemistrykit.solutions.core.base_system.Titration`:
+that class's abstract method is named and documented specifically as
+``pH_at`` (a *hydrogen-ion* activity readout), which is the wrong
+abstraction for a redox titration's electrode potential `E` or a
+complexometric titration's `pM`. Rather than force those into a
+pH-flavored interface (or reach across a domain boundary the way
+``chemistrykit.photochem`` reaches into ``chemistrykit.kinetics`` for
+substantial shared machinery -- not warranted here, since the shared
+logic is a handful of lines), :class:`TitrationCurve` reimplements the
+same small pattern (curve, steepest-ascent-or-descent equivalence-point
+detection) with a response-type-neutral abstract method name, exactly
+the way :mod:`chemistrykit.surface.utils.regression`,
+:mod:`chemistrykit.electrochem.utils.regression`, and
+:mod:`chemistrykit.photochem.utils.regression` each keep their own small
+``linear_fit`` rather than importing one another's. Acid-base titration
+curves are *not* reimplemented here at all -- :mod:`chemistrykit.analytical`'s
+examples and tests use
+:mod:`chemistrykit.solutions.systems.titration`'s classes directly for
+that case, side by side with the new redox/complexometric models below.
+
+Chromatography (:mod:`chemistrykit.analytical.systems.chromatography`),
+calibration curves (:mod:`chemistrykit.analytical.systems.calibration`),
+uncertainty propagation (:mod:`chemistrykit.analytical.systems.uncertainty`),
+and the Q-test (:mod:`chemistrykit.analytical.systems.qtest`) are each a
+self-contained set of formulas with no swappable sibling, so -- following
+``chemistrykit.electrochem``/``chemistrykit.photochem``/``chemistrykit.surface``'s
+precedent -- they stay as plain functions (plus small result dataclasses)
+in their own ``systems/`` modules.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = ["TitrationCurveResult", "TitrationCurve"]
+
+
+@dataclass
+class TitrationCurveResult:
+    """Container for the output of a :meth:`TitrationCurve.curve` call."""
+
+    V: np.ndarray
+    """ndarray: Volume(s) of titrant added, in L (or any consistent volume unit)."""
+
+    response: np.ndarray
+    """ndarray: The titration's response variable at each volume in `V`
+    (e.g. electrode potential `E` in volts, or `pM`)."""
+
+
+class TitrationCurve(ABC):
+    """Common base for a potentiometric titration-curve model whose response is not pH.
+
+    Concrete subclasses implement :meth:`response_at`; :meth:`curve` and
+    :meth:`find_equivalence_point` are then available for free, mirroring
+    :meth:`chemistrykit.solutions.core.base_system.Titration.curve`/
+    :meth:`~chemistrykit.solutions.core.base_system.Titration.find_equivalence_point`.
+    """
+
+    @abstractmethod
+    def response_at(self, V: np.ndarray) -> np.ndarray:
+        """Return the titration's response variable at each titrant volume in `V`.
+
+        Parameters
+        ----------
+        V : ndarray
+            Volume(s) of titrant added, in L.
+
+        Returns
+        -------
+        ndarray
+        """
+
+    def curve(self, V) -> TitrationCurveResult:
+        """Compute the full titration curve over a range of titrant volumes.
+
+        Parameters
+        ----------
+        V : array-like of float
+            Volumes of titrant added, in L.
+
+        Returns
+        -------
+        TitrationCurveResult
+        """
+        V = np.atleast_1d(np.asarray(V, dtype=np.float64))
+        response = np.asarray(self.response_at(V), dtype=np.float64)
+        return TitrationCurveResult(V=V, response=response)
+
+    def find_equivalence_point(self, V) -> float:
+        r"""Numerically locate the equivalence point as the point of steepest response change.
+
+        Parameters
+        ----------
+        V : array-like of float
+            A sufficiently fine grid of titrant volumes spanning the
+            equivalence point, in L.
+
+        Returns
+        -------
+        float
+        """
+        result = self.curve(V)
+        d_response_dV = np.gradient(result.response, result.V)
+        idx = int(np.argmax(np.abs(d_response_dV)))
+        return float(result.V[idx])