### featurize usage example from run.py

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/data_utils.md

Example call to featurize as used in run.py, passing protein_dict and arguments from command-line args. Demonstrates typical invocation with cutoff_for_score, use_atom_context, number_of_ligand_atoms, and model_type.

```python
feature_dict = featurize(
    protein_dict,
    cutoff_for_score=8.0,
    use_atom_context=args.ligand_mpnn_use_atom_context,
    number_of_ligand_atoms=atom_context_num,
    model_type=args.model_type,
)
```

--------------------------------

### Usage example from run.py

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/sc_utils.md

Shows how to instantiate the Packer model, load its checkpoint, and call pack_side_chains with arguments from run.py. The example sets the sampled sequences in the feature dictionary and extracts the packed coordinates, masks, and B-factors from the returned dictionary.

```python
from sc_utils import Packer, pack_side_chains

model_sc = Packer(node_features=128, edge_features=128, num_positional_embeddings=16,
                  num_chain_embeddings=16, num_rbf=16, hidden_dim=128,
                  num_encoder_layers=3, num_decoder_layers=3, atom_context_num=16,
                  lower_bound=0.0, upper_bound=20.0, top_k=32, dropout=0.0,
                  augment_eps=0.0, atom37_order=False, device=device, num_mix=3)
# ... load checkpoint_sc state dict, .to(device), .eval()

sc_feature_dict["S"] = S_list[c]   # per-batch sampled sequences
sc_dict = pack_side_chains(sc_feature_dict, model_sc,
                           args.sc_num_denoising_steps,  # 3
                           args.sc_num_samples,           # 16
                           args.repack_everything)        # 0 or 1
X, X_m, b_factors = sc_dict["X"], sc_dict["X_m"], sc_dict["b_factors"]
```

--------------------------------

### parse_PDB usage example

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/data_utils.md

Shows how to call parse_PDB and featurize together. The example parses only chain C from a PDB file, enables full atom parsing for side-chain packing, and then featurizes the result for the ligand_mpnn model.

```python
from data_utils import parse_PDB, featurize

protein_dict, backbone, other_atoms, icodes, water_atoms = parse_PDB(
    "./inputs/1BC8.pdb",
    device="cpu",
    chains=["C"],                      # parse only chain C
    parse_all_atoms=True,              # full 37-atom order (needed for side-chain packing)
    parse_atoms_with_zero_occupancy=False,
)
feature_dict = featurize(protein_dict, model_type="ligand_mpnn")
```

--------------------------------

### JSON Input File Formats

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/configuration.md

Describes the schemas and examples for the JSON input files used by the command-line tools.

```APIDOC
## JSON Input File Formats

### Description
These are the JSON file formats accepted by the command-line interface for specifying input structures, fixed residues, redesigned residues, and amino acid biases.

### File Formats

#### --pdb_path_multi
- **Schema**: `{"/abs/path/1.pdb": "", "/abs/path/2.pdb": ""}`
- **Example**: See `inputs/pdb_ids.json`

#### --fixed_residues_multi
- **Schema**: `{pdb: "A12 A13 B2"}`
- **Example**: See `inputs/fix_residues_multi.json`

#### --redesigned_residues_multi
- **Schema**: `{pdb: "A7 A8"}`
- **Example**: See `inputs/redesigned_residues_multi.json`

#### --bias_AA_per_residue
- **Schema**: `{"C1": {"G": -0.3, "C": -2.0, "P": 10.8}}`
- **Example**: See `inputs/bias_AA_per_residue.json`

#### --bias_AA_per_residue_multi
- **Schema**: `{pdb: {"C1": {"A": 3.0}}}`
- **Example**: See `inputs/bias_AA_per_residue_multi.json`

#### --omit_AA_per_residue
- **Schema**: `{"C1": "ACDEFGHIKLMNPQRSTVW"}`
- **Example**: See `inputs/omit_AA_per_residue.json`

#### --omit_AA_per_residue_multi
- **Schema**: `{pdb: {"C1": "ACDEFGHIKLMNPQRSTVW"}}`
- **Example**: See `inputs/omit_AA_per_residue_multi.json`

### Notes
- Residue codes are `chain + PDB residue number + insertion code`, e.g., `C1`, `B82A`.
- Letters must be in the 21-letter `alphabet`; bias/omit entries for unknown letters/residues are silently ignored.
```

--------------------------------

### Run with --redesigned_residues and insertion codes

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Specify residues using chain_id + residue_number + insertion_code. Example redesigns only residues B82, B82A, B82B, B82C.

```bash
python run.py \
        --seed 111 \
        --pdb_path "./inputs/2GFB.pdb" \
        --out_folder "./outputs/insertion_code" \
        --redesigned_residues "B82 B82A B82B B82C" \
        --parse_these_chains_only "B"
```

--------------------------------

### Direct decode usage example

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/sc_utils.md

