multiObjectiveDesign

MultiObjective Design for Protein Engineering

Overview

multiObjectiveDesign is a Python toolkit for running iterative, multi-objective optimisation loops on protein sequences. At its core it combines a genetic algorithm with a pluggable catalogue of metrics (e.g. ProteinMPNN, PyRosetta, FrustraR), allowing you to trade off stability, designability, frustration and custom objectives while keeping full visibility into each iteration.

Installation

The core package is a standard Python project defined by pyproject.toml and can be installed with either pip or mamba/conda.

With pip

# from PyPI
pip install protein_mood

# from a clone of the repository
pip install .

# editable / development install
pip install -e ".[dev]"

# straight from GitHub
pip install "git+https://github.com/AlbertCS/multiObjectiveOptimizationDesign.git"

A plain install pulls in only the lightweight scientific stack (numpy, pandas, scipy, scikit-learn, matplotlib, seaborn, biopython, overrides, tqdm, icecream). The heavier predictors are grouped into optional extras:

pip install ".[esm]"      # deep-learning metrics
pip install ".[all]"      # everything

PyRosetta is not distributed on PyPI. After installing the rosetta extra, download the wheel with:

python -m pyrosetta_installer  # or: pyrosetta-installer

With mamba / conda

An environment.yml is provided that builds an env named mood with the core stack (plus notebook tooling and PyTorch) and pip-installs the package in editable mode:

mamba env create -f environment.yml   # or: conda env create -f environment.yml
mamba activate mood

The package is also published on the bsc-eapm anaconda.org channel, so you can install it directly:

mamba install -c bsc-eapm -c conda-forge protein_mood

-c conda-forge is required so the scientific dependencies resolve.

For fully-pinned, reproducible environments used on HPC, see the lock files in configs/ (mood-dev.yml, mood-esmc.yml, mood-esmfold2.yml).

ProteinMPNN model weights

The ProteinMPNN weights (~70 MB) are not bundled with the package. The first time a ProteinMPNN metric runs, the required .pt file is downloaded, checksum-verified and cached under ~/.cache/mood/ (override with $MOOD_CACHE_DIR). You can control this:

Passing path_to_model_weights to the ProteinMPNN metric bypasses all of the above and uses that directory directly.

Verify the install

mood --help                 # console entry point
python -c "import mood; print('ok')"

Project layout

• mood/multiObjectiveOptimization.py – high-level orchestration that prepares folders, restores previous runs, evaluates metrics and persists artefacts.
• mood/optimizers/ – optimisation strategies. Currently the genetic algorithm is implemented with modular crossover/mutation helpers and a rich mutation biasing subsystem.
• mood/metrics/ – collection of metric classes with a shared interface. Each metric computes a dataframe of scores for the candidate sequences and exposes selection orientation (min/max) metadata used during ranking.
• mood/base/ – lightweight data structures (sequences, logging, state) shared across the codebase.
• mood/utils/ – utilities for structure handling, plotting, ProteinMPNN wrappers and misc helpers required by the optimiser/metrics.
• configs/ – ready-to-run JSON configurations demonstrating typical setups.
• tests/ – pytest/unittest suites covering the core pieces (GA, selection strategies, CLI integration, metrics) plus example notebooks for exploratory runs.

For a detailed catalogue of available metrics, their objectives, and example configurations, see For a detailed catalogue of available metrics, see Metrics overview

CLI Generator

The CLI now generates ready-to-run replica scripts instead of executing an optimisation in-place. Given a JSON/YAML config it produces:

• setUp_<folder_name>_<replica>.py scripts mirroring our manual setup style.
• A SLURM array runner that dispatches the correct setup per SLURM_ARRAY_TASK_ID.

Quick start

python3 -m mood.cli \
  --config configs/toy_example.json \
  --replicas 2 \
  --seed-start 1234 \
  --seed-step 1

Outputs are written to folder_name/ (or --output-prefix). Each replica inherits your config, with {seed} placeholders replaced by seed-start + index * seed-step.

HPC-friendly generation

Provide a preamble snippet and Python interpreter to match your cluster:

python3 -m mood.cli \
  --config configs/toy_example.json \
  --replicas 4 \
  --seed-start 1235 \
  --python-exec /path/to/conda/env/bin/python \
  --preamble-file configs/runner_preamble.sh \
  --ntasks 80 --cpus-per-task 1 --time 02-00:00:00

Submit the generated folder_name/runner_array.sh via sbatch. Re-run the CLI with --overwrite to refresh existing scripts. Check python3 -m mood.cli --help for the full option list.

Typical workflow

1. Prepare inputs – provide a native PDB (or scaffold), choose metrics, and declare mutable/fixed positions in your config. The metrics module exposes helpers to pre-compute ProteinMPNN priors or frustration files if needed.
2. Tune optimisation knobs – set population size, mutation/crossover cycle, parent-selection strategy (rank, crowding, objective bias) and iteration count in the configuration file.
3. Generate runners or integrate directly – use the CLI generator to emit replica setup scripts for HPC runs, or instantiate MultiObjectiveOptimization directly inside your own pipeline.
4. Inspect outputs – each iteration folder contains pickled sequences, per-chain dataframes, optional Pareto plots, and the metric-specific raw artefacts. The most recent iteration can be resumed without losing progress.

Development notes

• All metrics inherit from mood.metrics.metric.Metric; to add a new metric, implement compute, setup_iterations_inputs, and clean, populating the state (orientation) and objectives lists.
• Optimisers rely on AlgorithmDataSingleton to store sequences; when implementing alternative algorithms, follow the contract exposed by mood/optimizers/optimizer.py.
• The repository includes high-level regression tests (tests/test_top7.py, tests/test_mood.py) and targeted unit tests for selection strategies, mutation handlers, and metrics. Run python -m pytest before submitting changes.

Further reading

• Zitzler, Deb, Thiele (2000) – origin of the ZDT benchmarks used in mood/optimizers/benchmarks.py.
• ProteinMPNN and PyRosetta official documentation for understanding the external predictors invoked by this project.