Protein Design · Sequence prediction
LigandMPNN API
Protein sequence prediction, to conform with backbone coordinates. Takes external molecules into account; to some degree a superset of ProteinMPNN, but is a different model. A useful step after RFDiffusion in a protein design pipeline, and before validation with structure prediction.
A deep learning-based protein sequence design method that explicitly models all non-protein components of biomolecular systems. LigandMPNN generates not only sequences but also sidechain conformations to allow detailed evaluation of binding interactions. Experimental characterization demonstrates that LigandMPNN can generate small molecule and DNA-binding proteins with high affinity and specificity. It allows explicit modeling of small molecule, nucleotide, metal, and other atomic contexts.
Example presets
Send {"preset": "default"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.
| preset | Description |
|---|---|
default | Official README example; input files are bundled with the catalog. Source ↗ |
temperature | Official README example; input files are bundled with the catalog. Source ↗ |
random_seed | Official README example; input files are bundled with the catalog. Source ↗ |
verbose | Official README example; input files are bundled with the catalog. Source ↗ |
save_stats | Official README example; input files are bundled with the catalog. Source ↗ |
fix_residues | Official README example; input files are bundled with the catalog. Source ↗ |
redesign_residues | Official README example; input files are bundled with the catalog. Source ↗ |
batch_size | Official README example; input files are bundled with the catalog. Source ↗ |
global_bias | Official README example; input files are bundled with the catalog. Source ↗ |
per_residue_bias | Official README example; input files are bundled with the catalog. Source ↗ |
global_omit | Official README example; input files are bundled with the catalog. Source ↗ |
per_residue_omit | Official README example; input files are bundled with the catalog. Source ↗ |
symmetry | Official README example; input files are bundled with the catalog. Source ↗ |
homooligomer | Official README example; input files are bundled with the catalog. Source ↗ |
file_ending | Official README example; input files are bundled with the catalog. Source ↗ |
zero_indexed | Official README example; input files are bundled with the catalog. Source ↗ |
chains_to_design | Official README example; input files are bundled with the catalog. Source ↗ |
parse_these_chains_only | Official README example; input files are bundled with the catalog. Source ↗ |
ligandmpnn_default | Official README example; input files are bundled with the catalog. Source ↗ |
ligandmpnn_v_32_005_25 | Official README example; input files are bundled with the catalog. Source ↗ |
ligandmpnn_no_context | Official README example; input files are bundled with the catalog. Source ↗ |
ligandmpnn_use_side_chain_atoms | Official README example; input files are bundled with the catalog. Source ↗ |
soluble_mpnn_default | Official README example; input files are bundled with the catalog. Source ↗ |
global_label_membrane_mpnn_0 | Official README example; input files are bundled with the catalog. Source ↗ |
per_residue_label_membrane_mpnn_default | Official README example; input files are bundled with the catalog. Source ↗ |
fasta_seq_separation | Official README example; input files are bundled with the catalog. Source ↗ |
pdb_path_multi | Official README example; input files are bundled with the catalog. Source ↗ |
fixed_residues_multi | Official README example; input files are bundled with the catalog. Source ↗ |
redesigned_residues_multi | Official README example; input files are bundled with the catalog. Source ↗ |
omit_AA_per_residue_multi | Official README example; input files are bundled with the catalog. Source ↗ |
bias_AA_per_residue_multi | Official README example; input files are bundled with the catalog. Source ↗ |
ligand_mpnn_cutoff_for_score | Official README example; input files are bundled with the catalog. Source ↗ |
insertion_code | Official README example; input files are bundled with the catalog. Source ↗ |
parse_atoms_with_zero_occupancy | Official README example; input files are bundled with the catalog. Source ↗ |
autoregressive_score_w_seq | Official scoring example using the bundled upstream output backbone, so a prior design run is not required. Source ↗ |
autoregressive_score_wo_seq | Official scoring example using the bundled upstream output backbone, so a prior design run is not required. Source ↗ |
single_aa_score_w_seq | Official scoring example using the bundled upstream output backbone, so a prior design run is not required. Source ↗ |
single_aa_score_wo_seq | Official scoring example using the bundled upstream output backbone, so a prior design run is not required. Source ↗ |
sc_default_fast | Official fast-packing example corrected to request 1 pack: current run.py performs zero packs for the README value 0. Source ↗ |
sc_default | Official README example; input files are bundled with the catalog. Source ↗ |
sc_fixed_residues | Official README example; input files are bundled with the catalog. Source ↗ |
sc_fixed_residues_full_repack | Official README example; input files are bundled with the catalog. Source ↗ |
sc_no_context | Official README example; input files are bundled with the catalog. Source ↗ |
Tasks
Pick a mode with task
Fields belonging to another task are ignored, so send only the ones for the task you chose.
| task | Mode |
|---|---|
design default |
Design sequences |
autoregressive_score |
Autoregressive scores |
single_aa_score |
Single-residue scores |
These local CLI options are not applicable to Bio Web and are omitted from its inputs:
out_folder: The service creates a separate output directory for each job and archives the results.checkpoint_path_sc: Side-chain packing uses the installed official ligandmpnn_sc_v_32_002_16.pt checkpoint.
Request body
Fields
The same names the web form posts. See the field type table for what each kind means over HTTP.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
job_name
|
string text | no | ligandmpnn-demo |
Job name A label for this run and its results. |
pdb_path
|
string file | no | — |
Structure (PDB) Upload a protein or protein–ligand PDB, or choose a bundled official example. Required unless multiple structures are supplied. In this form: PDB contents are mapped to --pdb_path. Preserve HETATM records for ligand, nucleotide and metal context. This upstream parser reads PDB, not mmCIF. file types .pdb,.ent. |
pdb_path_multi
|
string textarea | no | — |
Multiple structures (JSON) Object mapping unique names to PDB contents or bundled references. Leave the single-structure field blank. In this form: Example: {"first": "bio-tools://ligandmpnn/inputs/1BC8.pdb", "second": "bio-tools://ligandmpnn/inputs/4GYT.pdb"}. The service creates a native --pdb_path_multi file with job-local paths; server paths are not accepted. |
chains_to_design
|
string text | no | — |
Chains to design or score Comma-separated chain IDs, e.g. A,B. Other chains remain fixed context. Blank selects all parsed protein chains. |
parse_these_chains_only
|
string text | no | — |
Parse only these chains Comma-separated chain IDs. Excludes every other chain, including its ligand atoms, from parsing and output; blank keeps all chains. |
parse_atoms_with_zero_occupancy
|
boolean checkbox | no | false |
Include atoms with zero occupancy Upstream normally discards atoms whose occupancy is zero. |
model_type
|
string select | no | protein_mpnn |
Model
The upstream default is ProteinMPNN. Select LigandMPNN to condition sequence design or scoring on non-protein atoms.
One of:
protein_mpnn, ligand_mpnn, soluble_mpnn, per_residue_label_membrane_mpnn, global_label_membrane_mpnn.
|
checkpoint_protein_mpnn
|
string select | no | proteinmpnn_v_48_020.pt |
ProteinMPNN checkpoint
Official checkpoint filename in the configured model directory. Noise is the training backbone noise in angstroms.
One of:
proteinmpnn_v_48_002.pt, proteinmpnn_v_48_010.pt, proteinmpnn_v_48_020.pt, proteinmpnn_v_48_030.pt.
|
checkpoint_ligand_mpnn
|
string select | no | ligandmpnn_v_32_010_25.pt |
LigandMPNN checkpoint
Official checkpoint filename in the configured model directory. Noise is the training backbone noise in angstroms.
One of:
ligandmpnn_v_32_005_25.pt, ligandmpnn_v_32_010_25.pt, ligandmpnn_v_32_020_25.pt, ligandmpnn_v_32_030_25.pt.
|
checkpoint_soluble_mpnn
|
string select | no | solublempnn_v_48_020.pt |
SolubleMPNN checkpoint
Official checkpoint filename in the configured model directory. Noise is the training backbone noise in angstroms.
One of:
solublempnn_v_48_002.pt, solublempnn_v_48_010.pt, solublempnn_v_48_020.pt, solublempnn_v_48_030.pt.
|
checkpoint_per_residue_label_membrane_mpnn
|
string select | no | per_residue_label_membrane_mpnn_v_48_020.pt |
Membrane: per-residue labels checkpoint
Official checkpoint filename in the configured model directory. Noise is the training backbone noise in angstroms.
One of:
per_residue_label_membrane_mpnn_v_48_020.pt.
|
checkpoint_global_label_membrane_mpnn
|
string select | no | global_label_membrane_mpnn_v_48_020.pt |
Membrane: global label checkpoint
Official checkpoint filename in the configured model directory. Noise is the training backbone noise in angstroms.
One of:
global_label_membrane_mpnn_v_48_020.pt.
|
batch_size
|
number number | no | 1 |
Batch size Samples evaluated together; reduce to 1 for a small CPU run. minimum 1, maximum 1000, step 1. |
number_of_batches
|
number number | no | 1 |
Number of batches Total samples = batch size × number of batches. For scoring, upstream recommends at least 10 batches to average decoding-order effects. minimum 1, maximum 100, step 1. |
temperature
design
|
number number | no | 0.1 |
Sampling temperature Positive temperature; higher values give more sequence diversity. minimum 1e-06. |
seed
|
number number | no | 0 |
Random seed Zero chooses a random seed. A nonzero seed is reproducible within the same runtime. minimum 0, maximum 2147483647, step 1. |
use_sequence
autoregressive_score
single_aa_score
|
boolean checkbox | no | true |
Condition scores on sequence Use the sequence in the PDB as well as the backbone. Disable for backbone-only probabilities. Scoring writes a .pt dictionary of per-residue probabilities and statistics. |
fixed_residues
|
string text | no | — |
Fixed residues Space-separated PDB residue IDs, e.g. C1 C2 C3. These residues retain their input amino acids. In this form: Uses chain + author residue number + optional insertion code, e.g. B82A. Unlike original ProteinMPNN, numbering gaps are not filled with X. |
fixed_residues_multi
|
string textarea | no | — |
Fixed residues per structure (JSON) Object keyed by the names in pdb_path_multi, with a space-separated residue list per structure. Overrides the common list for that structure. |
redesigned_residues
|
string text | no | — |
Redesign only these residues Space-separated PDB residue IDs; every other residue is fixed. Choose this or fixed_residues. In this form: Uses chain + author residue number + optional insertion code, e.g. B82A. Unlike original ProteinMPNN, numbering gaps are not filled with X. |
redesigned_residues_multi
|
string textarea | no | — |
Redesign only these residues per structure (JSON) Object keyed by the names in pdb_path_multi, with a space-separated residue list per structure. Overrides the common list for that structure. |
symmetry_residues
|
string text | no | — |
Tied residue groups Comma-separated residues within each group, | between groups: C1,C2,C3|C4,C5|C6,C7. Groups cannot overlap. |
symmetry_weights
design
|
string text | no | — |
Tied residue weights Matching weights for every group: 0.33,0.33,0.33|0.5,0.5|0.5,0.5. Required with explicit design symmetry; finite negative weights are supported. |
homo_oligomer
|
boolean checkbox | no | false |
Tie all parsed protein chains Upstream ties matching PDB residue numbers and insertion codes across ALL parsed chains with equal weights. Chains must have identical residue IDs. Use parse-only chains to restrict the assembly. |
bias_AA
design
|
string text | no | — |
Global amino-acid bias Comma-separated AA:value pairs, e.g. W:3.0,P:3.0,C:3.0,A:-3.0. Positive values favor an amino acid. |
omit_AA
design
|
string text | no | — |
Globally omitted amino acids One-letter codes to exclude, e.g. CDFGHILMNPQRSTVWY leaves A, E and K. LigandMPNN samples the 20 standard amino acids. |
bias_AA_per_residue
design
|
string textarea | no | — |
Per-residue amino-acid bias JSON keyed by PDB residue IDs, e.g. {"C1": {"G": -0.3, "P": 10.8}}. |
bias_AA_per_residue_multi
design
|
string textarea | no | — |
Per-residue amino-acid bias per structure JSON keyed by pdb_path_multi names; each value is a per-residue object. Overrides common guidance for that structure. |
omit_AA_per_residue
design
|
string textarea | no | — |
Per-residue amino-acid exclusions JSON keyed by PDB residue IDs, e.g. {"C1": "ACDEFGHIKLMNPQRSTVW"} leaves Y at C1. |
omit_AA_per_residue_multi
design
|
string textarea | no | — |
Per-residue amino-acid exclusions per structure JSON keyed by pdb_path_multi names; each value is a per-residue object. Overrides common guidance for that structure. |
ligand_mpnn_use_atom_context
|
boolean checkbox | no | true |
Use ligand atom context LigandMPNN only: condition on nearby non-protein atoms, including small molecules, nucleotides and metals. |
ligand_mpnn_use_side_chain_context
|
boolean checkbox | no | false |
Use fixed side chains as context LigandMPNN only: use side-chain atoms of fixed residues as additional context. |
ligand_mpnn_cutoff_for_score
|
number number | no | 8.0 |
Ligand score cutoff (Å) Selects residues near context atoms for the reported ligand confidence. It does not set the model’s atom-context neighborhood. minimum 1e-06. |
transmembrane_buried
|
string text | no | — |
Buried membrane residues Per-residue membrane model only: space-separated PDB residue IDs, e.g. C1 C2 C3 C11. Class 2 (hydrophobic). |
transmembrane_interface
|
string text | no | — |
Membrane interface residues Per-residue membrane model only: e.g. C4 C5 C6 C22. Class 1 (polar); unlisted residues are class 0. Lists must not overlap. |
global_transmembrane_label
|
string select | no | 0 |
Global membrane label
Global membrane model only: 0 = soluble, 1 = transmembrane.
One of:
0, 1.
|
pack_side_chains
design
|
boolean checkbox | no | false |
Pack designed side chains Run the official side-chain packing model after sequence design. |
number_of_packs_per_design
design
|
number number | no | 4 |
Packs per sequence Independent packed structures per generated sequence. Use 1 for one pack; upstream run.py produces no packed files at 0 despite the README’s fast-example text. minimum 1, maximum 32, step 1. |
sc_num_denoising_steps
design
|
number number | no | 3 |
Packing denoising steps Number of recycling/denoising steps per pack. minimum 1, maximum 100, step 1. |
sc_num_samples
design
|
number number | no | 16 |
Packing mixture samples Samples drawn from each mixture distribution; the highest-likelihood sample is used. minimum 1, maximum 1000, step 1. |
pack_with_ligand_context
design
|
boolean checkbox | no | true |
Pack with ligand context Consider ligand, DNA and other context atoms during packing. |
repack_everything
design
|
boolean checkbox | no | false |
Repack fixed residues too Off preserves side chains at fixed positions and uses them as packing context. |
force_hetatm
design
|
boolean checkbox | no | false |
Write packed context atoms as HETATM Force context atoms in packed output PDBs to use HETATM records. |
packed_suffix
design
|
string text | no | _packed |
Packed PDB suffix Suffix appended to packed PDB filenames; letters, digits, underscores, dots and hyphens only. |
save_stats
design
|
boolean checkbox | no | false |
Save design statistics Write .pt statistics including sequences, probabilities, decoding order, masks, seed and temperature. |
fasta_seq_separation
design
|
string text | no | : |
FASTA chain separator Separator between chains in output FASTA. PDB output preserves chain IDs and residue numbering. up to 10 characters. |
file_ending
|
string text | no | — |
Output filename ending Optional ending such as _xyz; letters, digits, underscores, dots and hyphens only. |
zero_indexed
design
|
boolean checkbox | no | false |
Number output designs from zero Start designed PDB file numbering at 0 instead of 1. |
verbose
|
boolean checkbox | no | true |
Print progress Include upstream progress messages in the run log. |
Example
A request that runs
These are the defaults, exactly as the web form would post them.
curl -X POST https://athanortools.com/api/ligandmpnn/ \
-H 'Content-Type: application/json' \
-d '{
"task": "design",
"job_name": "ligandmpnn-demo",
"pdb_path": "",
"pdb_path_multi": "",
"chains_to_design": "",
"parse_these_chains_only": "",
"parse_atoms_with_zero_occupancy": false,
"model_type": "protein_mpnn",
"checkpoint_protein_mpnn": "proteinmpnn_v_48_020.pt",
"checkpoint_ligand_mpnn": "ligandmpnn_v_32_010_25.pt",
"checkpoint_soluble_mpnn": "solublempnn_v_48_020.pt",
"checkpoint_per_residue_label_membrane_mpnn": "per_residue_label_membrane_mpnn_v_48_020.pt",
"checkpoint_global_label_membrane_mpnn": "global_label_membrane_mpnn_v_48_020.pt",
"batch_size": 1,
"number_of_batches": 1,
"temperature": 0.1,
"seed": 0,
"fixed_residues": "",
"fixed_residues_multi": "",
"redesigned_residues": "",
"redesigned_residues_multi": "",
"symmetry_residues": "",
"symmetry_weights": "",
"homo_oligomer": false,
"bias_AA": "",
"omit_AA": "",
"bias_AA_per_residue": "",
"bias_AA_per_residue_multi": "",
"omit_AA_per_residue": "",
"omit_AA_per_residue_multi": "",
"ligand_mpnn_use_atom_context": true,
"ligand_mpnn_use_side_chain_context": false,
"ligand_mpnn_cutoff_for_score": 8.0,
"transmembrane_buried": "",
"transmembrane_interface": "",
"global_transmembrane_label": "0",
"pack_side_chains": false,
"number_of_packs_per_design": 4,
"sc_num_denoising_steps": 3,
"sc_num_samples": 16,
"pack_with_ligand_context": true,
"repack_everything": false,
"force_hetatm": false,
"packed_suffix": "_packed",
"save_stats": false,
"fasta_seq_separation": ":",
"file_ending": "",
"zero_indexed": false,
"verbose": true
}'
The reply is 202 with a queued job; poll its
status_url until status is
succeeded or failed. See
the quick start for the
whole exchange.
Responses
What comes back
| status | Meaning |
|---|---|
queued |
Accepted, waiting for the jobs ahead of it. `position` counts how many those are. |
running |
The tool is executing now. |
succeeded |
Finished; `result` holds the tool's output and `license` the terms it came under. |
failed |
Finished; `error` holds a code and a message. |
cancelled |
Abandoned at the submitter's request; there is no result. A job cancelled before its turn never ran at all. |
Errors
| code | Meaning |
|---|---|
invalid_input |
The client supplied invalid or incomplete input. |
tool_unavailable |
The requested third-party dependency is not available on this host. |
execution_failed |
A configured third-party tool exited unsuccessfully. |
internal_error |
An adapter failed in a way it does not describe. The detail is in the server log, not the response. |
not_found |
No job has that id. Finished jobs are dropped eventually. |