Shows how to directly use decode outside pack_side_chains: sample from the predicted Von Mises mixture distribution. Requires model_sc.decode to return the three tensors.

```python
mean, concentration, mix_logits = model_sc.decode(feature_dict)
mix = torch.distributions.Categorical(logits=mix_logits)
comp = torch.distributions.VonMises(mean, concentration)
pred_dist = torch.distributions.MixtureSameFamily(mix, comp)
sample = pred_dist.sample([16])
```

--------------------------------

### Importable main() with argparse.Namespace (Python)

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/run.md

Shows how to import and call run.main() with an argparse.Namespace object. Provides all required arguments with defaults for a ligand-aware design.

```python
# main() is also importable; it expects an argparse.Namespace-shaped object
import argparse
import run

args = argparse.Namespace(
    model_type="ligand_mpnn", checkpoint_ligand_mpnn="./model_params/ligandmpnn_v_32_010_25.pt",
    checkpoint_protein_mpnn="", checkpoint_per_residue_label_membrane_mpnn="",
    checkpoint_global_label_membrane_mpnn="", checkpoint_soluble_mpnn="",
    fasta_seq_separation=":", verbose=1, pdb_path="./inputs/1BC8.pdb", pdb_path_multi="",
    fixed_residues="", fixed_residues_multi="", redesigned_residues="", redesigned_residues_multi="",
    bias_AA="", bias_AA_per_residue="", bias_AA_per_residue_multi="",
    omit_AA="", omit_AA_per_residue="", omit_AA_per_residue_multi="",
    symmetry_residues="", symmetry_weights="", homo_oligomer=0, out_folder="./outputs/api_example",
    file_ending="", zero_indexed=0, seed=111, batch_size=1, number_of_batches=1,
    temperature=0.1, save_stats=1, ligand_mpnn_use_atom_context=1,
    ligand_mpnn_cutoff_for_score=8.0, ligand_mpnn_use_side_chain_context=0,
    chains_to_design="", parse_these_chains_only="", transmembrane_buried="",
    transmembrane_interface="", global_transmembrane_label=0,
    parse_atoms_with_zero_occupancy=0, pack_side_chains=0, checkpoint_path_sc="",
    number_of_packs_per_design=4, sc_num_denoising_steps=3, sc_num_samples=16,
    repack_everything=0, force_hetatm=0, packed_suffix="_packed", pack_with_ligand_context=1,
)
run.main(args)
```

--------------------------------

### Run LigandMPNN with default settings

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Runs LigandMPNN with default settings using --model_type "ligand_mpnn".

```bash
python run.py \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/ligandmpnn_default"
```

--------------------------------

### ProteinMPNN.__init__

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/model_utils.md

Creates a ProteinMPNN model. Use this constructor then supply state dict from a LigandMPNN checkpoint.

