Coverage: Python tests plus JavaScript unit tests, uploaded by the Linux/Python 3.14 CI lane on eligible full runs; weekly and conditional nightly recovery retain the existing cadence. This report does not cover all browser, GUI or GPU behavior. The badge reflects the last uploaded report, which may lag later direct or skip-CI commits; it does not certify a full matrix or scientific correctness.
A Mol*-powered interactive molecular viewer for Jupyter, built around the idea that exploratory science should become reproducible science.
MolSysViewer is a modern 3D molecular visualisation tool built on the Mol* engine and exposed through a clean Python API. It renders structures, trajectories, and scientific overlays directly inside Jupyter notebooks and JupyterLab — and it is designed so that every meaningful thing you do interactively can be captured as replayable, exportable Python state.
Documentation: https://www.uibcdf.org/molsysviewer
import molsysviewer as msv
# A PDB ID, a local file, or a URL
view = msv.new_view("1TRS")
view.show()Objects you already have in memory go straight in:
import mdtraj as md
import molsysmt as msm
import molsysviewer as msv
traj = md.load(msm.systems["pentalanine"]["traj_pentalanine.h5"])
view = msv.new_view(traj) # an mdtraj.Trajectory: 62 atoms, 5000 structuresMDAnalysis Universe and AtomGroup objects, OpenMM topologies, and a long
list of file formats work the same way: new_view hands whatever you give it to
MolSysMT's convert, so anything MolSysMT
reads is accepted. Selections can be written in MolSysMT's own syntax or in
MDTraj's (syntax="MDTraj").
view = msv.demo["1TCD"] # triosephosphate isomerase, a dimer
view.make_regions_by(element="chain") # -> "A", "B", and the waters "A__2", "B__2"
view.regions["A"].set_representation("cartoon")
view.regions["A"].set_color("teal")
view.regions["B"].set_representation("spacefill")
view.regions["B"].hide() # a region can hide once it draws itselfimport numpy as np
import pyunitwizard as puw
atom_indices = view.regions["A"].atom_indices
view.shapes.add_displacement_vectors( # e.g. an ANM mode
origins=None, # None -> use the current atom positions
vectors=puw.quantity(np.random.randn(len(atom_indices), 3) * 0.5, "angstroms"),
atom_indices=atom_indices,
tag="anm-mode-0",
)Magnitudes carry units throughout the suite: a bare array is refused rather than silently assumed to be in Å.
view.export.html("my_scene.html", title="TIM — chain A")view.set_panel_mode("navigate", expanded=True) # native molecular toolsEverything above — and everything you do by hand in the Studio panel — is scene state, and scene state is a plain dictionary:
view.save_state("scene-state.json")
# later, on another machine, or as a paper's supplementary material
restored = msv.demo["1TCD"]
restored.load_state("scene-state.json")restored now carries the same regions, colours, representations, visibility and
overlays as the view you had been clicking around in. That round trip — not the
feature list below — is what MolSysViewer is for. The file stores scene state,
not the molecular system itself, so load the same or a compatible structure
before calling load_state().
- Load PDB/mmCIF strings, remote PDB IDs, URLs, or native MolSysMT systems
- High-quality Mol* rendering: cartoon, surface, ball-and-stick, spacefill, and more
- Built-in representation styles and publication-ready presets
- Multi-structure trajectory playback with configurable frame rate
- Regions — named atom subsets with independent visibility, colour, and representation
- Layers — non-structural visual groups (shapes, overlays) with tag-based lifecycle
- Styles — reusable scene recipes applied globally or per region
view.whole,view.regions,view.layersas first-class Python objects
- Displacement vectors, link shapes, H-bond overlays, anisotropy ellipsoids
- Pocket blobs, pocket surfaces, channel tubes
- Pharmacophore glyphs (donors, acceptors, hydrophobic patches, aromatic rings)
- Sphere and triangle-face primitives
- Persistent labels anchored to atom selections (
view.annotations) - Interactive distance, angle, and dihedral measurements (
view.measurements) - Canvas pickability: hover and click events on labels and measurements
- All artifacts survive export/replay/rebuild cycles
- Click, hover, and context-menu events forwarded to Python
region_tagsenrichment on every interaction payloadview.on_hover(fn)/view.on_click(fn)reactive callbacks- Active selection bridge: canvas selection → named region/selection/label
view.export.html(...)— portable interactive HTML (self-contained or CDN-lite)view.export.figure(...)— publication-quality PNG/SVG snapshotsview.export.figure_publication_set(...)— full light/dark/transparent bundleview.movie.export(...)— animated GIF or MP4 from trajectory frames- State serialisation:
view.export_state()/view.import_state()
MolSysViewer has a first-class addon API that lets external packages add workspaces, panels, context actions, and shape providers without modifying the core:
Optional MolSysSuite integrations are owned and distributed by their toolkit. Availability depends on the toolkit version; follow its installation instructions. The table below lists optional module names known to the host.
| Import as | Shipped by | What it adds | Maturity |
|---|---|---|---|
molsysviewer_topomt |
TopoMT | Pocket detection and topography visualisation | undeclared |
molsysviewer_elastnetmt |
ElastNetMT | GNM/ANM elastic network modes and contact network overlays | skeleton |
molsysviewer_pharmacophoremt |
PharmacophoresMT | Structure-based pharmacophore glyph overlays | minimal |
Maturity is what each add-on declares about itself, so the column reports rather than
grades. The shared vocabulary is experimental, development, beta and stable, decided in
devguide/archive/addon_maturity_and_ownership.md;
each toolkit adopts it when it re-declares. Provider-specific terms such as
skeleton and minimal are reproduced verbatim and retain their provider's meaning.
undeclared indicates that the add-on supplies no status.
MolSysMT is a required backend of MolSysViewer. Loading, selection and interaction calculations use it through the core API; you do not need a MolSysMT addon. The table records known optional module names, not a guarantee that each toolkit currently distributes or qualifies its integration. None of them is production-ready today. Discover optional addons explicitly when their toolkit provides them.
The former molsysviewer_molsysmt addon is retired. Automatic discovery ignores
its legacy entry point, and explicit registration explains the native API route.
controls_mode="minimal"— 3-icon cluster + keyboard shortcuts (N/W/H)panel_mode_style="floating"— centred overlay panel, no viewport shift
Install the published package with Conda:
conda create -n molsysviewer-env -c uibcdf -c conda-forge -c ambermd \
python=3.14 molsysviewer jupyterlab
conda activate molsysviewer-env
jupyter labConda installs the required MolSysMT backend and widget dependencies. The public installation route is Conda; MolSysViewer is not distributed through PyPI. An editable source installation is a developer workflow with its dependencies already provisioned, as described below.
| Capability | Platform and Python scope |
|---|---|
| Core Python API, Jupyter widget and interactive HTML | Linux x86_64/ARM64, macOS Apple Silicon, Windows x86_64; Python 3.11–3.14 |
| Local standalone launchers and Qt desktop host | Experimental for 1.0; native Qt dependencies and visible rendering require separate qualification |
| Remote sessions | Unsupported preview; supported workflows remain post-1.0 |
Viewer 0.24.0 build 1 and MolSysMT 0.23.0 build 0 passed all sixteen public
installed platform/Python cells. The three Windows console commands are present
and their --help checks pass; this repairs the missing launchers in the older
0.23.4 package (#101).
Command availability does not certify the experimental desktop or remote host.
Central admission of the public core package for Python 3.11–3.14 is frozen in MolSysSuite policy-v1.5.10; #93 records local adoption. New candidates and optional hosts retain their own qualification. Intel-based macOS is outside the current matrix. For experimental Qt work, see the separate development recipe. That recipe preserves Linux transport evidence and Windows/macOS solver-only observations; neither a successful solve nor the core noarch package certifies native Qt rendering. Interactive HTML export remains a supported output.
MolSysViewer uses Python for the API and widget layer, TypeScript + Mol* for
rendering, and esbuild for bundling. The JS bundle (viewer.js) is tracked in
the repository and ships inside the wheel/conda package so that users never need
a Node.js toolchain.
# Use the provisioned suite development environment
conda activate molsyssuite@uibcdf_3.14
python -m pip install --no-deps -e .
# Rebuild the JS bundle (only needed when editing TypeScript sources)
cd molsysviewer/js
npm install
npm run build:runtime
cd ../..
# Run the test suites
pytest tests/ # Python
npm --prefix molsysviewer/js run test:js # JS unit testsDeveloper guide: https://www.uibcdf.org/molsysviewer/content/developer/
Current development work and acceptance: pre-1.0 action ledger.
MolSysViewer is the visualisation engine for the UIBCDF MolSys ecosystem:
- MolSysMT — molecular systems and trajectories
- TopoMT — cavity and topography analysis
- PharmacophoresMT — pharmacophore modelling
- ElastNetMT — elastic network models
Use the stable concept DOI 10.5281/zenodo.18072956
when citing MolSysViewer generally. For reproducible work, cite the distinct version DOI
shown by Zenodo for the exact release you used. GitHub also renders the repository's
CITATION.cff through Cite this repository.
MIT License.
MolSysViewer uses the Mol* engine developed by the Mol* team and RCSB PDB.