# Cyclized Type-0/1 Block End-to-End Analysis

This script analyzes HOOMD GSD trajectories and measures the end-to-end distances of contiguous type-0/1 blocks **only in molecules classified as cyclized**.
The workflow uses `init.txt` to define per-molecule particle types and uses the last frame of each `sample.gsd` trajectory for classification and measurement.

## What the script does

For each experiment folder, the script performs the following steps:

1. Reads `init.txt` and reconstructs the particle-type layout for one molecule.
2. Builds contiguous folding-analysis blocks from particle types 2, 3, and 4.
3. Builds contiguous measurement blocks from particle types 0 and 1, treating types 0 and 1 as equivalent within each contiguous segment.
4. Opens the last frame of `sample.gsd`.
5. Classifies each molecule as `cyclized`, `misfolded`, or `unfolded` based on block-block contacts.
6. Measures the minimum-image end-to-end distance of each type-0/1 block for cyclized molecules only.
7. Pools all measured distances and writes summary statistics to a tab-delimited output file.

## Cyclization criterion

Cyclization is **not** decided from the end-to-end distance itself. Instead, it is decided from contacts between contiguous folding blocks made of particle types 2, 3, and 4.

For each folding block pair \(i, j\), the script computes:

- \(\mathrm{COM}_i\), \(\mathrm{COM}_j\): equal-weight geometric centers of the two blocks.
- \(R_{g,i}\), \(R_{g,j}\): equal-weight radii of gyration of the two blocks.
- \(d_{ij}\): minimum-image distance between the two block centers.
- \(d_{\mathrm{cut},ij} = c(R_{g,i} + R_{g,j})\), where `c = RG_C`.

A pair is counted as a contact when:

\[
d_{ij} < c(R_{g,i} + R_{g,j})
\]

Using those contacts, a molecule is labeled as follows:

- `cyclized`: at least one 3-4 contact exists, and no other block-block contact exists.
- `misfolded`: any non-(3,4) contact exists.
- `unfolded`: no block-block contacts exist.

This means the final end-to-end statistics are restricted to molecules that satisfy a geometry-based cyclization criterion rather than a direct chain-extension cutoff.

## End-to-end distance definition

After cyclized molecules are identified, the script finds every contiguous type-0/1 block in the one-molecule `init.txt` template.
For each such block, the end-to-end distance is defined as the minimum-image distance between the first and last particle in that contiguous block.

Because periodic boundary conditions are used, the script applies the minimum-image convention for an orthorhombic box when calculating distances.

## Input layout

The script expects a directory structure like this:

```text
.
├── B2/
│   ├── run1/
│   │   ├── sample.gsd
│   │   └── init.txt
│   └── run2/
│       ├── sample.gsd
│       └── init.txt
├── B3/
│   └── ...
├── B4/
├── B5/
└── B6/
```

Each top-level folder listed in `TOP_B_FOLDERS` is scanned, and each subfolder is treated as one experiment if both `sample.gsd` and `init.txt` are present.

## Required files

### `sample.gsd`

The trajectory file must be readable with `gsd.hoomd.open(...)`, which supports random frame access and frame indexing.
The script uses only the **last frame** of each trajectory file.

### `init.txt`

The first whitespace-delimited column must contain integer particle types.
The number of rows in `init.txt` is interpreted as the number of particles in one molecule, and the script assumes all molecules in the trajectory share the same per-molecule layout.

## Assumptions

This script makes the following assumptions:

- The simulation box is orthorhombic, so the simple minimum-image wrapping formula is valid.
- Particles are stored contiguously molecule-by-molecule in the trajectory.
- All molecules contain the same number of particles, equal to the row count of `init.txt`.
- Folding-analysis blocks are contiguous runs of particle types 2, 3, and 4.
- Measurement blocks are contiguous runs of particle types 0 and/or 1.
- Radius of gyration is computed with equal particle weights, not mass-weighted values.

## Output

For each top-level folder such as `B2`, the script writes:

```text
B2_summary_cyclized_type01_block_end_to_end.txt
```

The output table contains the following columns:

| Column | Meaning |
| --- | --- |
| `top_folder` | Top-level directory being processed. |
| `folder` | Experiment subfolder path. |
| `n_molecules` | Number of molecules inferred from the trajectory and `init.txt`. |
| `n_cyclized` | Number of molecules classified as cyclized in the last frame. |
| `n_type01_blocks_per_molecule` | Number of contiguous type-0/1 blocks in one molecule. |
| `n_distances_total` | Total number of measured end-to-end distances pooled across all cyclized molecules. |
| `mean_end_to_end_distance` | Mean pooled end-to-end distance. |
| `sem_end_to_end_distance` | Standard error of the mean for the pooled distances. |
| `block_ranges` | Local particle-index ranges for each type-0/1 block in one molecule. |

## Dependencies

Install the Python packages used by the script:

```bash
pip install numpy pandas gsd
```

The trajectory reader relies on the `gsd.hoomd` Python API for HOOMD-native GSD files.

## Usage

Run the script from the directory that contains the `B2`, `B3`, `B4`, `B5`, and `B6` folders:

```bash
python your_script_name.py
```

If needed, edit the user-configurable section near the top of the script to change:

- `TOP_B_FOLDERS`
- `TARGET_GSD_FILENAME`
- `TARGET_INIT_FILENAME`
- `RG_C`
- `ALLOWED_FOLD_TYPES`
- `TYPE01_SET`

## Interpretation notes

The reported mean and SEM are calculated from the pooled set of block end-to-end distances across all cyclized molecules in the last frame, not from a per-molecule average followed by a second averaging step.
That choice should be kept in mind when comparing systems with different numbers of cyclized molecules or different numbers of type-0/1 blocks per molecule.

The script is designed for a specific structural interpretation: folding-state classification is based on contacts among type-2/3/4 blocks, while the reported observable is the extension of type-0/1 segments inside molecules that satisfy that cyclization rule.

## Limitations

- Only the last frame is analyzed; no time averaging is performed.
- The minimum-image implementation is written for orthorhombic boxes only.
- The contact rule uses block COM and block \(R_g\), so changing `RG_C` changes the cyclized population and therefore also the final end-to-end statistics.
- The script does not unwrap full polymer conformations; it only applies minimum-image distances where needed for classification and end-to-end measurement.
