> For the complete documentation index, see [llms.txt](https://jwliaomath.gitbook.io/cocofold2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jwliaomath.gitbook.io/cocofold2/refinement-workflows/block_rigid_alignment.md).

# Chain and block alignment

Single-GPU training uses one complete diffusion cache, one decoder and one whole-structure latent. Per-chain alignment applies a separate R/t to each atom group after decoding; four chains do not require four models. Supply one reference CIF already placed in the experimental map frame. Its atom identities, count and order must match the cache, and all chains must share that reference frame.

## Generate a per-chain manifest

```bash
python src/prepare_block_alignment.py --target /path/to/placed.cif \
  --by-chain --fit-atoms ca --output /path/to/new_chains.json
```

Each CIF `auth_asym_id` becomes one group. By default, fitting uses all C-alpha atoms in each chain; `--fit-atoms all` uses all atoms. Either choice retains every atom and moves it with its assigned chain. Each fitting core requires at least three non-collinear atoms; an invalid core raises an error rather than falling back to a global fit. A manifest can manually restrict the fitting core while retaining atom identities and complete group assignments.

Add these options to the normal `train.py` command:

```
--coordinate-mode blocks --block-alignment /path/to/new_chains.json
--train_deterministic
```

Continue to supply the same `--cif_path`. For new per-chain manifests, `--alignment-sampler auto` uses the original train sampler and applies per-chain transforms to its output coordinates. The original dtype, cache and RNG behavior are retained. Old block checkpoints retain their original block decoder; sampling paths are not switched implicitly. The public block decoder supports single-structure decoding without private heterogeneity modules.

## Fitting and optional updates

Each initial coordinate core is fitted to its reference core by rigid least squares. These transforms contain rotation and translation, without scaling or shear. The coordinate module uses the row-vector convention: `Y[a] = X[a] @ R[body[a]] + t[body[a]]`.

Transforms remain fixed during training by default. With explicit `--update_affine_mat`, chains independently test the common `--block-update-trace-threshold` (default 2.5). A chain updates both R and t only when `trace(R_new @ R_old.T) < threshold`. Fitting is not differentiated; updates are recorded in JSONL and transforms are saved in the checkpoint. Global mode retains its existing update logic.

## Saving, export and restart

Epoch saving synchronously decodes the updated parameters, so the structure and checkpoint represent the same step. New checkpoints retain grouping, fitting cores, target coordinates, transforms and sampling information. `get_pdb.py` defaults to the saved experimental reference frame; raw export is optional. Use `--resume` for complete new epochs and `--warm-start` for older files. See [outputs and restart](/cocofold2/reference/outputs_and_restart.md).

The legacy `--atom-map` path accepts atom tables with `six_body_file` and `suggested_fit_core` fields for existing block manifests. It is a separate manifest preparation method from automatic one-group-per-chain assignment.

## Relationship to GPU grouping

Rigid fitting groups and compute groups are independent. Parallel uses one component cache per GPU; each cache may contain several chains and optionally fit them separately. Four chains can be optimized on one GPU as a whole or with two already prepared two-chain caches in a 2+2 layout. The program does not automatically combine four independent single-chain caches into two caches.

The accepted Contextual 6ZBH example uses 1+3: A and BCD each occupy one GPU. It fits each component as a whole, without per-chain transforms inside a component. Each epoch exports component structures and a merged CIF. See the [two-GPU example](/cocofold2/refinement-workflows/6zbh_parallel.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://jwliaomath.gitbook.io/cocofold2/refinement-workflows/block_rigid_alignment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.