Pipeline Architecture¶

Overview¶

The nf-proteindesign pipeline processes design YAML specifications through Boltzgen with a comprehensive suite of optional analysis modules for sequence optimization, structure validation, and quality assessment.

Complete Pipeline Flow¶

flowchart TD
    A[Input Samplesheet<br/>with Design YAMLs] --> B{Check Boltzgen<br/>Output Dir}

    B -->|Null| C[Run Boltzgen Design<br/>GPU Process]
    B -->|Provided| D[Stage Precomputed<br/>Boltzgen Results]

    C --> E[Budget Designs<br/>CIF + NPZ Files]
    D --> E

    E --> F{ProteinMPNN<br/>Enabled?}
    F -->|No| Z1[Output Boltzgen<br/>Designs Only]

    F -->|Yes| G[Convert CIF to PDB<br/>Per Design]
    G --> H[ProteinMPNN Optimize<br/>Parallel per Budget Design<br/>GPU Process]

    H --> I[Optimized Sequences<br/>FASTA + Scores]

    I --> J{Boltz-2 Refold<br/>Enabled?}
    J -->|No| Z2[Output MPNN<br/>Sequences Only]

    J -->|Yes| K[Prepare Boltz-2 Input<br/>Split MPNN FASTA<br/>Process Target FASTA]

    K --> L[Boltz-2 Structure Prediction<br/>Parallel per Sequence<br/>GPU Process]

    L --> M[Boltz-2 Outputs<br/>CIF + Confidence JSON<br/>+ PAE NPZ]

    M --> N{Analysis<br/>Modules<br/>Enabled?}

    N -->|IPSAE| O[IPSAE Calculate<br/>Interface Scoring<br/>GPU Process]
    N -->|PRODIGY| P[PRODIGY Predict<br/>Binding Affinity<br/>CPU Process]
    N -->|Foldseek| Q[Foldseek Search<br/>Structural Similarity<br/>GPU Process]

    O --> R[IPSAE Scores<br/>TXT + ByRes]
    P --> S[PRODIGY Results<br/>TXT Files]
    Q --> T[Foldseek Results<br/>TSV + Summary]

    R --> U{Consolidation<br/>Enabled?}
    S --> U
    T --> U

    U -->|Yes| V[Consolidate Metrics<br/>Combine All Results<br/>CPU Process]

    V --> W[Unified Report<br/>CSV + HTML + MD]

    W --> X[Final Output]
    M --> X
    Z1 --> X
    Z2 --> X

    style C fill:#9C27B0,color:#fff,stroke:#9C27B0,stroke-width:3px
    style H fill:#8E24AA,color:#fff,stroke:#8E24AA,stroke-width:3px
    style L fill:#7B1FA2,color:#fff,stroke:#7B1FA2,stroke-width:3px
    style V fill:#6A1B9A,color:#fff,stroke:#6A1B9A,stroke-width:3px

    classDef gpuProcess fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px
    classDef cpuProcess fill:#F3E5F5,stroke:#9C27B0,stroke-width:1px
    classDef dataNode fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px

    class C,H,L,O,Q gpuProcess
    class G,K,P,V cpuProcess
    class E,I,M,R,S,T,W dataNode

Key Components¶

1. Core Design Module¶

Boltzgen generates protein designs from YAML specifications:

process BOLTZGEN_RUN {
    label 'gpu'

    input:
    tuple val(meta), path(design_yaml), path(structure_files)
    path cache_dir

    output:
    tuple val(meta), path("${meta.id}_output"), emit: results
    tuple val(meta), path("${meta.id}_output/intermediate_designs_inverse_folded/refold_cif/*.cif"), emit: budget_design_cifs
    tuple val(meta), path("${meta.id}_output/intermediate_designs_inverse_folded/refold_confidence/*.npz"), emit: budget_design_npz

    script:
    """
    boltzgen design \\
        --design_file ${design_yaml} \\
        --output_dir ${meta.id}_output \\
        --num_designs ${meta.num_designs} \\
        --budget ${meta.budget}
    """
}

2. ProteinMPNN Sequence Optimization¶

Optimizes sequences for designed structures:

workflow {
    if (params.run_proteinmpnn) {
        CONVERT_CIF_TO_PDB(budget_designs)
        PROTEINMPNN_OPTIMIZE(pdb_files)

        if (params.run_boltz2_refold) {
            EXTRACT_TARGET_SEQUENCES(boltzgen_structures)
            PROTENIX_REFOLD(mpnn_sequences, target_sequences)
            CONVERT_PROTENIX_TO_NPZ(boltz2_outputs)
        }
    }
}

3. Parallel Analysis Modules¶

Multiple analyses run simultaneously:

workflow {
    // All analyses run in parallel on budget designs
    if (params.run_ipsae) {
        IPSAE_CALCULATE(boltzgen_cifs, boltzgen_npz)
        if (boltz2_enabled) {
            IPSAE_CALCULATE(boltz2_cifs, boltz2_npz)
        }
    }

    if (params.run_prodigy) {
        PRODIGY_PREDICT(all_cif_files)
    }

    if (params.run_foldseek) {
        FOLDSEEK_SEARCH(all_cif_files, database)
    }

    if (params.run_consolidation) {
        CONSOLIDATE_METRICS(all_results)
    }
}

Process Organization¶

Core Processes¶

Resource Labels¶

process {
    withLabel: cpu {
        cpus = 4
        memory = 16.GB
    }

    withLabel: gpu {
        cpus = 8
        memory = 32.GB
        clusterOptions = '--gres=gpu:1'
    }
}

Module Structure¶

main.nf                              # Main entry point with input parsing
workflows/
└── protein_design.nf                # Main workflow orchestration

modules/local/
├── boltzgen_run.nf                  # Boltzgen design generation (GPU)
├── convert_cif_to_pdb.nf            # CIF to PDB conversion
├── proteinmpnn_optimize.nf          # ProteinMPNN sequence optimization (GPU)
├── prepare_boltz2_sequences.nf      # Split MPNN FASTA + process target
├── boltz2_refold.nf                 # Boltz-2 structure prediction (GPU)
├── ipsae_calculate.nf               # ipSAE interface scoring (GPU, Boltz-2 only)
├── prodigy_predict.nf               # PRODIGY binding affinity (CPU, Boltz-2 only)
├── foldseek_search.nf               # Foldseek structural search (GPU, Boltz-2 only)
└── consolidate_metrics.nf           # Metrics consolidation (CPU)

assets/
├── schema_input_design.json         # Samplesheet validation schema
├── ipsae.py                         # ipSAE calculation script
├── parse_prodigy_output.py          # PRODIGY parser script
├── consolidate_design_metrics.py    # Consolidation script
├── NO_MSA                           # Placeholder for missing MSA
└── NO_TEMPLATE                      # Placeholder for missing template

Configuration¶

Profile System¶

profiles {
    docker {
        docker.enabled = true
        docker.runOptions = '--gpus all'
    }

    test {
        includeConfig 'conf/test.config'
    }
}

Resource Management¶

params {
    max_cpus = 16
    max_memory = 128.GB
    max_time = 48.h
}

Execution Flow¶

1. Initialization¶

• Parse samplesheet with design YAMLs
• Validate inputs and structure files
• Create input channels

2. Design Generation¶

• Parallel Boltzgen design runs
• Generate budget designs (CIF + NPZ)
• GPU-accelerated diffusion sampling

3. Sequence Optimization (Optional)¶

• Convert CIF to PDB format
• ProteinMPNN sequence optimization
• Boltz-2 structure prediction
• Convert Boltz-2 JSON to NPZ

4. Parallel Analysis (Optional)¶

• ipSAE: Interface quality scoring (Boltzgen + Boltz-2)
• PRODIGY: Binding affinity prediction (all structures)
• Foldseek: Structural similarity search (all structures)

5. Consolidation (Optional)¶

• Collect all analysis metrics
• Generate unified CSV report
• Create markdown summary

Performance Characteristics¶

Parallelization¶

Samples:    Parallel across all samples
Designs:    Parallel within each sample
GPU:        One design per GPU at a time

Scaling¶

Development¶

Adding New Modules¶

// modules/new_tool/main.nf
process NEW_TOOL {
    label 'cpu'

    input:
    tuple val(sample), path(input_file)

    output:
    tuple val(sample), path("output/*")

    script:
    """
    new_tool --input ${input_file} --output output/
    """
}

Further Reading¶

• Implementation Details
• Nextflow Documentation
• DSL2 Guide