molsysviewer package#

Subpackages#

Submodules#

molsysviewer.demo module#

class molsysviewer.demo.DemoCatalog(specs)[source]#

Bases: Mapping[str, MolSysView]

Dictionary-like access to built-in demo views.

Access demos by key:

>>> import molsysviewer as viewer
>>> view = viewer.demo["1TCD"]

Notes

Each access returns a fresh MolSysView instance (no shared state).
Demo systems are shipped inside the package under molsysviewer.data.h5msm.

Parameters:: specs (list[_DemoSpec])

molsysviewer.layers module#

class molsysviewer.layers.Layer(view, tag, *, kind=None, meta=None)[source]#

Bases: object

Wrapper for a non-structural visual layer (shapes, overlays) addressed by tag.

Parameters:

view (Any)
tag (str)
kind (str | None)
meta (Optional[Dict[str, Any]])

delete()[source]#

Remove this layer and its visuals.

Return type:: None

hide()[source]#

Hide this layer (all contained visuals).

Return type:: None

set_tag(new_tag)[source]#

Change this layer’s tag (and update the registry).

Parameters:: new_tag (str)
Return type:: None

show()[source]#

Show this layer (all contained visuals).

Return type:: None

molsysviewer.new_view module#

molsysviewer.new_view.new_view(molecular_system, selection='all', structure_indices='all', *, debug_js=None, view=None)[source]#

Create and return a MolSysView, optionally loading a molecular system.

This is a convenience factory. It instantiates a MolSysView (unless one is provided via view), calls view.load(...) with the given inputs, and returns the view.

Parameters:

molecular_system (Any)
selection (str | Sequence[int])
structure_indices (str | Sequence[int])
debug_js (bool | None)
view (MolSysView | None)

Return type:

MolSysView

molsysviewer.regions module#

class molsysviewer.regions.Region(view, tag, selection, *, atom_indices=None, representation=None, repr_params=None)[source]#

Bases: object

Wrapper for a molecular region (Mol* component) addressed by tag.

Parameters:

view (Any)
tag (str)
selection (str | Any)
atom_indices (Optional[list[int]])
representation (str | None)
repr_params (Optional[Dict[str, Any]])

delete()[source]#

Remove this region and its representations.

Return type:: None

get(element='system', selection='all', structure_indices='all', mask=None, syntax='MolSysMT', get_missing_bonds=True, output_type='values', skip_digestion=False, **kwargs)[source]#: Retrieve values, scoped to this region.

hide()[source]#

Hide this region (all attached representations).

Return type:: None

info(element='system', selection='all', syntax='MolSysMT', mask='all', skip_digestion=False)[source]#: Show a summary table, scoped to this region.

new_complementary_region(tag=None, **kwargs)[source]#

Create a new region with the complement of this region’s atoms.

The resulting tag defaults to f"Global-{self.tag}" if not provided.

Parameters:

tag (str | None)
kwargs (Any)

Return type:

Region

select(selection='all', structure_indices='all', element='atom', mask=None, syntax='MolSysMT', skip_digestion=False)[source]#: Select indices, scoped to this region.

set_representation(representation=None, *, preset=None, **params)[source]#

Apply or update a representation for this region.

Allowed Mol* types (normalized, case-insensitive): cartoon, backbone, ball-and-stick (aliases: sticks, ballstick), carbohydrate, ellipsoid, gaussian-surface, gaussian-volume, label, line (aliases: licorice, wire), molecular-surface (alias: surface), orientation, plane, point, putty, spacefill (alias: vdw).

If preset is provided, it supersedes representation and applies a Mol* preset (auto, atomic-detail, polymer-and-ligand, polymer-cartoon, coarse-surface, empty).

Parameters:

representation (str | None)
preset (str | None)
params (Any)

Return type:

None

show()[source]#

Show this region (all attached representations).

Return type:: None

molsysviewer.viewer module#

class molsysviewer.viewer.MolSysView(*, debug_js=None)[source]#

Bases: object

Mol* viewer widget with a Python-facing API.

Provides structure loading, visibility control, shape management, and utilities to export static HTML views for documentation or sharing.

Parameters:: debug_js (bool | None)

add(from_molecular_system, *, selection='all', structure_indices='all', keep_ids=True, syntax='MolSysMT')[source]#

Add atoms/structures from another system into this view and refresh the viewer (live).

Parameters:

from_molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
keep_ids (bool)
syntax (str)

Return type:

None

