Mario Valle Web

An introduction to
the molecular visualization toolkit STM4



Welcome to this quick introduction to STM4, the molecular visualization toolkit!

The first version of this tutorial has been delivered at the AVS Workshop 2008 at ETH Zürich.


First of all presenting myself.

After studies in Rome at the Università la Sapienza, I worked for Digital Equipment where I specialized in software engineering for (mildly boring) logistic applications. Then in 1995 I had the opportunity to start working for Advanced Visual Systems (AVS), where I discovered the fascinating world of visualization.

In 2003 I moved to the Swiss National Supercomputing Centre (CSCS) in the Data Analysis and Visualization Services. Here I started working mostly with the center's chemistry users helping them for their visualization needs, providing tools and developing chemistry visualization and data analysis projects.


In the first part of this course I will explain the motivations behind STM4 and why it is not simply another chemistry visualization tool.

Then a quick tour inside STM4, just to learn where are its main pieces, followed by an in-depth look at the various modules provided.

Time permitting, will be interesting to apply the concepts learned to a concrete case, better if this case is strongly related to your current work.


STM4 (and STM3 before it) is a framework for the development of unusual and enhanced techniques for chemistry visualization. Its main goal is not to replace existing tools, but to provide a platform on which new, advanced or unusual visualization techniques can be implemented.

The toolkit started as an Ohio Supercomputer Center project called See The Molecule and evolved through the work of many people. At CSCS was selected prior to my arrival as the chemistry visualization group workhorse. After my arrival I engineered it till it reached its current form.

STM3 was the first engineered version. But it started growing without much order. So a new version with a renewed data model and a more powerful structure visualization module was created and it is the current STM4. There is a list of differences between STM3 and STM4 that you can find useful. My plan is to remove STM3 when I'm sure no one is using it.


First motivation for providing not another chemistry visualization tool at CSCS, but a development platform was first to overcome current tools inflexibility: they are very good at doing one thing, but often they are very difficult to bend to the needs of the CSCS users.

For example there are very good crystallographic visualization tools, but they are unable to visualize a phase transition or other dynamic structures.


To offer broader set of techniques besides molecular structures visualization. For example in STM4 it is possible to visualize CFD data together with molecular structures.

The images show (clockwise from left): the flow around a nanotube represented as a LEA texture; electronic currents around water molecules in a magnetic field; electronic density represented with volume render visualization technique.


This is an example of a module developed to satisfy the visualization needs of a CSCS user. In this “Study of the diffusion of vacancies in solid LiAl alloys” by C. Cucinotta – Department of Chemistry and Applied Biosciences ETH Zürich, the electron density data was too low density to produce a nice isusurface (left). We developed inside STM4 a tricubic volume interpolator to increase volume subdivision. The same isosurface on the interpolated volume is on the right.


Which is the main difference between STM4 and other chemistry visualization tools like Molekel, VMD, Chimera and others?

These are end user tools, with a point-and-click, simple to use user interface. STM4 instead needs some more work to be used, but it is much more flexible and expandable.


The approach taken by STM4 at CSCS has been a successful one because:

  1. We are able to satisfy the real researcher's needs
  2. It helps elicit users' unstated requirements
  3. With the services and functionalities already in place let we focus on representation needs, not on implementation details

What STM4 is not?

  • A complete chemistry visualization tool
    It grows depending on user requests. If something is not requested, it is not added. Remember, STM4 goal is not to replace existing tools
  • A simple, end user tool
    It is more a LEGO construction box. But more power and flexibility comes at the expense of no close and all-encompassing point-and-click interface
  • A tool for a specific chemistry field (Biochemistry, Molecular Dynamics, Crystallography, etc.)
    Again its functionalities depend on what have been requested. But it is precisely its goal to be cross-field

Now we analyze the architecture of STM4.


STM4 is built on top of AVS/Express. STM4 is a collection of modules that are combined together to build an AVS/Express application (a network, in AVS/Express idiom).

As you see, STM4 has not only the user interface and the viewing area, but the whole AVS/Express environment available.

To learn more how AVS/Express works, see the slides of the “An introduction to AVS/Express user” course.


STM4 is composed by:

  • A library of modules
  • New data types

AVS/Express provides:

  • Common visualization services
  • The Network Editor
  • Modularization
  • Standard visualization techniques

