# README for the Research Software and Data Repository The research data management practices described in this README were developed in accordance with the *Research Data Management Plan Handbook: Guidelines for Developing a Research Data Management Plan* (Tas et al., 2026) for CRC 1615 SMART Reactors for Future Process Engineering. The handbook provides the underlying framework for documenting, organizing, preserving, and publishing research data in alignment with the FAIR principles and the research data management requirements of the German Research Foundation (DFG). > **Repository status and recommended use** > > This deposit is a **source-code and research-data repository**, not a conventional standalone tabular data set. It is best used in a **Git environment**. > The ZIP archive can still be inspected and executed, but it does not contain the `.git` history, branches, or tags. Keep the repository structure intact and run scripts from the documented section directories because the package and many scripts use relative paths. ## Project Title **Lyogel Equilibria with Helmholtz Equations of State** **CRC context:** CRC 1615 *SMART Reactors for Future Process Engineering*, with a focus on thermodynamic modeling and numerical calculation of responsive pNIPAM lyogel phase and swelling equilibria. This publication is part of the B01 subproject. ## Related Publications 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). DOI: [10.1021/acs.iecr.6c01490](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). DOI: [10.1021/acs.iecr.6c01731](https://doi.org/10.1021/acs.iecr.6c01731). ## Principal Investigators / Authors - **Nanning Jaeschke** - Corresponding author; Institute of Thermal Separation Processes, Hamburg University of Technology, 21073 Hamburg, Germany; ORCID: [0009-0000-0369-3568](https://orcid.org/0009-0000-0369-3568); Email: [nanning.jaeschke@tuhh.de](mailto:nanning.jaeschke@tuhh.de) - **Irina Smirnova** - Institute of Thermal Separation Processes, Hamburg University of Technology, 21073 Hamburg, Germany; ORCID: [0000-0003-4503-4039](https://orcid.org/0000-0003-4503-4039) - **Walter G. Chapman** - Department of Chemical and Biomolecular Engineering, Rice University, Houston, Texas 77005-1827, United States; ORCID: [0000-0002-8789-9041](https://orcid.org/0000-0002-8789-9041) ## Funding Acknowledgement This data set and research software repository were generated as part of the project funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation), SFB 1615, Project Number **503850735**. ## 1. General Information ### Data Set Title **Lyogel Equilibria with Helmholtz Equations of State: Research Software, Parameters, Experimental Records, and Calculated Results** ### Short Description This repository contains the code, parameter tables, curated literature-derived experimental records, calculated records, optimization histories, fitted parameter snapshots, continuation restart arrays, figures, and tables associated with the two publications listed above. The reusable Python package `equi_gel` implements utilities for PC-SAFT parameter handling, interfaces to the `feos` thermodynamic library, second-order phase-equilibrium calculations, binary and ternary phase-envelope tracing, gel-network elasticity contributions, fitting objectives, differential-evolution parameter optimization, JSON data exchange, and publication plotting. The repository supports calculations for solvent systems containing water, n-butanol, butyl acetate, and acetic acid; pNIPAM-water polymer solutions; and pNIPAM lyogels in pure and mixed solvents. It can be used to inspect the computational workflow, regenerate many of the archived figures and tables, rerun selected calculations, compare parameterizations and network models, and extend the research code. ### Date of Data Collection / Generation - Literature-derived experimental and parameter sources represented in the structured records span **1963-2025**. - Archived calculated records include generation timestamps from **2026-01-27** and **2026-03-29**. - The supplied repository snapshot is dated **2026-07-20**. - The associated publications were accepted in 2026. ### Geographical Coverage **Not applicable.** The repository contains computational thermodynamics software, literature-derived scientific data, and generated model results rather than geographically sampled observations. ### Keywords PC-SAFT; Helmholtz energy; phase equilibrium; lyogel; pNIPAM; PNIPAAm; polymer gel; liquid-liquid equilibrium; thermodynamic modeling; parameter optimization; responsive materials; reproducible research software ## 2. Methodological Information ### Data Collection and Processing The repository combines the following material: 1. **Literature-derived input data:** Experimental liquid-liquid equilibrium, polymer-solution, gel-swelling, polymer-density, and pure-component source records are curated as JSON files. PC-SAFT pure-component and binary interaction parameters are stored in CSV tables. Source citations are included in the relevant records and documentation. 2. **Calculated data:** Pure-component properties and phase-coexistence records are generated by the repository's thermodynamic routines and archived as `CAL_*` JSON files. 3. **Optimization and restart data:** Differential-evolution histories are stored as CSV files, fitted parameter snapshots as JSON files, and traced state vectors used as restart seeds as NPY arrays. 4. **Research outputs:** Scripts generate manuscript-support figures and tables in local `figures/` and `tables/` folders. The calculations use the Perturbed-Chain Statistical Associating Fluid Theory equation of state, PC-SAFT, through `feos`. Gel elasticity is represented explicitly as a Poynting-like correction to the phase-equilibrium condition rather than being folded into the equation of state. ### Experimental Design / Study Context No new laboratory measurements are reported as being collected through this repository. The experimental records are curated from published literature and are used for parameter fitting, validation, comparison, and plotting. The computational study follows two connected workflows: - **Part I, numerical framework:** A second-order Newton-Raphson method is combined with homotopy-based phase-envelope tracing and alternating-tangent initialization. The approach is designed for strongly asymmetric polymer-solvent systems and is demonstrated for binary and ternary pNIPAM gel systems. - **Part II, parameter and model assessment:** Literature PC-SAFT parameterizations for the butyl esterification system are evaluated and refined. A sequential fitting strategy proceeds from solvent liquid-liquid equilibria to pNIPAM-water polymer solutions, water-swollen gels, and mixed-solvent gel systems. Affine or Flory, phantom, and finite-extensibility or Miao network models are compared. Selected parameters are optimized using differential evolution. The main systems are: - water, n-butanol, butyl acetate, and acetic acid solvent mixtures; - pNIPAM-water polymer solutions at multiple polymer molar masses; - pNIPAM gels in water and water-acetic-acid mixtures; - pNIPAM lyogels in acetic-acid-butyl-acetate and butyl-acetate-butanol mixtures; - pNIPAM-water-ethanol examples for ternary tracing. ### Data Validation and Quality Assurance Validation and quality assurance include: - comparison of several literature PC-SAFT parameter sources; - comparison of calculated pure-component density and vapor-pressure behavior with reference data where licensing permits; - comparison of calculated binary and ternary phase behavior with curated liquid-liquid equilibrium records; - comparison of calculated degree of swelling with literature gel data; - geometric binodal-distance and relative degree-of-swelling objective functions; - sequential fitting that distinguishes fitted systems from out-of-fit predictions; - archived optimizer histories, fitted parameter files, calculated snapshots, tables, and figures; - explicit filenames, component labels, source citations, and structured schemas; - pinned software versions in `pyproject.toml`; - repository-specific license and third-party notices. Known limitations are documented rather than hidden. In particular, quantitative pNIPAM lower critical solution temperature behavior requires a temperature-dependent interaction parameter in the presented framework; fitted interaction parameters show limited transferability to some mixed-solvent systems; finite-extensibility effects are negligible for the investigated systems; and restricted thermophysical database values are not redistributed. ## 3. Data and File Overview ### List of Files and Structure The supplied repository contains **334 files** with a total uncompressed size of approximately **6.75 MiB**. | File / Folder | Description | Main formats | Files | Approx. size | |---|---|---|---:|---:| | Root files and `LICENCES/` | Main README, packaging and environment configuration, CI, attribution, license map, license texts, and third-party notices | MD, TOML, YML, TXT | 11 | 34 KiB | | `00_Lib/` | Installable `equi_gel` package and shared numerical, I/O, optimization, and plotting utilities | PY, MD, MPLSTYLE | 16 | 79 KiB | | `01_Parameters/` | Literature-derived and curated or fitted PC-SAFT parameter tables | CSV, MD | 5 | 9 KiB | | `02_CalculationData/` | Archived calculated pure-component and phase-coexistence records | JSON, MD | 76 | 1.83 MiB | | `03_ExperimentalData/` | Curated literature-derived experimental records and source metadata | JSON, MD | 48 | 106 KiB | | `04_Introduction/` | Numerical examples and methodology-support figures | PY, PDF, MD | 7 | 82 KiB | | `05_SolventSystems/` | Solvent-system scripts, optimizer histories, figures, and tables | PY, CSV, PDF, TEX, MD | 35 | 2.02 MiB | | `06_PolymerSystems/` | pNIPAM solution scripts, fitted models, histories, figures, and tables | PY, JSON, CSV, PDF, MD | 38 | 1.48 MiB | | `07_GelSystems/` | Gel tracing, swelling fits, network-model comparisons, optimization archives, figures, and tables | PY, JSON, CSV, NPY, PDF, PNG, MD | 98 | 1.12 MiB | Repository-wide format totals include 164 JSON files, 40 CSV files, 37 Python files, 32 PDF files, 21 Markdown files, 19 NPY arrays, 7 TeX files, and additional configuration, license, style, and image files. ### File Naming Convention - `EXP_*`: experimental or literature-derived structured records. - `CAL_*`: calculated structured records. - `EXP_PUR_*`: pure-component property source records. - `EXP_LLE_*`: liquid-liquid equilibrium tie-line records. - `EXP_SOL_*`: solvent coexistence or polymer-solution records. - `EXP_DOS_*`: degree-of-swelling records. - `EXP_POLY_DENS_*`: polymer-density records. - `CAL_PUR_*`: calculated pure-component records. - `CAL_LLE_*`: calculated phase-coexistence records. - Calculation filenames commonly encode components, temperature, parameter-source or comment labels, and a timestamp such as `2026_03_29_20_00`. - Differential-evolution histories use `*_de_gen.csv`. - Fitted or curated parameter snapshots use JSON. - Traced continuation states used as restart seeds use NPY and commonly include `last_y_lst` in the filename. - Source labels such as `grob`, `esper`, `bahrabadi`, and `arndt` must match the lookup keys in the parameter tables and scripts. - Component order inside structured records must remain consistent with the associated component-name fields. ### Number of Records / Observations - **334 files** in the supplied repository snapshot. - **120 primary JSON data records** in the dedicated data folders: - 74 calculated records in `02_CalculationData/`; - 46 experimental or literature-derived records in `03_ExperimentalData/`. - **3 main parameter tables** in `01_Parameters/`: - `LIT_PURE.csv`: 16 parameter rows; - `LIT_BINARY.csv`: 21 parameter rows; - `CAL_FULLSETS.csv`: 2 curated full parameter-set rows. - **164 JSON files** across the complete repository, including fitted parameter snapshots and workflow assets outside the dedicated data folders. The calculated-state and source-point totals are inventory measures rather than a single scientific sample size. Depending on the record type, an entry may represent a pure-component state, a point on a phase branch, a tie line, a solvent composition, a temperature, or a swelling measurement. ## 4. Access and Licensing Information ### Repository and Persistent Identifier The data and source code required to reproduce the figures in both associated publications are publicly available under the following persistent identifier: **DOI: [10.15480/882.16926](https://doi.org/10.15480/882.16926)** Repository title: **Lyogel Equilibria with Helmholtz Equations of State** ### License for Use Licensing is content-specific: - Python source code, configuration files, executable code snippets, and repository-authored documentation are licensed under the **MIT License**. - Repository-authored documentation is also offered under **Creative Commons Attribution 4.0 International, CC BY 4.0**, at the user's choice. - Original figures, plots, tables, calculated records, optimization histories, fitted-result archives, and other generated non-code outputs are available under **CC BY 4.0**, only to the extent that the licensors own the relevant rights. - Literature-derived experimental values and literature-derived parameter values are not covered by a blanket repository license. Original publication, database, institutional, and contractual terms continue to apply. - External Python dependencies are not vendored and retain their own license terms. Users must consult `LICENSE`, `LICENCES/README.md`, `LICENCES/CC-BY-4.0.txt`, `THIRD_PARTY_NOTICES.md`, `ATTRIBUTION.md`, and the local notices in `01_Parameters/`, `02_CalculationData/`, and `03_ExperimentalData/`. ### Access Restrictions **Open access with content-specific legal limitations.** The repository-authored code, documentation, and owned generated outputs are openly available under the licenses described above. The following restrictions remain: - proprietary experimental vapor-pressure and liquid-density values are not included; - the `EXP_PUR_*_DIPPR801.json` files contain placeholders and source metadata, not restricted DIPPR property values; - reuse of literature-derived measurements and parameter values is governed by the original sources; - users must supply equivalent licensed thermophysical property data to rerun workflows that depend on the omitted values. No embargo is stated in the supplied materials. ### Text for Citation Suggested repository citation: > Jaeschke, N.; Smirnova, I.; Chapman, W. G. (2026). *Lyogel Equilibria with Helmholtz Equations of State: Source Code* [Research software and data repository]. DOI: 10.15480/882.16926. Scientific users should also cite the relevant associated publication or publications listed above. For CC BY 4.0 material, include the authors, repository title, DOI, version or commit used, an indication of modifications, and the license. ## 5. Reproducibility and Software Dependencies ### Software Required The repository specifies: - Python **3.11.x**; - `numpy==2.3.4`; - `scipy==1.16.3`; - `pandas==2.3.3`; - `matplotlib==3.10.7`; - `mpltern==1.0.4`; - `feos==0.9.2`; - `si-units==0.11.0`; - Conda and `pip` for the documented environment setup. The installable package is `equi_gel`, version **0.1.0**. ### Scripts and Workflow Create and activate the pinned environment from the repository root: ```bash conda env create -f environment.yml conda activate lyogel_modeling_env ``` The environment installs the repository in editable mode with `pip -e .`. Run scripts from their own section directories because many workflows use relative paths. Methodology examples: ```bash cd 04_Introduction python alternating_tangents_example.py python plot_network_terms.py ``` Solvent systems: ```bash cd 05_SolventSystems python plot_esterification_systems_from_params.py python plot_esterification_systems_from_params_only_kij_aa.py ``` Polymer systems: ```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 ``` Gel systems: ```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 are deliberate refresh workflows rather than quick examples. They can be computationally expensive, may append to existing `*_de_gen.csv` histories, and may create or overwrite candidate JSON and NPY outputs. ### Reproducibility Notes - Preserve the full repository directory structure. - Create the pinned Conda environment from the repository root. - Execute each script from its documented section directory. - Use the archived `CAL_*` records and saved optimization assets to regenerate supplied plots without repeating every expensive calculation. - Back up or rename optimizer histories before a clean rerun because several optimizers append to existing CSV files. - Review optimization scripts before execution because some write candidate files to the current working directory. - `05_SolventSystems/pure_components.py` cannot run completely using only the open files in this deposit. Equivalent experimental vapor-pressure and liquid-density data from a licensed source are required. - Several scripts are publication-specific and contain hard-coded model selections rather than a general command-line interface. - Reproduced results may depend on platform-level numerical differences, solver tolerances, and the exact pinned dependency versions. ## 6. Ethical and Legal Aspects ### Data Protection The repository contains thermodynamic model inputs, literature-derived scientific measurements, calculated results, source code, and generated research outputs. It contains no documented personal, clinical, or sensitive participant data. Anonymization and pseudonymization are therefore not applicable. ### Consent Statement **Not applicable.** No human participants or personal-data collection are documented. Legal permission to reuse literature-derived values must still be assessed under the terms of the original publications and databases. ## 7. Versioning and Updates ### Version Number - README template version: **V01** - Persistent repository record: **DOI `10.15480/882.16926`** ### Date of Release **2026-07-20** for the supplied repository snapshot, based on the archive entries. ### Change Log **Initial supplied release:** - packaged the `equi_gel` research library and pinned Python environment; - included literature and curated or fitted PC-SAFT parameter tables; - included archived calculated records and curated literature-derived experimental records; - included solvent, polymer, and gel workflow scripts; - included optimizer histories, fitted parameter snapshots, restart arrays, figures, and tables; - included MIT and CC BY 4.0 license texts, attribution guidance, and third-party notices; - linked the repository to both associated 2026 publications and DOI `10.15480/882.16926`. No earlier repository-wide change log is included in the supplied snapshot. ## 8. Contact Information ### Corresponding Author **Name:** Nanning Jaeschke **Institution:** Institute of Thermal Separation Processes, Hamburg University of Technology, 21073 Hamburg, Germany **Email:** [nanning.jaeschke@tuhh.de](mailto:nanning.jaeschke@tuhh.de) **ORCID:** [0009-0000-0369-3568](https://orcid.org/0009-0000-0369-3568) **Repository / Project Record:** [https://doi.org/10.15480/882.16926](https://doi.org/10.15480/882.16926) **Related Publications:** [Part I](https://doi.org/10.1021/acs.iecr.6c01490); [Part II](https://doi.org/10.1021/acs.iecr.6c01731)