thermosac 0.1.0

High-throughput LLE prediction and screening using the COSMO-SAC model

ThermoSAC

ThermoSAC is a Python package for studying phase equilibria with the COSMO‑SAC model. The project accompanies the paper High‑Throughput Application and Evaluation of the COSMO‑SAC Model for Predictions of Liquid–Liquid Equilibria currently under review in Digital Discovery. It provides tools to analyse miscibility, solubility and phase stability of binary mixtures and reproduces the automated workflow described in the article.

Features

• COSMO-SAC activity model with optional dispersion and different combinatorial terms.
• Gibbs energy scanning to locate binodal and spinodal points.
• Liquid–liquid equilibrium tracing for miscibility curves.
• Solid–liquid equilibrium utilities for solubility predictions.
• High‑throughput modes for screening many systems in parallel.
• Extensive dataset – predicted LLE curves for 2478 binary systems with auxiliary metadata, plus the NIST/TRC reference dataset.
• Support for COSMO‑SAC‑2010 and COSMO‑SAC‑dsp, matching the variants assessed in the paper.
• Precomputed results in data/calculated including initial values and full miscibility curves.

Five example scripts (ex_01_GMixScanner.py to ex_05_EvaluateNISTBenchmark.py) demonstrating typical workflows.

Installation

1. Install the cCOSMO library from NIST (required for COSMO‑SAC calculations).
2. Install ThermoSAC via pip:

   pip install thermosac
   

   ⚠️ Note: The PyPI version includes only the core package functionality. Example data and auxiliary files (e.g., data/profiles) required for full reproducibility and examples are not included in the pip package to keep it lightweight. To access these materials, please clone the repository:

   git clone https://github.com/ivanantolo/thermosac
   cd thermosac
   pip install .
   

Python 3.12 or later is required.

Quick start

The snippet below mirrors the single-system scanning routine used for the paper's Figure 2.

import numpy as np
from thermosac import Component, Mixture, COSMOSAC
from thermosac.equilibrium.lle import GMixScanner
from thermosac.utils.spacing import spacing

# Set up a binary mixture
names = ["ETHYLENE_GLYCOL", "2,5-Dimethyltetrahydrofuran"]
mixture = Mixture(*[Component(n) for n in names])
model = COSMOSAC(mixture)
model._import_delaware(names, "./data/profiles/UD/sigma3")

# Scan Gibbs free energy of mixing
T = [200]
x = spacing(0, 1, 51, func_name="sigmoid", inflection=15)
scanner = GMixScanner(model, T, x)
initial_values, _ = scanner.find_all_binodal()
print(initial_values.head())

This snippet is adapted from the example script showing single‑system scanning (ex_01_GMixScanner.py).

Examples

Additional examples are provided in the repository:

• ex_01_GMixScanner.py – single system Gibbs-energy scan.
• ex_02_LLETracing.py – trace liquid–liquid equilibria using initial values.
• ex_03_HighThroughput-Screening.py – high-throughput binodal detection across multiple systems.
• ex_04_HighThroughput-Tracing.py – parallelized LLE tracing for a list of systems.
• ex_05_EvaluateNISTBenchmark.py – single-system benchmark evaluation using NIST/TRC data (basis of Table 5).

Each script contains plotting commands and annotations for reproducing the figures used in the accompanying paper. For instance, the single-system tracing routine loads initial values and computes miscibility curves as shown in lines 27–33 of ex_02_LLETracing.py.

Data and reproducibility

The data directory is included in the GitHub repository (but not in the PyPI package) and bundles everything needed to reproduce the analyses:

• data/calculated – initial values, critical points and the full miscibility curves generated with ThermoSAC.
• data/experimental – the lists of binary systems and substances used in the evaluation together with the curated reference set from the NIST Thermodynamics Research Center.
• data/profiles – sigma-profiles used by the COSMO-SAC model.
• data/statistics – summary tables and helper scripts for assessing model accuracy.

These files allow you to reproduce the statistical analyses and figures presented in the paper.

Citation

If you use ThermoSAC in your research, please cite the forthcoming paper once published. A CITATION.cff file will be added after publication.

Contributing

Contributions and feedback are welcome through GitHub issues and pull requests.