```APIDOC
## `ProteinMPNN.__init__`

### Description
Creates the ProteinMPNN encoder-decoder model.

### Method
`__init__`

### Signature
```python
def __init__(
    self,
    num_letters=21,
    node_features=128,
    edge_features=128,
    hidden_dim=128,
    num_encoder_layers=3,
    num_decoder_layers=3,
    vocab=21,
    k_neighbors=48,
    augment_eps=0.0,
    dropout=0.0,
    device=None,
    atom_context_num=0,
    model_type="protein_mpnn",
    ligand_mpnn_use_side_chain_context=False,
):
```

### Parameters
- **num_letters** (int) - Optional - Default: `21` - Output vocabulary size (the `W_out` linear maps `hidden_dim` → `num_letters`)
- **node_features** (int) - Optional - Default: `128` - Feature extractor node/edge feature dimension
- **edge_features** (int) - Optional - Default: `128` - Edge feature dimension
- **hidden_dim** (int) - Optional - Default: `128` - Encoder/decoder hidden dimension
- **num_encoder_layers** (int) - Optional - Default: `3` - Number of `EncLayer` blocks
- **num_decoder_layers** (int) - Optional - Default: `3` - Number of `DecLayer` blocks
- **vocab** (int) - Optional - Default: `21` - Embedding table size for `W_s` (sequence embedding)
- **k_neighbors** (int) - Optional - Default: `48` - Graph degree: number of nearest neighbor edges per node (`top_k`). Checkpoints store this as `num_edges` (48 for ProteinMPNN family, 32 for LigandMPNN) and `run.py` reads it from the checkpoint
- **augment_eps** (float) - Optional - Default: `0.0` - Gaussian coordinate noise added to inputs when training
- **dropout** (float) - Optional - Default: `0.0` - Dropout probability for encoder/decoder layers
- **device** (str/device) - Optional - Default: `None` - Device for feature extractor construction
- **atom_context_num** (int) - Optional - Default: `0` - Number of ligand context atoms per residue; read from the LigandMPNN checkpoint (`atom_context_num=25` for the released models). Ignored for non-ligand model types
- **model_type** (str) - Optional - Default: `"protein_mpnn"` - Selects the feature extractor branch, see behavior below
- **ligand_mpnn_use_side_chain_context** (bool) - Optional - Default: `False` - For `"ligand_mpnn"` only: use fixed-residue side-chain atoms as extra ligand context (`use_side_chains=True`)

### Behavior
Branches on `model_type`:
- **`"ligand_mpnn"`**: Uses `ProteinFeaturesLigand(... top_k=k_neighbors, atom_context_num=atom_context_num, use_side_chains=...)` and creates extra modules: `W_c`, `W_nodes_y`, `W_edges_y`, `V_C`, `V_C_norm`, 2× `DecLayer` context encoders, 2× `DecLayerJ` y-context encoders
- **`"protein_mpnn"` or `"soluble_mpnn"`**: Uses `ProteinFeatures(node_features, edge_features, top_k=k_neighbors, augment_eps=...)` and creates no extra modules
- **`"per_residue_label_membrane_mpnn"` or `"global_label_membrane_mpnn"`**: Uses `ProteinFeaturesMembrane(node_features, edge_features, top_k=k_neighbors, augment_eps=..., num_classes=3)` and creates `W_v`
- **anything else**: Prints `Choose --model_type flag from currently available models` and calls `sys.exit()`

The shared decoder stack is always built: `W_e` (edge projection), `W_s` (`nn.Embedding(vocab, hidden_dim)`), `W_out` (`Linear(hidden_dim, num_letters)`), `num_encoder_layers` × `EncLayer(hidden_dim, hidden_dim*2, dropout=...)`, `num_decoder_layers` × `DecLayer(hidden_dim, hidden_dim*3, dropout=...)`. All parameters with `dim() > 1` are initialized with Xavier uniform.

### Throws
- Unknown `model_type` → prints to stdout and `sys.exit()` (not an exception). No exceptions are raised for the valid values.

### Usage Example
```python
model = ProteinMPNN(
    node_features=128, edge_features=128, hidden_dim=128,
    num_encoder_layers=3, num_decoder_layers=3,
    k_neighbors=k_neighbors, device=device,
    atom_context_num=atom_context_num, model_type=args.model_type,
    ligand_mpnn_use_side_chain_context=ligand_mpnn_use_side_chain_context,
)
model.load_state_dict(checkpoint["model_state_dict"])
model.to(device)
model.eval()
```
```

--------------------------------

### Run with --parse_atoms_with_zero_occupancy

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Parse atoms in the PDB files with zero occupancy too.

```bash
python run.py \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/parse_atoms_with_zero_occupancy" \
        --parse_atoms_with_zero_occupancy 1
```

--------------------------------

### run.py CLI Options

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/configuration.md

Complete list of command-line arguments accepted by run.py, including model type selection, input/output paths, residue design controls, sampling parameters, and side-chain packing options.

