### ProteinMPNN Sampling (`proteinmpnn-sample`) Designs new sequences for a given backbone. Each input structure is encoded once and decoded into one or more candidate sequences, each returned with a perplexity and the sequence recovery against the structure's original sequence. #### API Reference

Source Per-structure inputs, each containing a structure plus optional `chains_to_redesign` and `fixed_positions` selections. Chains to redesign. `None` means redesign every chain in the structure. Accepts shorthand `"A"` or `["A", "B"]` at construction. Per-chain positions whose residue identity is held fixed during design (1-indexed). Accepts shorthand `{"A": [1, 2, 3]}` at construction. Protein structure. Accepts a file path, raw PDB/CIF content string, `Structure` object, or a dict in the shape produced by `Structure.model_dump(mode='json')`.

Source Model weights. `"proteinmpnn"` is ColabDesign's default `v_48_020` (0.20 Å backbone noise). The `v_48_002` / `v_48_010` / `v_48_030` variants are the same architecture trained at 0.02 / 0.10 / 0.30 Å backbone noise (the suffix is the noise level in Å x 100); more noise yields more diverse, robust designs at some cost to native-sequence recovery. `"abmpnn"` is antibody-optimized; `"soluble"` is soluble-protein-trained. Available options: `proteinmpnn`, `v_48_002`, `v_48_010`, `v_48_030`, `abmpnn`, `soluble` Gaussian noise (Å) added to backbone coordinates before each forward pass. One-letter codes of amino acids to exclude. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the model on. Options include 'cuda' (NVIDIA GPU), 'cpu' (CPU execution), or specific GPU devices like 'cuda:0'. Defaults to 'cuda'. Maximum execution time in seconds. `None` waits indefinitely. Random seed to use for sampling; None draws a fresh seed. Total number of sequences to generate per input structure. Number of sequences to process simultaneously on GPU. Defaults to num\_sequences\_per\_structure. Controls randomness in sampling from logits.

Source One `ProteinMPNNDesignSet` per input structure, in input order. Entry `i` holds all complexes for input structure `i`. The complexes generated for one input structure, each a complete multi-chain complex with per-design metrics.

#### Applications Use this to redesign or stabilize a natural protein, or to generate sequences for a de novo backbone (for example one from RFdiffusion). The standard design loop is to sample many sequences per backbone, rank by perplexity, and validate the top candidates with a structure predictor. #### Usage Tips * **`temperature` (default `0.1`) controls diversity.** Lower values are greedier and stay close to the single most likely sequence, while higher values sample more varied sequences. A value near `0.0` behaves like an argmax, and the temperature must be at least `0`. * **Lower `batch_size` if you hit GPU memory limits.** It defaults to `num_sequences_per_structure`, so every requested sequence is generated in one forward pass. For large requests or long backbones this can exhaust GPU memory, and a smaller `batch_size` trades speed for lower memory. * **`model_choice` selects the weights.** The default `proteinmpnn` is `v_48_020`. The `v_48_002`, `v_48_010`, and `v_48_030` variants are trained with increasing backbone noise, which makes designs more robust and diverse at the cost of native-sequence recovery. `abmpnn` is antibody-tuned. Use `soluble` when the design must be water-soluble, because the default model tends to place hydrophobic residues on membrane-like surfaces whereas `soluble` is retrained with transmembrane proteins excluded. * **`fixed_positions` is counted from 1, not 0.** Listing a position keeps that residue at its input identity, which is how you preserve catalytic or interface residues while redesigning everything else. * **`excluded_amino_acids` forbids residue types everywhere.** Use it to keep unwanted residues out of every design, for example `["C"]` to avoid introducing cysteines. * **`backbone_noise` (default `0.0`) and `seed`.** `backbone_noise` adds Gaussian noise in angstroms to the input backbone. Small values such as `0.02` increase diversity at some cost in recovery. Set `seed` for reproducible sampling.

### ProteinMPNN Scoring (`proteinmpnn-score`) Evaluates how well existing sequences fit a structure. Each (sequence, structure) pair is scored under ProteinMPNN's structure-conditioned likelihood, returning log-likelihood, average log-likelihood, and perplexity, with optional per-position logits. #### API Reference

Source List of sequence-structure pairs to score. Each pair contains a sequence, a structure, and optional per-pair `fixed_positions` excluded from the scoring metrics. Protein sequence to score against the structure. Protein structure to score the sequence against. Per-chain 1-indexed positions excluded from the aggregate scoring metrics. Accepts `{"A": [1, 2]}`.