Before continuing, take a look at some of the visualizations made inside STM4.


More can be found in the STM4 image gallery or on the CSCS pages.


The main component of STM4 is a library of modules that could be combined like a LEGO construction set.

The modules derive mainly from user requests or because they were needed in some visualization project.


The STM4 modules are grouped under Libraries → STM4

You notice there is also a STM3 entry. It contains the old set of modules and will be removed anytime soon.


The STM4 library contains various sub-libraries:

A. Readers and writers
For various chemical formats plus writers for screenshots and movies
B. Bonds related modules
Compute, count and edit bonds
C. Modules
Compute various derived structures
D. Atoms selection
Select part of a structure by various criteria
E. Trajectory
Modules related to sequences of structures, i.e. trajectories
F. Crystallography support modules
Symmetries, replications, etc.
G. Visualization of volumetric data
Like Gaussian cubes or DL_POLY CHGCAR files
H. Structure display
Chemical structures and related graphical objects
I. Probe, interaction and measurements
Measurement and manipulation of the displayed structure
J. Ready to run applications
Applications for the most common tasks (plus display of the STM4 version)
K. Experimental modules (not covered in this tutorial)
Modules not intended for general usage, for example modules for a very specific project

STM4 introduces two new data types inside AVS/Express:

The first one is the Molecular Data Type that describes a generic molecular structure.

The other one is the Display Parameters data type that carries information about how a given structure is visualized.

Other information is carried by standard AVS/Express data types, like volumetric data that is represented by a Field Data Type.

Other data types extensively used are the Graphical Object (the red line) and the Screen Image (the violet line).


More information about STM4, and AVS/Express, can be found in the following places:


So we are ready for a quick tour inside STM4.

After installing AVS/Express and, on top of it, the STM4 kit, launch AVS/Express (with STM4 included) following your platform method (see slide).

Now go to Libraries → STM4. Then go to the rightmost column (Full Apps). Drag the MolDisplayApp block in the area below marked Applications.

In the window that pops up select the file format (e.g. PDB) and read a file.

In the graphical window: Mouse rotate. Middle Mouse Button+Shift: Zoom. +Ctrl: Pan. Reset position with the [Reset Normalize Center button] button.

Using the Modules drop down menu select Display Structure and change the molecule appearance.


There are some special cases to consider launching AVS/Express on various platforms (see slide).

The script go-viz runs STM4 with AVS/Express Visualization Edition. If there are problems with OpenGL, like the ones appearing using a remote display, run go -nohw.


Remember the basic of an AVS/Express application:

  • Each module starts when it receives all the needed data
  • Colors of connection ports and lines are related to data type
  • The user interface docks in the right place automatically

Start instantiating from the Full Apps sublibrary the MolDisplayApp pre-built application. Then read a structure and experiment with the various Draw Structure molecular representation methods.


To add a second structure to the display instantiate a Read Structure module to read the second structure and another Draw Structure to visualize it. The red (Graphical Object) line goes, together with the first one, to the UViewer3D module.

Then change the appearance of one of the structures going to the Draw Structure or Draw Structure#1 Module panel.


Now delete the application (File → Delete Application) and instantiate the CrystalDisplayApp application.

Read a file containing unit cell and symmetries (for example one in Shel-X format) and change unit cell replication and symmetry computation.


Now add a Draw Polyhedra or Draw Simple Polyhedra module to add coordination polyhedra around selected atoms.


To enhance the presentation of the structure you can add:

  • Background Fade to provide a colored backdrop for which you can set the four corners colors.
  • Logo to create a logo image fixed in the viewer.
  • Color Legend to display a legend for the structure representation colors.
  • Text Title, one standard AVS/Express module, to put a title in the view.

Now delete the application (File → Delete Application) and instantiate the VolumeDisplayApp application.

Read a file containing volumetric data (for example one in Gaussian Cube format) and change unit cell replication and the isosurface level and coloring.

Note that the Replicate Lattice module replicates not only the molecular structure, but also the volumetric data.


Now delete the Isosurface module and substitute it with a Volume Render one.

Changing the module parameters see how the resulting visualization could transmit more information about the 3D structure respect to a simple isosurface.


Now we examine in detail the modules provided by STM4.

