Published: Vol 16, Iss 22, Nov 20, 2026 DOI: 10.21769/BioProtoc.5885 Views: 151
Reviewed by: Emmanuel Pio PastoreAmr Galal Abdelraheem IbrahimMigla Miskinyte
Abstract
Engineering CRISPR nucleases with expanded protospacer-adjacent motif (PAM) compatibility can increase the number of genomic sites accessible to genome editing. This protocol describes a fully computational UniDesign workflow for engineering point-mutant Staphylococcus aureus Cas9 (SaCas9) variants with relaxed PAM recognition. Starting from the SaCas9–sgRNA–DNA complex structure, the protocol provides step-by-step instructions for installing and configuring UniDesign, preparing PAM-altered structural models, selecting mutable and repackable residues, constructing RESFILEs, performing three iterative design steps, and analyzing the resulting variants. The first step identifies substitutions that reduce energetic discrimination among four PAM models, yielding R1015H as the fixed background for subsequent design. The second step searches for compensatory mutations that restore protein–DNA binding strength through favorable, sequence-independent interactions. The third step combines promising substitutions to generate and prioritize triple mutants based on mean PAM-binding energy, mean absolute deviation, and structural plausibility. Designed for users with limited computational experience, this protocol enables reproduction of the SaCas9 PAM-relaxation workflow and provides an adaptable framework for engineering other protein–nucleic acid interactions.
Key features
• Provides a step-by-step, fully computational workflow for designing PAM-relaxed SaCas9 point-mutant variants using UniDesign.
• Uses mutation-count and duplicate-sequence constraints to efficiently generate diverse single, double, and triple mutants.
• Integrates cross-PAM energetic analysis with structural inspection to balance relaxed PAM specificity and retained protein–DNA binding strength.
• Can be adapted to other protein–nucleic acid interfaces by modifying the input structure, design sites, allowed substitutions, and mutation constraints.
Keywords: CRISPR–Cas9Graphical overview
Graphical overview of the three-step UniDesign workflow for the fully computational design of PAM-relaxed CRISPR–SaCas9 point-mutation variants. Step 1 relaxes specificity at PAM position 3 by sampling substitutions at Arg1015 and selecting the one with the lowest mean absolute deviation (MAD) of the binding energy across the four PAM models. Step 2 keeps R1015H fixed and searches for a second-site substitution that restores protein–DNA binding through sequence-independent contacts with the DNA sugar–phosphate backbone. Step 3 combines R1015H with two of the substitutions retained from step 2 and ranks the resulting triple mutants by mean PAM-binding energy, MAD, and structural plausibility. Each step is executed as 10 independent runs for each of the four PAM models, i.e., 40 UniDesign jobs per step. The recommended directory structure for these calculations is shown in Figure 1.
Background
Staphylococcus aureus Cas9 (SaCas9) is attractive for in vivo genome editing because its compact size facilitates packaging in adeno-associated virus vectors, but its NNGRRT protospacer-adjacent motif (PAM) restricts targetable loci. The third PAM position (G) is particularly stringent, as the guanine is specifically recognized via bidentate hydrogen bonds with Arg1015 in the SaCas9–DNA complex [1–3]. Earlier PAM-relaxed variants, including E782K/N968K/R1015H (KKH), were isolated through iterative mutagenesis and selection [4]. Such approaches can be effective but provide limited atomic-level guidance and may require substantial experimental screening.
UniDesign is a physics-based computational framework for modeling and designing proteins and protein–nucleic acid interactions [1,2,5,6]. The protocol presented here converts our research workflow reported by Xiong et al. [1] into an executable, stepwise procedure. Its design principle is to weaken the sequence-specific preference at the third PAM position and then restore overall binding through sequence-independent interactions with the DNA backbone. Four PAMs that vary only at position 3 are modeled, allowing each protein variant to be assessed for both mean binding strength and energetic uniformity.
Compared with unrestricted de novo design, the improved workflow directly controls the desired number of point mutations and penalizes previously saved sequences [1]. Compared with molecular dynamics/free-energy perturbation strategies [7], it is suitable for rapid screening of many local sequence combinations. Its principal limitations are the need for a reliable protein–single guide RNA (sgRNA)–DNA structure, dependence on the UniEF energy model within the UniDesign protein design package, stochastic sampling, and the need for experimental validation before any biological application.
The purpose of this protocol is to document the workflow in sufficient detail for reproduction and adaptation. The SaCas9 PAM-relaxation design serves as a worked example; however, UniDesign is a general computational framework applicable to other protein–nucleic acid interaction design problems, including the redesign of protein–DNA and protein–RNA interfaces. When adapting the protocol to another PAM position, nuclease, or protein–nucleic acid complex, users should preserve the overall design logic while modifying the structural input, mutable and repackable residues, allowed amino acid identities, interaction partners, and mutation-count parameters according to the specific system and design objective.
Equipment
1. A high-performance computing (HPC) cluster running a Linux-based operating system and using the Slurm workload manager
Note: The protocol was developed and tested on a cluster running Red Hat Enterprise Linux 8.10 (Ootpa) with Slurm v25.11.8 and the GNU C++ compiler g++ v8.5.0, loaded through the environment module system. Other Linux distributions, compiler versions, and Slurm versions are expected to work, because UniDesign depends only on the C++ standard library, and the custom scripts require only Python v3.10.14 and NumPy v1.26.4. Each UniDesign calculation is single-threaded, so the job template supplied with this protocol (scripts/submit_pam_relax_design.py) requests one node, one task (i.e., one CPU core), 5 GB of memory, and a wall-time limit of 24 h per job. Each design step comprises four PAM models × 10 independent runs = 40 such jobs, which are independent of one another and may be run concurrently or sequentially, so the elapsed time for a step depends mainly on how many of the 40 jobs the cluster can run at once. Per-job runtimes depend strongly on the search space defined by the RESFILE and on <n_designs>
2. A personal computer with network access to the HPC cluster
Software and datasets
1. Software
a. UniDesign (v1.3.0; open source; https://github.com/tommyhuangthu/UniDesign/releases/tag/v1.3.0 or https://github.com/tommyhuangthu/UniDesign)
Note: UniDesign v1.2 was used in the original study. Version 1.3 corrects several minor issues related to file processing. The core energy functions and protein-design parameters are unchanged between the two versions. UniDesign is distributed under the MIT license.
b. Python (v3.10.14; open source; https://www.python.org)
c. NumPy (v1.26.4; https://numpy.org/)
Note: NumPy is the only third-party Python package required by this protocol; it is used by analyze_common_mutants.py. All other custom scripts use only the Python standard library.
d. Custom Python scripts developed in the original study [1] and further improved for this protocol (https://zenodo.org/records/22650473). The archive is version v3 (released 7 September 2026), citable as DOI: 10.5281/zenodo.22650473, distributed under the Creative Commons Attribution 4.0 International license, and includes a README describing the inputs, the outputs, and the order in which the scripts should be run.
e. GNU C++ compiler, g++ (v8.5.0 tested; GNU General Public License; https://gcc.gnu.org), required to compile UniDesign
f. Slurm workload manager (v25.11.8 on the cluster used here; GNU General Public License; https://slurm.schedmd.com)
g. Optional but recommended:
i. Microsoft Office, installed on the personal computer, for reviewing and organizing tabulated results
Note: LibreOffice or another spreadsheet application, such as Apple Numbers, may be used as an alternative; the tabulated results can also be processed with Python or R.
ii. PyMOL (v2.6.2; https://github.com/schrodinger/pymol-open-source) or UCSF ChimeraX (v1.12; https://www.cgl.ucsf.edu/chimerax/index.html), installed on the personal computer for structural visualization and inspection
Note: The licensed version of PyMOL (v2.6.2) was used for structural visualization in the original study and this protocol. The open-source version of PyMOL or ChimeraX may be used as an alternative.
2. Datasets
a. Crystal structure of the SaCas9–sgRNA–DNA complex (PDB ID: 5axw; https://www.rcsb.org/structure/5axw)
b. Processed input datasets and UniDesign-generated output data provided for protocol reproduction and verification (https://zenodo.org/records/22650473)
Procedure
General notes:
1. Perform all procedures in a Linux environment (or macOS with compatible GNU tools) unless otherwise specified.
2. Adjust file paths and Slurm settings according to the local workstation or HPC environment.
3. Throughout this protocol, the UniDesign package, associated scripts, and input data are assumed to be located under /home/<USER>
A. Set up the recommended directory structure
1. Organize the files and directories as shown in Figure 1. Using this structure helps prevent errors caused by directory names or paths that are referenced by the Python scripts.

Figure 1. Recommended directory structure for CRISPR–Cas PAM-relaxed variant design. Run all scripts and procedures from the pam_relax directory unless otherwise specified. The data_files directory contains the PAM mutant file and the RESFILE files during iterative mutant design. The pdbs directory contains the original, cleaned, and PAM-altered Cas9–sgRNA–DNA complex structures in PDB format. The record directory contains Slurm submission scripts, output files, and log files. The scripts directory contains the associated Python scripts. The summary directory contains parsed and summarized energetic scores for UniDesign-generated point-mutant variants. The UniDesign directory contains the UniDesign software package.
B. Install and configure UniDesign and the associated scripts
1. Navigate to the pam_relax directory and clone the UniDesign repository from GitHub:
cd /home/<USER>/pam_relax git clone https://github.com/tommyhuangthu/UniDesign.git2. Navigate to the extracted UniDesign source directory and compile the program:
cd UniDesigng++ -O3 -o UniDesign src/*.cppA successful compilation generates an executable file named UniDesign. If compilation fails, confirm that a compatible GNU C++ compiler (g++) is installed and available in the current environment. On an HPC cluster, the compiler may need to be loaded through the environment module system. UniDesign is written in standard C/C++ and depends only on the C++ standard library; no external libraries, build system, or configuration step is required. The protocol was tested with g++ v8.5.0. The -O3 optimization flag is the only compiler flag used; it is recommended for speed but is not required for correctness.
Test the compiled executable:
./UniDesign -hA successful installation displays the UniDesign help and usage information, as shown in Figure 2.

Figure 2. UniDesign command-line help displayed after successful compilation
Note: The -h test confirms only that the executable starts. To confirm that UniDesign can also read a structure and complete a calculation, run the RepairStructure command on the downloaded coordinate file as described in step C1b below. Successful completion writes UD_RepairedStructure.pdb and thereby verifies the executable before the full design workflow is launched.
3. Return to the pam_relax directory, download the associated scripts, and extract the archive:
cd ..wget https://zenodo.org/records/22650473/files/scripts.zipunzip scripts.ziprm scripts.zipNote: If the unzip command is unavailable, install it or load the corresponding software module before extracting the archive.
4. Modify the following variables in scripts/submit_pam_relax_design.py to match the local UniDesign executable and Slurm configuration:
UNIDESIGN = "/home/<USER>/pam_relax/UniDesign/UniDesign" HPC_ACCOUNT = "<SLURM_ACCOUNT>" HPC_PARTITION = "<SLURM_PARTITION>" Replace <USER> with the user’s account name, <SLURM_ACCOUNT>
UNIDESIGN = "/home/xiaoqiah/turbo/work/UniDesign/UniDesign"HPC_ACCOUNT = "xiaoqiah0"HPC_PARTITION = "standard"Note: These are the only user-specific settings in the workflow. They are collected in a single configuration block at the top of each script: UNIDESIGN, HPC_ACCOUNT, HPC_PARTITION, HPC_MEMORY, and HPC_TIME in scripts/submit_pam_relax_design.py, and UNIDESIGN in scripts/make_structure_mutants.py. The path assigned to UNIDESIGN must point to the compiled UniDesign executable, rather than only to the directory containing it. Every other path used by the scripts is derived from the current working directory and from the directory structure shown in Figure 1, so no further editing is required provided that structure is used. HPC_MEMORY and HPC_TIME set the memory and wall-time requested for each Slurm job, default at 5 GB and 24 h, respectively, and may be adjusted to local queue limits.
C. Prepare the input data files
1. Preprocess the input structure
a. From the pam_relax directory, create the pdbs directory, download the SaCas9–sgRNA–DNA complex structure (PDB ID: 5axw), and move it into the directory.
mkdir -p pdbswget https://files.rcsb.org/download/5axw.pdbmv 5axw.pdb pdbs/b. Clean the downloaded structure and repair missing side-chain atoms using UniDesign’s RepairStructure command:
./UniDesign/UniDesign \--command RepairStructure \--pdb pdbs/5axw.pdbThis command generates a repaired structure named UD_RepairedStructure.pdb. Rename it using a shorter, more convenient name (e.g., 5axw1.pdb) and move it into the pdbs directory:
mv UD_RepairedStructure.pdb pdbs/5axw1.pdbc. Optional but recommended: Open pdbs/5axw1.pdb in PyMOL or ChimeraX and visually inspect the repaired structure before proceeding. Confirm that the SaCas9 protein, sgRNA, target-strand DNA, and non-target-strand DNA are present and that the protein and nucleic acid chains are correctly assigned.
2. Generate PAM-relaxed structural models
a. Generate a mutation file describing the desired PAM substitutions:
mkdir -p data_filespython scripts/make_dna_mut_files.py \> data_files/dna_mut_file.txtThe resulting data_files/dna_mut_file.txt contains the PAM mutations to be modeled, with one mutant specification per line.
With the default settings, data_files/dna_mut_file.txt contains the following four lines:
gD3a,cC6t;gD3c,cC6g;gD3g,cC6c;gD3t,cC6a;Each line specifies one PAM model and ends with a semicolon, the line terminator used for specifying a mutant in UniDesign; within a line, substitutions are separated by commas. Each substitution concatenates four fields: the native nucleotide in lower case, the chain identifier in upper case, the residue number, and the substituted nucleotide in lower case. Thus, “gD3a” replaces the guanine at residue 3 of chain D with adenine, and the paired “cC6t” replaces the complementary cytosine at residue 6 of chain C with thymine. The third line, “gD3g,cC6c;”, reproduces the wild-type PAM and therefore provides the reference model.
Note: By default, make_dna_mut_files.py relaxes the third position of the SaCas9 NNGRRT PAM, using pam = ['gD3'] and pamrc = ['cC6']. In 5AXW, the PAM is TTGGGT at nucleotides 1–6 of chain D, and its complement occupies positions 3–8 of chain C, so “cC6” is the cytosine base-paired with “gD3”. Numbering refers to the repaired structure pdbs/5axw1.pdb and is identical to that of the 5AXW entry, because UniDesign preserves the original numbering; confirm in PyMOL or ChimeraX that the selected nucleotides are the intended PAM bases. To relax other positions, edit both lists so that every PAM substitution is paired with its complementary substitution, and rerun the script: for example, pam = ['tD6'] with pamrc = ['aC3'] relaxes the last position of the NNGRRT PAM, and pam = ['gD3', 'tD6'] with pamrc = ['cC6', 'aC3'] relaxes both.
b. Generate the PAM-altered structural models
i. In scripts/make_structure_mutants.py, change the value assigned to the UNIDESIGN variable from
UNIDESIGN = "/home/xiaoqiah/turbo/work/UniDesign/UniDesign"to the path of the UniDesign executable in the user’s working directory:
UNIDESIGN = "/home/<USER>/pam_relax/UniDesign/UniDesign" Replace <USER>
ii. Run the modified script:
python scripts/make_structure_mutants.py \--pdb pdbs/5axw1.pdb \--mut-file data_files/dna_mut_file.txtThe script calls UniDesign’s BuildMutant function to introduce the nucleotide substitutions listed in data_files/dna_mut_file.txt into the repaired scaffold structure, pdbs/5axw1.pdb. It generates four PAM-specific structural models in the pdbs directory: 5axw1_g3a.pdb, 5axw1_g3c.pdb, 5axw1_g3g.pdb, and 5axw1_g3t.pdb.
iii. Generate a text file listing all “G3N” PAM-variant structures
cd pdbsls 5axw1_g3*.pdb | sort > ../list_5axw1_pam_relax_g3ncd ..Note: Confirm that the list contains all four expected “G3N” models before proceeding. Subsequent UniDesign calculations assume that the PAM-altered structures have been generated successfully and are present in the pdbs directory.
3. Select mutable and repackable sites
a. Generate a preliminary list of mutable and repackable protein residues:
python scripts/find_mutable_repackable_sites.py \pdbs/5axw1.pdb \> data_files/preliminary_design_sites.txtNote: In the original study [1], mutable and repackable sites were selected manually using a series of PyMOL “select” commands. Because this procedure was cumbersome and difficult to reproduce consistently, in this protocol, we developed find_mutable_repackable_sites.py to automate the design-site selection criteria described in the original study. The sites identified by this script may differ slightly from those reported in the original paper because the original site selection included minor manual adjustments.
By default, the script treats Arg1015 of chain A—the residue making the direct, base-specific contact with the PAM—as the reference residue and always keeps it mutable (--reference). The DNA reference set comprises the PAM (chain D, residues 1–6; --pam) and its complementary strand (chain C, residues 3–8; --reverse-complement), each extended by three nucleotides on either side (--flank); only their sugar–phosphate backbone atoms are used, because the aim is to find residues able to form sequence-independent contacts. A chain-A residue becomes a mutable site if at least three of its side-chain heavy atoms (CB included) lie within 4.5 Å of the Arg1015 side chain (--reference-cutoff) or within 6.0 Å of the selected DNA backbone atoms (--dna-cutoff); residues with fewer than three such atoms must satisfy the rule with all of them (--min-mutable-atoms). Any residue that is not mutable but has a side-chain heavy atom within 4.0 Å of one at a mutable site becomes a repackable site (--repack-cutoff). Hydrogen atoms are ignored, only the first model of the PDB file is read, and the highest-occupancy conformer is used where alternate locations are present. For every mutable site, the script also reports the angle between the Cα→side-chain-centroid and Cα→nearest-DNA-backbone-atom vectors, for the PAM alone and for the PAM plus the three flanking nucleotides; an angle below 90° (reported as “yes”) indicates that the side chain points toward the DNA. All cutoffs are command-line options, so the search space can be widened or narrowed as required.
b. Review the preliminary design sites in PyMOL. Open pdbs/5axw1.pdb, select the residues listed in preliminary_design_sites.txt, and inspect their locations relative to the PAM, PAM-complementary nucleotides, adjacent nucleotides, and neighboring protein residues. Adjust the mutable and repackable sites as needed. Confirm that the mutable sites are positioned to influence PAM recognition or protein–DNA interactions and that the repackable sites provide an appropriate local environment for accommodating structural changes at the mutable sites.
Note: This step determines which positions UniDesign is allowed to change and therefore affects every subsequent calculation. The following criteria are recommended when adjusting the preliminary list. Keep a residue as a mutable site when its side chain is oriented toward the PAM-proximal DNA, as reported in the orientation table written by find_mutable_repackable_sites.py, and lies within the PAM-binding region, so that a substitution could plausibly form a new contact with the DNA sugar–phosphate backbone. Add a residue that the distance cutoffs just missed but whose side chain clearly points at the PAM-proximal DNA backbone on visual inspection. Demote a residue to a repackable site, or remove it altogether, when (i) the orientation test reports “no”, i.e., the side chain points away from the DNA and into the protein interior; (ii) the side chain is buried and makes mainly packing interactions, so that mutation is more likely to perturb folding than to create a new DNA contact; (iii) the residue contacts the sgRNA or the target strand rather than the PAM duplex; (iv) the residue belongs to the HNH or RuvC catalytic center or to another functionally essential element; or (v) the residue is a glycine or a proline that is likely to be required for the local backbone conformation. Residues that are removed from the mutable list are normally retained as repackable sites so that they can still relieve strain introduced at neighboring mutable positions. In the present example, Lys886 and Asn985 were reported as not oriented toward the DNA (>90°) and were therefore not carried into the final mutable set.
c. To reproduce the original study, use the following final sets of design sites. Mutable sites are: Lys37, Glu782, Asn785, Asp786, Thr787, Tyr789, Asn803, Lys815, Lys818, Lys822, Tyr882, Asn885, Asn888, Ala889, Ser908, Leu909, Lys910, Pro911, Asn968, Ile982, Leu988, Glu993, Arg1002, Arg1012, Pro1013, Arg1015, and Thr1019. Repackable sites are: Ile784, Ile801, Asn804, Leu805, Asn813, Asp814, Leu827, Val905, Leu907, Lys929, Asn930, Arg980, Leu989, Arg991, Asn995, Tyr1001, Asp1010, Pro1014, and Ile1017.
d. Encode mutable and repackable sites in the UniDesign RESFILE format (see below). Verify chain IDs and residue numbers against the processed structure.
D. Design point-mutation variants
1. Run single mutants in step 1
a. Manually create the step-1 RESFILE and save it as data_files/resfile_pam_relax_g3n_step1.txt (content shown in Figure 3A). At position 1015, allow the native Arg and the selected polar or positively charged amino acids (Cys, His, Lys, Asn, Gln, Ser, Thr, and Tyr). Keep all other mutable positions at their native identities and allow the designated repackable sites to change side-chain conformations without changing their amino acid identities.
Note: The UniDesign RESFILE is a plain-text file that defines the design space and contains two blocks. SITES_DESIGN_START … SITES_DESIGN_END encloses the design (mutable) sites; each line has three whitespace-separated fields, namely the chain identifier, the residue number, and a string of one-letter amino acid codes listing the identities that UniDesign is allowed to place at that position. SITES_REPACK_START … SITES_REPACK_END encloses the repackable sites; each line has only the first two fields. In both blocks, text following the “#” symbol is a comment that records the native amino acid, which makes it easy to verify the file against the input structure. Residues that are not listed in either block are held completely fixed in both identity and conformation.
A position is therefore fixed at its native identity by listing it in the design block with only the native one-letter code (for example, “A 785 N # N”), allowed to mutate by listing the permitted one-letter codes (for example, “A 1015 CHKNQRSTY # R”, or the full string ACDEFGHIKLMNPQRSTVWY to allow all 20 standard amino acids), fixed at a chosen non-native identity by listing only that one code (for example, “A 1015 H # R”, which fixes R1015H), and allowed only to change its side-chain conformation by listing it in the repack block. The order of the letters does not affect the search.

Figure 3. Contents of the RESFILEs used to design PAM-relaxed SaCas9 point-mutant variants. (A) RESFILE used in step 1. (B) RESFILE used in step 2. (C) RESFILE used in step 3. In each RESFILE, the # symbol denotes a comment, and the letter following it indicates the native amino acid at the corresponding residue position. The first field of each line is the chain identifier and the second the residue number; lines in the SITES_DESIGN block carry a third field listing the allowed amino acid identities, whereas lines in the SITES_REPACK block have none. Section D1a explains how these entries are interpreted.
b. Submit the step-1 design calculations using the following argument structure:
python scripts/submit_pam_relax_design.py \<pdb1> <relaxed_pam> <step> <min_mut> < max_mut> <n_designs> <run> For step 1, use the following values: <pdb1>
Submit 10 independent runs:
for i in {1..10}; \do python scripts/submit_pam_relax_design.py \5axw1 g3n step1 0 1 20 run${i}; \doneThe submit_pam_relax_design.py script reads the list of four “G3N” PAM structures from the list_5axw1_pam_relax_g3n file, prepares a separate UniDesign calculation for each structure, generates the corresponding Slurm submission files, and submits the jobs to the HPC scheduler. The script also activates the mutation-count and duplicate-sequence penalties used in this protocol.
Note: Setting min_muts to 0 and max_muts to 1 permits both the wild-type sequence and single-mutant sequences. Independent runs improve sampling and allow the consistency of the calculated energies to be assessed. Setting n_designs to 20 specifies a maximum of 20 variants per design run; however, the actual number of unique variants is also limited by the amino acid identities allowed in the RESFILE. In the step-1 design, only nine unique variants are possible and therefore generated per run.
c. After all Slurm jobs have completed, verify that the expected output directories and files are generated. Under the naming convention used in this protocol, the step-1 calculations should produce 40 directories:
designs_pam_relax_g3n_step1/5axw1_g3{a,c,g,t}_run{1..10}_0_1/Confirm that all 40 directories are present and that each contains UD_designs.tsv, UD_seqs.tsv, and one or more structural models named UD_mod*.pdb. Do not proceed to the analysis step until all 40 jobs have finished: analyze_common_mutants.py pools the results of all four PAM models and all 10 runs before computing the per-variant statistics, and it will stop with an error or report statistics derived from incomplete output if any design job is still running.
d. From the pam_relax directory, summarize the step-1 results:
mkdir -p summarypython scripts/analyze_common_mutants.py \5axw1 g3n list_5axw1_pam_relax_g3n step1 0 1 \> summary/summary_5axw1_pam_relax_g3n_step1_0_1.tsvThe arguments correspond to: <pdb1>
Note: The summary file contains one row per variant and the following columns: “Variants” (column A); the four per-PAM mean binding energies g3a(bind_mean), g3c(bind_mean), g3g(bind_mean), and g3t(bind_mean) (columns B–E); the four corresponding standard deviations g3a(bind_std), g3c(bind_std), g3g(bind_std), and g3t(bind_std) (columns F–I); pam_bind_mean (column J) and pam_bind_MAD (column K); and then the same 10 columns for the stability energy, namely g3a(stab_mean), g3c(stab_mean), g3g(stab_mean), g3t(stab_mean), g3a(stab_std), g3c(stab_std), g3g(stab_std), g3t(stab_std), pam_stab_mean, and pam_stab_MAD (columns L–U).
The values are obtained as follows. For each PAM model, the UD_designs.tsv files of the 10 independent runs are pooled and grouped by variant; for each variant, the three models with the lowest stability energy are retained (--top-n, default 3), and their binding and stability energies are averaged to give that variant’s bind_mean, bind_std, stab_mean, and stab_std for that PAM model. pam_bind_mean is the arithmetic mean of the four per-PAM bind_mean values, and pam_bind_MAD is their mean absolute deviation; pam_stab_mean and pam_stab_MAD are defined analogously. Only variants recovered in all four PAM models are reported. All energies are given in UniDesign energy units (UEU), and more negative values are more favorable for both binding and stability.
The same column layout applies to the summary files generated in steps 2 and 3.
e. Open summary/summary_5axw1_pam_relax_g3n_step1_0_1.tsv and examine the pam_bind_MAD column together with the mean PAM-binding energy (Figure 4, columns K and J). A low mean absolute deviation (MAD) indicates similar predicted binding energies across the four “G3N” PAM models, whereas a favorable mean binding energy indicates retention of overall protein–DNA binding. Select a substitution that reduces PAM-dependent energetic variation. R1015H produced the lowest MAD of 0.62 UniDesign energy units (UEU; Figure 4A) and was therefore selected as the fixed background for the next step (Figure 3B). However, R1015H had a substantially less favorable mean binding energy than that of the native enzyme bound to its native PAM (Figure 4B and C). The objective of the subsequent steps is therefore to restore binding strength toward the native level while maintaining a low MAD.

Figure 4. Screenshot of mean binding energies and MAD scores across the four PAM models obtained from the step-1 design. Column A lists the variant; columns B–E give the mean binding energy of the variant in each of the four PAM models; columns F–I give the corresponding standard deviations; column J (pam_bind_mean) is the mean of the four per-PAM mean binding energies; and column K (pam_bind_MAD) is their mean absolute deviation. Columns L–U report the same quantities for the stability energy. All energies are in UniDesign energy units (UEU), and more negative values are more favorable. Red boxes labeled A, B, and C mark, respectively, the lowest pam_bind_MAD value, obtained for R1015H; the corresponding pam_bind_mean for that variant; and the binding energy of wild-type SaCas9 bound to its native PAM.
2. Design double mutants in step 2
a. Manually create the step-2 RESFILE and save it as data_files/resfile_pam_relax_g3n_step2.txt (content shown in Figure 3B). Fix position 1015 as His, allow the remaining mutable positions to sample the intended amino acid identities, and retain the same repackable sites used in step 1 (Figure 3B).
b. Submit 10 independent step-2 design runs:
for i in {1..10}; \do python scripts/submit_pam_relax_design.py \5axw1 g3n step2 2 2 1000 run${i};\doneThe parameter values are: <pdb1>
Note: Setting both mutation-count limits to 2 restricts the output to double mutants relative to wild-type SaCas9. Because R1015H is fixed (Figure 3B), each design contains R1015H and one additional mutation. Setting n_designs to 1,000 specifies a maximum of 1,000 variants per design run; however, the actual number of unique variants is also limited by the amino acid identities allowed in the RESFILE. In the step-2 design, no more than 500 unique variants were generated.
c. After all Slurm jobs have completed, verify that the expected output directories and files are generated. Under the naming convention used in this protocol, the step-2 calculations should produce 40 directories:
designs_pam_relax_g3n_step2/5axw1_g3{a,c,g,t}_run{1..10}_2_2/Confirm that all 40 directories are present and that each contains UD_designs.tsv, UD_seqs.tsv, and one or more structural models named UD_mod*.pdb. Do not proceed to the analysis step until all 40 jobs have finished: analyze_common_mutants.py pools the results of all four PAM models and all 10 runs before computing the per-variant statistics, and it will stop with an error or report statistics derived from incomplete output if any design job is still running.
d. Summarize the step-2 results:
python scripts/analyze_common_mutants.py \5axw1 g3n list_5axw1_pam_relax_g3n step2 2 2 \> summary/summary_5axw1_pam_relax_g3n_step2_2_2.tsve. Examine summary/summary_5axw1_pam_relax_g3n_step2_2_2.tsv and rank the double mutants according to the following criteria:
i. Favorable mean binding energy across the four PAM models (Figure 5, column J).
ii. A low pam_bind_MAD value (Figure 5, column K).
iii. Formation of favorable, sequence-independent contacts with the DNA sugar–phosphate backbone rather than new DNA base-specific interactions.
iv. Absence of severe steric clashes or unrealistic side-chain conformations.
Evaluate criteria iii and iv by visually inspecting the structural models in PyMOL or ChimeraX. Select promising second-site substitutions for combination in step 3 (Figure 3C). In the original study, these substitutions included N968R/K, E782K, T787W/F/M, N803K/W, Y882R, K37R, and K822R. Representative structural models are provided in the original article [1].
Note: Step 2 is intended to recover binding strength lost after replacing Arg1015 with His while maintaining similar binding energies across the four PAM models.

Figure 5. Screenshot of mean binding energies and MAD scores across the four PAM models obtained from the step-2 design. Column A lists the variant; columns B–E give the mean binding energy of the variant in each of the four PAM models; columns F–I give the corresponding standard deviations; column J (pam_bind_mean) is the mean of the four per-PAM mean binding energies; and column K (pam_bind_MAD) is their mean absolute deviation. Columns L–U report the same quantities for the stability energy. All energies are in UniDesign energy units (UEU), and more negative values are more favorable. Red boxes highlight pam_bind_mean and pam_bind_MAD (columns J and K), the two columns used to rank the double mutants.
3. Design triple mutants in step 3
a. Manually create the step-3 RESFILE and save it as data_files/resfile_pam_relax_g3n_step3.txt (content shown in Figure 3C). Keep R1015H fixed and restrict the other design positions to the favorable substitutions identified in step 2 and their native amino acid identities (Figure 3C).
For reproduction of the original study, use the following allowed identities: Lys37 → Lys or Arg; Glu782 → Glu or Lys;
Thr787 → Thr, Met, Phe, or Trp; Asn803 → Asn, Lys, or Trp; Lys822 → Lys or Arg; Tyr882 → Tyr or Arg; Asn968 → Asn, Lys, or Arg; and Arg1015 → His.
Fix all other mutable positions at their native identities and retain the designated repackable sites.
b. Submit 10 independent step-3 design runs:
for i in {1..10}; \do python scripts/submit_pam_relax_design.py \5axw1 g3n step3 3 3 1000 run${i};\doneThe parameter values are: <pdb1>
Note: Setting both mutation-count limits to 3 restricts the output to triple mutants relative to wild-type SaCas9. Because R1015H is fixed (Figure 3C), each design contains R1015H and two additional mutations. Setting n_designs to 1,000 specifies a maximum of 1,000 variants per design run; however, the actual number of unique variants is also limited by the amino acid identities allowed in the RESFILE. In the step-3 design, no more than 100 unique variants were generated.
c. After all Slurm jobs have completed, verify that the expected output directories and files are generated. Under the naming convention used in this protocol, the step-3 calculations should produce 40 directories:
designs_pam_relax_g3n_step3/5axw1_g3{a,c,g,t}_run{1..10}_3_3/Confirm that all 40 directories are present and that each contains UD_designs.tsv, UD_seqs.tsv, and one or more structural models named UD_mod*.pdb. Do not proceed to the analysis step until all 40 jobs have finished: analyze_common_mutants.py pools the results of all four PAM models and all 10 runs before computing the per-variant statistics, and it will stop with an error or report statistics derived from incomplete output if any design job is still running.
d. Summarize the step-3 results:
python scripts/analyze_common_mutants.py \5axw1 g3n list_5axw1_pam_relax_g3n step3 3 3 \> summary/summary_5axw1_pam_relax_g3n_step3_3_3.tsve. Open summary/summary_5axw1_pam_relax_g3n_step3_3_3.tsv and rank the triple mutants according to the following criteria:
i. Favorable mean binding energy across the four PAM models (Figure 6, column J).
ii. A low pam_bind_MAD value (Figure 6, column K).
iii. Formation of favorable, sequence-independent contacts with the DNA sugar–phosphate backbone rather than new DNA base-specific interactions.
iv. Absence of severe steric clashes or unrealistic side-chain conformations.
As in step 2, evaluate criteria iii and iv by visually inspecting the structural models in PyMOL or ChimeraX. Select the highest-ranked, structurally plausible triple mutants for experimental evaluation. In the original study, E782K/N968R/R1015H (KRH) had a mean binding energy of −513.75 UEU, close to that of the native enzyme bound to its native PAM (−514.65 UEU), together with a low MAD of 0.61 UEU. KRH was therefore selected as the leading computational design. In addition, the workflow independently recovered the evolution-derived KKH variant, E782K/N968K/R1015H, which ranked fourth in Figure 6. This result supports the ability of the computational workflow to identify functionally relevant mutation combinations.
Note: KKH contains N968K, whereas KRH contains N968R.

Figure 6. Screenshot of mean binding energies and MAD scores across the four PAM models obtained from the step-3 design. Column A lists the variant; columns B–E give the mean binding energy of the variant in each of the four PAM models; columns F–I give the corresponding standard deviations; column J (pam_bind_mean) is the mean of the four per-PAM mean binding energies; and column K (pam_bind_MAD) is their mean absolute deviation. Columns L–U report the same quantities for the stability energy. All energies are in UniDesign energy units (UEU), and more negative values are more favorable. Red boxes highlight pam_bind_mean and pam_bind_MAD (columns J and K), the two columns used to rank the triple mutants.
Validation of protocol
This protocol (or parts of it) has been used and validated in the following research article:
• Xiong et al. [1] Fully computational design of PAM-relaxed Staphylococcus aureus Cas9 with expanded targeting capability using UniDesign. eLife (Figure 1C–M and Supplementary file 1)
Computational validation included recovery of the evolution-derived KKH combination [4] among the top triple mutants, convergence assessment using repeated SAMC runs, and agreement between predicted cross-PAM energetic balance and experimentally observed PAM relaxation. KRH was selected directly from the computational workflow without an additional experimental optimization cycle [1]. In each design step, 10 independent runs were performed for each of the four PAM models, i.e., 40 independent calculations per step and 120 in total across the three steps, with up to 20 design trajectories per run in step 1 and up to 1,000 in steps 2 and 3. Convergence and reproducibility were assessed using the criteria given in General note 6 below. The specific validation results are shown in Xiong et al. [1]: Figure 1C–M and Supplementary file 1.
General notes and troubleshooting
General notes
1. The protocol is transferable to other Cas proteins only when a reliable nuclease–guide RNA–target DNA complex structure or model is available and the PAM nucleotides can be mapped unambiguously.
2. For a different PAM-relaxation objective, construct a representative PAM panel that changes the position of interest while holding other positions constant.
3. Sampling is stochastic. Report all independent repeats, not only the best-scoring trajectory, and use consistent computational resources and settings when comparing variants.
4. The distance-based site-selection rules define a local search space. Expanding the mutable shell may reveal additional solutions but increases runtime and risks perturbing distal structural roles.
5. Predicted energies and models prioritize candidates; they do not establish editing efficiency, specificity, protein expression, or cellular compatibility.
6. Convergence across independent runs can be assessed in practice as follows: First, analyze_common_mutants.py reports only variants that are recovered in all four PAM models, so repeated recovery across the four models is the first requirement. Second, the per-PAM standard deviations g3*(bind_std), which measure the spread among the three best models within a PAM model, should be small relative to the binding-energy differences that separate the top-ranked variants; if they are comparable, the ranking is not reliable. Third, the analysis can be repeated on subsets of the independent runs, for example runs 1–5 versus runs 6–10; the sampling may be regarded as converged when the identity of the top-ranked variants and the sign of their energy differences are preserved between subsets. If the top-ranked set changes substantially, increase the number of design trajectories (<n_designs>
7. For the resources requested per job and the typical runtimes of each step, see the Note in Equipment. Disk space also needs planning: In addition to UD_designs.tsv and UD_seqs.tsv, each job writes one or more UD_mod*.pdb models, so confirm that sufficient space is available in the designs_pam_relax_* directories before launching a step. For the SaCas9 example described here, the intermediate data—principally the structural models generated in 3 steps × 10 runs × 4 PAM models—together with the final results occupy up to 16 GB.
Troubleshooting
Problem 1: UniDesign fails to compile.
Possible cause(s): The GNU C++ compiler is unavailable, the compilation command is being executed from the wrong directory, or the local compiler configuration is incompatible with the supplied source code.
Solution(s): Confirm that g++ is installed and available in the current environment using:
g++ --versionRun the compilation command from the UniDesign root directory. If compilation still fails, save the complete compiler output and identify the first error before modifying the source code.
Problem 2: submit_pam_relax_design.py reports Can't exec sbatch.
Possible cause(s): The script is being executed on a computer that does not have Slurm installed, or the sbatch command is not available in the current environment.
Solution(s): Run the script on the intended Slurm-managed HPC cluster and confirm that sbatch is available:
which sbatchIf the calculations will be performed without Slurm, modify the job-submission portion of the script for direct local execution. Also, verify the UniDesign executable path and all cluster-specific settings, including the Slurm account and partition. Concretely, the generated job file is an ordinary bash script whose #SBATCH lines are simply comments to bash, so it is sufficient to replace the line subprocess.run(["sbatch", str(job_file)], check=True) in scripts/submit_pam_relax_design.py with subprocess.run(["bash", str(job_file)], check=True) to run the jobs sequentially, or with subprocess.Popen(["bash", str(job_file)]) to run them concurrently. Because each job is single-threaded, the number of concurrently launched jobs should not exceed the number of available CPU cores. When running locally, the standard output and error of each job appear in the terminal rather than in the record directory, so users may wish to redirect them to a file.
Problem 3: The submission or analysis script cannot locate the UniDesign executable, an input file, or an output directory.
Possible cause(s): One or more paths hard-coded in the helper scripts do not match the user’s working directory or the directory structure specified in this protocol.
Solution(s): Verify that the UniDesign executable path and working-directory variables in the Python scripts point to the correct locations. In particular, confirm that the UniDesign executable exists and is executable:
ls -l /home/<USER>/pam_relax/UniDesign/UniDesign Update all user-specific paths, Slurm settings, and output-directory paths before resubmitting the jobs.
Problem 4: UniDesign cannot read the input PDB file or RESFILE.
Possible cause(s): The input file is missing, incorrectly named, stored in an unexpected directory, or inconsistent with the path supplied to UniDesign. File capitalization may also differ because Linux-like systems use case-sensitive filenames.
Solution(s): Confirm that the input PDB file is located in the pdbs directory and that the appropriate RESFILE is located in data_files. Verify the exact filenames, capitalization, permissions, and paths used in the generated UniDesign command. Also confirm that both files are non-empty and use valid formatting.
Problem 5: An output directory is created, but the expected PDB or TSV files are missing or empty.
Possible cause(s): The Slurm job was submitted but subsequently failed because of an incorrect executable path, missing input file, malformed RESFILE, insufficient computational resources, or an invalid working directory.
Solution(s): Inspect the corresponding standard-output and error files in the record directory:
less record/<job_name>.out less record/<job_name>.err For local execution, inspect the terminal output. Identify the first reported error, then verify the UniDesign executable, input PDB file, RESFILE, working directory, and Slurm resource settings before rerunning the calculation.
Problem 6: The analyze_common_mutants.py script does not generate the expected summary TSV file.
Possible cause(s): The structure-list file, PAM identifier, design-step label, mutation-count arguments, directory names, or design outputs do not match the analysis command.
Solution(s): Confirm that <pdb1>
Problem 7: The mutations or energetic rankings differ among independent runs.
Possible cause(s): UniDesign uses stochastic sampling, and the design landscape may contain multiple near-optimal sequences with similar energies.
Solution(s): Compare energy distributions and recurring mutation patterns across all independent runs rather than relying on a single calculation. For exact reproduction, use the same processed structure, PAM models, RESFILE, mutation-count limits, number of designs, number of independent runs, and analysis procedure. If convergence remains poor, increase the number of designs or independent runs.
Problem 8: Unexpected residues are mutated or repacked.
Possible cause(s): The chain identifiers, residue numbers, native residue identities, or RESFILE definitions do not match the processed PDB structure.
Solution(s): Open the processed PDB structure in PyMOL or ChimeraX and verify each RESFILE entry against the intended chain, residue number, and native amino acid. Ensure that mutable and repackable sites are assigned the correct design instructions. Correct the RESFILE and rerun the affected design step.
Acknowledgments
This work was supported by the National Institutes of Health grant GM149016 (to X.H.). We thank the Advanced Research Computing (ARC) at the University of Michigan for providing the computational resources and services that supported this work. This protocol was used in [1].
Author contributions
Conceptualization, X.H.; Investigation, E.S.W., J.Z.X., and K.T.; Writing—Original Draft, E.S.W., J.Z.X., and K.T.; Writing—Review & Editing, Y.E.C. and X.H.; Funding acquisition, X.H.; Supervision, X.H.
Competing interests
The authors declare no conflicts of interest.
References
Article Information
Publication history
Received: Sep 9, 2026
Accepted: Oct 28, 2026
Available online: Nov 12, 2026
Published: Nov 20, 2026
Copyright
© 2026 The Author(s); This is an open access article under the CC BY license (https://creativecommons.org/licenses/by/4.0/).
How to cite
Readers should cite both the Bio-protocol article and the original research article where this protocol was used:
Do you have any questions about this protocol?
Post your question to gather feedback from the community. We will also invite the authors of this article to respond.
Share
Bluesky
X
Copy link