```APIDOC
## CLI Options for run.py

### Description
This is the command-line interface for the LigandMPNN protein design tool. It accepts a variety of options to control model selection, input structures, residue design constraints, sampling behavior, and side-chain packing.

### Usage
```
python run.py [options]
```

### Options

#### Model Selection
- `--model_type` (str, default: `"protein_mpnn"`) - Model type: `protein_mpnn`, `ligand_mpnn`, `per_residue_label_membrane_mpnn`, `global_label_membrane_mpnn`, `soluble_mpnn`
- `--checkpoint_protein_mpnn` (str, default: `"./model_params/proteinmpnn_v_48_020.pt"`) - Path to model weights
- `--checkpoint_ligand_mpnn` (str, default: `"./model_params/ligandmpnn_v_32_010_25.pt"`) - Path to model weights
- `--checkpoint_per_residue_label_membrane_mpnn` (str, default: `"./model_params/per_residue_label_membrane_mpnn_v_48_020.pt"`) - Path to model weights
- `--checkpoint_global_label_membrane_mpnn` (str, default: `"./model_params/global_label_membrane_mpnn_v_48_020.pt"`) - Path to model weights
- `--checkpoint_soluble_mpnn` (str, default: `"./model_params/solublempnn_v_48_020.pt"`) - Path to model weights

#### Input/Output
- `--pdb_path` (str, default: `""`) - Path to the input PDB
- `--pdb_path_multi` (str, default: `""`) - Path to JSON mapping `{pdb_path: ""}` — only keys are used
- `--out_folder` (str, required) - Output folder (seqs/, backbones/, packed/, stats/)
- `--file_ending` (str, default: `""`) - Suffix appended to output file names
- `--zero_indexed` (str, default: `0`) - Declared with `type=str`; 1 = start output PDB numbering at 0

#### Residue Design Controls
- `--fixed_residues` (str, default: `""`) - Space-separated residue codes, e.g. `"C1 C2 C3"`
- `--fixed_residues_multi` (str, default: `""`) - JSON `{pdb_path: "A12 A13"}` (values whitespace-split)
- `--redesigned_residues` (str, default: `""`) - Space-separated residue codes to design (rest fixed)
- `--redesigned_residues_multi` (str, default: `""`) - JSON `{pdb_path: "A7 A8"}`
- `--chains_to_design` (str, default: `""`) - Comma-separated chains to redesign; others fixed
- `--parse_these_chains_only` (str, default: `""`) - Comma-separated chains to parse

#### Amino Acid Biases and Omissions
- `--bias_AA` (str, default: `""`) - Global AA bias, `"A:-1.024,P:2.34,C:-12.34"`
- `--bias_AA_per_residue` (str, default: `""`) - JSON `{"A12": {"G": -0.3, "C": -2.0}}`
- `--bias_AA_per_residue_multi` (str, default: `""`) - JSON `{pdb_path: {residue: {AA: bias}}}`
- `--omit_AA` (str, default: `""`) - Letter string to restrict, e.g. `"ACG"`
- `--omit_AA_per_residue` (str, default: `""`) - JSON `{"A12": "APQ", "A13": "QST"}`
- `--omit_AA_per_residue_multi` (str, default: `""`) - JSON `{pdb_path: {residue: "letters"}}`

#### Symmetry
- `--symmetry_residues` (str, default: `""`) - Groups separated by `\|`, members by `,`: `"C1,C2,C3\|C4,C5"`
- `--symmetry_weights` (str, default: `""`) - Matching weight groups, `"0.33,0.33,0.33\|0.5,0.5"`
- `--homo_oligomer` (int, default: `0`) - 1 = auto equal-weight symmetry across chains

#### Sampling
- `--seed` (int, default: `0`) - Seed for torch/numpy/python random (0 → random seed)
- `--batch_size` (int, default: `1`) - Sequences generated per forward pass
- `--number_of_batches` (int, default: `1`) - Number of sampling passes
- `--temperature` (float, default: `0.1`) - Sampling temperature

#### Ligand Context
- `--ligand_mpnn_use_atom_context` (int, default: `1`) - 1 = use atom context; 0 = mask all ligand atoms
- `--ligand_mpnn_cutoff_for_score` (float, default: `8.0`) - Å cutoff selecting residues near ligand for `num_ligand_res`/`ligand_confidence`
- `--ligand_mpnn_use_side_chain_context` (int, default: `0`) - 1 = fixed-residue side chains used as ligand context (`parse_all_atoms=True`)

#### Membrane Models
- `--transmembrane_buried` (str, default: `""`) - Buried residues for per-residue-label membrane model
- `--transmembrane_interface` (str, default: `""`) - Interface residues for per-residue-label membrane model
- `--global_transmembrane_label` (int, default: `0`) - 1 = transmembrane, 0 = soluble (global-label model)

#### Parsing and Packing
- `--parse_atoms_with_zero_occupancy` (int, default: `0`) - 1 = parse atoms with zero occupancy
- `--pack_side_chains` (int, default: `0`) - 1 = run the side-chain packer
- `--checkpoint_path_sc` (str, default: `"./model_params/ligandmpnn_sc_v_32_002_16.pt"`) - Packer weights
- `--number_of_packs_per_design` (int, default: `4`) - Independent packing samples per design
- `--sc_num_denoising_steps` (int, default: `3`) - Denoising/recycling steps for packing
- `--sc_num_samples` (int, default: `16`) - Mixture samples drawn per residue (max-likelihood kept)
- `--repack_everything` (int, default: `0`) - 1 = repack all residues; 0 = fixed residues keep native side chains
- `--force_hetatm` (int, default: `0`) - 1 = force ligand atoms to HETATM in packed PDBs
- `--packed_suffix` (str, default: `"_packed"`) - Suffix for packed PDB paths
- `--pack_with_ligand_context` (int, default: `1`) - 1 = pack with ligand context; 0 = without

#### Miscellaneous
- `--fasta_seq_separation` (str, default: `":"`) - Symbol joining chains in FASTA output
- `--verbose` (int, default: `1`) - Print statements (0 = silent)
- `--save_stats` (int, default: `0`) - 1 = save stats/<name>.pt

### Notes
- All options are passed as command-line arguments to `run.py`.
- The `--out_folder` option is required.
- The `--zero_indexed` option is declared with `type=str` but expects integer-like values (0 or 1).
```

--------------------------------

### Run with --pdb_path_multi and JSON config

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Specify multiple PDB input paths in a JSON file. More efficient because the model is loaded from checkpoint only once. The JSON file maps PDB paths to an empty string.

```json
#{
#"./inputs/1BC8.pdb": "",
#"./inputs/4GYT.pdb": ""
#}
```

```bash
python run.py \
        --pdb_path_multi "./inputs/pdb_ids.json" \
        --out_folder "./outputs/pdb_path_multi" \
        --seed 111
```