Various modules are illustrated not only by their resulting visualization, but also by showing the AVS/Express network that generated this visualization.


Those are prebuilt applications that are ready to run after instantiation. They could be a starting point also for more specialized applications.


The base visualization application.


Visualization specialized for crystal structures.


Visualization plus the Measure Structure module. Using it you can measure distances and angles in the structure.


A rather specialized application. It is here just because the setup of the application is not trivial.

At its core it has the Pick Unit Cell module. With it you pick on 4 atoms (in the order: Origin, the end of the A vector, the end of the B vector, the end of the C vector). Then the module builds a new unit cell (and atom structure) within this new unit cell.


Again this application simplifies the usage of the Accumulate Traces module.

Goal of the application is to show the movement of selected atoms either as a line trail or as a cloud of occupied positions in a grid of cells.


Readers for various chemistry formats and scalar or vector data.

The writers write some chemistry formats. Make Movie creates a movie out of an animation (for example a trajectory) and Output Image captures a snapshot of the viewer.

A tip for Make Movie. Capture to disk and not to memory. This way you find an ImgNNNNN.x or ImgNNNNN.bmp (depending on AVS/Express version) file for each frame in the selected directory. Those images could then be assembled in a higher quality movie.

Instead Output Image has a half-bug: lines and fonts are made smaller in the file compared to the one on the screen. The trick here is to increase line widths and font sizes on screen before capturing it. Also sometimes (e.g. if you use depth cueing) you should change Draw Structure modules to Draw Sw Structure ones to produce a good image.


The up to date list of formats read by STM4 is available on the STM4 page.


Nothing special is needed to read a file: set the file format, set the kind of animation method present (if any), and enter the filename (or filenames if the format needs more than one file).


Display the molecular structure and other graphical objects that could help visualization understanding.


This is the most important piece of STM4: it converts the Molecular Data Type into the graphical representation of the chemical structure.

With the module controls you can change the molecular representation of atoms (normal, licorice, space filling) and bonds (tube, line, none); their coloring and labeling.

Special settings concern the colormap and range used to convert scalar values to color.

With a final set of controls you can chose the InfoSet used to set atom and fragments colors and radii. Here you can fine tune also bonds and sphere radius and quality.


This module tries to simplify a global structure by substituting a set of atoms with an enclosing ellipsoid.

There are two methods to compute the ellipsoid: inertia tensor and minimum enclosing ellipsoid. Try both to find the best one.

This module could be better, but the project requiring it has ended…


An Info Set is a group of information about:

  • Atoms colors, radius (covalent and Van der Waals), mass and max bonds number
  • Combined bonding distance for alternate method in Compute Bonds
  • Color for fragments (i.e. protein residues)

You can select the Info Set to use in Draw Structure.

To edit existing or create a new set, drop the Info Sets Editor module in your application and go to its panel. The functionalities are quite straightforward. After editing, the module could be deleted.


To enhance the presentation of the structure you can add:

  • Background Fade to provide a colored backdrop for which you can set the four corners colors.
  • Logo to create a logo image fixed in the viewer.
  • Color Legend to display a legend for the structure representation colors.
  • Text Title, one standard AVS/Express module, to put a title in the view.

STM4 could compute (or recompute) the structure bonds. The Compute Bonds module normally comes together with the modules that need a bonds recomputation (like Replicate Lattice). If you are sure that the bonds will be recomputed, then use Read Structure No Bonds to read the data.


The only peculiar module in this set is Compute Selected Bonds. It adds distance based bonds to selected atoms and, optionally, adds also a coordination polyhedra.


This library contains modules that compute various derived structures like protein surface, backbone, interpolating planes etc.


For example the Backbone module computes the classical Traces or Tube protein representation.

As in other tools this module requires a certain naming of the atoms: in fact the backbone passes through CA Carbon atoms sandwiched between one C and one N atoms.

A similar module (General Backbone) draws a tube between user selected atoms.


A visualization tool by definition is an output only tool. But sometimes the direct manipulation on the screen of quantities is much more immediate than a list selection. This library contains modules to measure structures (distances, angles, torsion angles) and to query single atoms.