append_structures(from_molecular_system, *, selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Append structures (frames) to the loaded system and refresh the viewer (live).

Notes

This method mutates the molecular system behind this view and then reloads the frontend payload. It aims to preserve regions, layers, visibility, and shapes.

Parameters:

from_molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
syntax (str)

Return type:

None

clear_decorations(*, shapes=True, styles=True, labels=True)[source]#

Clear decorative elements (shapes/styles/labels) without touching the loaded structure or camera.

Parameters:

shapes (bool)
styles (bool)
labels (bool)

Return type:

None

get(element='system', selection='all', structure_indices='all', mask=None, syntax='MolSysMT', get_missing_bonds=True, output_type='values', skip_digestion=False, **kwargs)[source]#: Retrieve attribute values from the current molecular system (MolSysMT get).

get_camera_snapshot(*, pretty=False)[source]#

Return the last camera snapshot received from the frontend.

Parameters:: pretty (bool) – If True, return a formatted JSON string instead of a dict.
Return type:: dict | str | None

hide(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Hide atoms matching the given selection (MolSysMT syntax by default).

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)

info(element='system', selection='all', syntax='MolSysMT', mask='all', skip_digestion=False)[source]#

isolate(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Show only the atoms in selection; hide everything else (reset if selection == ‘all’).

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)

property js_logs: list[dict[str, str]]#: Logs received from the frontend when debug_js is enabled.

property layers: Mapping[str, Layer]#: Public registry of layers (non-structural visuals).

load(molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', label=None)[source]#

Load a molecular system (MolSysMT-compatible) into the viewer.

Parameters:

molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
syntax (str)
label (str | None)

Return type:

None

property molsys#

Read-only handle to the loaded MolSysMT molecular system.

This property exposes the underlying molsysmt.MolSys instance created when you call load(…). It is intended for inspection (for example, via molsysmt.info(…) or molsysmt.select(…)).

Notes

This is a read-only property (no setter): you cannot reassign it.
The returned object may be mutable. If you modify it directly, you can desynchronize what you see in the viewer. If you need to change the system, modify your data and call load(…) again.

new_layer(*, tag=None, kind=None, **meta)[source]#

Create a new layer (non-structural visual group).

Parameters:

tag (str | None)
kind (str | None)
meta (Any)

Return type:

Layer

new_region(selection='all', *, atom_indices=None, tag=None, representation=None, complement_of_regions=None, **repr_params)[source]#

Create a new region (structural subset) with an optional representation.

Parameters:

selection (str | Any) – MolSysMT selection string/expression. Ignored if atom_indices is provided.
atom_indices (list[int] | None) – Explicit atom indices for the region (bypasses selection). If not provided, they are computed from selection when possible.
tag (str | None) – Optional tag for the region. Auto-generated if omitted.
representation (str | None) – Optional representation type (normalized and validated).
complement_of_regions (str | list[str] | None) – Tags of regions to exclude. If “all”/”All”/”ALL”, the region covers the complement of all existing regions. Ignored if atom_indices is set.
repr_params (Any)

Return type:

Region

Notes

Requires a loaded molecular system. Call load(...) before creating regions. When using complement_of_regions, the union of those regions’ atom indices is removed from the full system to build the new region. Region indices are taken from their stored atom_indices (acks) when available.

property regions: Mapping[str, Region]#: Public registry of regions (structural selections).

remove(*, selection=None, structure_indices=None, syntax='MolSysMT')[source]#

Remove atoms and/or structures from this view and refresh the viewer (live).

Atom removals require remapping stored atom indices so that regions and shapes remain consistent.

Parameters:

selection (str | Any | None)
structure_indices (str | Any | None)
syntax (str)

Return type:

None

reset_camera()[source]#

Reset the camera / view in the frontend.

Return type:: None

reset_viewer()[source]#

Fully clear the viewer and reset internal state (requires a new load(…)).

Return type:: None

select(selection='all', structure_indices='all', element='atom', mask=None, syntax='MolSysMT', skip_digestion=False)[source]#

Select indices from the current molecular system (MolSysMT selection language).

Notes

This method intentionally focuses on the common workflow: returning indices.

set(*, element=None, selection='all', structure_indices='all', syntax='MolSysMT', **kwargs)[source]#

Set attribute values on the loaded system and refresh the viewer (live).

This forwards to molsysmt.set(…) and then reloads the frontend payload so that changes become visible.

Parameters:

element (str | None)
selection (str | Any)
structure_indices (str | Any)
syntax (str)
kwargs (Any)

Return type:

None

set_camera_snapshot(snapshot, *, duration_ms=0)[source]#

Apply a previously saved camera snapshot.

Parameters:

snapshot (dict) – Camera snapshot dict (Mol* format).
duration_ms (int) – Transition duration in milliseconds.

Return type:

None

set_controls_visible(visible, *, autohide=None, position=None, position_fullscreen=None)[source]#

Show or hide the on-canvas controls (reset/full/bg/spin/swing + trajectory bar). Optionally toggle autohide and positions.

Parameters:

visible (bool)
autohide (bool | None)
position (list[str] | tuple[str, str] | None)
position_fullscreen (list[str] | tuple[str, str] | None)

Return type:

None

show(selection='all', structure_indices='all', syntax='MolSysMT', *, force=False)[source]#

Show the widget (first call or if force=True) and optionally adjust visibility.

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)
force (bool)

property visible_atom_indices#: Return the indices of currently visible atoms.

property visible_structure_indices#: Return the indices of currently visible structures.

write_html(output_filename, *, title='MolSysViewer', include_controls=True, include_popout=True, mode='standalone', inline_messages=True)[source]#

Export this viewer widget to an HTML file.

Parameters:

output_filename (str) – Path to the HTML file to create.
title (str) – Optional title for the exported HTML page.
include_controls (bool) – If True (default), include the on-canvas control buttons (Reset, Fullscreen, background toggle, Spin, Swing) in the exported view. Set this to False if you prefer a minimal viewer without these controls, for example when embedding inside another application that already provides its own UI.
include_popout (bool) – If True (default), include the popout button and allow opening a popout window.
mode (str) –
- "standalone" (default): produce a self-contained HTML using the widget embed machinery.
- "lite": produce a lightweight HTML that loads the runtime from the CDN and replays messages (suitable for embedded docs-light views).
inline_messages (bool) – Only used when mode="lite". If True (default), embed the replay messages inline in the HTML.

Return type:

None

zoom(selection='all', structure_indices='all', syntax='MolSysMT', *, duration='250 ms', duration_ms=None, extra_radius='4.0 angstroms', min_radius='1.0 angstroms')[source]#

Focus the camera on the geometric center of a selection of atoms.

Parameters:

selection (str | Any) – MolSysMT selection string/expression or a list of atom indices. If a list is provided, it is passed through MolSysMT and used directly.
structure_indices (str | Any) – Structure indices to apply when resolving the selection.
syntax (str) – Selection syntax understood by MolSysMT.
duration (Any) – Transition duration for the camera move (any time unit supported by PyUnitWizard).
duration_ms (Any | None) – Backward-compatible alias for duration. If provided, it overrides duration.
extra_radius (Any) – Extra padding (Å) added to the selection’s bounding sphere.
min_radius (Any) – Minimum radius (Å) to enforce for the camera focus.

Return type:

None

molsysviewer.whole module#

class molsysviewer.whole.Whole(view)[source]#

Bases: object

Wrapper for operations on the whole structure (non-deletable, non-retaggable).

Parameters:: view (Any)

add(*args, **kwargs)[source]#

Add elements from another system (delegates to MolSysView.add).

Parameters:

args (Any)
kwargs (Any)

append_structures(*args, **kwargs)[source]#

Append structures to the underlying system (delegates to MolSysView.append_structures).

Parameters:

args (Any)
kwargs (Any)

get(*args, **kwargs)[source]#

Retrieve values from the whole system (delegates to MolSysView.get).

Parameters:

args (Any)
kwargs (Any)

hide()[source]#

Hide the global representation(s).

Return type:: None

info(*args, **kwargs)[source]#

Show a summary table for the whole system (delegates to MolSysView.info).

Parameters:

args (Any)
kwargs (Any)

remove(*args, **kwargs)[source]#

Remove atoms/structures from the system (delegates to MolSysView.remove).

Parameters:

args (Any)
kwargs (Any)

select(*args, **kwargs)[source]#

Select indices from the whole system (delegates to MolSysView.select).

Parameters:

args (Any)
kwargs (Any)

set(*args, **kwargs)[source]#

Set attributes on the underlying system (delegates to MolSysView.set).

Parameters:

args (Any)
kwargs (Any)

set_representation(representation=None, *, preset=None, **params)[source]#

Set or update the global representation for the whole structure.

If the global representation was hidden, this call will show it again.

Parameters:

representation (str | None) – Simple representation type (e.g., cartoon, ball-and-stick, line). Ignored if preset is provided.
preset (str | None) – Optional Mol* preset (auto, atomic-detail, polymer-and-ligand, polymer-cartoon, coarse-surface, empty). When provided, supersedes representation and applies the preconfigured style bundle.
params (Any)

Return type:

None

show()[source]#

Show the global representation(s).

Return type:: None

molsysviewer.widget module#

class molsysviewer.widget.MolSysViewerWidget(**kwargs)[source]#

Bases: AnyWidget

Parameters:

args (object)
kwargs (object)

autohide_controls#: A boolean (True, False) trait.

controls_position#: An instance of a Python list.

controls_position_fullscreen#: An instance of a Python list.

debug_js#: A boolean (True, False) trait.

enable_popout#: A boolean (True, False) trait.

initial_messages#: An instance of a Python list.

popup_js_source#: A trait for unicode strings.

show_controls#: A boolean (True, False) trait.

Module contents#

class molsysviewer.MolSysView(*, debug_js=None)[source]#

Bases: object

Mol* viewer widget with a Python-facing API.

Provides structure loading, visibility control, shape management, and utilities to export static HTML views for documentation or sharing.

Parameters:: debug_js (bool | None)

add(from_molecular_system, *, selection='all', structure_indices='all', keep_ids=True, syntax='MolSysMT')[source]#

Add atoms/structures from another system into this view and refresh the viewer (live).

Parameters:

from_molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
keep_ids (bool)
syntax (str)

Return type:

None

append_structures(from_molecular_system, *, selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Append structures (frames) to the loaded system and refresh the viewer (live).

Notes

This method mutates the molecular system behind this view and then reloads the frontend payload. It aims to preserve regions, layers, visibility, and shapes.

Parameters:

from_molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
syntax (str)

Return type:

None

clear_decorations(*, shapes=True, styles=True, labels=True)[source]#

Clear decorative elements (shapes/styles/labels) without touching the loaded structure or camera.

Parameters:

shapes (bool)
styles (bool)
labels (bool)

Return type:

None

get(element='system', selection='all', structure_indices='all', mask=None, syntax='MolSysMT', get_missing_bonds=True, output_type='values', skip_digestion=False, **kwargs)[source]#: Retrieve attribute values from the current molecular system (MolSysMT get).

get_camera_snapshot(*, pretty=False)[source]#

Return the last camera snapshot received from the frontend.

Parameters:: pretty (bool) – If True, return a formatted JSON string instead of a dict.
Return type:: dict | str | None

hide(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Hide atoms matching the given selection (MolSysMT syntax by default).

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)

info(element='system', selection='all', syntax='MolSysMT', mask='all', skip_digestion=False)[source]#

isolate(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Show only the atoms in selection; hide everything else (reset if selection == ‘all’).

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)

property js_logs: list[dict[str, str]]#: Logs received from the frontend when debug_js is enabled.

property layers: Mapping[str, Layer]#: Public registry of layers (non-structural visuals).

load(molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', label=None)[source]#

Load a molecular system (MolSysMT-compatible) into the viewer.

Parameters:

molecular_system (Any)
selection (str | Any)
structure_indices (str | Any)
syntax (str)
label (str | None)

Return type:

None

property molsys#

Read-only handle to the loaded MolSysMT molecular system.

This property exposes the underlying molsysmt.MolSys instance created when you call load(…). It is intended for inspection (for example, via molsysmt.info(…) or molsysmt.select(…)).

Notes

This is a read-only property (no setter): you cannot reassign it.
The returned object may be mutable. If you modify it directly, you can desynchronize what you see in the viewer. If you need to change the system, modify your data and call load(…) again.

new_layer(*, tag=None, kind=None, **meta)[source]#

Create a new layer (non-structural visual group).

Parameters:

tag (str | None)
kind (str | None)
meta (Any)

Return type:

Layer

new_region(selection='all', *, atom_indices=None, tag=None, representation=None, complement_of_regions=None, **repr_params)[source]#

Create a new region (structural subset) with an optional representation.

Parameters:

selection (str | Any) – MolSysMT selection string/expression. Ignored if atom_indices is provided.
atom_indices (list[int] | None) – Explicit atom indices for the region (bypasses selection). If not provided, they are computed from selection when possible.
tag (str | None) – Optional tag for the region. Auto-generated if omitted.
representation (str | None) – Optional representation type (normalized and validated).
complement_of_regions (str | list[str] | None) – Tags of regions to exclude. If “all”/”All”/”ALL”, the region covers the complement of all existing regions. Ignored if atom_indices is set.
repr_params (Any)

Return type:

Region

Notes

Requires a loaded molecular system. Call load(...) before creating regions. When using complement_of_regions, the union of those regions’ atom indices is removed from the full system to build the new region. Region indices are taken from their stored atom_indices (acks) when available.

property regions: Mapping[str, Region]#: Public registry of regions (structural selections).

remove(*, selection=None, structure_indices=None, syntax='MolSysMT')[source]#

Remove atoms and/or structures from this view and refresh the viewer (live).

Atom removals require remapping stored atom indices so that regions and shapes remain consistent.

Parameters:

selection (str | Any | None)
structure_indices (str | Any | None)
syntax (str)

Return type:

None

reset_camera()[source]#

Reset the camera / view in the frontend.

Return type:: None

reset_viewer()[source]#

Fully clear the viewer and reset internal state (requires a new load(…)).

Return type:: None

select(selection='all', structure_indices='all', element='atom', mask=None, syntax='MolSysMT', skip_digestion=False)[source]#

Select indices from the current molecular system (MolSysMT selection language).

Notes

This method intentionally focuses on the common workflow: returning indices.

set(*, element=None, selection='all', structure_indices='all', syntax='MolSysMT', **kwargs)[source]#

Set attribute values on the loaded system and refresh the viewer (live).

This forwards to molsysmt.set(…) and then reloads the frontend payload so that changes become visible.

Parameters:

element (str | None)
selection (str | Any)
structure_indices (str | Any)
syntax (str)
kwargs (Any)

Return type:

None

set_camera_snapshot(snapshot, *, duration_ms=0)[source]#

Apply a previously saved camera snapshot.

Parameters:

snapshot (dict) – Camera snapshot dict (Mol* format).
duration_ms (int) – Transition duration in milliseconds.

Return type:

None

set_controls_visible(visible, *, autohide=None, position=None, position_fullscreen=None)[source]#

Show or hide the on-canvas controls (reset/full/bg/spin/swing + trajectory bar). Optionally toggle autohide and positions.

Parameters:

visible (bool)
autohide (bool | None)
position (list[str] | tuple[str, str] | None)
position_fullscreen (list[str] | tuple[str, str] | None)

Return type:

None

show(selection='all', structure_indices='all', syntax='MolSysMT', *, force=False)[source]#

Show the widget (first call or if force=True) and optionally adjust visibility.

Parameters:

selection (str | Any)
structure_indices (str | Any)
syntax (str)
force (bool)

property visible_atom_indices#: Return the indices of currently visible atoms.

property visible_structure_indices#: Return the indices of currently visible structures.

write_html(output_filename, *, title='MolSysViewer', include_controls=True, include_popout=True, mode='standalone', inline_messages=True)[source]#

Export this viewer widget to an HTML file.

Parameters:

output_filename (str) – Path to the HTML file to create.
title (str) – Optional title for the exported HTML page.
include_controls (bool) – If True (default), include the on-canvas control buttons (Reset, Fullscreen, background toggle, Spin, Swing) in the exported view. Set this to False if you prefer a minimal viewer without these controls, for example when embedding inside another application that already provides its own UI.
include_popout (bool) – If True (default), include the popout button and allow opening a popout window.
mode (str) –
- "standalone" (default): produce a self-contained HTML using the widget embed machinery.
- "lite": produce a lightweight HTML that loads the runtime from the CDN and replays messages (suitable for embedded docs-light views).
inline_messages (bool) – Only used when mode="lite". If True (default), embed the replay messages inline in the HTML.

Return type:

None

zoom(selection='all', structure_indices='all', syntax='MolSysMT', *, duration='250 ms', duration_ms=None, extra_radius='4.0 angstroms', min_radius='1.0 angstroms')[source]#

Focus the camera on the geometric center of a selection of atoms.

Parameters:

selection (str | Any) – MolSysMT selection string/expression or a list of atom indices. If a list is provided, it is passed through MolSysMT and used directly.
structure_indices (str | Any) – Structure indices to apply when resolving the selection.
syntax (str) – Selection syntax understood by MolSysMT.
duration (Any) – Transition duration for the camera move (any time unit supported by PyUnitWizard).
duration_ms (Any | None) – Backward-compatible alias for duration. If provided, it overrides duration.
extra_radius (Any) – Extra padding (Å) added to the selection’s bounding sphere.
min_radius (Any) – Minimum radius (Å) to enforce for the camera focus.

Return type:

None

molsysviewer.new_view(molecular_system, selection='all', structure_indices='all', *, debug_js=None, view=None)[source]#

Create and return a MolSysView, optionally loading a molecular system.

This is a convenience factory. It instantiates a MolSysView (unless one is provided via view), calls view.load(...) with the given inputs, and returns the view.

Parameters:

molecular_system (Any)
selection (str | Sequence[int])
structure_indices (str | Sequence[int])
debug_js (bool | None)
view (MolSysView | None)

Return type:

MolSysView