--------------------------------

### Constructor Parameters

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/configuration.md

Lists the constructor parameters for the ProteinMPNN and Packer classes, showing the fixed values used at call sites and the configurable defaults.

```APIDOC
## Constructor Parameters

### Description
These are the parameters used to instantiate the ProteinMPNN and Packer classes. The values marked as fixed are hardcoded at the call sites, while others can vary at runtime.

### Parameters

#### ProteinMPNN
- **node_features** (int) - Fixed: 128 - Default: 128 - Number of node features.
- **edge_features** (int) - Fixed: 128 - Default: 128 - Number of edge features.
- **hidden_dim** (int) - Fixed: 128 - Default: 128 - Hidden dimension size.
- **num_encoder_layers** (int) - Fixed: 3 - Default: 3 - Number of encoder layers.
- **num_decoder_layers** (int) - Fixed: 3 - Default: 3 - Number of decoder layers.
- **k_neighbors** (int) - Fixed: checkpoint["num_edges"] - Default: 48 - Number of neighbors.
- **atom_context_num** (int) - Fixed: checkpoint["atom_context_num"] (ligand) or 1 - Default: 0 - Number of atom context.
- **model_type** (string) - Fixed: args.model_type - Default: "protein_mpnn" - Model type.
- **ligand_mpnn_use_side_chain_context** (bool) - Fixed: args.ligand_mpnn_use_side_chain_context - Default: False - Whether to use side chain context.

#### Packer
- **top_k** (int) - Fixed: 32 - Default: 30 - Top-k value.
- **dropout** (float) - Fixed: 0.0 - Default: 0.1 - Dropout rate.
- **num_mix** (int) - Fixed: 3 - Default: 3 - Number of mix.
- **atom_context_num** (int) - Fixed: 16 - Default: 16 - Number of atom context.
- **lower_bound** (float) - Fixed: 0.0 - Default: 0.0 - Lower bound.
- **upper_bound** (float) - Fixed: 20.0 - Default: 20.0 - Upper bound.

#### featurize
- **cutoff_for_score** (float) - Fixed: 8.0 - Default: 8.0 - Cutoff for score.
- **number_of_ligand_atoms** (int) - Fixed: atom_context_num (design) or 16 (packing) - Default: 16 - Number of ligand atoms.
```

--------------------------------

### Basic design with ProteinMPNN default (bash)

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/run.md

Runs a basic design using the default ProteinMPNN model type. Sets a seed and specifies input PDB and output folder.

```bash
python run.py --seed 111 --pdb_path "./inputs/1BC8.pdb" --out_folder "./outputs/default"
```

--------------------------------

### Run sequence design with --pdb_path and --out_folder

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/run.md

Command-line invocation to run the sequence design pipeline on a PDB file, outputting results to a specified folder.

```bash
python run.py --pdb_path "./inputs/1BC8.pdb" --out_folder "./outputs/default"
```

--------------------------------

### Run LigandMPNN with 0.05A model checkpoint

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Runs LigandMPNN using the 0.05A model by specifying the --checkpoint_ligand_mpnn flag.

```bash
python run.py \
        --checkpoint_ligand_mpnn "./model_params/ligandmpnn_v_32_005_25.pt" \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/ligandmpnn_v_32_005_25"
```

--------------------------------

### Packer.__init__

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/sc_utils.md

Constructor for the Packer model.

