This repository contains the modified EvolveX implementation used in the optimisation stage of NOMINEE. Starting from nanobody–antigen complex structures and a defined set of mutable positions, EvolveX explores sequence variants using FoldX energy estimates.
This fork extends the original binding-centred search with a combined objective: favour predicted binding improvements, reward improved nanobody stability, and discourage unnecessary divergence from the original sequence. Structural checks, mutation limits, and composition-dependent proposal weights provide additional constraints during the search.
Overview · Scoring and acceptance · Design constraints · Outputs and interpretation · Code and integration · Attribution
EvolveX combines local Monte Carlo mutation steps with recombination between models derived from the same starting complex. FoldX evaluates proposed structures, and the search decides whether to retain each proposal or keep the current model.
The changes described here apply to the genetic algorithm / Monte Carlo search selected by search_algorithm: GA. The separate systematic search enumerates mutation combinations and does not use this acceptance rule.
| Component | Original EvolveX | This fork |
|---|---|---|
| Acceptance objective | Binding-energy changes | Combined binding, nanobody stability, and mutation-count changes |
| Structural checks | Hard stability and intraclash filters | Revised stepwise filters and a stability limit relative to the original nanobody |
| Sequence divergence | No explicit mutation-burden term in acceptance | A mutation-count penalty, a soft cap, and a hard cap |
| Mutation proposals | Fixed amino-acid proposal weights | Weights adjusted according to the current sequence composition |
| Search records | Structural and energetic properties of retained models | Additional proposed and retained objective changes, plus mutation burden |
For an energy score
Lower values are better: a negative binding change indicates improved predicted interaction energy, and a negative nanobody stability change indicates improved predicted stability.
The fork uses the following change in score for each proposal:
| Term | Meaning |
|---|---|
| Change in the binding objective, defined below | |
| Change in the FoldX stability energy of the nanobody chain group | |
| Change in the number of mutable positions that differ from the original sequence |
The coefficients are fixed in the current implementation.
The mutation term uses a count, rather than an unscaled fraction:
where
This lets stability improvements or a reduction in mutation burden offset a modest worsening in predicted binding energy.
With the standard FoldX calculation, the binding objective is simply the binding-energy change. When the optional water-aware calculation is enabled, the two changes are averaged:
After the hard checks described below, the combined score enters a Metropolis acceptance step:
Favourable moves pass this step, while unfavourable moves can still be retained probabilistically. The scale factor
Passing the Metropolis step does not guarantee final acceptance: the soft mutation cap can still reject a move that increases divergence.
The GA search applies structural checks from its first search iteration. A proposal is rejected if it:
- worsens nanobody stability by more than
$3.0$ in a single step; - increases the nanobody intraclash score by more than
$3.0$ in a single step; or - exceeds the following nanobody stability limit relative to the original input:
The last check limits accumulated stability drift across many individually permissible steps. It uses the more permissive of the two bounds shown above. Intraclash is a FoldX score and should be distinguished from the energy terms.
Mutation burden is defined over the mutable positions tracked by the search, not over the full nanobody sequence:
| Constraint | Behaviour |
|---|---|
| Soft cap: 25% | Above this fraction, an otherwise accepted move that further increases divergence faces an additional probabilistic rejection. |
| Hard cap: 50% | Proposals above this fraction are rejected. |
These mutation limits apply to proposals evaluated during the GA search; they are not enforced when generating the initial model population.
For divergence-increasing moves between the soft and hard caps, the probability of surviving the additional soft-cap check decreases linearly:
This additional check applies only when
The tab-separated input specified by PositionsToExplore_file_path uses AA_Allowed to restrict substitutions at each position. Set it to AUTO to screen candidate residues (with MakeAla=Y), a string such as KRH to allow K, R, or H, or a single one-letter code such as K to allow only K. Single-letter restrictions are supported.
MakeAla=Y replaces the position with alanine during initial preparation; MakeAla=N retains the original residue at that stage. At least one position must have MakeAla=Y. With MakeAla=N, a single allowed amino acid limits subsequent mutation proposals but does not force a change in the initial model.
The fork also adjusts how mutations are proposed, before they are evaluated. It monitors the combined fraction of F, H, I, R, W, and Y among the mutable positions and scales their baseline proposal weights as follows:
| Current fraction of these residues | Weight multiplier |
|---|---|
| Up to 15% | 1.0 |
| Above 15%, up to 30% | 0.7 |
| Above 30%, up to 40% | 0.5 |
| Above 40% | 0.3 |
The removed weight is redistributed proportionally among the other amino acids. Proposals still respect the allowed amino acids at each position.
This is a composition-control heuristic: it reduces further enrichment of the selected residue group without banning those residues. It is not an explicit prediction of aggregation, solubility, or experimental developability.
For the GA search, the main outputs are:
| Output | Contents |
|---|---|
generated_models_info.csv |
Search-step records, retained model properties, mutation acceptance, and objective diagnostics |
model_PDB_files/ |
Compressed PDB snapshots of the retained models |
EvolveX/ |
Per-backbone working files and mutation-screening results |
The CSV distinguishes proposed score changes from retained changes. Columns prefixed with proposed_ record the evaluated proposal even when it is rejected; the corresponding retained objective-delta columns are zero for rejected proposals. Mutation fraction and structural properties describe the retained state.
The package requires Python 3.9 or later and an external FoldX installation. Python dependencies and the evolvex command-line entry point are declared in setup.py.
For the integrated workflow, see NOMINEE. For the original EvolveX usage documentation and examples, see the upstream repository. The upstream example configuration and example dataset files are not bundled in this fork.
EvolveX was developed by Gabriel Cia and Rob Van Der Kant at SwitchLab. This repository is a modified fork of SwitchLab-VIB/EvolveX; the upstream project provides the underlying FoldX-based design framework.
Code is distributed under the Apache License 2.0. FoldX is obtained separately under its own licensing terms.