Boltz Constraint Builder¶
Builds one or more structural constraints in the Boltz YAML format. Supports bond, pocket, and contact constraints, with validation of formats and automatic batching when multiple pairs are provided. For bonds and contacts, multiple pairs can be specified using semicolons; pocket contacts are entered one per line.
Usage¶
Use this node when defining geometric constraints to guide Boltz structure modeling. Select the constraint type and provide the appropriate tokens/atoms in the required format. Chain these constraints with sequence/template/property builders, then feed the combined configuration into downstream Boltz prediction nodes.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| constraint_type | True | ENUM | Type of constraint to create. Determines which additional fields are used. | |
| bond_atom1 | False | STRING | First atoms for bond constraints; semicolon-separated entries. Each entry must be chain_id,residue_idx,atom_name. | A,1,N;B,2,CA |
| bond_atom2 | False | STRING | Second atoms for bond constraints; semicolon-separated entries. Must have the same number of entries as bond_atom1. | B,1,C;C,2,CB |
| pocket_binder | False | STRING | Binder chain ID for pocket constraints. | L |
| pocket_contacts | False | STRING | Residue contact list for pocket constraints; one per line. Each line must be chain_id,residue_idx. | A,10 A,12 B,30 |
| contact_token1 | False | STRING | First tokens for contact constraints; semicolon-separated entries. Each entry must be chain_id,residue_idx. | A,10;A,20;B,30 |
| contact_token2 | False | STRING | Second tokens for contact constraints; semicolon-separated entries. Must have the same number of entries as contact_token1. | B,20;C,30;D,40 |
| max_distance | False | FLOAT | Optional maximum distance threshold in Angstroms for pocket or contact constraints. Set to 0 for no limit. | 6.0 |
| force | False | BOOLEAN | Whether to enforce the constraint with a potential. | true |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| constraints | * | A list of constraint objects in Boltz YAML format, one per specified pair or pocket definition. | [{"bond": {"atom1": ["A", 1, "N"], "atom2": ["B", 2, "CA"]}}, {"contact": {"token1": ["A", 10], "token2": ["B", 20], "max_distance": 6.0, "force": true}}] |
Important Notes¶
- Formats are strict: bond atoms require chain_id,residue_idx,atom_name; contact tokens require chain_id,residue_idx; pocket contacts require chain_id,residue_idx, one per line.
- Multiple entries: For bond and contact constraints, separate multiple pairs using semicolons in both corresponding fields, and ensure counts match.
- Pocket entries: pocket_contacts must be provided one per line; pocket_binder is a single chain ID.
- Integer indices: residue_idx must be integers; invalid numbers will raise errors.
- Optional fields: max_distance (0 means no limit) and force are only applied to pocket/contact constraints; bonds have no distance parameter.
- Validation: The node raises errors for missing required fields, mismatched counts, or invalid formats.
Troubleshooting¶
- Error: Both bond_atom1 and bond_atom2 are required for bond constraints: Provide both fields with semicolon-separated lists of equal length.
- Error: Number of ... entries must match: Ensure the number of entries in bond_atom1 equals bond_atom2, or contact_token1 equals contact_token2.
- Error: Invalid ... format: Check each entry matches the required format. Examples: bond 'A,1,N'; contact 'A,10'; pocket 'A,10' (one per line).
- Error: Binder and contacts are required for pocket constraints: Set pocket_binder and at least one valid line in pocket_contacts.
- No valid constraints found for type: Verify that inputs are not empty and correctly formatted for the selected constraint_type.
- Non-integer residue index: Ensure residue indices are integers without spaces (e.g., 'A,10' not 'A,10.0' or 'A,ten').