```APIDOC
## Packer.__init__(edge_features=128, node_features=128, num_positional_embeddings=16, num_chain_embeddings=16, num_rbf=16, top_k=30, augment_eps=0.0, atom37_order=False, device=None, atom_context_num=16, lower_bound=0.0, upper_bound=20.0, hidden_dim=128, num_encoder_layers=3, num_decoder_layers=3, dropout=0.1, num_mix=3)

### Description
Initializes the Packer model, a side-chain packing model that is a `torch.nn.Module`. It builds a graph encoder over backbone + ligand context and a decoder that predicts a `num_mix`-component Von Mises mixture per residue per chi angle.

### Parameters
- **edge_features** (int) - Optional - Edge feature dimension. Default: 128.
- **node_features** (int) - Optional - Node feature dimension. Default: 128.
- **num_positional_embeddings** (int) - Optional - Relative-offset embedding size. Default: 16.
- **num_chain_embeddings** (int) - Optional - Accepted for parity; the internal `ProteinFeatures` registers it but chain features are not used in the edge construction. Default: 16.
- **num_rbf** (int) - Optional - RBF bin count. Default: 16.
- **top_k** (int) - Optional - Graph degree (`run.py` constructs with `top_k=32`). Default: 30.
- **augment_eps** (float) - Optional - Coordinate noise during training. Default: 0.0.
- **atom37_order** (bool) - Optional - Whether the input `X` uses the 37-atom order (affects the oxygen index). Default: False.
- **device** (str/device) - Optional - Device. Default: None.
- **atom_context_num** (int) - Optional - Ligand context atoms per residue. Default: 16.
- **lower_bound** (float) - Optional - RBF distance lower bound (`run.py` passes `0.0`; `ProteinFeatures` for design uses 2.0). Default: 0.0.
- **upper_bound** (float) - Optional - RBF distance upper bound. Default: 20.0.
- **hidden_dim** (int) - Optional - Hidden dimension of encoder/decoder layers. Default: 128.
- **num_encoder_layers** (int) - Optional - Number of `EncLayer` blocks. Default: 3.
- **num_decoder_layers** (int) - Optional - Number of `DecLayer` blocks. Default: 3.
- **dropout** (int) - Optional - Dropout (`run.py` constructs with `dropout=0.0`). Default: 0.1.
- **num_mix** (int) - Optional - Mixture components per torsion angle. Default: 3.

### Notes
Constructor builds the internal `ProteinFeatures` (sc_utils variant), `W_e`, `W_v`, `W_f`, `W_v_sc`, `linear_down`, `W_torsions` (`Linear(hidden_dim, 4*3*num_mix)`), encoder layers, context encoders (`W_c`, `W_e_context`, `W_nodes_y`, `W_edges_y`, 2× `DecLayer`, `V_C`, `V_C_norm`, 2× `DecLayerJ`), and decoder layers, then Xavier-initializes all parameters with `dim() > 1`.
```

--------------------------------

### Define main(args) function

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/run.md

Defines the main entry point for the CLI. The function is called when the script is executed directly.

```python
def main(args) -> None:
    """
    Inference function
    """

```

--------------------------------

### pack_side_chains(feature_dict, model_sc, num_denoising_steps, num_samples=10, repack_everything=True, num_context_atoms=16)

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/sc_utils.md

Runs the full packing pipeline: builds torsion features, encodes once, then iteratively decodes a mixture of Von Mises distributions, samples torsions, and re-derives atom14 coordinates. Returns a mutated feature_dict with packed coordinates and uncertainty metrics.

```APIDOC
## pack_side_chains(feature_dict, model_sc, num_denoising_steps, num_samples=10, repack_everything=True, num_context_atoms=16)

### Description
Runs the full packing pipeline: builds torsion features, encodes once (`model_sc.encode`), then for each of `num_denoising_steps` iterations decodes a mixture of Von Mises distributions, draws `num_samples` torsion samples per residue, keeps the most likely sample, re-derives atom14 coordinates, and re-injects them as `feature_dict["X"]`.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `feature_dict` | dict | yes | — | Feature dictionary from `run.py`: `featurize(protein_dict, cutoff_for_score=8.0, ...)` with a batch dim, `S` set to each sampled design sequence, plus `xyz_37`/`xyz_37_m` for fixed-residue context (`--repack_everything 0`) |
| `model_sc` | `Packer` | yes | — | Packing model (loaded from `--checkpoint_path_sc`) |
| `num_denoising_steps` | int | yes | — | Number of denoising/recycling steps (`run.py`: `--sc_num_denoising_steps`, default 3) |
| `num_samples` | int | no | `10` | Samples drawn from the mixture per residue; the max-likelihood one is kept (`run.py`: `--sc_num_samples`, default 16) |
| `repack_everything` | bool | no | `True` | `True`: all torsions randomized initially and all residues repacked; `False`: torsions of fixed residues (chain_mask=0) are kept at native values |
| `num_context_atoms` | int | no | `16` | Padding size for the ligand context when `feature_dict` has no `Y` key (zeros are created) |

### Returns
Returns the mutated `feature_dict` with additional keys:

| Key | Shape | Description |
|-----|-------|-------------|
| `X` | `[B,L,14,3]` | Final packed atom14 coordinates |
| `X_m` | `[B,L,14]` | Atom14 mask (copy of `xyz14_m`) |
| `b_factors` | `[B,L,14]` | Per-atom uncertainty: log-probability density per chi-angle group (4 rigid groups), reported as B-factors in output PDBs |
| `mean` | `[B,L,4,num_mix]` | Von Mises means per torsional angle and mixture component |
| `concentration` | `[B,L,4,num_mix]` | Von Mises concentrations (`0.1 + softplus(...)`) |
| `mix_logits` | `[B,L,4,num_mix]` | Mixture logits |
| `log_prob` | `[B,L,4]` | Log-probability of the chosen sample (fixed positions scored as 2.0) |
| `sample` | `[B,L,4]` | Chosen torsion angles (radians, per chi angle) |
| `true_torsion_sin_cos` | `[B,L,4,2]` | Native (sin, cos) torsion pairs for fixed residues |
| `h_V`, `h_E`, `E_idx` | — | Encoder outputs used for the denoising loop |

### Throws
Requires `model_sc.encode`/`model_sc.decode` compatible feature keys (`mask`, `S`, `X`, ...). If `feature_dict` lacks `Y`, zero contexts of size `num_context_atoms` are synthesized (as in `run.py` when passing `model_type="ligand_mpnn"` featurization which always includes `Y`); `KeyError` if `mask`, `S`, `X` or `X_m` are absent.

### Usage Example
```python
from sc_utils import Packer, pack_side_chains

