Proto is not affiliated with the Steinegger Lab and the Söding Lab. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.

```bibtex theme={null} @article{steinegger2017mmseqs2, title={MMseqs2 enables sensitive protein sequence searching for the analysis of massive data sets}, author={Steinegger, Martin and S{\"o}ding, Johannes}, journal={Nature Biotechnology}, volume={35}, number={11}, pages={1026--1028}, year={2017}, publisher={Nature Publishing Group}, doi={10.1038/nbt.3988} } @article{kallenborn2025mmseqs2gpu, title={GPU-accelerated homology search with MMseqs2}, author={Kallenborn, Felix and Chacon, Alvaro and Hundt, Christian and Sirelkhatim, Hassan and Didi, Kieran and Cha, Sooyoung and Dallago, Christian and Mirdita, Milot and Schmidt, Bertil and Steinegger, Martin}, journal={Nature Methods}, year={2025}, publisher={Nature Publishing Group}, doi={10.1038/s41592-025-02819-8} } @article{mirdita2022colabfold, title={ColabFold: making protein folding accessible to all}, author={Mirdita, Milot and Sch{\"u}tze, Konstantin and Moriwaki, Yoshitaka and Heo, Lim and Ovchinnikov, Sergey and Steinegger, Martin}, journal={Nature Methods}, volume={19}, number={6}, pages={679--682}, year={2022}, publisher={Nature Publishing Group}, doi={10.1038/s41592-022-01488-1} } ```

Copy citation

### MMseqs2 Protein Search (`mmseqs2-search-proteins`) Performs `mmseqs easy-search` of one or more protein query sequences against either a user-supplied target database or an inline list of target proteins. Returns the alignment hits per query, each with target identifier, percent identity, and E-value. The local execution mode runs on CPU by default and supports an opt-in GPU mode for searches against a prebuilt database with a GPU-padded index. #### API Reference

Source List of protein sequence strings (amino acid sequences) to search. Labeled positionally (`seq_0`, `seq_1`, ...) as `query_id` in the output; results are returned in input order.

