Sidechain

Sidechain packing and mutation runner system for generating mutant protein structures.

Architecture Overview

The sidechain system uses a two-layer design:

1. SidechainSolver — A singleton that manages configuration and lifecycle. It reads the desired solver name, repack radius, and model from ConfigBus, then instantiates and caches the appropriate MutateRunnerAbstract subclass.
2. MutateRunnerAbstract — An abstract base class defining the interface for mutation runners. Concrete implementations (discovered via build_plugin_registry from REvoDesign.sidechain.mutate_runner) each wrap a specific sidechain packing tool.

SidechainSolver

Singleton that manages sidechain packing workflows. Reads configuration from the UI (solver name, repack radius, model), creates the appropriate mutate runner via MutateRunnerManager, and provides a refresh() method to reconfigure when settings change.

REvoDesign.sidechain.sidechain_solver.SidechainSolver

Bases: SingletonAbstract

SidechainSolverConfig

Immutable configuration dataclass holding the solver name, repack radius, and model. Supports change detection via reconfigured().

REvoDesign.sidechain.sidechain_solver.SidechainSolverConfig dataclass

MutateRunnerAbstract

Abstract base class for mutation runners. All mutation tools must implement run_mutate() (single mutation) and run_mutate_parallel() (batch mutation). Integrates with the citation system via CitableModuleAbstract.

REvoDesign.basic.mutate_runner.MutateRunnerAbstract

Bases: ThirdPartyModuleAbstract

Abstract base class for running mutation tools.

Subclasses should implement the specific methods for protein mutation, and optionally, reconstruction.

reconstruct()

Reconstruct the protein structure.

This method can be overridden by subclasses that support reconstruction. By default, it raises a NotImplementedError.

run_mutate(mutant) abstractmethod

Perform mutation on the protein and return the PDB path

Parameters:

Name	Type	Description	Default
mutant	Mutant	An object or data structure representing the mutation.	required

This method should be implemented by subclasses to provide the specific mutation functionality.

run_mutate_parallel(mutants, nproc=2) abstractmethod

Perform mutation on the protein in parallel and return the PDB paths

Parameters:

Name	Type	Description	Default
nproc	int	Nproc	2
mutants	list[Mutant]	An list object or data structure representing the mutation.	required

This method should be implemented by subclasses to provide the specific mutation functionality.

MutateRunnerManager

Dataclass that discovers and instantiates mutation runners by name. The get() static method looks up a runner class from the auto-discovered registry and returns an instance initialized with the provided PDB file, model, and radius.

REvoDesign.sidechain.sidechain_solver.MutateRunnerManager dataclass

Runner Registry

Auto-discovered mutation runners indexed by name. Created at import time by build_plugin_registry scanning REvoDesign.sidechain.mutate_runner for MutateRunnerAbstract subclasses.

Available Runners

The following runners are discovered from REvoDesign.sidechain.mutate_runner:

• DLPacker_worker ("DLPacker") — Deep learning sidechain packing
• DLPackerPytorch_worker ("DLPackerPytorch") — PyTorch port of DLPacker
• PIPPack_worker ("PIPPack") — Rotamer-based packing
• PyMOL_mutate ("Dunbrack Rotamer Library") — Dunbrack rotamer library via PyMOL
• DiffPack_worker ("DiffPack") — Diffusion-based sidechain packing
• MutateRelax_worker ("Rosetta-MutateRelax") — Rosetta mutation + relaxation

Registry Access

REvoDesign.sidechain.sidechain_solver.RUNNER_REGISTRY = build_plugin_registry(base_class=MutateRunnerAbstract, package='REvoDesign.sidechain.mutate_runner') module-attribute

REvoDesign.sidechain.sidechain_solver.ALL_RUNNER_CLASSES = list(RUNNER_REGISTRY.all_classes) module-attribute

REvoDesign.sidechain.sidechain_solver.IMPLEMENTED_RUNNER = RUNNER_REGISTRY.implemented_map module-attribute

Usage from Python

See the Programmatic Mutagenesis guide for a full walkthrough of generating mutant PDBs for downstream MD, docking, and free energy calculations.

The in-repo README at src/REvoDesign/sidechain/mutate_runner/README.md has additional examples including homooligomeric multi-chain mutants.

Basic workflow with any runner:

from RosettaPy.common.mutation import RosettaPyProteinSequence
from REvoDesign.tools.mutant_tools import extract_mutants_from_mutant_id
from REvoDesign.sidechain.mutate_runner import PyMOL_mutate

pdb_file = 'protein.pdb'
seq = RosettaPyProteinSequence.from_pdb(pdb_file, True)

mut_lists = ['AR42K', 'AV196A', 'AL268R', 'AR42K_AV196A_AL268R']
mut_objs = [extract_mutants_from_mutant_id(m, seq) for m in mut_lists]

worker = PyMOL_mutate(pdb_file)
pdb_paths = [worker.run_mutate(m) for m in mut_objs]