model_sc = Packer(node_features=128, edge_features=128, num_positional_embeddings=16,
                  num_chain_embeddings=16, num_rbf=16, hidden_dim=128,
                  num_encoder_layers=3, num_decoder_layers=3, atom_context_num=16,
                  lower_bound=0.0, upper_bound=20.0, top_k=32, dropout=0.0,
                  augment_eps=0.0, atom37_order=False, device=device, num_mix=3)
# ... load checkpoint_sc state dict, .to(device), .eval()

sc_feature_dict["S"] = S_list[c]   # per-batch sampled sequences
sc_dict = pack_side_chains(sc_feature_dict, model_sc,
                           args.sc_num_denoising_steps,  # 3
                           args.sc_num_samples,           # 16
                           args.repack_everything)        # 0 or 1
X, X_m, b_factors = sc_dict["X"], sc_dict["X_m"], sc_dict["b_factors"]
```
```

--------------------------------

### Ligand-aware design with fixed residues, bias, and side-chain packing (bash)

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/run.md

Runs a ligand-aware design with fixed residues, per-residue bias, and side-chain packing. Uses the ligand_mpnn model type and specifies multiple packs per design.

```bash
python run.py \
    --model_type "ligand_mpnn" \
    --seed 111 \
    --pdb_path "./inputs/1BC8.pdb" \
    --out_folder "./outputs/sc_default" \
    --fixed_residues "C1 C2 C3 C4 C5" \
    --bias_AA_per_residue "./inputs/bias_AA_per_residue.json" \
    --pack_side_chains 1 \
    --number_of_packs_per_design 4 \
    --pack_with_ligand_context 1
```

--------------------------------

### score.py CLI Options

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/configuration.md

Complete list of command-line options for score.py, including type, default, and description for each argument.

```APIDOC
## score.py CLI Options

### Description
This is the command-line interface for the score.py script. It accepts various options to configure model checkpoints, input structures, residue selections, and scoring behavior.

### Usage
```
python score.py [options]
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--model_type` | str | `"protein_mpnn"` | Same 5 model families as `run.py` |
| `--checkpoint_protein_mpnn` | str | `"./model_params/proteinmpnn_v_48_020.pt"` | Model weights |
| `--checkpoint_ligand_mpnn` | str | `"./model_params/ligandmpnn_v_32_010_25.pt"` | Model weights |
| `--checkpoint_per_residue_label_membrane_mpnn` | str | `"./model_params/per_residue_label_membrane_mpnn_v_48_020.pt"` | Model weights |
| `--checkpoint_global_label_membrane_mpnn` | str | `"./model_params/global_label_membrane_mpnn_v_48_020.pt"` | Model weights |
| `--checkpoint_soluble_mpnn` | str | `"./model_params/solublempnn_v_48_020.pt"` | Model weights |
| `--verbose` | int | `1` | Print statements |
| `--pdb_path` | str | `""` | Input PDB |
| `--pdb_path_multi` | str | `""` | JSON `{pdb_path: ""}` |
| `--fixed_residues` | str | `""` | Residue codes to fix |
| `--fixed_residues_multi` | str | `""` | JSON `{pdb_path: [...]}` |
| `--redesigned_residues` | str | `""` | Residue codes to redesign |
| `--redesigned_residues_multi` | str | `""` | JSON `{pdb_path: [...]}` |
| `--symmetry_residues` | str | `""` | Symmetry groups (weight strings are not read for scoring) |
| `--homo_oligomer` | int | `0` | Auto symmetry groups |
| `--out_folder` | str | *(required)* | Output folder for `<name>.pt` |
| `--file_ending` | str | `""` | Output suffix |
| `--zero_indexed` | str | `0` | Declared with `type=str`; unused by `main()` |
| `--seed` | int | `0` | Random seed |
| `--batch_size` | int | `1` | Scoring batch size |
| `--number_of_batches` | int | `1` | Scoring repetitions |
| `--ligand_mpnn_use_atom_context` | int | `1` | 1 = use atom context |
| `--ligand_mpnn_use_side_chain_context` | int | `0` | Use side chains as context (`parse_all_atoms`) |
| `--ligand_mpnn_cutoff_for_score` | float | `8.0` | Cutoff used inside `featurize` |
| `--chains_to_design` | str | `None` | Chains to redesign (None = all) |
| `--parse_these_chains_only` | str | `""` | Chains to parse |
| `--transmembrane_buried` | str | `""` | Buried residues |
| `--transmembrane_interface` | str | `""` | Interface residues |
| `--global_transmembrane_label` | int | `0` | Global membrane label |
| `--parse_atoms_with_zero_occupancy` | int | `0` | Parse zero-occupancy atoms |
| `--use_sequence` | int | `1` | 1 = score with sequence info; 0 = backbone only |
| `--autoregressive_score` | int | `0` | 1 = use `model.score` |
| `--single_aa_score` | int | `1` | 1 = use `model.single_aa_score` |

### Notes
- The following options are declared but unused by `score.main`: `--zero_indexed`, `--temperature`, `--save_stats`, `--fasta_seq_separation`.

```

