From Boltz to DiffDock to SBML: designing a composable workflow
A practical pattern for turning structure prediction, docking, and pathway dynamics into an inspectable lab without hiding the seams between models.
On this page
Structure prediction, molecular docking, and pathway simulation answer different questions. Boltz can predict a protein–ligand complex and affinity-related outputs. DiffDock samples ligand poses against a receptor and ranks them by confidence. An SBML model advances biochemical dynamics over time.
Putting those tools in one workflow is useful, but only if the handoffs remain scientifically legible. A file produced by one stage is not automatically a valid biological input to the next.
This tutorial presents the composition pattern rather than claiming that three independent models share a ready-made schema.
Start with the outputs you need to inspect
Begin at the end. Decide which outputs should survive the run and be available for review:
| Stage | Inspectable outputs |
|---|---|
| Boltz-2 | Predicted complex, binding probability, pIC50, run metadata |
| DiffDock-L | Ranked poses, confidence values, SDF artifacts, top complex |
| SBML | Time-series observables, final state, solver metadata |
This list immediately separates scalar signals from durable artifacts. A confidence score can travel through a typed scalar port. A predicted complex should remain a versioned file artifact. A time series may be a structured signal during execution and a CSV or plot after the run.
Run the structure and docking stages independently
The Biosimulant examples package the upstream tools with pinned versions and explicit inputs.
The Boltz-2 affinity lab accepts a protein amino-acid sequence and ligand SMILES. It returns a predicted complex together with binding probability and pIC50. The managed version uses a GPU-enabled runtime; local execution requires a suitable CUDA device.
The DiffDock-L lab accepts a receptor PDB plus a ligand SMILES or supported ligand file. It produces diffusion-sampled poses ranked by a confidence score. The score is useful for ranking outputs from the model, not as a universal measure of physical binding affinity.
Run and inspect these stages separately before wiring them into a larger lab. That gives each model a known-good baseline and makes later failures easier to localize.
sequence + ligand ──▶ Boltz-2 ──▶ predicted complex + affinity outputs
receptor + ligand ──▶ DiffDock ──▶ ranked poses + confidence outputsDefine the scientific adapter
The difficult step is not connecting two filenames. It is deciding how a structural result should influence the dynamic pathway model.
An adapter module should make that decision explicit. Depending on the study, it might:
- select a pose according to a declared ranking policy;
- convert a predicted affinity into a bounded parameter proposal;
- map a ligand or target identifier to an SBML species or reaction;
- reject results that do not meet a confidence or quality threshold;
- retain the original structural artifact alongside the derived parameter.
class StructureToKinetics(biosim.BioModule):
"""Study-specific mapping, reviewed like any other model."""
def inputs(self):
return {
"binding_probability": biosim.SignalSpec.scalar(unit="1"),
"predicted_pic50": biosim.SignalSpec.scalar(unit="1"),
}
def outputs(self):
return {
"inhibition_fraction": biosim.SignalSpec.scalar(unit="1"),
}The mapping inside this module is part of the scientific hypothesis. It should not be buried in a workflow runner or assumed by the runtime.
Wrap the SBML model as a module
Biosimulant can wrap a Tellurium-backed SBML model behind the same BioModule
contract. The wrapper owns model loading, parameter updates, time advancement,
and observable extraction.
The lab can then wire the adapter’s bounded output into a named SBML input:
world:
models:
structure_to_kinetics:
model: local/structure-to-kinetics@0.1.0
pathway:
model: local/sbml-pathway@1.0.0
wiring:
- source: structure_to_kinetics.outputs.inhibition_fraction
target: pathway.inputs.inhibition_fraction
runtime:
communication_step: 1.0The package references above are illustrative. The important pieces are the version pins, named ports, units, and explicit wiring.
Preserve provenance across the workflow
For every stage, retain both the model-native output and the derived value used downstream. A reviewable run should answer:
- Which sequence, receptor, and ligand inputs were used?
- Which Boltz, DiffDock, and SBML package versions resolved?
- Which structural artifact was selected, and by what rule?
- Which adapter version transformed the prediction?
- Which SBML parameter changed?
- Which compute profile, seed, and runtime produced the run?
This makes the graph auditable. If the pathway response changes after a model upgrade, the result can be traced to a new structural prediction, a different selection, a changed adapter, or the dynamic model itself.
Treat the first composition as an experiment
The first useful lab should be deliberately small:
- one pinned Boltz or DiffDock input fixture;
- one adapter with bounded, tested behavior;
- one SBML parameter influenced by the adapter;
- one baseline run with the adapter disabled;
- one comparison that exposes both structure-stage and pathway-stage outputs.
Only after that path is inspectable should the workflow expand to pose ensembles, parameter sweeps, or alternative pathway models.
Composition earns trust by preserving seams, not by hiding them.
