### FAMPNN Sampling (`fampnn-sample`) Designs a sequence for a backbone and co-generates its full-atom sidechains. Each input structure is returned as a designed structure with packed sidechain coordinates and a per-residue pSCE. #### API Reference

Source Per-structure inputs, each containing a structure and optional `chains_to_redesign` / `fixed_positions` / `fixed_sidechain_positions` selections. Per-chain residue positions whose sidechain coordinates condition the model during sampling/packing (1-indexed). Accepts shorthand `{"A": [1, 2]}` 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')`. 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.

Source FAMPNN checkpoint variant. '0.3' for sequence design (PDB-trained, 0.3 Å noise), '0.0' for sidechain packing (PDB-trained, 0.0 Å noise), '0.3\_cath' for mutation scoring (CATH-trained). Number of iterative unmasking steps for sequence design. More steps yield higher quality but slower inference. 10 steps is sufficient for high self-consistency; 100 for best quality. If True, skip sidechain generation during sampling. If True, repack sidechains after final sequence is determined. Only condition on sidechains with predicted sidechain error below this threshold during iterative sampling. Number of sidechain diffusion denoising steps. Step scale for sidechain diffusion (eta parameter). 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; None draws a random seed per run. 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 `FAMPNNDesignSet` per input structure, in input order. The FAMPNN complexes generated for one input, each a complete multi-chain complex.

#### Applications Use this to redesign or stabilize a protein when sidechain packing matters, for example interface or active-site redesign, since the model commits to a concrete sidechain arrangement rather than leaving it implicit. The pSCE flags residues whose packing the model is unsure about. #### Usage Tips * **`psce_threshold` (default `0.3`) controls which generated sidechains the model conditions on.** FAMPNN designs by iterative unmasking, and at each step only sidechains whose predicted error (pSCE, in angstroms) falls below this threshold are kept as context for decoding the remaining residues. Sidechains the model is less certain about (pSCE at or above the threshold) are not used as context, so low-confidence placements do not bias later predictions. Lower it to condition only on the most confident sidechains. Raise it to let more, lower-confidence sidechains inform the design. * **`fixed_positions` and `fixed_sidechain_positions` are different settings.** `fixed_positions` holds a residue's amino-acid identity, while `fixed_sidechain_positions` instead conditions on its existing sidechain coordinates. Both are per chain and indexed from 1 to match biological residue selection conventions. * **`seq_only` (default `False`) skips sidechain co-generation.** Setting it `True` is faster but gives up the full-atom modeling that distinguishes FAMPNN, so leave it off unless you only need a sequence. * **Output is structured per design.** `output.design_sets[i].complexes[j]` is a `FAMPNNDesign` with `.chains`, the full-atom `.structure`, and `.metrics["avg_psce"]`. `FAMPNNDesigns` are a `Complex` subclass and can be passed directly to structure predictors.

### FAMPNN Sidechain Packing (`fampnn-pack`) Places sidechain atoms onto a structure whose sequence is fixed, returning the packed structure with per-atom pSCE confidence. #### API Reference

Source List of structure inputs for sidechain packing. Per-chain residue positions whose sidechain coordinates condition the model during sampling/packing (1-indexed). Accepts shorthand `{"A": [1, 2]}` 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')`. 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.

Source Checkpoint variant. '0.0' recommended for best packing accuracy. Number of packing samples per input structure. Number of samples to process simultaneously on GPU. Number of sidechain diffusion denoising steps. Step scale for sidechain diffusion. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run on. 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 One entry per input structure, in input order. Packed structures for this input, one per packing sample. B-factor column carries per-atom pSCE. Per-residue predicted sidechain error in Angstroms, one list per packing sample.

#### Applications Use this to build or rebuild sidechains for a known sequence and backbone, for example after backbone-only design or to repair incomplete models before docking or molecular dynamics. #### Usage Tips * **pSCE tells you which sidechains to trust.** It is the predicted per-atom sidechain error in angstroms, so high-pSCE residues are the ones to inspect or rebuild. * **Lower `batch_size` if you run out of GPU memory.** It defaults to `16` samples per forward pass; reduce it for large structures.

### FAMPNN Mutation Scoring (`fampnn-score`) Scores specified mutations on a structure with full-atom context, returning a likelihood-based score per mutation. #### API Reference

Source List of MutationInput objects, each containing a structure and mutations to score. Protein structure to evaluate mutations against. List of mutation strings. Each mutation uses the format '\\<1-indexed\_position>\' with single-letter amino acid codes. Multiple simultaneous mutations are joined with colons: 'N1P:N2R'.

Source Checkpoint variant. '0.3\_cath' recommended for scoring. Number of mutations to score simultaneously on GPU. If True, score without sidechain context (backbone-only). Number of sidechain diffusion denoising steps. Step scale for sidechain diffusion. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run on. 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 MutationScoreResult objects, one per input structure. Mutation strings that were scored. Log-likelihood ratio scores for each mutation. Positive = mutation is more likely than wild-type.

#### Applications Use this to estimate the effect of specific point or multi-site mutations, for example triaging a designed variant list or interpreting a mutational scan, with sidechain context rather than backbone alone. #### Usage Tips * **Mutation strings are 1-indexed and colon-joined.** Use `A1V` for a single mutation and `A1V:G5L` for a multi-site variant. The position is counted from 1. * **`seq_only` (default `False`) removes sidechain context.** Leaving it off scores with full-atom context, which is the point of FAMPNN; set it `True` only for a faster, weaker backbone-style score.

### FAMPNN Score All Mutations (`fampnn-score-all-mutations`) Scores every possible single substitution at every position of a structure, returning a position-by-residue map of log-likelihood-ratio scores. #### API Reference

Source List of structures to score all mutations for. 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.

Source Checkpoint variant. '0.3\_cath' recommended for scoring. Number of positions to score simultaneously on GPU. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run on. 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 AllMutationsScoreResult objects, one per input structure. Dictionary mapping position labels (e.g., '1A' for position 1, wild-type Ala) to dictionaries of \{mutant\_residue: score}. Scores are log-likelihood ratios (positive = favored over wild-type).

#### Applications Use this for a full in-silico deep mutational scan, to find stabilizing or tolerated substitutions across a protein without enumerating mutations by hand. #### Usage Tips * **Lower `batch_size` if you run out of GPU memory.** It defaults to scoring `16` positions per forward pass, which dominates memory for large proteins. * **Scores are log-likelihood ratios relative to the native residue.** Positive values mean the substitution is favored over the wild-type residue under the model, so rank candidates by score rather than reading absolute values.