bindtools 0.1.0__tar.gz → 0.1.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bindtools-0.1.2/PKG-INFO +127 -0
- bindtools-0.1.2/README.md +94 -0
- bindtools-0.1.2/pyproject.toml +137 -0
- {bindtools-0.1.0 → bindtools-0.1.2}/src/bindtools/binding.py +497 -468
- bindtools-0.1.0/PKG-INFO +0 -17
- bindtools-0.1.0/pyproject.toml +0 -28
- {bindtools-0.1.0 → bindtools-0.1.2}/src/bindtools/__init__.py +0 -0
bindtools-0.1.2/PKG-INFO
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: bindtools
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Keywords: chemistry,analytical chemistry,binding constants,supramolecular
|
|
5
|
+
Author: Martin Peeks
|
|
6
|
+
Author-email: Martin Peeks <martinp23@googlemail.com>, m.peeks@unsw.edu.au
|
|
7
|
+
Classifier: Development Status :: 3 - Alpha
|
|
8
|
+
Classifier: Intended Audience :: Science/Research
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
14
|
+
Requires-Dist: arviz==0.21.0
|
|
15
|
+
Requires-Dist: corner==2.2.3
|
|
16
|
+
Requires-Dist: emcee==3.1.6
|
|
17
|
+
Requires-Dist: h5py==3.13.0
|
|
18
|
+
Requires-Dist: lmfit==1.3.3
|
|
19
|
+
Requires-Dist: matplotlib==3.10.7
|
|
20
|
+
Requires-Dist: numba>=0.65.1
|
|
21
|
+
Requires-Dist: numpy>=2.3.4
|
|
22
|
+
Requires-Dist: openpyxl==3.1.2
|
|
23
|
+
Requires-Dist: pandas>=2.3.3
|
|
24
|
+
Requires-Dist: scipy==1.16.3
|
|
25
|
+
Requires-Dist: tqdm==4.66.3
|
|
26
|
+
Requires-Dist: uncertainties==3.2.3
|
|
27
|
+
Requires-Python: >=3.12
|
|
28
|
+
Project-URL: Homepage, https://github.com/martinp23/bindtools
|
|
29
|
+
Project-URL: Documentation, https://readthedocs.org
|
|
30
|
+
Project-URL: Repository, https://github.com/martinp23/bindtools.git
|
|
31
|
+
Project-URL: Issues, https://github.com/martinp23/bindtools/issues
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# bindtools
|
|
35
|
+
|
|
36
|
+
[](https://badge.fury.io/py/bindtools)
|
|
37
|
+
[](https://pypi.org/project/bindtools/)
|
|
38
|
+
[](https://opensource.org/licenses/MIT)
|
|
39
|
+
|
|
40
|
+
`bindtools` is a Python library for supramolecular chemistry designed for modeling, fitting, and analyzing binding equilibria. It provides numerical and analytical solvers for complex chemical systems, robust parameter optimization, and Bayesian parameter estimation.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Features
|
|
45
|
+
|
|
46
|
+
- **Speciation Solvers**:
|
|
47
|
+
- **Numerical**: A Newton-Raphson solver (`DoNR` and `getConcs`) JIT-compiled with `numba` for fast operation.
|
|
48
|
+
- **Analytical**: High-speed analytical solvers for common topologies (e.g., `1:1`, `1:2`, `2:1` fast exchange).
|
|
49
|
+
- **Flexible Optimization**:
|
|
50
|
+
- Uses `lmfit` to manage model parameters (binding constants, physical observables).
|
|
51
|
+
- Handles various experimental data including NMR integrations, chemical shifts (NMR `deltaH`/`deltaF`), and linear concentration-weighted observables (UV-vis / fluorescence).
|
|
52
|
+
- **Bayesian Inference & Uncertainty Quantification**:
|
|
53
|
+
- Uses `emcee` for Markov Chain Monte Carlo (MCMC) sampling.
|
|
54
|
+
- Generates trace/chain convergence plots and corner plots using `corner` and `arviz`.
|
|
55
|
+
- MCMC runs can be serialized and stored as HDF5 files for future analysis.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Installation
|
|
60
|
+
|
|
61
|
+
`bindtools` is available on PyPI. You can install it directly using `pip`:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install bindtools
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Using Conda / Mamba (Recommended for Virtual Environments)
|
|
68
|
+
|
|
69
|
+
To avoid dependency conflicts, you can set up a dedicated environment with Conda/Mamba and install `bindtools` inside it:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# 1. Create and configure environment with base scientific dependencies
|
|
73
|
+
mamba create -n binding -c conda-forge \
|
|
74
|
+
python jupyter tqdm ipython uncertainties lmfit scipy numpy emcee tqdm numba corner matplotlib numdifftools
|
|
75
|
+
|
|
76
|
+
# 2. Activate the environment
|
|
77
|
+
conda activate binding
|
|
78
|
+
|
|
79
|
+
# 3. Install bindtools via pip
|
|
80
|
+
pip install bindtools
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Quick Start
|
|
86
|
+
|
|
87
|
+
### 1. Speciation (Solving Concentration Problems)
|
|
88
|
+
|
|
89
|
+
You can compute the equilibrium concentration of free species (components and complexes) given initial total concentrations, a stoichiometry matrix, and equilibrium constants ($K$ values).
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
import numpy as np
|
|
93
|
+
from bindtools import binding as bd
|
|
94
|
+
|
|
95
|
+
# Define total concentrations: 50 data points of Host (1e-3 M) and Guest (0 to 1e-2 M)
|
|
96
|
+
component_concs = np.zeros((50, 2))
|
|
97
|
+
component_concs[:, 0] = 1e-3
|
|
98
|
+
component_concs[:, 1] = np.linspace(0, 1e-2, 50)
|
|
99
|
+
|
|
100
|
+
# Stoichiometry / Equilibrium Matrix
|
|
101
|
+
# Row 0: Host balance, Row 1: Guest balance
|
|
102
|
+
# Columns represent: [Free Host, Free Guest, Host-Guest Complex (1:1)]
|
|
103
|
+
eq_mat = np.array([
|
|
104
|
+
[1, 0, 1], # [H]_tot = [H] + [HG]
|
|
105
|
+
[0, 1, 1] # [G]_tot = [G] + [HG]
|
|
106
|
+
])
|
|
107
|
+
|
|
108
|
+
# log10(K) values for each species.
|
|
109
|
+
# Constants for free components are fixed at logK = 0.
|
|
110
|
+
# The complex (HG) has logK = 4 (K = 10,000 M^-1).
|
|
111
|
+
logK = np.array([0, 0, 4])
|
|
112
|
+
|
|
113
|
+
# Solve for concentrations at each point
|
|
114
|
+
results = []
|
|
115
|
+
for total_concs in component_concs:
|
|
116
|
+
spec_concs = bd.getConcs(eq_mat, total_concs, logK)
|
|
117
|
+
results.append(spec_concs)
|
|
118
|
+
|
|
119
|
+
results = np.array(results)
|
|
120
|
+
print("First point [H, G, HG]:", results[0])
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# bindtools
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/bindtools)
|
|
4
|
+
[](https://pypi.org/project/bindtools/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
`bindtools` is a Python library for supramolecular chemistry designed for modeling, fitting, and analyzing binding equilibria. It provides numerical and analytical solvers for complex chemical systems, robust parameter optimization, and Bayesian parameter estimation.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Speciation Solvers**:
|
|
14
|
+
- **Numerical**: A Newton-Raphson solver (`DoNR` and `getConcs`) JIT-compiled with `numba` for fast operation.
|
|
15
|
+
- **Analytical**: High-speed analytical solvers for common topologies (e.g., `1:1`, `1:2`, `2:1` fast exchange).
|
|
16
|
+
- **Flexible Optimization**:
|
|
17
|
+
- Uses `lmfit` to manage model parameters (binding constants, physical observables).
|
|
18
|
+
- Handles various experimental data including NMR integrations, chemical shifts (NMR `deltaH`/`deltaF`), and linear concentration-weighted observables (UV-vis / fluorescence).
|
|
19
|
+
- **Bayesian Inference & Uncertainty Quantification**:
|
|
20
|
+
- Uses `emcee` for Markov Chain Monte Carlo (MCMC) sampling.
|
|
21
|
+
- Generates trace/chain convergence plots and corner plots using `corner` and `arviz`.
|
|
22
|
+
- MCMC runs can be serialized and stored as HDF5 files for future analysis.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
`bindtools` is available on PyPI. You can install it directly using `pip`:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install bindtools
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Using Conda / Mamba (Recommended for Virtual Environments)
|
|
35
|
+
|
|
36
|
+
To avoid dependency conflicts, you can set up a dedicated environment with Conda/Mamba and install `bindtools` inside it:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# 1. Create and configure environment with base scientific dependencies
|
|
40
|
+
mamba create -n binding -c conda-forge \
|
|
41
|
+
python jupyter tqdm ipython uncertainties lmfit scipy numpy emcee tqdm numba corner matplotlib numdifftools
|
|
42
|
+
|
|
43
|
+
# 2. Activate the environment
|
|
44
|
+
conda activate binding
|
|
45
|
+
|
|
46
|
+
# 3. Install bindtools via pip
|
|
47
|
+
pip install bindtools
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
### 1. Speciation (Solving Concentration Problems)
|
|
55
|
+
|
|
56
|
+
You can compute the equilibrium concentration of free species (components and complexes) given initial total concentrations, a stoichiometry matrix, and equilibrium constants ($K$ values).
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
import numpy as np
|
|
60
|
+
from bindtools import binding as bd
|
|
61
|
+
|
|
62
|
+
# Define total concentrations: 50 data points of Host (1e-3 M) and Guest (0 to 1e-2 M)
|
|
63
|
+
component_concs = np.zeros((50, 2))
|
|
64
|
+
component_concs[:, 0] = 1e-3
|
|
65
|
+
component_concs[:, 1] = np.linspace(0, 1e-2, 50)
|
|
66
|
+
|
|
67
|
+
# Stoichiometry / Equilibrium Matrix
|
|
68
|
+
# Row 0: Host balance, Row 1: Guest balance
|
|
69
|
+
# Columns represent: [Free Host, Free Guest, Host-Guest Complex (1:1)]
|
|
70
|
+
eq_mat = np.array([
|
|
71
|
+
[1, 0, 1], # [H]_tot = [H] + [HG]
|
|
72
|
+
[0, 1, 1] # [G]_tot = [G] + [HG]
|
|
73
|
+
])
|
|
74
|
+
|
|
75
|
+
# log10(K) values for each species.
|
|
76
|
+
# Constants for free components are fixed at logK = 0.
|
|
77
|
+
# The complex (HG) has logK = 4 (K = 10,000 M^-1).
|
|
78
|
+
logK = np.array([0, 0, 4])
|
|
79
|
+
|
|
80
|
+
# Solve for concentrations at each point
|
|
81
|
+
results = []
|
|
82
|
+
for total_concs in component_concs:
|
|
83
|
+
spec_concs = bd.getConcs(eq_mat, total_concs, logK)
|
|
84
|
+
results.append(spec_concs)
|
|
85
|
+
|
|
86
|
+
results = np.array(results)
|
|
87
|
+
print("First point [H, G, HG]:", results[0])
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "bindtools"
|
|
7
|
+
version = "0.1.2"
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
classifiers = [
|
|
10
|
+
# How mature is this project? Common values are
|
|
11
|
+
# 3 - Alpha
|
|
12
|
+
# 4 - Beta
|
|
13
|
+
# 5 - Production/Stable
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
|
|
16
|
+
# Indicate who your project is intended for
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
|
|
19
|
+
# Specify the Python versions you support here.
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Programming Language :: Python :: 3.14",
|
|
23
|
+
|
|
24
|
+
"Topic :: Scientific/Engineering :: Chemistry",
|
|
25
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
26
|
+
]
|
|
27
|
+
requires-python = ">=3.12"
|
|
28
|
+
keywords = ["chemistry", "analytical chemistry", "binding constants", "supramolecular"]
|
|
29
|
+
dependencies = [
|
|
30
|
+
"arviz==0.21.0",
|
|
31
|
+
"corner==2.2.3",
|
|
32
|
+
"emcee==3.1.6",
|
|
33
|
+
"h5py==3.13.0",
|
|
34
|
+
"lmfit==1.3.3",
|
|
35
|
+
"matplotlib==3.10.7",
|
|
36
|
+
"numba>=0.65.1",
|
|
37
|
+
"numpy>=2.3.4",
|
|
38
|
+
"openpyxl==3.1.2",
|
|
39
|
+
"pandas>=2.3.3",
|
|
40
|
+
"scipy==1.16.3",
|
|
41
|
+
"tqdm==4.66.3",
|
|
42
|
+
"uncertainties==3.2.3",
|
|
43
|
+
]
|
|
44
|
+
authors = [
|
|
45
|
+
{name = "Martin Peeks", email = "martinp23@googlemail.com"},
|
|
46
|
+
{email = "m.peeks@unsw.edu.au"},
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
[project.urls]
|
|
50
|
+
Homepage = "https://github.com/martinp23/bindtools"
|
|
51
|
+
Documentation = "https://readthedocs.org"
|
|
52
|
+
Repository = "https://github.com/martinp23/bindtools.git"
|
|
53
|
+
Issues = "https://github.com/martinp23/bindtools/issues"
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
# Exclude a variety of commonly ignored directories.
|
|
58
|
+
exclude = [
|
|
59
|
+
".bzr",
|
|
60
|
+
".direnv",
|
|
61
|
+
".eggs",
|
|
62
|
+
".git",
|
|
63
|
+
".git-rewrite",
|
|
64
|
+
".hg",
|
|
65
|
+
".ipynb_checkpoints",
|
|
66
|
+
".mypy_cache",
|
|
67
|
+
".nox",
|
|
68
|
+
".pants.d",
|
|
69
|
+
".pyenv",
|
|
70
|
+
".pytest_cache",
|
|
71
|
+
".pytype",
|
|
72
|
+
".ruff_cache",
|
|
73
|
+
".svn",
|
|
74
|
+
".tox",
|
|
75
|
+
".venv",
|
|
76
|
+
".vscode",
|
|
77
|
+
"__pypackages__",
|
|
78
|
+
"_build",
|
|
79
|
+
"buck-out",
|
|
80
|
+
"build",
|
|
81
|
+
"dist",
|
|
82
|
+
"node_modules",
|
|
83
|
+
"site-packages",
|
|
84
|
+
"venv",
|
|
85
|
+
]
|
|
86
|
+
|
|
87
|
+
# Same as Black.
|
|
88
|
+
line-length = 120
|
|
89
|
+
indent-width = 4
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
[tool.ruff.lint]
|
|
93
|
+
# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default.
|
|
94
|
+
# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
|
|
95
|
+
# McCabe complexity (`C901`) by default.
|
|
96
|
+
select = ["E4", "E7", "E9", "F"]
|
|
97
|
+
ignore = []
|
|
98
|
+
|
|
99
|
+
# Allow fix for all enabled rules (when `--fix`) is provided.
|
|
100
|
+
fixable = ["ALL"]
|
|
101
|
+
unfixable = []
|
|
102
|
+
|
|
103
|
+
# Allow unused variables when underscore-prefixed.
|
|
104
|
+
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
|
|
105
|
+
|
|
106
|
+
[tool.ruff.format]
|
|
107
|
+
# Like Black, use double quotes for strings.
|
|
108
|
+
quote-style = "double"
|
|
109
|
+
|
|
110
|
+
# Like Black, indent with spaces, rather than tabs.
|
|
111
|
+
indent-style = "space"
|
|
112
|
+
|
|
113
|
+
# Like Black, respect magic trailing commas.
|
|
114
|
+
skip-magic-trailing-comma = false
|
|
115
|
+
|
|
116
|
+
# Like Black, automatically detect the appropriate line ending.
|
|
117
|
+
line-ending = "auto"
|
|
118
|
+
|
|
119
|
+
# Enable auto-formatting of code examples in docstrings. Markdown,
|
|
120
|
+
# reStructuredText code/literal blocks and doctests are all supported.
|
|
121
|
+
#
|
|
122
|
+
# This is currently disabled by default, but it is planned for this
|
|
123
|
+
# to be opt-out in the future.
|
|
124
|
+
docstring-code-format = false
|
|
125
|
+
|
|
126
|
+
# Set the line length limit used when formatting code snippets in
|
|
127
|
+
# docstrings.
|
|
128
|
+
#
|
|
129
|
+
# This only has an effect when the `docstring-code-format` setting is
|
|
130
|
+
# enabled.
|
|
131
|
+
docstring-code-line-length = "dynamic"
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
[dependency-groups]
|
|
135
|
+
dev = [
|
|
136
|
+
"pytest>=9.1.0",
|
|
137
|
+
]
|