# Lyogel Equilibria with Helmholtz Equations of State

This repository contains the code, parameter tables, experimental datasets, and generated results associated with the following studies:

1. Jaeschke, N.; Smirnova, I.; Chapman, W. G. *Lyogel Equilibria with Helmholtz Equations of State. Part I: A Robust Second-Order Framework.* **Industrial & Engineering Chemistry Research** 2026. https://doi.org/10.1021/acs.iecr.6c01490

2. Jaeschke, N.; Chapman, W. G.; Smirnova, I. *Lyogel Equilibria with Helmholtz Equations of State. Part II: Assessment of PC-SAFT Parametrizations and Network Models for pNIPAM Lyogels.* **Industrial & Engineering Chemistry Research** 2026. https://doi.org/10.1021/acs.iecr.6c01731

The reusable Python package is `equi_gel`; the numbered directories contain the
section-specific data, figures, tables, and optimization archives used by the
solvent, polymer, and gel case studies.

## Repository Layout

- [`00_Lib/`](00_Lib/README.md): installable `equi_gel` package and shared numerical utilities
- [`01_Parameters/`](01_Parameters/README.md): literature and curated/fitted PC-SAFT parameter tables
- [`02_CalculationData/`](02_CalculationData/README.md): archived calculated JSON records
- [`03_ExperimentalData/`](03_ExperimentalData/README.md): curated experimental JSON records
- [`04_Introduction/`](04_Introduction/README.md): compact methodology examples and manuscript-support figures
- [`05_SolventSystems/`](05_SolventSystems/README.md): solvent-only esterification-system calculations and parameter studies
- [`06_PolymerSystems/`](06_PolymerSystems/README.md): PNIPAAm solution calculations and optimized PNIPAAm-water variants
- [`07_GelSystems/`](07_GelSystems/README.md): PNIPAAm gel tracing, swelling fits, and network-model comparisons

Each section README documents the local scripts, outputs, and archived fit
artifacts in more detail.

## Environment

- Python `3.11` is required by [`pyproject.toml`](pyproject.toml).
- The supplied [`environment.yml`](environment.yml) creates a minimal Conda
  environment and installs this repository in editable mode with `pip -e .`.
- Runtime dependencies are pinned in `pyproject.toml`: `numpy`, `scipy`,
  `pandas`, `matplotlib`, `mpltern`, `feos`, and `si-units`.

Create the environment from the repository root:

```bash
conda env create -f environment.yml
conda activate lyogel_modeling_env
```

## Running Scripts

Run section scripts from their own directory. Many scripts read and write
relative paths such as `figures/`, `tables/`, `optimizer_histories/`, or local
parameter/result folders.

```bash
cd 04_Introduction
python alternating_tangents_example.py
python plot_network_terms.py
```

```bash
cd 05_SolventSystems
python pure_components.py
python plot_esterification_systems_from_params.py
python plot_esterification_systems_from_params_only_kij_aa.py
```

> [!NOTE]
> The following command will not run successfully with the files included in this repository:
>
> ```bash
> cd 05_SolventSystems
> python pure_components.py
> ```
>
> The required experimental vapor-pressure and liquid-density data are not open source and therefore cannot be published in this repository.
>
> To run the script, provide equivalent property data from a licensed source such as DIPPR or another suitable thermophysical-property database.

```bash
cd 06_PolymerSystems
python plot_polymer_lle.py
python plot_polymer_lle_waters.py
python plot_polymer_lle_t_scale_study.py
python tracing_example_polymer.py
```

```bash
cd 07_GelSystems
python plot_gel_lle_different_elastics.py
python plot_gel_lle_different_m.py
python plot_gel_lle_different_water_models.py
python plot_gel_lle_binaries_wa_aa.py
python plot_gel_lle_binaries_aa_ba.py
python plot_gel_lle_binaries_ba_bu.py
python example_tracing_ternary.py
python random_walk_2d.py
```

Optimization scripts live in the section directories as well. They can be slow,
may append to existing `*_de_gen.csv` histories, and may overwrite candidate
JSON/NPY outputs. Treat them as deliberate refresh workflows rather than quick
examples.

