Boltz Workflow: Protein-Ligand 101

About lab

Boltz Workflow: Protein-Ligand 101

Protein-Ligand 101 is the first curated BioSimulant Boltz workflow. It runs a single protein sequence and a single ligand SMILES through Boltz-2, then presents the predicted complex, affinity-style outputs, confidence metrics, run metadata, and report-ready caveats in the standard Biosimulant lab interface.

The workflow is designed for learning and early biological hypothesis generation. It is not experimental validation, a clinical prediction, or a replacement for docking review, MD/FEP, assay design, or wet-lab confirmation.

Workflow Status

This lab validates locally, exports as a portable .bsilab package, and has a successful pre-publication GPU-backed run. It is published on Biosimulant Hub and now uses a multi-stage Compose graph. The graph separates source-backed context, input assembly, Boltz-2 prediction, conservative interpretation, and visual reporting.

Publication checklist:

manifest validation passes: complete
strict package export passes: complete
entrypoints import successfully: complete
unit tests pass: complete
at least one real GPU run completes: complete
run results include structure, affinity, confidence, and metadata outputs: complete
screenshots/assets are captured from the real run: complete
Hub workflow card is public and points at the published lab id: complete

Pre-Publication Run Evidence

The current assets and metrics are derived from this private staged remote run:

run id: 9dd3dd34-97ba-42b9-8009-afdb61ef1d52
staged lab id: 60f6f549-0987-4862-9981-d2e84e6b98d3
staged lab commit: 59bc08432c3058c8e370bc8f5053f7ac255fad55d6325b2f9a0b67360169c561
remote size: GPU A10G
status: completed
duration: 496.8 seconds
credits settled: 45

Key outputs from the run:

affinity_probability_binary: 0.4089837670326233
affinity_pred_value: 2.592836618423462
confidence_score: 0.9358484148979187
complex_plddt: 0.9302065968513489
iptm: 0.9584157466888428
ligand_iptm: 0.9584157466888428

The first staged run completed but exposed an artifact persistence warning because the model emitted the raw remote prediction_dir path. The workflow copy of the runner was updated to emit prediction_dir_name instead, and the second staged run completed without that warning.

What This Workflow Does

The bundled example starts with:

a protein amino-acid sequence embedded in lab.yaml
a ligand SMILES string embedded in lab.yaml
Boltz-2 run options suitable for a small guided workflow example
MSA server usage enabled for the default example

When run, the workflow:

Builds a Boltz-2 request from the protein and ligand inputs.
Runs the Boltz-2 CLI on a GPU-backed runtime.
Parses the top-ranked structure artifact.
Parses affinity and confidence summaries.
Emits Biosimulant visuals and report-ready outputs.

Compose Workflow Graph

The published workflow is intentionally split into real BioSimulant modules:

protein_ligand_tutorial_context emits source-backed target, ligand, disease/use-case, provenance, and caveat context.
protein_ligand_setup resolves the public protein, ligand, MSA, and run-option inputs into the exact Boltz request.
boltz_boltz2_affinity_predictor runs the unchanged Boltz-2 scientific wrapper.
boltz_prediction_interpreter converts raw Boltz outputs into conservative evidence fields without adding new biological claims.
visualisation renders the 3D structure, confidence/affinity summaries, source context, request traceability, and Q/A caveat cards.

This makes the Compose view match the workflow promise while keeping Boltz-2 as the only predictive scientific model. The surrounding modules are provenance, request assembly, interpretation, and presentation stages.

Inputs

protein_sequence: amino-acid sequence for the target protein. If omitted, the bundled known example is used.
ligand_smiles: SMILES string for the ligand. If omitted, the bundled known example ligand is used.
msa_path: optional path to a precomputed .a3m MSA file.
run_options: optional record for workflow/runtime options.

The known example mode works because lab.yaml defines defaults directly on the Boltz runner model. A new user can click Run without knowing YAML, SMILES formatting details, or Boltz CLI arguments.

Outputs

structure_artifacts: paths to the predicted complex structure files, usually mmCIF.
affinity_summary: affinity-style outputs parsed from Boltz-2.
confidence_summary: model confidence outputs for the top-ranked prediction.
run_metadata: execution metadata, output paths, captured logs, and status.

The visualisation model turns these records into the standard Biosimulant run visuals, including a structure viewer and summary metrics.