Source Target DB (path/slug/AssetRef). Mutually exclusive with `target_sequences`; required at dispatch. Inline target sequences. Mutually exclusive with `mmseqs_db`; required at dispatch. CPU threads; `0` auto-detects all cores (the wrapper omits `--threads` since `mmseqs` rejects `--threads 0`). Split into N chunks to bound memory; `0` = auto. Max prefilter memory per split (e.g. `"90G"`); `None` uses all system memory. Prefilter sensitivity (1.0-7.5); higher = slower but finds more remote homologs. E-value threshold for reported hits. Minimum sequence identity (0.0-1.0) for reported hits. Minimum aligned-residue fraction (0.0-1.0); semantics depend on `cov_mode`. 0=query AND target, 1=target, 2=query, 3-5=length-ratio variants. Available options: `0`, `1`, `2`, `3`, `4`, `5` Max prefilter results per query. Wrapper filter; keep only the best hit (highest pident) per query sequence. Verbatim `mmseqs easy-search` CLI tokens for niche flags (e.g. `["--alignment-mode", "3"]`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. A `cuda` device runs MMseqs2-GPU (`--gpu 1`); requires a `.idx_pad` sibling on the target DB (built via `mmseqs makepaddedseqdb`). Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source List of search results, one per input sequence. The order matches the input sequences order. Identifier of the query sequence. The input query sequence. All hits found for this query, sorted by pident descending.

#### Applications This tool is appropriate for ad-hoc protein homology search at scale, ranking hits against a custom reference database, identifying functional homologs across a sequenced library, and any analysis in which the BLAST-style hit table is the deliverable. The MMseqs2 sensitivity model finds remote homologs that fall well below the sequence-identity range where standard BLAST searches lose signal. #### Usage Tips * **Targets are specified on `Mmseqs2SearchProteinsConfig` via either `mmseqs_db` or `target_sequences`, but not both.** Use `mmseqs_db` for a path to a FASTA file or a prebuilt MMseqs2 database when the target set is large or reused across calls. Use `target_sequences` for short inline lists. They live on Config because every query in a run searches against the same target collection. * **`mmseqs_db` is cached by path, not by contents.** The per-item cache key includes the path string but not the bytes at that path, so mutating the database in place (overwriting `/dbs/uniref90` with a new build at the same path) will silently return stale hits. If you swap a DB at a stable path, either clear the cache or use a versioned filename (`/dbs/uniref90_v2`) so the new path forces a fresh key. * **`sensitivity=5.7` is the wrapper default and matches upstream `easy-search`.** Higher values recover more distant homologs at the cost of additional runtime. The accepted range is 1.0 to 7.5. * **`only_top_hits=True` (the default) returns only the best hit per query by percent identity.** Set it to `False` to retain every hit that passes the configured thresholds. * **A `cuda` device requires a GPU-padded index alongside the target database.** Build the index once with `mmseqs makepaddedseqdb .idx_pad`. The configuration validator hard-errors when the `.idx_pad` companion is missing or when a `cuda` device is combined with inline `target_sequences` (the GPU path does not accept inline targets). * **`extra_args` accepts verbatim [`mmseqs easy-search`](https://github.com/soedinglab/MMseqs2/wiki#easy-search) CLI tokens.** Pass any flag not exposed as a typed field through this list (for example `["--alignment-mode", "3"]`). Tokens are appended after the typed flags.

### MMseqs2 Genome Search (`mmseqs2-search-genomes`) Performs the full MMseqs2 nucleotide search pipeline against either a user-supplied target database or an inline list of target genomes. The tool builds query and target databases with `createdb`, runs `search`, and converts the result to the BLAST-style tabular schema with `convertalis`. Runs on CPU only. #### API Reference

Source List of nucleotide sequence strings (DNA/RNA) to use as queries. Labeled positionally (`seq_0`, `seq_1`, ...) as `query_id` in the output; results are returned in query order.

Source Inline target genomes. Mutually exclusive with `target_db`; required at dispatch. Target FASTA or MMseqs2 DB stem (path/slug/AssetRef). Mutually exclusive with `target_genomes`; required at dispatch. CPU threads; `0` auto-detects all cores (the wrapper omits `--threads` since `mmseqs` rejects `--threads 0`). Prefilter sensitivity (1.0-7.5). Wrapper default 7.5 (upstream MMseqs2 = 5.7). E-value threshold for reported hits. Minimum sequence identity (0.0-1.0) for reported hits. Minimum aligned-residue fraction (0.0-1.0); semantics depend on `cov_mode`. 0=query AND target, 1=target, 2=query, 3-5=length-ratio variants. Available options: `0`, `1`, `2`, `3`, `4`, `5` Max prefilter results per query. 0=reverse, 1=forward, 2=both. Wrapper default 2 (upstream MMseqs2 = 1). Available options: `0`, `1`, `2` Verbatim `mmseqs search` CLI tokens for niche flags (e.g. `["--alignment-mode", "2"]`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source List of search results, one per input query genome. The order matches the input query genomes order. Identifier of the query sequence. The input query sequence. All hits found for this query, sorted by pident descending.

#### Applications This tool is appropriate for genome-to-genome similarity analysis, locating homologous regions between assembled genomes, comparative genomics over closely related strains, and any nucleotide analog of the protein-search workflow. #### Usage Tips * **Targets are specified on `Mmseqs2SearchGenomesConfig` via either `target_db` or `target_genomes`, but not both.** Use `target_db` for a FASTA file or a prebuilt MMseqs2 database; use `target_genomes` for inline nucleotide sequences. They live on Config because every query in a run scans against the same target collection. * **`target_db` is cached by path, not by contents.** The per-item cache key includes the path string but not the bytes at that path, so mutating the database in place will silently return stale hits. If you swap a DB at a stable path, either clear the cache or use a versioned filename so the new path forces a fresh key. * **`sensitivity=7.5` is the wrapper default for nucleotide search.** This is a wrapper bias above the upstream MMseqs2 default of 5.7, chosen because nucleotide searches typically benefit from the higher sensitivity setting. The accepted range is 1.0 to 7.5. * **`strand=2` (both strands) is the wrapper default.** Upstream defaults to forward strand only. Set `strand=1` to restrict to the forward strand or `strand=0` for reverse only. * **`extra_args` accepts verbatim [`mmseqs search`](https://github.com/soedinglab/MMseqs2/wiki#search-workflow) CLI tokens.** Tokens are appended after the typed flags.

### MMseqs2 Clustering (`mmseqs2-clustering`) Performs `mmseqs cluster` over an inline list of sequences or a prebuilt MMseqs2 database and returns per-sequence cluster assignments. Each result records the cluster identifier and whether the sequence is the cluster representative. Runs on CPU only. #### API Reference

Source Inline sequences to cluster. Mutually exclusive with `mmseqs_db`. Pre-built MMseqs2 DB (path/slug/AssetRef). Mutually exclusive with `input_sequences`. Optional IDs for inline sequences (defaults to seq\_0, seq\_1, ...).

Source Min identity (0.0-1.0) to share a cluster. Wrapper default 0.6 (upstream MMseqs2 = 0.0). Minimum aligned-residue fraction (0.0-1.0); semantics depend on `cov_mode`. 0=query AND target, 1=target, 2=query, 3-5=length-ratio variants. Available options: `0`, `1`, `2`, `3`, `4`, `5` E-value threshold for the prefilter step. 0=Set-Cover (greedy), 1=Connected component (BLASTclust), 2-3=Greedy by length (CD-HIT). Available options: `0`, `1`, `2`, `3` Max prefilter results per query. Prefilter sensitivity (1.0-7.5). Verbatim `mmseqs cluster` CLI tokens for niche flags (e.g. `["--similarity-type", "2"]`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source List of clustering results, one per input sequence. The order matches the input sequences order. Identifier of the input sequence. Original input sequence; `None` when the caller used `mmseqs_db`. Identifier of the cluster (usually the representative's ID). Whether this sequence is the cluster representative.

#### Applications This tool is appropriate for deduplicating a sequence set before downstream analysis, partitioning a protein library into functional families, selecting representative sequences from a redundant collection, and any analysis that benefits from a similarity-based grouping of sequences. #### Usage Tips * **Inputs are specified via either `input_sequences` or `mmseqs_db`, but not both.** Use `input_sequences` for inline sequences; use `mmseqs_db` for a prebuilt database that may be reused across calls. * **`mmseqs_db` is cached by path, not by contents.** The cache key includes the path string but not the bytes at that path, so mutating the database in place will silently return stale cluster assignments. If you swap a DB at a stable path, either clear the cache or use a versioned filename so the new path forces a fresh key. * **`min_seq_id=0.6` is the wrapper default.** This is a wrapper bias above the upstream MMseqs2 default of 0.0, chosen as a reasonable starting point for grouping proteins into functional families. Set it higher (for example `0.95`) to remove near-duplicates, or lower (for example `0.3`) to group remote homologs. * **`cluster_mode=0` (set-cover) is the default greedy algorithm.** Alternative modes are `1` (connected-component, BLASTclust-style) and `2` or `3` (greedy by length, CD-HIT-style). * **The cluster representative is the first sequence to cover the cluster during greedy set-cover.** It is not necessarily the longest or most central sequence. Choose an alternative `cluster_mode` if a different representative-selection policy is needed. * **`extra_args` accepts verbatim [`mmseqs cluster`](https://github.com/soedinglab/MMseqs2/wiki#clustering) CLI tokens.** Tokens are appended after the typed flags.

### MMseqs2 Homology Search (`mmseqs2-homology-search`) Generates a multiple sequence alignment per query protein using the ColabFold homology-search pipeline. Returns one `MSA` object per query, suitable as the MSA input to AlphaFold-class structure predictors. By default (`search_mode="remote"`) it queries the hosted ColabFold MSA API over the network and needs no local database; set `search_mode="local"` to run MMseqs2 against a registry-provisioned reference database on disk (GPU-accelerated by default on supported hardware). #### API Reference

Source List of query groups, in input order.

Source `"local"` runs MMseqs2 against a registry-provisioned DB on disk; `"remote"` (the default) queries the ColabFold MSA API over the network and needs no local DB. Available options: `local`, `remote` Local-only (ignored when remote). Registered key of the searchable reference database; one ColabFold protein DB. Available options: `colabfold-envdb-202108`, `uniref30-2302` Include the metagenomic/environmental DB (ColabFoldDB envdb) to deepen unpaired MSAs. Works in both modes; local mode requires the `colabfold-envdb-202108` dataset provisioned. Default `False`. Does not affect cross-chain pairing. Cross-chain pairing strategy for paired (multi-chain) groups. `"greedy"` pairs a species found in at least two chains; `"complete"` only pairs a species present in every chain. Ignored for singleton groups. Available options: `greedy`, `complete` Local-only (ignored when remote). MMseqs2 `-s` override; ignored on a `cuda` device. `None` uses the dataset's registered default. Local-only. CPU threads; `None` auto-detects all cores. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Local-only (ignored when remote). A `cuda` device runs MMseqs2-GPU and requires a `.idx_pad` index, an NVIDIA GPU (Turing+), and a Linux host; `"cpu"` (the default) runs the CPU pipeline. A specific device such as `"cuda:1"` is honoured. Local subprocess cap, or seconds to wait for a remote submission. Generous by default: the MSA server queues, and a submission carries many queries. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source One result per input group (matches the order of `Mmseqs2HomologySearchInput.queries`). Identifiers for the chains in this group. Per-chain unpaired MSAs. `None` when no homologs were found beyond the query itself. Per-chain taxonomy-paired MSAs, row-aligned across the group's chains. `[None]` for singleton groups (nothing to pair). Registry keys of datasets hit for this group. Number of homologs per chain (excludes the query itself).

#### Applications This tool is the proto-tools entry point for generating the MSA input to structure-prediction tools. It also drives coevolutionary analyses that identify covarying residue pairs as candidate spatial contacts, conservation analyses that highlight functionally important residues, and homolog mining for protein engineering and design pipelines. #### Usage Tips * **The `dataset` field selects one registered reference database.** The default is `uniref30-2302`. It is a scalar enum of the searchable ColabFold-style protein databases; non-searchable or non-protein datasets are rejected by validation. * **`search_mode="remote"` is the default.** It queries the hosted ColabFold MSA API over the network; `dataset`, `device`, and `sensitivity` are ignored, and no local database or GPU is required. Set `search_mode="local"` to run MMseqs2 against a provisioned on-disk database instead. * **Local mode (`search_mode="local"`) runs on CPU unless `device` names a CUDA device.** Set `device="cuda"` (or a specific `cuda:N`) to run MMseqs2-GPU; the configuration validator hard-errors for a CUDA device on a local search on macOS or Windows, since GPU search is Linux-only. * **Local mode requires the reference database to be provisioned once before the first call.** Run `python -m proto_tools.tools.sequence_alignment.mmseqs2.setup_databases `, where the dataset key matches the value of `Mmseqs2HomologySearchConfig.dataset`. The wrapper does not auto-download databases at call time. (Remote mode skips this entirely.) * **Local search needs enough RAM to hold the dataset's sequence database.** When available memory (cgroup-aware) is below that file's size, the tool logs a warning and falls back to a disk-paged (mmap) search that completes but is much slower; for a responsive search, allocate more memory or use `search_mode="remote"`. * **Each query produces an `MSA` object or `None`.** Always check `result.msas[i] is not None` before accessing alignment properties. The `num_homologs_found` list returns `0` for queries that produced no homologs. `MSA` objects serialise to A3M or FASTA through the standard export interface.