3DCA POLYMER SIMULATION CODE ============================ This repository contains the Python simulation and analysis code used for the article "3D Cellular Automata of Polymer Structural Response to Solvent Quality". The model represents polymer segments and solvent on a three-dimensional cubic lattice. Polymer motion is generated by local polymer-solvent exchange attempts with Metropolis-type acceptance, fixed chain connectivity, excluded volume, and bond-crossing rejection. This README starts with the simplest useful workflow: run one short simulation, inspect its output, and create images and a video. INSTALL ALL DEPENDENCIES ------------------------ The requirements.txt file next to this README contains the external Python packages required by both the simulation code in common and the complete analysis workflow in analysis. From the 20260827 folder, run: python -m pip install -r requirements.txt If you use a virtual environment or a specific Python executable, replace `python` with the corresponding executable path. QUICK START: COPY AND PASTE --------------------------- Linux/macOS: set -e cd /path/to/20260827 PYTHON=python3 $PYTHON -m unittest discover -s common -p "test_*.py" -v cd linear_chain $PYTHON 1_simulation_test.py $PYTHON 2_make_png_mp4.py On the authors' Linux server, Python is located at: PYTHON=/home/v/venvs/v/bin/python Windows PowerShell: Set-Location C:\path\to\20260827 python -m unittest discover -s common -p "test_*.py" -v Set-Location linear_chain python 1_simulation_test.py python 2_make_png_mp4.py The test calculation uses one finite chain of length 20, poor-solvent conditions, 1,000 Monte Carlo steps, and a snapshot interval of 100 steps. WHAT THE QUICK START CREATES ---------------------------- The simulation creates a new folder named approximately: trajectories_DATE_TIME_linear_chain_L20_Epp-2.0_Esp-0.3_seed...-... The folder contains: trajectories.npz Saved lattice snapshots, snapshot steps, polymer identifiers, and bonds. final.npz Final configuration. metadata.json Geometry, box size, polymer fraction, energies, seeds, runtime, bond-crossing statistics, and source-code hashes. Post-processing adds: first_frame_polymer.png last_frame_polymer.png trajectories_all_polymer.mp4 Do not open the MP4 while it is still being written. Wait until the terminal prints "Saved: ...trajectories_all_polymer.mp4". RUN ONE SIMULATION WITH YOUR OWN PARAMETERS ------------------------------------------- Each system folder contains a small user-facing script called 1_simulation.py. Run it from that system folder and supply the required parameters. Example: one finite linear chain, L=100, one million Monte Carlo steps: cd /path/to/20260827/linear_chain python 1_simulation.py \ --L 100 \ --Epp -2.0 \ --Esp -0.3 \ --steps 1000000 \ --interval 1000 \ --init-seed 2026090201 \ --dynamics-seed 2026090202 \ --output-root . The same command on the authors' server is: /home/v/venvs/v/bin/python 1_simulation.py \ --L 100 \ --Epp -2.0 \ --Esp -0.3 \ --steps 1000000 \ --interval 1000 \ --init-seed 2026090201 \ --dynamics-seed 2026090202 \ --output-root . Important parameters: --L Chain length. For the disordered 30-chain structures, L must be 20. --Epp Polymer-polymer nearest-neighbor contact energy. --Esp Polymer-solvent contact energy. The article uses -0.3, -0.75, and -1.0 for poor-, theta-like-, and good-solvent conditions, respectively, with Epp fixed at -2.0. --steps Number of Monte Carlo steps. --interval Number of Monte Carlo steps between saved snapshots. --init-seed Controls stochastic construction of the initial geometry. It has no effect on deterministic linear-chain and cylinder initial structures. --dynamics-seed Controls update order, trial directions, and Metropolis decisions for the complete trajectory. Independent replicates require different dynamics seeds. Repeating the same seed does not increase statistics. --output-root Directory in which the new trajectories_* folder is created. Bond-crossing rejection is enabled by default. Do not disable it for new production calculations. The legacy option --bond-crossing-check off exists only to reproduce trajectories generated with the historical move rule. CHOOSE AN INITIAL STRUCTURE --------------------------- Run the corresponding 1_simulation.py from one of these folders: linear_chain/ One finite straight chain in a 50 x 50 x L box. cylinder/ Twenty-nine finite parallel chains forming a radius-3 bundle. cylinder_PBC/ The same cylindrical bundle with each chain closed through the axial periodic boundary. random_many_linear_chains/ Thirty finite chains of length 20: ten initially aligned along each of the X, Y, and Z directions. random_many_linear_chains_PBC/ The same 30-chain structure with every chain periodically self-closed. All simulation boxes are spatially periodic in X, Y, and Z. Therefore, a chain leaving one side of a saved snapshot reappears on the opposite side. The "PBC" suffix in a geometry name has an additional meaning: the last segment of each chain is bonded to its first segment through the periodic boundary. A normal finite linear chain still has two free ends. EXAMPLES FOR THE OTHER FOUR SYSTEMS ----------------------------------- The test scripts are the easiest way to verify each geometry: cd /path/to/20260827/cylinder python 1_simulation_test.py cd /path/to/20260827/cylinder_PBC python 1_simulation_test.py cd /path/to/20260827/random_many_linear_chains python 1_simulation_test.py cd /path/to/20260827/random_many_linear_chains_PBC python 1_simulation_test.py Each command creates one short poor-solvent trajectory directly in the selected system folder. The production queues described below instead save trajectories inside that system's results folder. POST-PROCESSING OPTIONS ----------------------- Open the relevant system folder's 2_make_png_mp4.py to edit these clearly marked options: MAKE_FIRST_LAST_PNG = True MAKE_POLYMER_VIDEO = True OVERWRITE_EXISTING_PNG = True OVERWRITE_EXISTING_VIDEO = False VIDEO_FRAMERATE = 10 In all five system folders, 2_make_png_mp4.py processes every valid trajectories_* folder located directly inside that system's results folder. The trajectories are processed sequentially. Direct test trajectories and other nested directories are intentionally not searched. If video generation was interrupted, the partial MP4 may already exist. Set OVERWRITE_EXISTING_VIDEO = True and rerun post-processing to rebuild it from the beginning. REQUIREMENTS ------------ Python 3.9 or newer is recommended. Core simulation: NumPy Plots and scientific analysis: Matplotlib PNG and MP4 rendering: PyVista FFmpeg support available to PyVista an off-screen rendering environment when running without a display Typical installation in a virtual environment: python -m venv venv Linux/macOS: source venv/bin/activate Windows PowerShell: .\venv\Scripts\Activate.ps1 Install the Python dependencies: python -m pip install --upgrade pip python -m pip install numpy matplotlib pyvista imageio-ffmpeg RUN THE TESTS ------------- From the 20260827 folder: python -m unittest discover -s common -p "test_*.py" -v Run the tests after moving the project to another computer and after changing the simulation engine or initial structures. OPTIONAL: REPRODUCE ALL SIMULATIONS WITHOUT SLURM ------------------------------------------------- The common/queue folder contains two detached local queues for reproducing the complete simulation datasets. Before starting either queue, open its .sh file and edit the two values near the top: MaxJobs=12 Python="/usr/bin/python3" Set MaxJobs to the maximum number of simulations that your computer should run simultaneously, and set Python to your Python executable. Then enter the queue folder: cd /path/to/20260827/common/queue To reproduce all single-chain calculations (10 chain lengths, 3 solvent conditions, and 5 independent replicates; 150 simulations), run: bash run_nohup_queue_single_chain.sh To reproduce all cylinder and disordered-assembly calculations (4 systems, 3 solvent conditions, and 5 independent replicates; 60 simulations), run: bash run_nohup_queue_multi_chain.sh To start both queues with one command, run: bash reproduce_all_simulations.sh Both scripts locate the system folders automatically from common/queue and write every trajectory to the corresponding system's results folder. Queue lists, logs, and PID files remain in common/queue. The queues run in the background, so the terminal may be closed after launch. If both queues are started simultaneously, the computer may run up to twice the MaxJobs value; reduce MaxJobs accordingly or run the queues one after the other. REPRODUCE ALL ANALYSIS TABLES AND FIGURES ----------------------------------------- After the trajectory datasets have been generated, open the analysis folder and edit only the PYTHON line at the top of analysis_00_reproduce_all_figures.sh so that it points to your Python executable. Then run: cd /path/to/20260827/analysis bash analysis_00_reproduce_all_figures.sh The script executes the complete analysis in the required order. Its output is organized as follows: analysis/results/figures/ All generated PNG figures in one folder. analysis/results/data_for_figures/ CSV and JSON data used to construct the figures, grouped by analysis. The script stops immediately if an analysis step fails or if a required trajectory dataset is missing. The final common comparison of all multi-chain systems is performed in two steps: analysis_05_compare_multi_chain_calc.py Calculates the shared multi-chain descriptors and saves the numerical data used for plotting. analysis_05_compare_multi_chain_make_summary_figures_styled.py Reads those calculated data and creates the corresponding comparison figures. PROJECT MAP ----------- common/ Shared simulation engine, initial structures, post-processing tools, analysis helpers, and automated tests. common/queue/ Optional local background queues for reproducing all single-chain and multi-chain simulations without Slurm. linear_chain/ cylinder/ cylinder_PBC/ random_many_linear_chains/ random_many_linear_chains_PBC/ User-facing entry scripts for the five article geometries. analysis/ Quantitative calculations and figure-generation scripts used for the article. Run analysis_00_reproduce_all_figures.sh here to reproduce all numerical tables and figures in the correct order. SHA256SUMS.txt SHA-256 checksums for the maintained source files. WHAT EACH FILE IN common DOES ----------------------------- simulation_core.py Main simulation engine. It parses parameters, performs randomized local exchange attempts, checks bond length and bond crossing, evaluates local energy changes, applies Metropolis acceptance, and saves trajectories and metadata. Normal users call it through a geometry folder's 1_simulation.py rather than running it directly. initial_structures.py Public collection of the five initial structures used in the article. This is where geometry selection is mapped to its initializer. initial_structures_helpers.py Internal utilities for assigning polymer identifiers, creating bonds, and constructing lattice arrays. post_processing.py Shared PNG and MP4 rendering functions called by the user-facing 2_make_png_mp4.py scripts. analysis_common.py Shared trajectory reader and structural-analysis utilities, including minimum-image treatment, chain reconstruction, and contact detection. It does not create figures by itself. test_simulation_core.py Automated tests for initialization, connectivity, identifiers, seeds, energies, periodic geometry, and bond-crossing rejection. test_post_processing.py Automated tests for post-processing geometry and current/legacy trajectory compatibility. REPRODUCIBILITY NOTES --------------------- - Solvent cells are stored as 0. Polymer segments are stored as consecutive positive identifiers 1, 2, ..., Np. Identifier values have no physical meaning. - Every simulation box is spatially periodic. Distance-dependent analysis uses the minimum-image convention. - init_seed and dynamics_seed are recorded separately in metadata.json. - A reproducible independent ensemble must use distinct dynamics seeds. Running the same seed twice produces a duplicate, not an additional replicate. - New trajectories record whether bond-crossing rejection was active and how many geometrically admissible moves were rejected because of crossing. - metadata.json records hashes of simulation_core.py and initial_structures.py. These hashes identify the code that generated an individual trajectory. - New and legacy trajectories should not be pooled as equivalent production data because the simulation rules changed. Legacy files remain readable for auditing and historical comparison. AUTHORS AND LONG-TERM CONTACT ----------------------------- Authors: Vasilii Korotenko Irina Smirnova Pavel Gurikov Hamburg University of Technology (TUHH) Institute for Thermal Separation Processes Eißendorfer Straße 38 21073 Hamburg, Germany For long-term questions regarding the code, dataset, scientific use, reuse, or citation, please contact: Pavel Gurikov Hamburg University of Technology (TUHH) Email: pavel.gurikov@tuhh.de LICENSE ------- The source code is released under the MIT License. HOW TO CITE ----------- If you use this model, its initial structures, simulation code, analysis tools, or figure-reproduction workflow, please cite both the corresponding publication and this TORE repository. Publication: Vasilii Korotenko, Irina Smirnova, and Pavel Gurikov, "3D Cellular Automata of Polymer Structural Response to Solvent Quality", Macromolecular Theory and Simulations Code and simulation data repository: Korotenko, V.; Smirnova, I.; Gurikov, P. (2026): "Source Code for 3D Cellular Automata of Polymer Structural Response to Solvent Quality". TUHH Open Research (TORE). https://doi.org/10.15480/882.16813 Please replace or supplement the publication entry with the final journal citation and article DOI when available.