Loading and inspection#

This page is a gentle starting point. We will load a small demo system, display it in Jupyter, and get comfortable with where the molecular system lives on the Python side.

If you are new to MolSysViewer, here is the mental model we will use throughout the User Guide:

  • You interact with a single Python object called view (a molsysviewer.viewer.MolSysView).

  • view talks to the browser, where Mol* renders the 3D scene.

  • The data you are visualizing is a MolSysMT molecular system, available as view.molsys.

If you only remember one thing from this page, make it this: view is your handle to both the viewer and the data behind it.

A gentle “hello, structure”#

To keep things reproducible, we will use a built-in demo system. Demos are exposed as a dictionary-like catalog:

  • viewer.demo["pentalanine"] returns a fresh view every time you access it (no shared state).

  • This is great for tutorials: you never inherit state from earlier cells.

import molsysviewer as viewer

list(viewer.demo)



['dialanine', '1TCD', '181L', 'pentalanine', 'chicken_villin_HP35']

view = viewer.demo["pentalanine"]
view.show()

What did we just load?#

MolSysViewer stores the underlying molecular system in view.molsys.

That object is a native MolSysMT container (molsysmt.MolSys). MolSysViewer uses MolSysMT to represent and query the system, while Mol* focuses on rendering the scene in the browser.

You do not need to be a MolSysMT expert to use MolSysViewer. We will introduce the MolSysMT concepts you need as we go. If you want a deeper dive, see the MolSysMT documentation.

Two gentle guidelines help avoid confusion:

  • If you want to visualize something, use MolSysViewer methods.

  • If you want to query the data (atoms, residues, chains, coordinates…), use MolSysMT helpers through view.molsys, view.select(...), view.info(...), and view.get(...).

view.molsys is a read-only property (you cannot reassign it), but the object itself may be mutable. If you mutate it directly, you can desynchronize what you see from what you think you loaded. When in doubt: modify your data upstream and call load(...) again.

Form-agnostic loading#

MolSysViewer delegates loading to MolSysMT. That is why you can often load “different kinds of things” (a file path, a PDB ID, a trajectory object…), and still get a consistent workflow afterwards.

Internally, MolSysViewer converts what you load into a single, stable representation: molsysmt.MolSys. That converted object is what you access as view.molsys.

You do not need to call MolSysMT conversion functions manually most of the time. But it helps to know that conversion is happening, because it explains why MolSysViewer stays predictable even when inputs come from different sources.

type(view.molsys)

molsysmt.native.molsys.MolSys

A quick inspection checklist#

When you load a new system, it helps to ask three simple questions:

  1. What is the system, globally?

  2. Which entity types are present?

  3. How is it organized into chains?

MolSysViewer offers two small inspection helpers:

  • view.info(...) shows a readable summary table in Jupyter.

  • view.get(...) returns values you can use in Python (arrays, lists, labels…).

Both delegate to MolSysMT and can work at different hierarchical element levels (for example: "atom", "group", "chain", "entity").

Let’s answer the first three questions with view.info(...):

view.info(element="system")
form n_atoms n_groups n_components n_chains n_molecules n_entities n_peptides n_structures
molsysmt.MolSys 62 7 1 1 1 1 1 200 
view.info(element="entity")
index name type n atoms n groups n components n chains n molecules
0 peptide 0 peptide 62 7 1 1 1

And here is a small get example: we retrieve the group names for the first chain (chain_index==0).

view.get(element="chain", selection="chain_index==0", group_name=True)

[['ACE', 'ALA', 'ALA', 'ALA', 'ALA', 'ALA', 'NME']]

For more examples of info, get, and how they interact with selections, see Quick info and Getting attributes.

Loading your own molecular system#

When you move from demos to your own work, you will typically load a molecular system from a local file or from an object you already have in memory (for example, an mdtraj.Trajectory, an OpenMM topology + coordinates, or a MolSysMT object).

There are two common patterns:

  1. Create a new view from a molecular-system-like input with molsysviewer.new_view().

  2. Create a view first, then call view.load(...).

Both are valid; pick the one that matches your style.

view = viewer.MolSysView()
view.load('181L')
view.info()
form n_atoms n_groups n_components n_chains n_molecules n_entities n_waters n_ions n_small_molecules n_proteins n_structures
molsysmt.MolSys 1441 302 141 6 141 5 136 2 2 1 1 
view = viewer.new_view('181L')
view.info()
form n_atoms n_groups n_components n_chains n_molecules n_entities n_waters n_ions n_small_molecules n_proteins n_structures
molsysmt.MolSys 1441 302 141 6 141 5 136 2 2 1 1

And if your main goal is simply to display the structure, just call view.show():

view.show()

Where to go next#

Now that you can load and display a system, the next pages will help you build the mental model:

  • Topology: what the topology is (atoms → residues → chains…).

  • Structures: what a structure is (coordinates, box, time; trajectories vs ensembles).

  • Selecting elements: how you pick subsets of atoms.

  • Quick info: how to get a quick overview of a system.

  • Getting attributes: how to extract attribute values into Python.

If you want more datasets to play with, see Demo systems.