EMAP-SSN: Embedding- and Multiple-Alignment-integrated Protein Sequence Similarity Network Platform

Abstract

EMAP-SSN v0.3.0 EMAP-SSN v0.3.0 adds 3D layout generation with reproducible seeds and an optional VR viewer, protein-property metadata computed from the input FASTA, and residue-level alignment inspection over MCP. It installs ESM and Transformers from PyPI instead of bundling wheels, moves the managed environment to Python 3.13, and consolidates AMD support into a single ROCm 7.14 backend. Upgrading from v0.2.0? Read the Upgrade Notes below first. Saved color scale commands, alignment references, ESMC and ProstT5 embedding files, and the ESM-2 3B/15B models are affected, and the managed environment is rebuilt on first launch. Highlights 3D layouts and reproducible seeds: The physics and UMAP engines generate 2D or 3D coordinates (LAYOUT_DIMENSIONS), and LAYOUT_SEED (default 42) makes UMAP and CPU physics layouts reproduce exactly. 3D caches serve the new optional VR viewer; the desktop Viewer keeps using 2D layouts. Optional VR viewer (opt_vr): A Git submodule (EMAP-SSN-VR) that opens 3D caches in a headset on Windows with a supported NVIDIA or AMD GPU and an OpenXR runtime such as SteamVR. Fetch it with git clone --recurse-submodules or git submodule update --init opt_vr; GitHub source archives do not include it. Its Godot 4.7.2 client 1.0.0 is downloaded from the EMAP-SSN-VR releases and checked against a pinned SHA-256. Protein properties as metadata: New layout caches carry Length, kDa, pI (Bjellqvist), and GRAVY columns computed from the input FASTA, and metadata ranges accept negative bounds such as {GRAVY=(-1)-0}. Residue-level inspection over MCP: get_summary with include_alignment freezes the displayed alignment into a snapshot, the new get_residue_distribution returns paged per-position residue counts with cluster and group cross-tabulations, create_subset accepts residue predicates, and query_nodes gains a fields projection. No bundled Python wheels: The MIT-licensed esm 3.4.1.post1 and the Apache-2.0 transformers 5.17.0 are installed from PyPI, which removes the project's wheel-redistribution obligations entirely. Python 3.13 and one ROCm backend: The managed environment moves to Python 3.13, and Windows and Linux share a single ROCm 7.14 profile from AMD's multi-architecture channel. On Linux, AMD GPUs outside the model-name snapshot, including Instinct and RDNA1/RDNA2 parts, can now resolve their target from the ROCm runtime. Upgrade Notes color scales use a trailing x: Write 2x, 0.5x, or 0x. The prefix form is removed: x2 now selects residue X at position 2, and uppercase C always selects a cysteine. Alignment references resolve against the network headers: An exact header first, then a leading identifier, then a substring or wildcard match, and the alignment anchors only on that header. A saved ALIGNMENT_REFERENCE can therefore anchor on a different sequence than in v0.2.0, or stay inactive when the MSA lacks it, and positions in residue commands change with it. ESM-2 3B and 15B are no longer supported: esm2_t33_650m is the largest ESM-2 model. Saved settings that name esm2_t36_3b or esm2_t48_15b must select another model, and embedding files made with them can no longer be resumed, extended, or queried. Regenerate ESMC and ProstT5 embedding files: ESMC now runs in float32 on every device, and ProstT5 loads the unrounded Rostlab/ProstT5 checkpoint (an 11.3 GB download), so new embeddings differ from v0.2.0's. Do not resume or extend v0.2.0 files for these models. Regenerate layout caches to get the new metadata columns: Caches written by v0.2.0 still open, without metadata columns. Windows ROCm requires Windows 11 25H2: On earlier builds, AMD GPUs fall back to the next eligible accelerator or the CPU. The managed environment is rebuilt on first launch with Python 3.13. Only the EMAP-SSN and EMAP-SSN Tools launchers rebuild it, so close EMAP-SSN windows and MCP clients, launch EMAP-SSN or EMAP-SSN Tools once, and then restart the MCP clients. Restart Viewers that were running during the upgrade before inspecting them over MCP. VR client installed before 2026-10-01? The client 1.0.0 asset was rebuilt with the VR logo under the same version, so an installed 1.0.0 is kept as current; run opt_vr\install_vr.bat --reinstall to replace it. See the changelog for the complete notes. What's Changed Added 2D or 3D layout generation (LAYOUT_DIMENSIONS) for the physics and UMAP engines in layout settings, Layout_Cache_Generator.py, and emapssn_pipeline(action="start_layout_job"). 3D caches live in _3D folders, and 3D physics layouts place components on concentric spherical shells. LAYOUT_SEED (default 42; null opts out) for the physics and UMAP engines. FASTA-derived Length, kDa, pI, and GRAVY metadata in every new layout cache. Parenthesised negative bounds in metadata ranges, such as {GRAVY=(-1)-0}. Alignment snapshots, get_residue_distribution, residue predicates in create_subset, and query_nodes field projection for MCP agents. XPU eligibility for the integrated Intel Arc 130V/140V and 130T/140T GPUs on Windows; Arc B370/B390 now rank as integrated GPUs. The optional opt_vr submodule with the EMAP-SSN-VR viewer for 3D caches. src/esm_runtime_requirements.txt, declaring ESM's runtime dependencies. Linux AMD target resolution from rocm_agent_enumerator/rocminfo for GPUs outside the model-name snapshot. Changed esm 3.3.0 → 3.4.1.post1 and transformers 4.57.6+biohub.3a8956f → 5.17.0, both from PyPI; torch pinned to 2.12.0 on every backend; numba 0.67.0 with numpy 2.5.3, plus routine dependency updates. One ROCm 7.14 backend for Windows and Linux replaces the four ROCm profiles. The managed environment targets Python 3.13. Backend state moves to schema 6 and compatibility revision 7, and its requirement-file fingerprints ignore comments, blank lines, and line endings. Every local pLM plugin requests float32 weights explicitly. ESMC loads the bare EsmcModel and EsmcTokenizer, ProstT5 loads Rostlab/ProstT5, and the Ankh adapter compensates for the Transformers 5 T5 tokenizer. Generate_Embeddings.py hides Transformers weight-load reports whose only entries are unused pretraining tensors. validate_package_consistency parses uv pip check output and accepts only the documented deviations. color and spectrum prefer a valid selection expression over a color or colormap name, and color scales take a trailing x, so C53 and x2 select residues. Node metadata is created during layout-cache generation, and Length is now a floating-point column, so MCP returns values such as 350.0. Viewer settings accept an MSA that lacks ALIGNMENT_REFERENCE and fall back to occupancy numbering with a warning. MCP parameters jobs use the project's saved Tools directories, and start_layout_job re-reads the saved layout directory on every call. Selection-neighbor lookups use a cached CSR adjacency index, and the Viewer skips unnecessary edge-geometry uploads. Metadata handling moved into src/Metadata_Core.py, which the VR viewer shares. load_alignment_smart and resolve_selected_cache return a single value instead of a pair. The MCP server reports version 0.11.0. Fixed logo positions match query numbering when no reference is active. print svg applies the screen's edge filter and the configured EDGE_COLOR and NODE_BOUNDARY_COLOR. Alignment references resolve with one rule everywhere, including wildcards, the success message, and the Configuration consistency check. Headless Viewer launches through MCP on Windows no longer open a stray terminal window. Sanitize Sequences no longer drops the first record of a FASTA file saved with a UTF-8 byte-order mark. The Configuration window keeps its normalization-mode options in sync with the score mode. label reads 0.5% as half a percent and rejects nan and inf thresholds. The MCP command catalog reads help text whole and catalogs alternative usage lines. The in-app agent's system prompt now matches the parser: header lists are @FILE@, the viewer snapshot block is named correctly, and subcluster takes a bare cluster_N. select save is accepted only in its leading form, and select save .fasta saves the sanitized sequences the Viewer loaded, under their canonical headers. spectrum treats infinite values as invalid, and color rejects negative, NaN, and infinite scales. subcluster clear and subcluster cluster_N remove only generated subcluster labels. start_layout_job rejects unknown or misplaced parameters keys instead of ignoring them. Removed ESM-2 esm2_t36_3b and esm2_t48_15b, and the prefix x scale syntax of color. The bundled ESM and Transformers wheels and their verification path. The Windows ROCm 7.2.1 profile, its AMD Software version gate, and the other legacy ROCm profile names. The unused agent_config.json, the non-sparse alignment code path, unused frequency helpers, and the reference lookup in resolve_selected_cache. Full Changelog: https://github.com/Xuebin-Feng/EMAP-SSN/compare/v0.2.0...v0.3.0