# 3D Cellular Automata Simulation of Polymer Gels

## Overview

This repository contains Python scripts used to perform three dimensional cellular automata simulations of polymer chains in a solvent environment.

The code was developed for the research work:

**3D Cellular Automata of Polymer Gel Response to Solvent Change**

The model describes polymer segments and solvent cells on a three dimensional lattice. Polymer conformational changes are generated through local Monte Carlo type exchange moves between polymer cells and neighboring solvent cells. The solvent quality is controlled through the polymer polymer and polymer solvent interaction energies.

## Authors

Vasilii Korotenko

Irina Smirnova

Pavel Gurikov

Thermal Separation Processes

Hamburg University of Technology, TUHH

Eissendorfer Str. 38

21073 Hamburg, Germany

## Long term contact

For long term questions about the code, dataset, scientific use, and citation, please contact:

Pavel Gurikov

Hamburg University of Technology, TUHH

Email: [pavel.gurikov@tuhh.de](mailto:pavel.gurikov@tuhh.de)

## Keywords

polymer gel; cellular automata; solvent response; lattice model; Monte Carlo simulation

## Repository content

The scripts are intended to be executed in numerical order. The visualization scripts are provided in two variants: a standard visualization variant and a PBC aware visualization variant. The PBC aware variant accounts for periodic boundary conditions during visualization and suppresses bonds that appear artificially long because they cross the simulation box.

### 1_simulation.py

Main simulation script.

It performs the three dimensional cellular automata simulation of polymer chains in a solvent environment. It generates lattice snapshots, polymer graph data, final lattice data, and trajectory files in NPZ format.

### 2_time.py

Post processing script for extracting or analyzing timing information.

### 3_png_polymer_1proc.py

Generates PNG images of polymer configurations from the saved trajectory folders using the standard visualization mode.

This is a single process script. Each trajectory folder is processed using one CPU core, and trajectory folders are processed sequentially.

### 3_png_polymer_1proc_PBC.py

Generates PNG images of polymer configurations from the saved trajectory folders using the PBC aware visualization mode.

This version accounts for periodic boundary conditions and removes visual bonds that would appear too long because they cross the simulation box.

This is a single process script. Each trajectory folder is processed using one CPU core, and trajectory folders are processed sequentially.

### 4_combine_png_polymer.py

Combines generated PNG images into summary figures.

### 5_video_polymer_1proc.py

Creates MP4 animations of polymer chain conformational changes using the saved lattice snapshots in the standard visualization mode.

This is a single process script. Each trajectory folder is processed using one CPU core, and trajectory folders are processed sequentially.

### 5_video_polymer_1proc_PBC.py

Creates MP4 animations of polymer chain conformational changes using the saved lattice snapshots in the PBC aware visualization mode.

This version accounts for periodic boundary conditions and removes visual bonds that would appear too long because they cross the simulation box.

This is a single process script. Each trajectory folder is processed using one CPU core, and trajectory folders are processed sequentially.

### 6_Rg_vs_frame.py

Computes the radius of gyration, Rg, for every saved frame and generates Rg versus frame data and plots.

### 7_Rg_t_relax.py

Computes relaxation times by analyzing the time dependence or autocorrelation behavior of Rg.

### 8_Rg_avg_relaxed_L.py

Computes averaged relaxed Rg values and performs scaling analysis as a function of polymer chain length or system parameter L.

## Software requirements

The code was tested with:

Python 3.12.3

Required Python packages are listed in the separate file:

requirements.txt

The tested package versions are:

matplotlib==3.10.7

networkx==3.5

numba==0.62.1

numpy==2.3.4

psutil==7.1.3

pyvista==0.46.4

scipy==1.16.3

Standard Python modules such as os, time, random, datetime, re, and csv are part of the Python standard library and do not need to be installed separately.

## Installation

Create and activate a Python environment if desired. Then install the required packages using:

```bash
python -m pip install -r requirements.txt
```

## How to run the simulation