Reading The Affinity Outputs

Boltz-2 distinguishes two affinity-oriented outputs that should not be collapsed into one meaning.

affinity_probability_binary is most useful as a binder-vs-decoy style signal. In product language, it is the binder probability. It is useful when comparing likely binders against unlikely binders under a hit-discovery framing.

affinity_pred_value is intended for ligand-optimization style use cases. In product language, it is an affinity-like value. It should be used cautiously and comparatively, not as a direct experimental measurement.

Both outputs are model predictions. They can help rank hypotheses for follow-up, but they do not prove binding, potency, selectivity, mechanism, or biological effect.

Reading The Structure

The structure viewer shows the predicted protein-ligand complex from the top-ranked Boltz output. Use it as a sanity check:

Is the ligand near a plausible pocket?
Is the interface confidence reasonable?
Does the pose look inconsistent with the score?
Are there warnings in run metadata?

A high binder probability with an implausible pose should be treated as suspicious. A plausible pose with weak confidence should also be treated as uncertain.

Safe Use Cases

Learn protein-ligand modeling workflows.
Compare known ligand examples.
Generate early hypotheses.
Prepare candidate lists for deeper review.
Create reproducible computational biology reports.
Teach structure-based drug-discovery concepts.

Do Not Claim

Validated drug discovery.
Clinical prediction.
Medical diagnosis.
Final compound selection.
Wet-lab replacement.
FEP replacement.
Experimentally guaranteed binding-affinity certainty.

Assets

The current screenshots were captured from the successful pre-publication GPU run above, using its persisted mmCIF structure artifact and parsed run metrics.

Boltz-2 predicted protein-ligand complex structure

Boltz-2 affinity and confidence summary metrics

Implementation Notes

This workflow intentionally reuses the existing Boltz-2 affinity predictor and visualisation modules. The product difference is in the lab packaging:

guided title and README
workflow tags
known example defaults
safe input names
report-oriented caveats
future Hub placement in the Boltz Workflows section

Batch ligand ranking should be implemented as a separate workflow rather than overloading this lab.

Guided Boltz-2 workflow for learning how a protein sequence and ligand SMILES become a predicted complex, binder probability, affinity-like value, confidence metrics, and reproducible report context.

Runtime

Duration0.01

Comms Step0.01

Settle Steps1

Runs

Total0

Completed0

Failed0

Metadata

Packageboltz-workflow-protein-ligand-101

Created2026-05-22

Updated2026-05-23

boltz-workflowboltzprotein-ligandaffinitystructural-biologyguided-workflowgpucontextprovenanceinput-assemblyinterpretationdockingvisualisationother

Manifest