## Data And Output Conventions

- Experimental source records live in [`03_ExperimentalData/`](03_ExperimentalData/README.md) and use `EXP_*` filenames.
- Archived calculated records live in [`02_CalculationData/`](02_CalculationData/README.md) and use `CAL_*` filenames.
- Parameter tables live in [`01_Parameters/`](01_Parameters/README.md).
- Figures are typically written to local `figures/` folders.
- Tables are typically written to local `tables/` folders.
- Differential-evolution histories use `*_de_gen.csv` filenames.
- Saved parameter snapshots are stored as JSON; traced state vectors used as
  restart seeds are stored as NPY where applicable.

## Source labels and references for literature parameters

Source labels such as `grob`, `esper`, `bahrabadi`, and `arndt` are used as
lookup keys in the parameter tables and section scripts. They correspond to
the following publications:

| Source label | Usage and reference |
|---|---|
| `grob` | Experimental phase- and chemical-equilibrium data for the esterification system.<br><br>Grob, S.; Hasse, H. Thermodynamics of Phase and Chemical Equilibrium in a Strongly Nonideal Esterification System. *Journal of Chemical & Engineering Data* **2005**, *50*, 92-101. [https://doi.org/10.1021/je0498199](https://doi.org/10.1021/je0498199) |
| `esper` | Pure-component PCP-SAFT parameters are taken from Esper et al. The associated binary interaction parameters used with this parameter set are taken from Rehner et al.<br><br>Esper, T.; Bauer, G.; Rehner, P.; Gross, J. PCP-SAFT Parameters of Pure Substances Using Large Experimental Databases. *Industrial & Engineering Chemistry Research* **2023**, *62*, 15300-15310. [https://doi.org/10.1021/acs.iecr.3c02255](https://doi.org/10.1021/acs.iecr.3c02255)<br><br>Rehner, P.; Bardow, A.; Gross, J. Modeling Mixtures with PCP-SAFT: Insights from Large-Scale Parametrization and Group-Contribution Method for Binary Interaction Parameters. *International Journal of Thermophysics* **2023**, *44*, 179. [https://doi.org/10.1007/s10765-023-03290-3](https://doi.org/10.1007/s10765-023-03290-3) |
| `bahrabadi` | Compilation of esterification reactions and PC-SAFT modeling of reaction kinetics and equilibria.<br><br>Bahrabadi Jovein, I.; Baco, S.; Sadowski, G.; Doghieri, F.; Giacinti Baschetti, M.; Yu, G.; Leveneur, S.; Legros, J.; Held, C. Comprehensive Compilation on Esterification Reactions and Predicting Reaction Kinetics and Equilibrium Using PC-SAFT. *ACS Engineering Au* **2025**, *5*, 234-246. [https://doi.org/10.1021/acsengineeringau.5c00002](https://doi.org/10.1021/acsengineeringau.5c00002) |
| `arndt` | PC-SAFT model and parameters for pNIPAM hydrogels in water/alcohol mixtures.<br><br>Arndt, M. C.; Sadowski, G. Modeling Poly(N-isopropylacrylamide) Hydrogels in Water/Alcohol Mixtures with PC-SAFT. *Macromolecules* **2012**, *45*, 6686-6696. [https://doi.org/10.1021/ma300683k](https://doi.org/10.1021/ma300683k) |

## License and reuse

- Python source code, configuration files, and repository-authored
  documentation are available under the [MIT License](LICENSE).
- Repository-authored documentation is also available under
  [CC BY 4.0](LICENSES/CC-BY-4.0.txt), at the user's choice.
- Original figures, tables, calculated results, and generated non-code research
  outputs are available under CC BY 4.0 only to the extent the licensors own
  the relevant rights.
- Literature-derived experimental values and parameter values are not covered
  by a blanket repository license. Their original source terms continue to
  apply.

See the [license map](LICENSES/README.md),
[third-party notices](THIRD_PARTY_NOTICES.md), and the local notices in
`01_Parameters/`, `02_CalculationData/`, and `03_ExperimentalData/`.


## Citation

If this repository contributes to your work, cite the associated publication(s)
listed above.
