Skip to content
Boltz Boltz Boltz API Docs
Go to Boltz API
Guides
Design small molecules

Design small molecules

Generate novel small molecules against a protein target, monitor progress, fetch scored results, and stop early if needed.

Small molecule design generates novel molecules scored by binding confidence (likelihood of binding, for hit discovery), optimization score (binding strength ranking, for lead optimization), and structure confidence. Results stream in as they’re generated — you can fetch them before the run finishes and stop early if you’ve found what you need.

Results and artifacts

Section titled “Results and artifacts”

Design runs generate molecule results over time. As soon as a molecule is computed, you can read and download the result without waiting for the full design run to finish.

Each generated molecule result includes scoring metrics such as binding confidence, optimization score, and structure confidence. Each result also includes downloadable artifacts for the predicted bound structure and PAE.

Define a target

Section titled “Define a target”

Targets are protein-only entities. The engine automatically identifies the binding pocket to use during the run. You can provide hints to help it find the right one:

  • pocket_residues — If you already know the pocket residues, pass them directly as a map of chain ID to an array of 0-indexed residue indices.
  • reference_ligands — If you have known binders, pass them as an array of SMILES strings. The engine uses these to locate the pocket region.

You can provide one or both. Either will help the engine use the correct binding pocket, and providing both gives it the strongest signal.

{
  "target": {
    "entities": [
      { "type": "protein", "value": "MKTIIALSYIFCLVFA...", "chain_ids": ["A"] }
    ],
    "pocket_residues": {
      "A": [10, 11, 12, 35, 36, 37]
    }
  }
}

Chemical space

Section titled “Chemical space”

The chemical_space parameter controls the building blocks available for molecule generation. By default, design uses the enamine_real chemical space, which is constrained to commercially available and synthetically accessible building blocks. This ensures that generated molecules can actually be made in the lab — avoiding the common pitfall of generating computationally promising molecules that turn out to be impossible or prohibitively expensive to synthesize.

Contact contact@boltz.bio for access to other chemical spaces.

Molecular filters

Section titled “Molecular filters”

Filters control which generated molecules pass through to results. All custom filters use AND logic — a molecule must pass every filter.

Built-in filter

The boltz_smarts_catalog_filter_level parameter controls Boltz’s built-in structural alert filtering. Our medicinal chemistry team has curated these filters from extensive drug discovery experience, encoding patterns known to cause toxicity, reactivity, or poor pharmacokinetics.

LevelDescription
recommended (default)Balanced filtering that catches the most common problematic substructures.
extraStricter filtering with additional alerts.
aggressiveMost conservative — rejects anything with a known structural concern.
disabledNo built-in filtering.

Custom filters

Add any combination of these to the custom_filters array:

Filter typeWhat it does
lipinski_filterLipinski’s Rule of Five — set max_mw, max_logp, max_hbd, max_hba. Optional allow_single_violation.
rdkit_descriptor_filterRDKit descriptor ranges — mol_wt, mol_logp, tpsa, num_h_donors, num_h_acceptors, num_rotatable_bonds, num_heteroatoms, num_aromatic_rings, num_rings, fraction_csp3. Each accepts {min, max}.
smarts_custom_filterReject molecules matching any of the provided SMARTS patterns.
smarts_catalog_filterReject molecules matching a named catalog: PAINS, PAINS_A, PAINS_B, PAINS_C, BRENK, CHEMBL, CHEMBL_BMS, CHEMBL_Dundee, CHEMBL_Glaxo, CHEMBL_Inpharmatica, CHEMBL_LINT, CHEMBL_MLSMR, CHEMBL_SureChEMBL, NIH.
smiles_regex_filterReject molecules whose SMILES matches any of the provided regex patterns.

Run a design and download results

Section titled “Run a design and download results”

run_small_molecule_design() submits the design run, waits for generated molecules, downloads result archives, and returns a local run directory.

import os
from boltz_api import Boltz


client = Boltz(api_key=os.environ["BOLTZ_API_KEY"])


run_dir = client.experiments.run_small_molecule_design(
    target={
        "entities": [
            {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
        ],
        "pocket_residues": {"A": [10, 11, 12, 35, 36, 37]},
    },
    num_molecules=100,
    molecule_filters={
        "boltz_smarts_catalog_filter_level": "recommended",
        "custom_filters": [
            {
                "type": "lipinski_filter",
                "max_mw": 500,
                "max_logp": 5,
                "max_hbd": 5,
                "max_hba": 10,
            },
        ],
    },
    name="small-molecule-design",
)
print(run_dir)

The run directory contains the sanitized run record, resumable download state, a result manifest, and downloaded files for each generated molecule:

boltz-experiments/small-molecule-design/
  .boltz-run.json
  run.json
  results/
    index.jsonl
    sm_des_result_.../
      metadata.json
      archive.tar.gz
      files/
        result/
          metrics.json
          predicted_structure.cif
          pae.npz

Start now, download later

Section titled “Start now, download later”

The main run_small_molecule_design() example already waits and downloads. To submit now and download later, use start_small_molecule_design() and resume with wait_and_download().

run_dir = client.experiments.start_small_molecule_design(
    target={
        "entities": [
            {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
        ],
        "pocket_residues": {"A": [10, 11, 12, 35, 36, 37]},
    },
    num_molecules=100,
    name="submit-now-finish-later",
)


client.experiments.wait_and_download(run_dir=run_dir)

Inspect downloaded results

Section titled “Inspect downloaded results”

Result pages and artifact archives are already downloaded into the run directory.

print(run_dir)
for result_dir in (run_dir / "results").iterdir():
    print(result_dir)

Stop early

Section titled “Stop early”

If you’ve collected enough molecules, stop the run. The status transitions to stopped and no further molecules are generated. Results already produced remain available.

client.experiments.stop(run_dir=run_dir)

Metrics

Section titled “Metrics”
MetricRangeWhat it measures
binding_confidence0–1Likelihood of binding. Primary metric for hit discovery.
optimization_score—Binding strength ranking. Use for lead optimization.
structure_confidence0–1Overall confidence in the predicted structure.
iptm0–1Interface predicted TM-score.
ptm0–1Global predicted TM-score.
plddt0–1Per-residue structure confidence.
complex_plddt0–1pLDDT across the full complex.
complex_iplddt0–1Interface pLDDT for the complex.

Status values

Section titled “Status values”
StatusMeaning
pendingThe run is queued and has not started yet.
runningThe run is actively generating molecules. Results may already be available.
succeededThe run completed all requested molecules.
failedThe run encountered an error. Check the error field.
stoppedThe run was stopped early. Partial results are available.