Source Whether to include per-position logits in the output. When `True`, returns logits for each sequence. When `False`, only returns metrics (saves memory and serialization time). Default: `False`. Model weights. `"proteinmpnn"` is ColabDesign's default `v_48_020` (0.20 Å backbone noise). The `v_48_002` / `v_48_010` / `v_48_030` variants are the same architecture trained at 0.02 / 0.10 / 0.30 Å backbone noise (the suffix is the noise level in Å x 100); more noise yields more diverse, robust designs at some cost to native-sequence recovery. `"abmpnn"` is antibody-optimized; `"soluble"` is soluble-protein-trained. Available options: `proteinmpnn`, `v_48_002`, `v_48_010`, `v_48_030`, `abmpnn`, `soluble` Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the model on. Options include `"cuda"` (NVIDIA GPU), `"cpu"` (CPU execution). Default: `"cuda"`. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source List of scoring outputs, one per input sequence-structure pair. Each entry is a `Metrics` subclass with scalar metrics (accessed via `score.perplexity` or `score["perplexity"]`) plus declared `logits` / `vocab` fields. Per-position logits array `(seq_len, vocab_size)`. `None` unless the tool returns logits. Token ordering for `logits`. Name of the metric that best summarizes the result overall (e.g. `"avg_plddt"` for AlphaFold2). Used by downstream UI and reporting to pick a headline value. Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip. **Metrics** (one set per `scores` item) | Metric | Type | Range | Availability | | -------------------- | ----- | ----- | ------------ | | `log_likelihood` | float | ≤ 0.0 | always | | `avg_log_likelihood` | float | ≤ 0.0 | always | | `perplexity` | float | ≥ 1.0 | always |

#### Applications Use this to rank candidate sequences or point mutations by structural compatibility without generating new ones: compare designs, assess the effect of a substitution, or filter a library before experimental testing. Lower perplexity indicates a better structure-sequence fit. #### Usage Tips * **Set `fixed_positions` per (sequence, structure) pair to score only part of a chain.** It lives on each input pair as a `{chain: [positions]}` selection, not in the config. Listed positions are skipped when computing log-likelihood and perplexity, so the score reflects just the residues you care about instead of the whole sequence. **NOTE:** Positions are per chain and counted from 1, not 0, to match biological residue selection conventions. * **`return_logits` (default `False`) has a size trade-off.** Enabling it returns a per-position `(sequence length x 21)` logit array per sequence for residue-level analysis. That array dominates output size and memory for long sequences or large batches, so leave it off unless you need it.

### ProteinMPNN Gradient (`proteinmpnn-gradient`) Exposes ProteinMPNN as a differentiable structure-conditioned objective: given a relaxed `(L, 20)` sequence distribution and a backbone, it returns the mean negative log-likelihood and its gradient with respect to the input logits, for use as a loss in gradient-based or MCMC sequence optimization. #### API Reference

Source Relaxed sequence state, shape `L x 20` in canonical amino-acid order `ACDEFGHIKLMNPQRSTVWY`. Backbone structure to condition ProteinMPNN on. Raw structure content in PDB or CIF format. Format of the content string (auto-detected if omitted). What the B-factor column represents. Optional source identifier (filepath or tool name). Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction. Chains to score/design. If `None`, all chains in `structure` are used. Per-chain positions excluded from the perplexity objective. Optional softmax temperature. When set, applies `softmax(input / temperature)` before evaluating the relaxed sequence. When `None`, the input is used as-is.

Source ProteinMPNN weight variant. Available options: `proteinmpnn`, `v_48_002`, `v_48_010`, `v_48_030`, `abmpnn`, `soluble` Use hard one-hot forward pass with soft-probability gradients. Return gradients when true; run forward scoring only when false. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device for ProteinMPNN execution. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Gradient w\.r.t. input logits. None when `compute_gradient=False`. Mean negative log-likelihood over ProteinMPNN-scored positions. Log-likelihood, perplexity, sequence length, and objective details. Canonical amino-acid column ordering for logits and gradients.

#### Applications Use this when ProteinMPNN is one term in a larger optimization over a continuous sequence representation (for example combined with other structure or property objectives), rather than for standalone sampling. Set `compute_gradient=False` for forward-only NLL scoring, such as ranking MCMC proposals. #### Usage Tips * **`logits` columns must be in the order `ACDEFGHIKLMNPQRSTVWY`.** The columns are read by position, so a different amino-acid ordering silently produces the wrong gradient. An optional `temperature` runs `softmax(logits / T)` first. Leave it unset to use the logits as they are. * **`compute_gradient` (default `True`).** Returns the gradient of the mean negative log-likelihood with respect to `logits`. Set `False` for forward-only scoring (`loss` only, `gradient` is `None`), for example to cheaply rank MCMC proposals. * **`use_ste` (default `True`) sets the forward pass.** Straight-through: a hard one-hot in the forward pass with soft-probability gradients in the backward pass. Set `False` for fully soft blended embeddings, smoother but biased. * **`fixed_positions` is counted from 1 and is left out of the objective.** Positions you list are excluded from both the loss and its gradient, so set it to optimize only the residues you are designing.