The main simulation script is:

```bash
1_simulation.py
```

Example command:

```bash
python 1_simulation.py --L 20 --W 30 --Epp -2.0 --Ewp -0.75 --steps 100000 --interval 1000
```

A second example with a different polymer solvent interaction energy is:

```bash
python 1_simulation.py --L 20 --W 30 --Epp -2.0 --Ewp -1.0 --steps 100000 --interval 1000
```

## Command line arguments

`--L`

Polymer chain length or lattice/polymer size parameter used by the simulation script.

`--W`

Solvent or water content parameter used by the simulation script.

`--Epp`

Polymer polymer interaction energy.

`--Ewp`

Polymer solvent or polymer water interaction energy.

`--steps`

Total number of cellular automata or Monte Carlo simulation steps.

`--interval`

Interval for saving lattice snapshots during the simulation.

## How to run post processing

After the main simulation has finished, the post processing scripts can be executed sequentially.

For the standard visualization mode:

```bash
python 2_time.py
python 3_png_polymer_1proc.py
python 5_video_polymer_1proc.py
python 6_Rg_vs_frame.py
python 7_Rg_t_relax.py
python 8_Rg_avg_relaxed_L.py
```

For the PBC aware visualization mode:

```bash
python 2_time.py
python 3_png_polymer_1proc_PBC.py
python 5_video_polymer_1proc_PBC.py
python 6_Rg_vs_frame.py
python 7_Rg_t_relax.py
python 8_Rg_avg_relaxed_L.py
```

The PBC aware visualization scripts account for periodic boundary conditions and suppress bonds that appear artificially long because they cross the simulation box.

The scripts with `_1proc` in their names are single process scripts. Each trajectory folder is processed using one CPU core, and trajectory folders are processed sequentially rather than all at once.

If combined summary images are required, run:

```bash
python 4_combine_png_polymer.py
```

## Input and output format

The simulation creates output folders with names following the general scheme:

```text
trajectories_YYYYMMDD_HHMMSS_Lp{L}_W{W}_Epp{Epp}_Ewp{Ewp}
```

Each trajectory folder may contain:

```text
final.npz
trajectories.npz
gel_graph_data.npz
Rg_vs_frame.csv
tau_relaxation.csv
PNG files
MP4 files
additional CSV summary files
```

## Main output files

### final.npz

Contains the final lattice state and metadata saved at the end of the simulation.

### trajectories.npz

Contains saved lattice snapshots collected during the simulation.

### gel_graph_data.npz

Contains polymer graph data with covalent bond information.

### Rg_vs_frame.csv

Contains radius of gyration values calculated for saved frames.

### tau_relaxation.csv

Contains relaxation time data generated by the relaxation analysis script.

### PNG files

Static visualizations of polymer configurations or analysis results.

### MP4 files

Video animations of polymer conformational changes.

## Reproducibility notes

The simulation uses stochastic Monte Carlo type trial moves. Therefore, repeated runs may not produce identical trajectories unless the random seed is fixed in the script.

For statistical reproducibility, simulations should be repeated with the same input parameters and, if exact trajectory reproduction is required, with the same random seed.

The polymer chain topology is represented by a graph structure. Covalent connectivity is preserved during the simulation by applying bonded constraints to the polymer segments.

## License

The code is released under the MIT License.

The full license text should be provided in a separate file:

LICENSE.txt

## Dataset DOI

https://doi.org/10.15480/882.16813

## Recommended citation

If you use this code, please cite the corresponding dataset and publication:

Korotenko, V.; Smirnova, I.; Gurikov, P. (2026): Code for 3D Cellular Automata of Polymer Gel Response to Solvent Change. TUHH Open Research (TORE). DOI: https://doi.org/10.15480/882.16813

## Notes for reuse

This code was developed for research purposes. Users may need to adapt local paths, filenames, simulation parameters, and visualization settings to their own computing environment.

The scripts do not require SLURM for reuse. They can be executed directly from the command line using the commands shown above.