| Name | chromasurr JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Surrogate modeling and Bayesian calibration of chromatographic processes using CADET and Gaussian Processes. |
| upload_time | 2025-08-17 13:50:41 |
| maintainer | None |
| docs_url | None |
| author | Tala Al-Sunna |
| requires_python | <4,>=3.12 |
| license | MIT |
| keywords |
chromatography
cadet
surrogate
bayesian
mcmc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
chromasurr – Uncertainty-Quantification Toolkit for Chromatography
===================================================================
*A lightweight Python library that couples the CADET process simulator with modern sensitivity analysis, Gaussian-process surrogates, and diagnostic tools.*
✨ Highlights
-------------
- **Vectorized KPI extractor** – Compute retention time, peak width, and number of plates from any simulation in one call (``chromasurr.metrics.extract``)
- **Global Sobol sensitivity** – One-liner ``run_sensitivity_analysis()`` to rank parameters with Saltelli sampling and automatic metric extraction
- **Gaussian-process surrogate manager** – The ``Surrogate`` class trains, prunes, and re-trains emulators in log-space; includes built-in sensitivity on the GP itself
- **Reusable process builder** – The ``BatchElution`` class provides a ready-to-use CADET process object with configurable parameters like cycle time and feed duration
- **End-to-end example** – Full demo in ``examples/chromasurr_demo.py`` covering sensitivity analysis, calibration, and UQ
🚀 Quick start
--------------
Run the demo in *≈ 60 seconds*:
.. code-block:: bash
# 1. Clone the repository
git clone https://github.com/talasunna/chromasurr.git && cd chromasurr
# 2. Create environment (Python ≥ 3.10)
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 3. Launch the demo
python examples/chromasurr_demo.py
This runs a full workflow using a preconfigured ``BatchElution`` process and guides you through GP surrogate modeling, Sobol sensitivity analysis, and Bayesian calibration.
📦 Installation
---------------
.. code-block:: bash
pip install git+https://github.com/talasunna/chromasurr.git
**Note** – CADET-Core must be installed or compiled on your system. See the `CADET-Core Installation Guide <https://cadet.github.io/master/getting_started/installation_core.html>`_ for details.
CADET-Process is automatically installed via pip when installing ``chromasurr``.
🛠️ Usage at a glance
---------------------
.. code-block:: python
from chromasurr.surrogate import Surrogate
from chromasurr.uq import perform_monte_carlo_uq, latin_hypercube_sampler
from chromasurr.visualize import sobol_indices, summarize_results, uq_distribution
from chromasurr.process.batch_elution import BatchElution
# 1. Instantiate a configurable process object
proc = BatchElution(cycle_time=600.0, feed_duration=50.0)
# 2. Set up parameter configuration and choose metric
param_config = {
"ax_disp": "flow_sheet.column.axial_dispersion",
"porosity": "flow_sheet.column.total_porosity",
}
bounds = {
"ax_disp": [1e-6, 1e-2],
"porosity": [0.35, 0.95],
}
metrics = ["peak_width"]
# 3. Train surrogate
surr = Surrogate(proc, param_config, bounds, metrics, n_train=128)
surr.train()
# 4. Run sensitivity analysis
surr.analyze_sensitivity(n_samples=1024)
sobol_results = surr.sensitivity
# 5. Selection of most important parameters, either based on a threshold or the number of parameters you want, and retrain model based on selection
surr.select_important_params(threshold=0.05)
surr.retrain()
# 6. Set up latin hypercube sampler and run uncertainty quantification
lhs_sampler = latin_hypercube_sampler(list(surr.bounds.values()))
uq = perform_monte_carlo_uq(surrogate=surr, sample_input=lhs_sampler, metric=metrics[0], n_samples=1000)
# 7. Visualize your analyses: sobol indices, uq distribution, and your results
uq_distribution(uq, metric="peak_width")
sobol_indices(sobol_results, metric=metrics[0])
summarize_results(
surrogate=surr,
metric=metrics[0],
uq_result=uq,
)
Sensitivity Analysis Workflow Options
--------------------------------------
- **Option 1: Run Sensitivity Analysis First, Then Train Surrogate**
Use ``run_sensitivity_analysis`` on the CADET model to rank parameters, then train a surrogate focusing on the important ones (based on the number of parameters you'd like to retain, or on a threshold you can decide).
- **Option 2: Train Surrogate First, Then Run Sensitivity Analysis**
Fit a surrogate with ``Surrogate``, then analyze it with ``analyze_sensitivity()``.
Both paths support uncertainty quantification and parameter calibration workflows.
---
All public functions include **NumPy-style docstrings** and **Python 3.10+ type hints** for autocompletion and static analysis.
📚 Documentation
----------------
Docs are hosted on GitHub Pages: https://talasunna.github.io/chromasurr/
🖇️ Project structure
---------------------
.. code-block:: text
chromasurr/
│ __init__.py
│ metrics.py ← KPI extractor
│ sensitivity.py ← Saltelli driver + helpers
│ surrogate.py ← Surrogate manager
│ uq.py ← Uncertainty quantification tools
│ error_analysis.py ← Error diagnostics
├── process/
│ └── batch_elution.py ← Configurable CADET Process class
└── examples/
└── chromasurr_demo.py ← End-to-end demo script
docs/
tests/
📜 License
-----------
Distributed under the **MIT License** – see *LICENSE* for details.
Made with ☕ by **Tala Al-Sunna**.
Raw data
{
"_id": null,
"home_page": null,
"name": "chromasurr",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.12",
"maintainer_email": null,
"keywords": "chromatography, CADET, surrogate, Bayesian, MCMC",
"author": "Tala Al-Sunna",
"author_email": "tala.sunna@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ae/0f/fa726a4a4d33c013a8eb899714f1edb2d9057af7b5f7455b1227982ff2b2/chromasurr-0.1.1.tar.gz",
"platform": null,
"description": "chromasurr \u2013 Uncertainty-Quantification Toolkit for Chromatography\n===================================================================\n\n*A lightweight Python library that couples the CADET process simulator with modern sensitivity analysis, Gaussian-process surrogates, and diagnostic tools.*\n\n\u2728 Highlights\n-------------\n\n- **Vectorized KPI extractor** \u2013 Compute retention time, peak width, and number of plates from any simulation in one call (``chromasurr.metrics.extract``)\n- **Global Sobol sensitivity** \u2013 One-liner ``run_sensitivity_analysis()`` to rank parameters with Saltelli sampling and automatic metric extraction\n- **Gaussian-process surrogate manager** \u2013 The ``Surrogate`` class trains, prunes, and re-trains emulators in log-space; includes built-in sensitivity on the GP itself\n- **Reusable process builder** \u2013 The ``BatchElution`` class provides a ready-to-use CADET process object with configurable parameters like cycle time and feed duration\n- **End-to-end example** \u2013 Full demo in ``examples/chromasurr_demo.py`` covering sensitivity analysis, calibration, and UQ\n\n\ud83d\ude80 Quick start\n--------------\n\nRun the demo in *\u2248 60 seconds*:\n\n.. code-block:: bash\n\n # 1. Clone the repository\n git clone https://github.com/talasunna/chromasurr.git && cd chromasurr\n\n # 2. Create environment (Python \u2265 3.10)\n python3 -m venv .venv && source .venv/bin/activate\n pip install -r requirements.txt\n\n # 3. Launch the demo\n python examples/chromasurr_demo.py\n\nThis runs a full workflow using a preconfigured ``BatchElution`` process and guides you through GP surrogate modeling, Sobol sensitivity analysis, and Bayesian calibration.\n\n\ud83d\udce6 Installation\n---------------\n\n.. code-block:: bash\n\n pip install git+https://github.com/talasunna/chromasurr.git\n\n**Note** \u2013 CADET-Core must be installed or compiled on your system. See the `CADET-Core Installation Guide <https://cadet.github.io/master/getting_started/installation_core.html>`_ for details.\n\nCADET-Process is automatically installed via pip when installing ``chromasurr``.\n\n\ud83d\udee0\ufe0f Usage at a glance\n---------------------\n\n.. code-block:: python\n\n from chromasurr.surrogate import Surrogate\n from chromasurr.uq import perform_monte_carlo_uq, latin_hypercube_sampler\n from chromasurr.visualize import sobol_indices, summarize_results, uq_distribution\n from chromasurr.process.batch_elution import BatchElution\n\n # 1. Instantiate a configurable process object\n proc = BatchElution(cycle_time=600.0, feed_duration=50.0)\n\n # 2. Set up parameter configuration and choose metric\n param_config = {\n \"ax_disp\": \"flow_sheet.column.axial_dispersion\",\n \"porosity\": \"flow_sheet.column.total_porosity\",\n }\n bounds = {\n \"ax_disp\": [1e-6, 1e-2],\n \"porosity\": [0.35, 0.95],\n }\n metrics = [\"peak_width\"]\n\n # 3. Train surrogate\n surr = Surrogate(proc, param_config, bounds, metrics, n_train=128)\n surr.train()\n\n # 4. Run sensitivity analysis\n surr.analyze_sensitivity(n_samples=1024)\n sobol_results = surr.sensitivity\n\n # 5. Selection of most important parameters, either based on a threshold or the number of parameters you want, and retrain model based on selection\n surr.select_important_params(threshold=0.05)\n surr.retrain()\n\n # 6. Set up latin hypercube sampler and run uncertainty quantification\n lhs_sampler = latin_hypercube_sampler(list(surr.bounds.values()))\n uq = perform_monte_carlo_uq(surrogate=surr, sample_input=lhs_sampler, metric=metrics[0], n_samples=1000)\n\n # 7. Visualize your analyses: sobol indices, uq distribution, and your results\n uq_distribution(uq, metric=\"peak_width\")\n\n sobol_indices(sobol_results, metric=metrics[0])\n\n summarize_results(\n surrogate=surr,\n metric=metrics[0],\n uq_result=uq,\n )\n\n\n\n\n\n\n\nSensitivity Analysis Workflow Options\n--------------------------------------\n\n- **Option 1: Run Sensitivity Analysis First, Then Train Surrogate**\n\n Use ``run_sensitivity_analysis`` on the CADET model to rank parameters, then train a surrogate focusing on the important ones (based on the number of parameters you'd like to retain, or on a threshold you can decide).\n\n- **Option 2: Train Surrogate First, Then Run Sensitivity Analysis**\n\n Fit a surrogate with ``Surrogate``, then analyze it with ``analyze_sensitivity()``.\n\nBoth paths support uncertainty quantification and parameter calibration workflows.\n\n---\n\nAll public functions include **NumPy-style docstrings** and **Python 3.10+ type hints** for autocompletion and static analysis.\n\n\ud83d\udcda Documentation\n----------------\nDocs are hosted on GitHub Pages: https://talasunna.github.io/chromasurr/\n\n\ud83d\udd87\ufe0f Project structure\n---------------------\n\n.. code-block:: text\n\n chromasurr/\n \u2502 __init__.py\n \u2502 metrics.py \u2190 KPI extractor\n \u2502 sensitivity.py \u2190 Saltelli driver + helpers\n \u2502 surrogate.py \u2190 Surrogate manager\n \u2502 uq.py \u2190 Uncertainty quantification tools\n \u2502 error_analysis.py \u2190 Error diagnostics\n \u251c\u2500\u2500 process/\n \u2502 \u2514\u2500\u2500 batch_elution.py \u2190 Configurable CADET Process class\n \u2514\u2500\u2500 examples/\n \u2514\u2500\u2500 chromasurr_demo.py \u2190 End-to-end demo script\n\n docs/\n tests/\n\n\ud83d\udcdc License\n-----------\n\nDistributed under the **MIT License** \u2013 see *LICENSE* for details.\n\nMade with \u2615 by **Tala Al-Sunna**.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Surrogate modeling and Bayesian calibration of chromatographic processes using CADET and Gaussian Processes.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://talasunna.github.io/chromasurr",
"Homepage": "https://github.com/talasunna/chromasurr",
"Repository": "https://github.com/talasunna/chromasurr"
},
"split_keywords": [
"chromatography",
" cadet",
" surrogate",
" bayesian",
" mcmc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7faf2c7f6a2984ea07ea7aee9d9653eabe75dc4802a82efd655a75f92a69a83a",
"md5": "9beeb629cc4880f3ea6aed51832531ed",
"sha256": "fb1deb9ab15bda192e1f3722f10afe1bc7f29cea6cef3ee9123a1e419c7a7641"
},
"downloads": -1,
"filename": "chromasurr-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9beeb629cc4880f3ea6aed51832531ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.12",
"size": 21126,
"upload_time": "2025-08-17T13:50:37",
"upload_time_iso_8601": "2025-08-17T13:50:37.173500Z",
"url": "https://files.pythonhosted.org/packages/7f/af/2c7f6a2984ea07ea7aee9d9653eabe75dc4802a82efd655a75f92a69a83a/chromasurr-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ae0ffa726a4a4d33c013a8eb899714f1edb2d9057af7b5f7455b1227982ff2b2",
"md5": "61b5d0654ce0afb4100588874b5dba97",
"sha256": "d013a1df53f49f6de1db29fe7aa50ef9cea564321996ba0dab313894e1fa327d"
},
"downloads": -1,
"filename": "chromasurr-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "61b5d0654ce0afb4100588874b5dba97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.12",
"size": 18773,
"upload_time": "2025-08-17T13:50:41",
"upload_time_iso_8601": "2025-08-17T13:50:41.495496Z",
"url": "https://files.pythonhosted.org/packages/ae/0f/fa726a4a4d33c013a8eb899714f1edb2d9057af7b5f7455b1227982ff2b2/chromasurr-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 13:50:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "talasunna",
"github_project": "chromasurr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chromasurr"
}
