# SKILL: Structure Alignment Tool

## Protocol Version
1.0.0

## Name
Structure Alignment Tool

## Description
Performs 3D alignment of two protein structures, calculating RMSD (Root Mean Square Deviation) and TM-score (Template Modeling score) to evaluate protein structure similarity.

## Input Specification

### Required Inputs
- `target`: Target protein structure (PDB file path or PDB ID, e.g., "1ABC")
- `reference`: Reference protein structure (PDB file path or PDB ID)

### Optional Parameters
- `chain_id`: Specify chain ID (default: first chain)
- `min_seq_len`: Minimum sequence length filter (default: 30)
- `output_dir`: Output directory (default: current directory)

### Input Format
```json
{
  "target": "path/to/target.pdb or PDB ID",
  "reference": "path/to/reference.pdb or PDB ID",
  "chain_id": "A",
  "min_seq_len": 30,
  "output_dir": "./output"
}
```

## Execution Steps

### Step 1: Structure Reading
```
1.1 Parse target PDB file or download from PDB database
1.2 Parse reference PDB file or download from PDB database
1.3 Extract CA atom coordinates (or all backbone atoms)
1.4 Validate structure integrity
```

### Step 2: Sequence Preprocessing
```
2.1 Remove non-standard amino acids
2.2 Align sequences (if lengths differ)
2.3 Extract comparable residue indices
```

### Step 3: Structure Alignment (Kabsch Algorithm)
```
3.1 Center: Translate both structures to origin
3.2 Compute covariance matrix H = P^T * Q
3.3 SVD decomposition: H = U * S * V^T
3.4 Compute optimal rotation matrix R = V^T * U^T
3.5 Handle chirality: Ensure right-handed coordinate system det(R) = 1
3.6 Apply rotation: Q_aligned = Q * R
```

### Step 4: RMSD Calculation
```
RMSD = sqrt(1/N * sum(|P_i - Q_i|^2))
```
Where N is the number of atoms, P_i and Q_i are the corresponding atom coordinates.

### Step 5: TM-score Calculation
```
TM-score = max(1/N * sum(1/(1 + (d_i/d_0)^2)))
d_0 = 1.24 * (N - 15)^(1/3) - 1.8
```
TM-score ranges [0, 1], where:
- TM-score > 0.5 indicates similar fold
- TM-score > 0.6 indicates reliable structural alignment
- TM-score > 0.8 indicates highly similar structure

### Step 6: Identify Similar Structure Regions
```
6.1 Calculate distance for each residue pair
6.2 Mark regions with distance < 2A as similar
6.3 Identify domain boundaries
```

### Step 7: Generate Report
```
7.1 Summarize RMSD and TM-score
7.2 List similar structure regions
7.3 Optional: Output aligned PDB file
```

## Output Specification

### Output Format
```json
{
  "status": "success" | "error",
  "target": "PDB ID",
  "reference": "PDB ID",
  "num_atoms": integer,
  "rmsd": float,
  "tm_score": float,
  "similarity_level": "high" | "medium" | "low",
  "similar_regions": [
    {
      "residue_range": "1-50",
      "num_residues": 50,
      "avg_distance": float
    }
  ],
  "alignment_matrix": [[float]],  // 4x4 transformation matrix
  "execution_time_ms": integer
}
```

### Text Report Format
```
Structure Alignment Report
===========================
Target:     protein1.pdb
Reference:  protein2.pdb
Atoms:      150 CA atoms

RMSD:       2.34 Angstrom
TM-score:   0.78

Similarity Level: HIGH (TM-score > 0.5)

Similar Regions:
  - Region 1: residues 1-50 (avg distance: 1.82 A)
  - Region 2: residues 55-100 (avg distance: 2.15 A)

Transformation Matrix:
[ 0.95, -0.12,  0.28,  0.00]
[ 0.15,  0.91, -0.38,  0.00]
[-0.25,  0.41,  0.87,  0.00]
[ 0.00,  0.00,  0.00,  1.00]

Execution time: 123 ms
```

## Tools & Dependencies

### Required
- Python 3.8+
- NumPy
- Biopython (optional, for full PDB parsing)

### Optional Tools
- TM-align binary tool (for more precise TM-score calculation)
- PyMOL (for visualization)

### Fallback Strategy
If external tools are unavailable, use pure Python implementation of Kabsch algorithm.

## Error Handling

### Common Errors
1. **Invalid PDB file**: Return error message, indicate file format issue
2. **Structure length mismatch**: Truncate to shorter structure or return alignment error
3. **Missing CA atoms**: Use backbone atoms or return error
4. **Download failed**: Return local file path suggestions

### Error Response Format
```json
{
  "status": "error",
  "error_code": "INVALID_PDB" | "DOWNLOAD_FAILED" | "ALIGNMENT_FAILED",
  "message": "Detailed error description",
  "suggestion": "Fix suggestion"
}
```

## Example Usage

### Basic Usage
```
target: "protein1.pdb"
reference: "protein2.pdb"
```

### Using PDB IDs
```
target: "1ABC"
reference: "2DEF"
```

### Complete Parameters
```json
{
  "target": "d:/data/1crn.pdb",
  "reference": "d:/data/2ccy.pdb",
  "chain_id": "A",
  "min_seq_len": 20
}
```