{
  "io": {
    "inputs": [
      {
        "name": "protein_sequence",
        "label": "Target Protein Sequence",
        "maps_to": "protein_ligand_setup.protein_sequence",
        "description": "Amino-acid sequence for the curated teaching target; maps directly to the Boltz-2 protein input."
      },
      {
        "name": "ligand_smiles",
        "label": "Ligand SMILES",
        "maps_to": "protein_ligand_setup.ligand_smiles",
        "description": "SMILES string for the curated teaching ligand; maps directly to the Boltz-2 ligand input."
      },
      {
        "name": "msa_path",
        "label": "Precomputed MSA Path",
        "maps_to": "protein_ligand_setup.msa_path",
        "description": "Optional path to a precomputed MSA file; leave unset when the configured Boltz MSA server is used."
      },
      {
        "name": "run_options",
        "label": "Boltz Run Options",
        "maps_to": "protein_ligand_setup.run_options",
        "description": "Optional structured controls for the Boltz workflow, including sampling settings and interpretation scope."
      }
    ],
    "outputs": [
      {
        "name": "scenario_context",
        "label": "Workflow Scenario Context",
        "maps_to": "protein_ligand_tutorial_context.scenario_context",
        "description": "Source-backed target, ligand, use-case, provenance, and caveat context for this Boltz workflow."
      },
      {
        "name": "assembled_boltz_request",
        "label": "Assembled Boltz Request",
        "maps_to": "protein_ligand_setup.assembled_boltz_request",
        "description": "Traceable summary of the protein, ligand, MSA, and run options prepared for Boltz."
      },
      {
        "name": "affinity_summary",
        "label": "Affinity-Style Summary",
        "maps_to": "boltz_boltz2_affinity_predictor.affinity_summary",
        "description": "Parsed Boltz-2 binder probability and affinity-like outputs for this protein-ligand prediction."
      },
      {
        "name": "confidence_summary",
        "label": "Structure Confidence Summary",
        "maps_to": "boltz_boltz2_affinity_predictor.confidence_summary",
        "description": "Parsed Boltz-2 confidence outputs for the predicted protein-ligand complex."
      },
      {
        "name": "structure_artifacts",
        "label": "Predicted Complex Structure Artifacts",
        "maps_to": "boltz_boltz2_affinity_predictor.structure_artifacts",
        "description": "File-backed predicted complex structures used by the 3D visualisation."
      },
      {
        "name": "run_metadata",
        "label": "Boltz Run Metadata",
        "maps_to": "boltz_boltz2_affinity_predictor.run_metadata",
        "description": "Runtime status, command metadata, logs, and caveats for the latest Boltz invocation."
      },
      {
        "name": "prediction_evidence",
        "label": "Conservative Prediction Evidence",
        "maps_to": "boltz_prediction_interpreter.prediction_evidence",
        "description": "Interpreted Boltz output evidence with request traceability and explicit scientific caveats."
      }
    ]
  },
  "tags": [
    "boltz-workflow",
    "boltz",
    "protein-ligand",
    "affinity",
    "structural-biology",
    "guided-workflow",
    "gpu"
  ],
  "title": "Boltz Workflow: Protein-Ligand 101",
  "models": [
    {
      "path": "owned/models/protein_ligand_tutorial_context",
      "alias": "protein_ligand_tutorial_context",
      "parameters": {
        "scenario": {
          "caveat": "Boltz-2 outputs are computational structure and affinity-style predictions for hypothesis generation; they are not experimental binding, potency, selectivity, clinical, or efficacy evidence.",
          "ligand_role": "teaching ligand",
          "disease_area": "training workflow",
          "target_family": "teaching protein-ligand example",
          "workflow_name": "Protein-Ligand 101",
          "workflow_context": "Guided single protein-ligand Boltz-2 example",
          "workflow_question": "How does a source-backed protein sequence and ligand SMILES become a Boltz-2 complex prediction?",
          "interpretation_scope": "Learning and early hypothesis generation only",
          "protein_sequence_length": 384
        },
        "integration_step": 0.01
      },
      "provenance": {
        "owned_path": "owned/models/protein_ligand_tutorial_context"
      }
    },
    {
      "path": "owned/models/protein_ligand_setup",
      "alias": "protein_ligand_setup",
      "parameters": {
        "workflow_kind": "single",
        "workflow_name": "Protein-Ligand 101",
        "integration_step": 0.01,
        "default_run_options": {
          "workflow_name": "Protein-Ligand 101",
          "workflow_context": "Guided single protein-ligand Boltz-2 example",
          "interpretation_scope": "Learning and early hypothesis generation only"
        },
        "default_ligand_smiles": "N[C@@H](Cc1ccc(O)cc1)C(=O)O",
        "default_protein_sequence": "MVTPEGNVSLVDESLLVGVTDEDRAVRSAHQFYERLIGLWAPAVMEAAHELGVFAALAEAPADSGELARRLDCDARAMRVLLDALYAYDVIDRIHDTNGFRYLLSAEARECLLPGTLFSLVGKFMHDINVAWPAWRNLAEVVRHGARDTSGAESPNGIAQEDYESLVGGINFWAPPIVTTLSRKLRASGRSGDATASVLDVGCGTGLYSQLLLREFPRWTATGLDVERIATLANAQALRLGVEERFATRAGDFWRGGWGTGYDLVLFANIFHLQTPASAVRLMRHAAACLAPDGLVAVVDQIVDADREPKTPQDRFALLFAASMTNTGGGDAYTFQEYEEWFTAAGLQRIETLDTPMHRILLARRATEPSAVPEGQASENLYFQ"
      },
      "provenance": {
        "owned_path": "owned/models/protein_ligand_setup"
      }
    },
    {
      "path": "owned/models/boltz_boltz2_affinity_predictor",
      "alias": "boltz_boltz2_affinity_predictor",
      "parameters": {
        "override": true,
        "accelerator": "gpu",
        "runtime_mode": "managed",
        "output_format": "mmcif",
        "sampling_steps": 200,
        "use_msa_server": true,
        "recycling_steps": 3,
        "diffusion_samples": 1
      },
      "provenance": {
        "owned_path": "owned/models/boltz_boltz2_affinity_predictor"
      }
    },
    {
      "path": "owned/models/boltz_prediction_interpreter",
      "alias": "boltz_prediction_interpreter",
      "parameters": {
        "mode": "single",
        "caveat": "Boltz-2 outputs are computational structure and affinity-style predictions for hypothesis generation; they are not experimental binding, potency, selectivity, clinical, or efficacy evidence.",
        "core_alias": "boltz_boltz2_affinity_predictor",
        "workflow_name": "Protein-Ligand 101",
        "integration_step": 0.01
      },
      "provenance": {
        "owned_path": "owned/models/boltz_prediction_interpreter"
      }
    },
    {
      "path": "owned/models/visualisation",
      "alias": "visualisation",
      "parameters": {
        "mode": "boltz",
        "lab_title": "Boltz Workflow: Protein-Ligand 101",
        "source_alias": "boltz_boltz2_affinity_predictor",
        "context_alias": "protein_ligand_tutorial_context",
        "assembler_alias": "protein_ligand_setup",
        "integration_step": 0.01,
        "interpreter_alias": "boltz_prediction_interpreter"
      },
      "provenance": {
        "owned_path": "owned/models/visualisation"
      }
    }
  ],
  "wiring": [
    {
      "to": [
        "protein_ligand_setup.scenario_context",
        "boltz_prediction_interpreter.scenario_context",
        "visualisation.protein_ligand_tutorial_context_scenario_context"
      ],
      "from": "protein_ligand_tutorial_context.scenario_context"
    },
    {
      "to": [
        "boltz_boltz2_affinity_predictor.protein_sequence"
      ],
      "from": "protein_ligand_setup.protein_sequence"
    },
    {
      "to": [
        "boltz_boltz2_affinity_predictor.ligand_smiles"
      ],
      "from": "protein_ligand_setup.ligand_smiles"
    },
    {
      "to": [
        "boltz_boltz2_affinity_predictor.msa_path"
      ],
      "from": "protein_ligand_setup.msa_path"
    },
    {
      "to": [
        "boltz_boltz2_affinity_predictor.run_options"
      ],
      "from": "protein_ligand_setup.run_options"
    },
    {
      "to": [
        "boltz_prediction_interpreter.assembled_boltz_request",
        "visualisation.protein_ligand_setup_assembled_boltz_request"
      ],
      "from": "protein_ligand_setup.assembled_boltz_request"
    },
    {
      "to": [
        "visualisation.boltz_boltz2_affinity_predictor_affinity_summary",
        "boltz_prediction_interpreter.boltz_boltz2_affinity_predictor_affinity_summary"
      ],
      "from": "boltz_boltz2_affinity_predictor.affinity_summary"
    },
    {
      "to": [
        "visualisation.boltz_boltz2_affinity_predictor_confidence_summary",
        "boltz_prediction_interpreter.boltz_boltz2_affinity_predictor_confidence_summary"
      ],
      "from": "boltz_boltz2_affinity_predictor.confidence_summary"
    },
    {
      "to": [
        "visualisation.boltz_boltz2_affinity_predictor_structure_artifacts",
        "boltz_prediction_interpreter.boltz_boltz2_affinity_predictor_structure_artifacts"
      ],
      "from": "boltz_boltz2_affinity_predictor.structure_artifacts"
    },
    {
      "to": [
        "visualisation.boltz_boltz2_affinity_predictor_run_metadata",
        "boltz_prediction_interpreter.boltz_boltz2_affinity_predictor_run_metadata"
      ],
      "from": "boltz_boltz2_affinity_predictor.run_metadata"
    },
    {
      "to": [
        "visualisation.boltz_prediction_interpreter_prediction_evidence"
      ],
      "from": "boltz_prediction_interpreter.prediction_evidence"
    }
  ],
  "runtime": {
    "duration": 0.01,
    "settle_steps": 1,
    "initial_inputs": {},
    "communication_step": 0.01
  },
  "description": "Guided Boltz-2 workflow for learning how a protein sequence and ligand SMILES become a predicted complex, binder probability, affinity-like value, confidence metrics, and reproducible report context.",
  "schema_version": "2.0"
}

Select a run from History to view its results.