# Hierarchical Folding of Linear Block Copolymer Chains into Polygons and Membrane-like Assemblies

This simulation script models the hierarchical folding of a linear block copolymer–type chain that first forms polygonal motifs and then assembles into membrane-like structures.  
The code uses HOOMD-blue to evolve a coarse-grained chain with patchy and isotropic interactions through a sequence of preparation, folding, deposition, and assembly stages, and writes the resulting trajectory to `sample.gsd`.

## Physical picture

The model represents a **linear block copolymer–type chain** whose segments differ in geometry and interaction type.  
Selected blocks carry directional patches that promote polygonal folding, while others control flexibility, lateral association, and surface binding; the protocol is designed so that:

- individual chains first fold into **polygon-like shapes**, and  
- these polygonal units subsequently assemble into **membrane-like structures** on a substrate.

The wall, external forces, and box-resize protocol steer the system from a bulk-like initial state to a dense, quasi-2D deposited assembly.

## What the script does

The run script performs the following major steps:

1. **Initialization**
   - Creates a HOOMD simulation on CPU with a random seed.
   - Reads text templates describing particle types, initial positions, rigid sub-units, bonds, and patch directions.

2. **System construction**
   - Builds rigid sub-units corresponding to different blocks of the linear chain.
   - Assigns bonded connectivity (FENE-WCA bonds) for the copolymer backbone.
   - Replicates the initial template in the plane to obtain multiple chains.

3. **Interaction setup**
   - Defines:
     - rigid-body constraints for core segments,
     - isotropic Lennard-Jones interactions for excluded volume and selected attractions,
     - anisotropic patchy LJ interactions that drive **local polygonal folding**,
     - Yukawa repulsion for tunable longer-range screening,
     - FENE-WCA bonds for chain connectivity and bond shortening,
     - an external LJ wall to represent a surface for deposition.
   - Uses an NVT ensemble with a Nosé–Hoover–type thermostat (`ConstantVolume` + MTTK).

4. **Staged dynamic protocol**
   - Gradual FENE bond tightening,
   - bond equilibration at fixed temperature,
   - temperature cycling with enhanced patch attractions to promote **folding into polygon-like motifs**,
   - gravity-like forcing and stronger wall attraction to deposit chains onto a substrate,
   - slow box compression/expansion in the surface plane to control areal density,
   - a long final run at fixed conditions for **membrane-like assembly**.

5. **Output and logging**
   - Periodically writes the full particle configuration to `sample.gsd`,
   - prints timestep / TPS / estimated time remaining to the terminal.

## Required input files

The script expects the following files in the working directory:

- `init.txt`  
  Defines initial particle positions, integer type ids, body indices, and size parameters for one chain (or one unit cell).

- `init_bond.txt`  
  Specifies bonded pairs (and bond types) that define the linear block copolymer backbone and auxiliary connections.

- `init_rigid.txt`  
  Layout of constituent particles for one rigid sub-unit (e.g., a core block of the chain).

- `init_rigid_secondary.txt`  
  Layout for a second type of rigid sub-unit used in the copolymer architecture.

- `director_helix.txt`  
  Patch direction vectors for the anisotropic patchy LJ potential, used to encode local “bonding directions” that favor polygonal folding.

All of these files are plain-text templates that encode the geometry and composition of the chain before dynamics starts.

## Model ingredients and hierarchy

The hierarchical folding picture is implemented through distinct interaction types:

- **Backbone blocks**  
  Represent the main linear copolymer backbone and determine flexibility and contour length.

- **Patchy blocks for polygon formation**  
  Selected segments carry directional patches; their anisotropic attractions and geometry favor folded polygon-like states when the chain is cooled and bonds are tightened.

- **Lateral association blocks**  
  Other segments primarily control lateral attractions and repulsions between polygonal units, enabling membrane-like aggregation once folding has occurred.

- **Surface coupling**  
  A wall potential plus a gravity-like external force drives chains toward a substrate, so polygonal units assemble into **quasi-2D membranes** rather than 3D aggregates.

The combination of these elements turns a linear block copolymer into folded polygons first, and then into extended, membrane-like assemblies.

## Simulation protocol (high level)

### 1. FENE bond ramp (chain preparation)

- FENE bond extension limits are reduced from a loose initial value to tighter final values using a smooth ramp.
- This gradually “locks in” the backbone geometry of the linear chain without creating large transient forces.

### 2. Bond equilibration

- The system is equilibrated at a base temperature with the tightened bonds.
- The goal is to relax local distortions and obtain a well-prepared starting ensemble.

### 3. Folding stage (polygon formation)

- Patch attractions and selected isotropic attractions are strengthened.
- A temperature cycle between lower and higher `kBT` is applied.
- Under these conditions, the linear block copolymer chains are driven to fold; the patch geometry and bond constraints favor polygon-like folded states along the chain.

### 4. Deposition stage (surface confinement)

- A constant force along the surface-normal direction pulls selected blocks toward a wall.
- Wall attraction is increased for specific segments, pinning chains and polygonal units to the surface.
- This converts a 3D folding problem into an effectively 2D, surface-confined assembly problem.

### 5. In-plane compression / expansion

- The simulation box is rescaled in the plane of the substrate (keeping the wall-normal dimension fixed) to reach target packing fractions.
- First, the system is compressed to a higher areal density, then partially re-expanded.
- This tunes how densely polygonal units and chains are packed before the final assembly run.

### 6. Membrane-like assembly

- With folding, deposition, and density control in place, a long production run is performed.
- During this stage, polygonal units organize into larger, membrane-like surface assemblies that can be analyzed downstream.

## Output

The main output of the script is:

- `sample.gsd`  
  A GSD-format trajectory containing the full particle positions, types, and topology at regular time intervals throughout the protocol.

This file is the starting point for analysis scripts that:

- identify polygonal motifs along each chain,
- classify folding states,
- characterize membrane-like domains and defects,
- compute geometric or thermodynamic observables.

## Assumptions and limitations

- The coarse-grained mapping from chemistry to particle types and patches is encoded in the input templates and the potential parameters in the script; the README does not specify a specific chemical system.
- Rigid-body definitions and patch directions are fixed in time; only positions and orientations evolve.
- The protocol is **scenario-specific**: it is tuned for hierarchical folding of a linear block copolymer into polygonal motifs and membrane-like assemblies, rather than generic polymer melts.

## Dependencies

The script requires:

- Python 3
- `hoomd`
- `gsd`
- `numpy`
- `freud` (for possible post-processing or analysis)
- `coxeter` (for geometrical utilities, if used elsewhere)

Install, for example, with:

```bash
pip install hoomd gsd numpy freud-analysis coxeter
```

## Usage

1. Prepare the input files (`init.txt`, `init_bond.txt`, `init_rigid*.txt`, `director_helix.txt`) matching the desired block copolymer architecture.
2. Place the run script and input files in the same directory.
3. Run:

```bash
python run_hierarchical_folding.py
```

4. After completion, analyze `sample.gsd` with separate analysis scripts (e.g., polygon area/angle measurement and membrane structure characterization) to quantify hierarchical folding behavior.

This script is intended as the **protocol layer** in a larger workflow that also includes geometry-based analysis tools for polygons and membrane-like assemblies.