The Measure Structure module:

  1. Returns picked atoms information (name, coordinate, values, etc.)
  2. Measures distance between two picked atoms
  3. Measures angle created by three picked atoms (the angle is: Atom1 — Atom2 (vertex) — Atom3)
  4. Measure torsion angle when picking four atoms. The torsion angle is between the two planes that pass through A1-A2-A3 and through A2-A3-A4

The red input port should be connected to the leftmost (picked_obj) output red port of Uviewer3D. Picking happens with Ctrl-LeftMouseButton. If you click not on an atom, the selection is reset.


Measure Closer Atoms is not really an interactive module. You have to select one or more atoms from a list and it displays all the interatomic distances in a given range.


You can select or exclude a subset of atoms from a structure based on:

  • Atom name or type
  • Fragment name
  • Scalar value associated to an atom

You can also manual deleting atoms. This functionality is really an interactive one, but seems more appropriate to be put here.


An atom can have one or more associated scalar or vector data. The Threshold Data module consider the first scalar value associated to atoms and outputs only the atoms that satisfy one of the following conditions against one or two values set on the module user interface.

The conditions are:

  • below min
  • below or equal min
  • between min and max
  • proper between min and max
  • above max
  • above or equal max
  • exactly equal max

STM4 represents trajectories, i.e. a sequence of atomic structures presumably evolving in time, as a sequence of frames. The frames are read one by one by the Read Structure module. In other words, a trajectory is not a first class data type in STM4.

The modules in this library have a permanent status that unifies the various frames of a sequence. For example the Interpolate Sequence must save the atom positions of the previous frame and have the next frame before outputting the interpolated frames in between.


The Accumulate Traces module accumulates the position of selected atoms in a trajectory in two different ways: as single positions and as occupancy of cells in a grid.

The first method produces a line for each traced atom. The line is colored by frame number. A nice effect is obtained adding the Illuminated Field Lines AVS/Express standard module.

There is a threshold value you can set to correctly split traces that exit from one side of the unit cell and re-enter on the opposite side.

The second method creates a 3D regular grid around the structure. At each frame the cells that contain one or more of the selected atoms have their associated count value incremented. The resulting volumetric data is visualized with volume render.


If the file format contains an associated scalar volumetric data (Gaussian Cube, CHGCAR, PLT), it can be visualized using standard AVS/Express visualization techniques. Here some of them are replicated for convenience plus other specific for STM4.

One example of specific module is the Interpolate Volume module that computes a tricubic interpolation of the input volume.


Volume Render is a standard AVS/Express module replicated here for convenience.

Here are some small tips.

BTF texture plus OpenGL rendering is fast, but not overly nice. Instead Ray tracer under software render (the "spark" button in the viewer should be gray) is better looking, but it is slower.

Alpha Range Model normally should not be Step.

Under BTF texture mode the Alternate Object toggle could be not set to speedup the interaction.


In STM4 there are plenty of modules for crystallography (because those users were much more active than other ones in suggesting functionalities).

Besides symmetries, the other modules deal with unit cell related functionalities.


To remove atoms inside or outside a given geometric shape you can use the Crop Structure module.

The shapes currently available are:

  • Sphere
  • Tube XYZ
  • Tube abc
  • Slab XYZ
  • Slab abc
  • Axis aligned block
  • Block

Another functionality commonly used by crystallographers is to put polyhedra around specific atoms. In STM4 this is done by the Draw Polyhedra and Draw Simple Polyhedra modules.

For the first module the criteria to select polyhedra vertices could be coordination or distance. The polyhedra could also be changed into a sphere. The 2nd one instead is a porting of the old STM3 module Find Polyhedra.


As already mentioned you can mix with STM4 modules the standard AVS/Express ones, like has been done in the three visualization here (from left): trajectory in a 3-parameter space; electronic currents represented as LIC textures and arrow glyphs; and the already seen flow around a nanotube.


In this example the input data is a structure plus a 3D scalar volumetric data.

Using Orthoslice a 2D slice is extracted. Then using the standard gradient AVS/Express module plus an arrow glyph the scalar field gradient around an atom is visualized.


To close this brief overview, think about this: with STM4 you can concentrate on the chemistry, not on the visualization tool.

And then contribute to STM4 with your ideas: it needs your creative ideas to grow. Another way to contribute is to try it with your data and your real visualization problems.


Thank you for your attention!

And do not forget to contact me if you need more information or have wild ideas to experiment with.