> This page is for OpenFold2, version 2.6.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 2.6.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/openfold2/2.6.0/llms.txt
> - 2.5.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.5.0/llms.txt
> - 2.4.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.4.0/llms.txt
> - 2.3.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.3.0/llms.txt
> - 2.2.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.2.0/llms.txt
> - 2.1.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.1.0/llms.txt
> - 2.0.0: https://docs.nvidia.com/nim/bionemo/openfold2/2.0.0/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/bionemo/openfold2/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/bionemo/openfold2/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/openfold2/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Template Processing

OpenFold2 NIM supports incorporating structural templates into protein structure prediction using mmCIF format strings. This document provides technical details about how template inputs are processed to generate template features.

<Note>
Starting with version 2.0.0, HHR-based template processing has been removed. If you want to migrate from previous versions, refer to the [Migration Guide](/nim/bionemo/openfold2/migrating-from-hhr-to-explicit-templates) for detailed instructions.
</Note>

## Overview

Template processing in OpenFold2 follows two main approaches:

- **No template input**: Template atomic coordinates are not used for structure prediction
- **Direct template processing**: Uses mmCIF format strings provided directly in the request

This document focuses on the technical details of direct template processing, which incorporates structural templates directly from the request.

## Template Processing

This section explains the fundamental concepts of template processing in OpenFold2.

### Required Fields

- **use_templates**: `true` (required to enable template processing)
- **explicit_templates**: mmCIF format strings containing structural template data (supports both `mmcif` and `mmcif.gz` formats)

<Note>
The API data model includes a `rank` field for template objects. For OpenFold2 monomer use-cases, this field should remain at its default value of `-1`.
</Note>

### Processing Pipeline

1. **Parse mmCIF strings**: Extract structural data directly from the provided mmCIF content

2. **Chain selection**: Automatically select chains with `_atom_site.label_asym_id=A` from the template structure for featurization

3. **Sequence alignment**: Align the query sequence to the template chain sequence using Kalign to establish residue correspondence

4. **Sequence identity validation**: Ensure at least 90% sequence identity between query and template sequences (based on the shorter sequence length)

5. **Mapping validation**: Create query-to-template residue mapping based on the alignment results

6. **Feature extraction**: Generate template features using structural information and alignment mapping

### Template Feature Composition

The resulting template features combine structural and alignment information:
- **Structural information**: From mmCIF content (atomic coordinates, residue types)
- **Sequence alignment**: Uses Kalign to align query sequence to template chain sequence
- **Residue mapping**: Query-to-template correspondence based on alignment results
- **Fixed confidence**: Template confidence set to maximum value
- **Direct processing**: Processing without database dependencies

### Use Cases

- Custom template structures not available in curated databases
- User-provided experimental or computational structures
- Rapid prototyping without database infrastructure dependencies
- When structural geometry is more important than alignment statistics

### Example Request Structure

In both examples below, `rank` is set to `-1`, the default value for the OpenFold2 monomer use-case.

**Uncompressed mmCIF format:**

```json
{
    "sequence": "GGSKENEISHHAKEIERLQKEIERHKQ...",
    "use_templates": true,
    "explicit_templates": [
        {
            "name": "my_custom_template",
            "format": "mmcif",
            "structure": "MMCIF_STRING_CONTENT_HERE",
            "rank": -1
        }
    ]
}
```

**Compressed mmCIF format:** the request body is JSON, so `structure` is always a string containing the mmCIF text. Set `format` to `mmcif.gz` and the NIM gzip-compresses the string server-side, reducing in-memory and processing overhead for large templates.

```json
{
    "sequence": "GGSKENEISHHAKEIERLQKEIERHKQ...",
    "use_templates": true,
    "explicit_templates": [
        {
            "name": "my_compressed_template",
            "format": "mmcif.gz",
            "structure": "MMCIF_STRING_CONTENT_HERE",
            "rank": -1
        }
    ]
}
```

## Key Technical Features

| Aspect | Implementation |
|--------|----------------|
| **Data Sources** | mmCIF strings (uncompressed) and mmCIF.gz (gzip-compressed) |
| **Alignment Method** | Kalign sequence alignment |
| **Confidence Scoring** | Fixed maximum confidence |
| **Dependencies** | Kalign binary for alignment |
| **Error Handling** | mmCIF parsing and alignment validation |
| **Processing Complexity** | Direct processing with alignment step |

## Impact on Structure Prediction

This section highlights the advantages of the current template processing approach.

### Template Processing Advantages

- **Flexibility**: Accepts any structural template, including novel or experimental structures
- **Speed**: Direct processing without database lookup overhead
- **Custom structures**: Incorporates user-generated models, NMR structures, or computational predictions
- **Minimal dependencies**: No template database required; only mmCIF parsing and Kalign alignment
- **Reduced footprint**: No large template databases required
- **Faster startup**: Eliminates database loading time

### Performance Considerations

- **Direct processing** provides maximum flexibility and speed with simplified confidence weighting
- **Fixed confidence** ensures consistent template utilization across different structure types
- **Single-step processing** reduces computational overhead and potential failure points

## Best Practices

This section describes the best practices for template processing in OpenFold2.

### When to Use Templates

- When you have high-quality structural templates related to your target sequence
- For proteins with known homologs or structural domains
- When incorporating experimental structures or high-confidence computational models
- For improving prediction accuracy in regions with structural similarity

### Template Selection Guidelines

- Use templates with good sequence similarity to your target (≥90% sequence identity required)
- Ensure mmCIF files contain complete atomic coordinate information
- Use templates with high experimental resolution, when available
- Consider using multiple complementary templates for better coverage
- Use `mmcif.gz` format for large template files to reduce request payload size

### Sequence Identity Requirements

- **Minimum threshold**: 90% sequence identity between query and template sequences
- **Calculation method**: Based on the shorter of the two sequences (query or template)
- **Validation timing**: Performed during the alignment step before feature extraction
- **Failure handling**: Templates below 90% identity are rejected with clear error messages

## Technical Implementation Notes

Template processing in OpenFold2 produces standardized template feature data structures that are fully compatible with the OpenFold2 model. Key implementation details:

- **Confidence weighting**: Uses fixed maximum confidence for consistent template utilization
- **Alignment method**: Kalign-based sequence alignment establishes query-to-template residue correspondence
- **Error handling**: mmCIF parsing and sequence identity validation with clear error messages for debugging
- **Chain selection**: Automatically selects chains with `label_asym_id=A` for featurization
- **Memory efficiency**: Direct processing without intermediate database storage

If you want to migrate from HHR-based workflows, refer to the [Migration Guide](/nim/bionemo/openfold2/migrating-from-hhr-to-explicit-templates) for detailed transition instructions and code examples.