How JSmol Works

From Proteopedia

This is intended to be a minimally technical overview of how JSmol and Jmol work in websites, such as Protopedia, FirstGlance in Jmol, and many others.

1 Providing JSmol
2 Invoking JSmol
3 Displaying Molecules
4 Chemical Bonds
5 Rendering and Coloring
6 See Also

Providing JSmol

The website server provides not only the web pages, but also JSmol. The web browser simply displays JSmol, and molecular data, provided by the server. Thus, the version of JSmol is matched to the web pages. JSmol is updated frequently at Jmol.Org, but the version of JSmol on a given website remains fixed until the site administrator upgrades it.

A website has, at the very least, some hypertext markup language files (filenames ending .htm or .html). Usually there are also some image files (filenames ending .png, .jpg, .gif, etc.) for images that are displayed in the web pages. And usually there are also some JavaScript files (filenames ending .js) and some cascading style sheet files (filenames ending .css). JavaScript (not to be confused with Java) is a programming language that is interpreted by the web browser.

In order to invoke JSmol, the files on the website server must also include the javascript code for JSmol (filenames ending .js). If the Jmol Java applet is to be invoked, the Java archive files for Jmol (filenames ending .jar) must also be included. All these are included in the download package from jmol.sourceforge.net/download.

Invoking JSmol

The web page invokes JSmol, specifying a position on the page and a size. Generally, there is a JavaScript Info variable (Info = {...}) that specifies whether JSmol or Jmol is to be invoked, the size in pixels, and optionally the initial molecule to be displayed, and the display style (JSmol script commands), and other options. This Info variable is then referenced in the actual invocation of JSMol.

The actual invocation generates the necessary HTML by a JavaScript call to Jmol.getApplet() or Jmol.getAppletHtml().

Examples can be seen in the files supersimple.htm, simple.htm, simple_old.htm, etc. These and other demonstration files will be found in the jsmol directory in the downloaded package from jmol.sourceforge.net/download. You can drag these local files from the downloaded file set, and drop them into the Firefox or Safari web browsers (or Internet Explorer, but it runs JSmol very slowly), to see the web pages they generate. (Local files that invoke JSmol do not work when dropped into Chrome or Edge.)

Displaying Molecules

JSmol is designed to display data files that contain atoms; that is, atomic resolution molecular models. The data file lists atoms, specifying the position in space of each atom (usually in Cartesian coordinates X, Y, Z), the chemical element of the atom, and for macromolecules, the amino acid or nucleotide residue name to which the atom belongs, its position within the residue (e.g. alpha carbon, beta, gamma, etc.), the polymer chain to which the residue belongs, and its sequence number, etc.

Such molecular structure data files are called atomic coordinate files. JSmol is able to read more than 50 formats of such files. The most common are XYZ format for small organic compounds (usually <100 atoms), and PDB or mmCIF formats for macromolecules.

Small molecule structures are available from several large databases. The international repository of macromolecular structures is the Protein Data Bank. The most reliable macromolecular structures are determined experimentally by X-ray crystallography, Nuclear magnetic resonance, or cryo-electron microscopy. Macromolecular models determined from theory are much less reliable, and are excluded from the Protein Data Bank.

Chemical Bonds

Interestingly, the common data formats (XYZ, PDB) do not specify where covalent bonds occur. JSmol determines when a covalent bond occurs between a pair of atoms based on the inter-atomic distance and the chemical elements involved.

JSmol does not determine whether covalent bonds are single, double, triple, or delocalized (e.g. aromatic). However, bond order information is available for every residue present in the Protein Data Bank, and can be loaded along with the PDB file on request to JSmol. When such data are loaded, JSmol is capable of displaying single, double, triple and delocalized covalent bonds appropriately.

JSmol can also determine the positions of (non-covalent) hydrogen bonds and display them as dotted bonds.

Rendering and Coloring

JSmol script commands specify how different portions of the molecule are to be rendered (ball and stick, wireframe, backbone trace, ribbon trace, etc. etc.) and colored. The command language is extensive and complex. The Scene Authoring Tools of Proteopedia free authors of molecular scenes from learning the command language.

Green links in Proteopedia use JavaScript to send scripts of commands to JSmol to change the rendering and coloring of the molecular scene, as well as the center of rotation, the degree of zooming, and many other options. In other web pages (e.g. Proteopedia's Scene Authoring Tools, FirstGlance in Jmol, or the simple.htm example mentioned above), buttons and forms use JavaScript to send command scripts to JSmol.