--------------------------------

### python run.py

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Runs the LigandMPNN or ProteinMPNN model for protein sequence design on a given PDB file. Accepts various command-line arguments to control the model type, checkpoint paths, and output settings.

```APIDOC
## [RUN] python run.py

### Description
Runs the LigandMPNN or ProteinMPNN model for protein sequence design on a given PDB file. Accepts various command-line arguments to control the model type, checkpoint paths, and output settings.

### Method
Command-line execution

### Endpoint
python run.py

### Parameters
#### Command-Line Arguments
- **--seed** (integer) - Optional - Random seed for reproducibility.
- **--pdb_path** (string) - Required - Path to the input PDB file.
- **--out_folder** (string) - Required - Output folder for results.
- **--model_type** (string) - Optional - Model type to use. Options: "protein_mpnn", "ligand_mpnn", "soluble_mpnn", "global_label_membrane_mpnn", "per_residue_label_membrane_mpnn". Default: "protein_mpnn".
- **--checkpoint_protein_mpnn** (string) - Optional - Path to ProteinMPNN checkpoint.
- **--checkpoint_ligand_mpnn** (string) - Optional - Path to LigandMPNN checkpoint.
- **--checkpoint_soluble_mpnn** (string) - Optional - Path to SolubleMPNN checkpoint.
- **--checkpoint_global_label_membrane_mpnn** (string) - Optional - Path to global label membrane model checkpoint.
- **--checkpoint_per_residue_label_membrane_mpnn** (string) - Optional - Path to per-residue label membrane model checkpoint.
- **--checkpoint_path_sc** (string) - Optional - Path to side chain packing model checkpoint.

### Request Example
```
python run.py \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/default"
```

### Response
#### Success Response
- Outputs .fasta and .pdb files in the specified output folder.
- Fasta files contain `overall_confidence` and `ligand_confidence` scores.

#### Response Example
No explicit response example provided.
```

--------------------------------

### ProteinMPNN.__init__ signature

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/model_utils.md

Constructor signature for ProteinMPNN. Parameters control architecture, graph construction, and feature extraction. Defaults are shown; k_neighbors is read from checkpoint by run.py.

```python
def __init__(
    self,
    num_letters=21,
    node_features=128,
    edge_features=128,
    hidden_dim=128,
    num_encoder_layers=3,
    num_decoder_layers=3,
    vocab=21,
    k_neighbors=48,
    augment_eps=0.0,
    dropout=0.0,
    device=None,
    atom_context_num=0,
    model_type="protein_mpnn",
    ligand_mpnn_use_side_chain_context=False,
):
```

--------------------------------

### Instantiate ProteinMPNN model

Source: https://github.com/dauparas/ligandmpnn/blob/main/_autodocs/api-reference/model_utils.md

Creates a ProteinMPNN model with typical hyperparameters, loads a checkpoint's state dict, moves to device, and sets to eval mode. Used by run.py and score.py.

```python
model = ProteinMPNN(
    node_features=128, edge_features=128, hidden_dim=128,
    num_encoder_layers=3, num_decoder_layers=3,
    k_neighbors=k_neighbors, device=device,
    atom_context_num=atom_context_num, model_type=args.model_type,
    ligand_mpnn_use_side_chain_context=ligand_mpnn_use_side_chain_context,
)
model.load_state_dict(checkpoint["model_state_dict"])
model.to(device)
model.eval()
```

--------------------------------

### Run global label membrane MPNN with --model_type "global_label_membrane_mpnn"

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Runs global label membrane MPNN, trained with an extra binary label input (1 for membrane, 0 for soluble).

```bash
python run.py \
        --model_type "global_label_membrane_mpnn" \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/global_label_membrane_mpnn_0" \
        --global_transmembrane_label 0
```

--------------------------------

### Use side chain context with --ligand_mpnn_use_side_chain_context

Source: https://github.com/dauparas/ligandmpnn/blob/main/README.md

Uses fixed residue side chain atoms as extra ligand atoms.

```bash
python run.py \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/ligandmpnn_use_side_chain_atoms" \
        --ligand_mpnn_use_side_chain_context 1 \
        --fixed_residues "C1 C2 C3 C4 C5 C6 C7 C8 C9 C10"
```