Click on a link below to see what it does. You can also type a command in the box below the model to see its effect. The script run in this case was load caffeine.xyz.
This page lists all features in Jmol 12.0, released 7/29/2010, that were not in Jmol 11.8. For a categorized listing, see new12.htm. New features being added in Jmol 12 are at ../examples-12/new.htm. Features introduced in Jmol 11.8 (with links there to previous versions) are described in new8.htm Documentation for all commands can be found in the Interactive Documentation for Jmol 12.0. For the complete change log development summary, see Jmol.properties. Comments? Suggestions? Bob Hanson
TRY/CATCH
Jmol 12.0.RC27 adds the try/catch option similar to that of JavaScript and Java, allowing you to catch script errors, including file load issues, BEFORE they trash your model.
Jmol 12.0.RC27 completes the full-fledged scripting capability of Jmol by adding associative arrays -- arrays that allow you to retrieve information using a string-based key rather than a number. See the documentation for details.
Jmol 12.0.RC26 adds the PROMPT command to allow pausing a script until the user presses OK. If no parameter is given, PROMPT returns a script stack trace showing where it is. This may be useful for debugging script files.
Jmol 12.0.RC26 fixes a long-standing problem with halos and selection halos. With "halos ON" (the default size) they are supposed to track the spacefill size, appearing slightly larger. In previous versions their size was simply set to 20% of the default van der Waals radius. You can still set them to that if you want, with halos 20%.
Jmol 12.0.RC26 adds the RESET option, which returns wireframe or spacefill to the Jmol default settings. Thus, a simple "Ball&Stick" rendering is simply wireframe only;wireframe reset;spacefill reset. (The "wireframe only" removes any other rendering.)
... well, ALMOST! Starting with Jmol 12.0.RC26, you can easily write the files necessary to add a Jmol-like 3D model into PDF files. To do this you are going to need a few pieces of software besides Jmol. The idea is Jmol --write--> IDTF + TEX --idtfConverter--> U3D + TEX --pdflatex--> PDF. (I think that equation is balanced!) It is a bit of a process, but it is not too bad. Once you get it working, the process takes a few seconds only. Those who are TeX savvy are at an advantage here, but if you have Adobe Acrobat PRO you should not need to know any TeX at all to do this. Sample files are in the pdf subdirectory. test1.idtf.pdf is an example.
168. full 3D-SEARCH SMILES/SMARTS and bioSMILES/bioSMARTS implementation
Jmol 12.0 implements a full version of SMILES and SMARTS matching, augmenting that with extensive capabilities for 3D conformation matching (distance, angle, and torsion ranges, as well as conformational RMSD comparison measurements of selected atoms) and additional extensions to search biomolecular substructure such as sequence and base-pairing. All aspects of Daylight SMARTS matching are implemented -- see the 3D-SEARCH specifications for details.
Jmol 12.0.RC25 merges the DATA "model..." and DATA "append..." methods with the LOAD command, thus extending all of the options to the LOAD command to the DATA command.
Jmol 12.0.RC23 adds a powerful new way to transfer properties from one atom set to another. The operation involves identifying two sets of atoms and properties and also a common "key" property such as atomno or resno. If no key is given, atomno is assumed. A shortcut allows quick transfer of atom selection.
Jmol 12.0.RC23 combines the quaternion and ramachandran commands into a new command, plot, and adds to that the capability to graph any two or three atom properties. Optional parameters for the PROPERTIES option include MIN and MAX. All plots are scaled to fit a 200 x 200 x 200 angstrom box using a unit cell to convert actual (now "fractional") units to Jmol xyz units. This allows access still to the actual data coordinates via fractional coordinate notation (such as {2.0 3.0 5.0/1}).
Jmol 12.0.RC23 adds nucleic acid conformation properties eta and theta as per Carlos M. Duarte, Leven M. Wadley, and Anna Marie Pyle, RNA structure comparison, motif search and discovery using a reduced representation of RNA conformational space, Nucleic Acids Research, 2003, Vol. 31, No. 16 4755-4761. eta is the C4'[i-1]-P[i]-C4'[i]-P[i+1] dihedral angle; theta is the P[i]-C4'[i]-P[i+1]-C4'[i+1] dihedral angle.
Jmol 12.0.RC21 introduces a new way to render nucleic acid cartoons. set cartoonBaseEdges TRUE tells Jmol to displays nucleic acid bases as triangles that highlight the sugar edge (red), Watson-Crick edge (green), and Hoogsteen edge (blue). See Nasalean L, Strombaugh J, Zirbel CL, and Leontis NB in Non-Protein Coding RNAs, Nils G. Walter, Sarah A. Woodson, Robert T. Batey, Eds., Chapter 1, p 6.
Jmol 12.0.RC19 adds preliminary molecular lipophilic potential mapping by allowing MEP (molecular electrostatic potential) to be mapped using functions other than the standard Coulomb potential (1/d). The data for the mapping comes by default from the partialCharge atom property, but can easily be drawn from any property or a variable. See the Jmol 12.0 documentation for details.
Jmol 12.0.RC19 deprecates the substructure() function, which used a SMILES string to search for substructure. Really, SMILES strings were never intended to be for searching; that is what SMARTS is for. The find() and search() functions are recommended.
Jmol 12.0.RC16 lets you quickly find the molecular formula of the SMILES or SMARTS string associated with a set of atoms or SMILES string. The two options allow for a full all-hydrogen formula or one without hydrogen atoms.
Jmol 12.0.RC15 will read SMILES strings into 3D using the smi23d server at Indiana University. Only catch is that since this is a third-party server, you will have to use the SIGNED APPLET to do it. Note that this service uses PCMODEL v9.1 for its conversion.
Jmol 12.0.RC15 adds a new sort of selectionHalo. The HIGHLIGHT is a just a small ring around an atom. The default color is red, but you can use color highlight to set it to a different color. It is not an "atom property", so individual atoms cannot have their own colored highlight.
Jmol 12.0.RC15 represents a first attempt at creating a model kit option for Jmol. I cannot seem to get the menu to pop up using "set modelKitMode" via Javascript, but you can call it up yourself from the menu. It is under "computation". Using set allowModelKit FALSE you can disallow modelKitMode.
The FIX command takes an atom expression argument like the display or select commands. It fixes the positions of atoms and ensures that no atoms of this set will be moved or dragged anywhere accidentally.
Starting with Jmol 12.0.RC15, selecting an atom that is part of a ring after set picking invertStereo will reverse the two non-ring atoms -- actually rotating them 180 degrees, not doing a planar inversion, thus preserving whatever chirality might be attached to them.
146. set picking dragMinimizeMolecule -- responsive docking
With Jmol 12.0.RC15 you can move a small molecule around and watch it react to its environment. Grab the caffeine molecule and move it toward the protein. Holding SHIFT down allows rotation. CTRL-Z undoes an action; CTRL-Y does a redo.
Wouldn't it be fun to have a real "sculpture" mode, where you can play with a molecule like an artist does with clay, molding it to the shape you want -- within the limitations of the medium? (Don't try this with a protein.) Well, it's very possible this is a bad idea, but Jmol 12.0.RC13 adds this capability.
just grab atoms and move them. Or click on an atom to further minimize. I know...quesionable pedagogy...Actually, there is a sort of lesson here in how minimization works...
Jmol 12.0.RC13 adds set picking dragAtom, allowing dragging of atoms to new locations. Attached hydrogens atoms are dragged along with the selected atom.
143. drag-and-drop to signed applet and from browsers
Jmol 12.0.RC13 adds drag-and-drop capability for the signed applet and adds MULTIPLE-FILE drag-and-drop for both signed applet and application. Just fire up a page such as drop.htm that uses the signed applet and then drag from a directory listing into the applet as many files as you like. They will be loaded into different frames, and frame *;reset will be issued so that they are all displayed. (PNG and JPG images created by Jmol can be loaded this way, but only one at a time, since they reset the state when loaded.) For standard model files, if set defaultLoadScript is defined, then that script will be executed. (For example, a simple one might be set defaultLoadScript 'select protein or nucleic;cartoons only'.) Electron density MAP files may also be dropped in. Or you can simply clip file name(s) in a file directory, then CTRL-V into Jmol loads the file(s).
142. COMPARE with SMILES or SMARTS allows conformational testing and alignment
Jmol 12.0.RC12 adds the capability to align two structures based on SMILES or SMARTS atom matching. The basic idea is to use a SMILES (whole molecule) or SMARTS (substructure) description to find the atoms in one structure that correlate one-for-one with atoms in the second structure, then find the rotation and translation that best aligns them. If no actual atom moving is desired, you can get the standard deviation alone using the compare() function with the "STDDEV" option. A return of "NaN" indicates that the desired SMILES/SMARTS match could not be made in one or the other structure.
Jmol 12.0.RC11 adds a new light-weight applet (only 43K) that checks SMILES strings. This is particularly useful for comparison of drawn stereochemistry, which is not possible using JME alone. See JmolSmiles.htm, JmolSmilesTest.htm, and JmolSmilesApplet.jar."
Jmol 12.0.RC11 allows unprecedented matching of non-canonical SMILES strings independent of any 3D structure. This includes both atom and bond stereochemistry, including cis/trans, allene, tetrahedral, square planar, trigonal bipyramidal, and octahedral stereochemistry. Starting with a SMILES string from some source, you can test for an equivalent structure WITHOUT any need for "canonicalization" of the SMILES (that is, turning it into some standard form). While canonicalization is important for database searching just in terms of speed, with this addition to Jmol, canonicalization is no longer necessary for pattern matching between two SMILES strings or pattern searching of a SMILES string using a SMARTS pattern. This feature is completely independent of any actual Jmol model (although that, too, can be tested against a SMILES or SMARTS string). Thus, for example, you can have a user create a 2D structure in JME and use Jmol to test its equivalence to some reference SMILES or SMARTS string you are expecting.
Jmol 12.0.RC11 adds a completely new way to select atoms based on the SMARTS chemical informatics search language. 3D-SEARCH is an almost exact implementation of SMARTS, differing primarily in how 3D-SEARCH defines "aromatic" and also adding a "search and select" capability as opposed to just "search." The search language allows very precise selection of atoms based on connectivity. Examples include "all alpha carbons" {C}C=O, "all meta-related groups" {[A&!H]}aaa{[A&!H]}, "all trans double bonds" */{C=C}/*, and "all biphenyl connecting atoms" a:a. All stereochemical capability of SMARTS described on that page is implemented, including double-bond, allenic, tetrahedral, square planar, trigonal pyramidal, and octahedral stereochemistry. "Aromatic" is defined simply as any atom in a flat ring that has all sp2 hybridization. This is a compromise definition meant to be inclusive of some compounds that by Hueckel analysis would not be considered aromatic. In addition, setting { } around an atom or group of atoms specifies to select only those atoms, and an optional second parameter allows selecting atoms within a specific subset of atoms.Variables may be assigned within the SMARTS string (which unlike the specification at the Daylight site does allow white space and comments). Just a few examples are shown below.
Jmol 12.0.RC10 adds the noOrient filter for loading Spartan and Cygress (CAChe) files. Generally these files are loaded with a default orientation that was the orientation when the file was saved.
Jmol 12.0.RC10 adds the capability to automatically load electron density maps from the Uppsala Electron Density Server into the application and signed applet. Supporting this are the global variables edsUrlCutoff and edsUrlFormat, which set the method of getting cutoff and file from electron density server.
Jmol 12.0.RC9 adds the capability to duplicate isosurface areas based on the unit cell lattice. This is a rendering option, so it can be applied any time after an isosurface is created. It is best done with packed unit cells.
Jmol 12.0.RC7 adds two new option for wireframe, stars, halos, spacefill, cartoons, etc. "ONLY" removes all other atom rendering; "-x.y" does the same, but allows setting of the radius.
Jmol 12.0.RC6 introduces parallel processing for Jmol. Jmol 12 will be able to use multiple processors on a multiple-CPU machine. Basically what you can do is to tell Jmol which statements in a script you want to run in parallel, and it will do that. The way this is done is to create a function using the keyword PARALLEL in place of the keyword function. Within that block of code, any group of commands surrounded by PROCESS{ } will be collected and run in parallel just before Jmol returns from the function. Any commands NOT within these sets will be run BEFORE any PROCESS commands. For example:
parallel twoIsosurfaces(model1, model2) {
var x = 1
process {
isosurface s1 model @model1 molecular; color isosurface red
}
process {
isosurface s2 model @model2 molecular; color isosurface green
}
x = 2
}
load files "1crn.pdb" "1blu.pdb"
twoIsosurfaces("1.1", "2.1")
frame *
In this case, the variable x will be 2 BEFORE the isosurfaces are created. See also multi-mo.txt, multi-surface.txt, and multiProcessTest.txtmultiProcessTest.txt. You can selectively turn on and off the use of multiprocessors using set multiProcessor. If this setting cannot be set true, then it means you do not have a multiprocessor machine. Not all processes will work; currently the only implemented parallel processes are for isosurfaces and molecular orbitals. The parallel capability of Jmol should be considered experimental at this time.
Jmol 12.0.RC5 adds the option to make minimization totally silent. The default value is FALSE. In association with set useMinimizationThread FALSE, this option is used automatically to effect the loading of 2D JME strings into Jmol as 3D objects directly. Note that in some cases, more than the default set minimizationSteps 100 may be necessary for a satisfying result.
Jmol 12.0.RC5 allows inline load of data that have no new-line characters (JME strings) using load INLINE, and any model using load "@x", where x is a Jmol variable containing the model. Note that JME models are automatically turned into 3D.
Jmol 12.0.RC5 adds the FILTER "2D" option to read MOL files that have all zero z coordinates and automatically minimize the structure into 3D, as with JME, below.
127. JME reader reads stereochemistry and automatically turns 2D to 3D with addition of H atoms
The JME format is a two-dimensional file format that is very easy to create using, for example, JmeToJmol.htm but not easily adapted to 3D (until now!). Jmol 12.0.RC5 adds the automatic addition of H atoms and transformation of simple JME structures (including stereochemistry) to 3D. The 2D-to-3D conversion can be prevented using the FILTER "noMinimization" option. The transfer is not perfect, and it may take some testing to get this right.
Jmol 12.0.RC5 adds the capability to select atoms within a certain number of residues along a chain of a specified group of atoms. This feature works for nucleic acids, proteins, and carbohydrates.
Jmol 12.0.RC3 will calculate hydrogen bonds of the standard sort -- connecting H atoms with other atoms. See the documentation for details. In short, calculate HBONDS will behave as previously with standard no-hydrogen PDB files -- creating "pseudo-hydrogen" bonds between O and N atoms. However, with PDB files having hydrogen atoms and other files with hydrogen atoms, the calculate HBONDS command will generate standard hydrogen bonds from hydrogen atoms on O or N to any other atoms. If it is desired to have RasMol-like behavior even in the case of PDB files with no H atoms, one can simply select not hydrogens. The two settable parameters hbondsAngleMinimum (default value 90) and hbondsDistanceMaximum (default 3.25 for pseudo-hydrogen bonds; 2.5 for standard hydrogen bonds) can be adjusted to suit.
Jmol 12.0.RC2 adds the STEREO option to the invertSelected command. This option rotates branches connected to a center by 180 degrees around a line connecting that center and the geometric center of specified connected atoms not to invert. Simply put, thus carries out the standard organic chemist's "stereochemical inversion" at that point -- which does not invert stereochemistry along the branches, but instead switches two connected branches by simple rotation only.
Jmol 11.9.37 adds the HELIX option to the rotate command. Given a 4x4 matrix or a combination of translation and rotation, Jmol will determine the helical (screw-motion) path instead of the direct-line path of motion. Notice that the SELECTED parameter is unnecessary when in this context because the group being moved (model 2.1) is listed explicitly after the definition of the motion.
Jmol 11.9.37 adds the capability to define rotations in the ROTATE command as 3x3 or 4x4 matices. In the case of a 4x4 matrix, the indicated translation will also be conducted along with the rotation to provide a screw motion; in the case of a 3x3 matrix, one can use the new TRANSLATE option for the ROTATE command to also apply a translation separately.
Jmol 11.9.37 adds the compare function. The function takes either two sets of atoms or two arrays of atom positions (or any other sort of positions) and returns a 4x4 matrix m indicating the rotation (m%1) and translation (m%2) required to BEST transform set 1 into set 2. Unlike the COMPARE command, no filtering is done -- every atom or position in set1 is compared with every position in set2. An optional third parameter "stddev" allows return of just the RMSD for this comparison.
Jmol 11.9.37 adds %1 and %2 modulus for 4x4 matrices: m%1 returns the 3x3 rotation matrix, and m%2 returns the translation vector. Note that quaternion(m%1) then returns a quaternion equivalent of the rotation matrix, which has its own % operations.
With Jmol 11.9.37, the COMPARE command adds the option to indicate the number of seconds to use to animate the comparison. This is primariy just for WOW effect. But associated with new ROTATE SELECTED options, can be reversed.
Jmol 11.9.37 introduces a number of new options for the ROTATE command. rotateSelected is deprecated. The SELECTED option for the rotate command takes care of this need.
NBO PLOT output may be visualized by Jmol. Starting with version 11.9.36, Jmol can LOAD any of the files xx.31 - xx.41 as well as the ASCII GenNBO output file xx.48 (sometimes referred to as the "xx.nbo" file). These files are generated by adding PLOT to any NBO parameter list ($NBO $END), which may appear in Gaussian, GAMESS, Jaguar, Psi, QChem, or GenNBO input decks. The xx.48 file may be used as input for visualization specifically if AONBO=P is added to the input parameters. (This visualization is equivalent to that of xx.37 files -- NBO orbitals in AO basis.) Any of the files xx.31 - xx.41 may be used in the LOAD command (or drag-dropped into the Jmol application) provided the necessary xx.31 and xx.46 files are also present in the same directory. Note that JPG and PNG files create by Jmol using the WRITE command and stored in the directory of the .nn files contain a full state description along with the image and can be loaded or dragged into Jmol the same as the original .nn file, with the added benefit of recreating the exact 3D model state as shown in their image.
Jmol 11.9.35 adds a translucent option for color schemes. The idea is that a color scheme can go from "tranparent" to "opaque" while it goes from one color to another.
Jmol 11.9.35 adds SELECTED to the list of properties of atoms that can be checked, averaged, listed, and set. The value of the property is 1.0 if an atom is selected and 0.0 if not. As for all properties, the value for a set of atoms is the average, which in this case is the fraction of atoms selected. The example used here uses {*}.selected to get the fraction of all atoms selected and displays that in an echo at the top left.
Jmol 11.9.35 introduces the capability to compare two models and to reorient one model relative to another based on a given atom-atom coordinate pairing or quaternion-based group-group orientation pairing. References to the atom-atom correlation algorithm can be found in the literature [1] and [2]. Quaternion-based orientation pairing is an unpublished technique specific to Jmol at this point. It minimizes the standard deviation of the correlated quaternion frames for groups in the two models using spherical averaging. (Results of this option depend upon the setting of set quaternionFrame.)
By default the command does not move any atoms and just reports RMSD. The independent options ROTATE and TRANSLATE allow the option to do just rotation, do just center-of-mass translation, or do both. The basic command involves specifying at the very least two models. If no other parameters are included, the models are matched atom-for-atom based on "SPINE" atoms (or, with orienational comparisons, group by group). A subset of atoms for pairing other than SPINE, such as {*.CA} can be specified using the SUBSET option. Finally, any number of atom sets to be correlated atoms can be given. The result of atom-atom pairing comparison is essentially the same as the PyMol pair_fit command, though easier to implement and using an exact form of the structure-structure correlation rather than an iterative process.
Jmol 11.9.34 adds SPINE to the list of predefined sets that can be used in Jmol. Spine includes just the atoms that form the continuous backbone set: *.CA, *.N, *.C for proteins; *.P, *.O3*, *.O5*, *.C3*, *.C4*, *.C5 for nucleic acids. Phosphate oxygens OP1 and OP2 are not included but can be added using spine or *.OP1 or *.OP2.
101. set quaternionFrame "A", "C", and "P" for nucleic acids
quaterion frames are predefined orientations used by Jmol to compare relative or absolute orientations in space. Frame "A" was introduced in Jmol 11.8.1 and relates one alpha carbon to the next along a protein chain. In Jmol 11.9.34, this is extended to the phosphorus atoms along a nucleic acid chain. Specifically, this frame allows calculation and display of straightness and identification of secondary structure in models that only contain alpha carbons and phosphorus backbone atoms. Frame "C" is a frame that indicates the orientation of the sidechain of a protein in relation to the backbone. In Jmol 11.9.34 this is extended to purines and pyrimidine bases. Frame "P" for proteins indicates the absolute orientations of the peptide planes. Jmol 11.9.34 extends this to nucleic acids, indicating the absolute orientations of the phosphorus backbone tetrahedra.
100. quaternion arrays, differences, means, and standard deviations
Quaterions can be used in Jmol to characterize the orientation of groups. In particular, Jmol can assign quaternion frames to amino acid and nucleic acid residues automatically. This suggests the possibility of manipulating arrays of quaternions and investigating their properties. Jmol 11.9.35 adds the capability to create arrays of quaternions, find the mean, and determine their standard deviation. In addition, Jmol 11.9.35 adds the capability to calculate the quaternion differences of an array of quaternions. Quaternion differences are intersting in the area of protein-protein alignment and in quantifying the regularity of structure in helixes, strands, and other secondary structure motifs.
Jmol 11.9.32 adds a new option to lcaoCartoon, CPK, which creates a sphere at the current spacefill radius. The reason this could be useful is that such spheres, though associated with an atom, can be slabbed and capped like an isosurface. This allows for a useful "unit cell only" rendering of spacefill models, for example.
Jmol 11.9.32 allows the clean slabbing of an isosurface based on a plane definition such as x=3 or {1 0 0 -3} or the currently defined unitcell or boundbox. A negative sign prior to a plane definition indicates "the opposite-facing plane". The distinction between SLAB and CAP is that SLAB leaves the isosurface open at the boundaries, whereas CAP closes it off.
Jmol 11.9.33 allows readers to create atom-based property data that is unique to their specific reader. For example, the Crystal09 reader can read atomic spin and magnetic moment properties.
Jmol 11.9.32 generalizes unit cells to 1D (polymer) and 2D (slab) periodicity. To date, the only reader that supports this sort of symmetry is the Crystal09 solid state computation reader. When reading these files, unit cell designations {1 2 3} are adjusted to only involve the appropriate dimensionality.
Jmol 11.9.31 allows setting the frame title similar to the way echos are set, using variables, and to set all frame titles at once. The default title is the model name.
Jmol 11.9.30 adds the SIGMA option for automatically setting the isosurface cutoff to multiples of root mean square deviation (RMSD) as found specifically in CCP4/MRC electron density data files. Specifically, "sigma 2.0" delivers an electron density plot that is tighter around the nuclei. If, for example, a cutoff of 0.35 is associated with "sigma=1", then sigma 2.0 sets the isosurface cutoff at 0.75.
Jmol 11.9.28. This flag, when set TRUE, forces focus at all times and presumes no underlying applets. This allows multi-touch to activate immediately and not wait for a second click on the applet, using the first to establish focus.
Jmol 11.9.28 sets _multiTouchServer and _multiTouchClient to indicate whether it has been successful in connecting to a multi-touch device (and is thus working as a server) or to a server (and is thus working as a client).
Jmol 11.9.28 allows the local signed applet to turn off the frank. Especially useful for KIOSK applications in science exhibitions such as the recent installation of "Touch a Molecule" at the Epcot Theme Park.
Introduced in Jmol 11.9.24, Jmol 12.0 will change the default sensitivity of the mouse wheel to work less agressively. To use the older Jmol 11.8 sensitivity, use set mouseWheelFactor 1.15; the default for Jmol 12.0 is 1.02. Similarly, Jmol 12.0 will have a less agressive drag sensitivity for the mouse, allowing the mouse to work more appropriately, especially in a touch-screen environment, (where the "mouse" is a finger). The default value of 1.0 for set mousedragFactor allows a 180-degrees rotation when the pointer drags across the full window width.
Jmol 11.9.24 makes any command given of the type xxxx.xxx into an implicit SCRIPT xxxx.xxx command. This is just for convenience when working with the console, primarily.
Jmol 11.9.24 adds a new command specifically for the signed applet and the application. The LOG command works the same as print but records the information in a log file. If the printed data starts with the characters NOW, then those are replaced by the date and time. For example: log "NOW
" + getProperty("modelInfo"). The file to log to must first be designated using set logFile "someName". This name will be prepended with "JmolLog_" and must not contain any directory path. The file will always be created in the Jar file directory. Note that logging is not ever possible with the web-based version, even with the signed applet, but signed applet or application running locally can log to a file. In addition to explicit use of the LOG command, two settings, set logCommands and set logGestures allow automatic tracking of commands and gestures (swipe, pinch, zoom, spin) to the designated log file.
In Jmol versions prior to 11.9.24, all moveTo operations executed to completion prior to continuing a script. With set waitForMoveTo FALSE, one can allow moveTo operations to work asynchronously, meaning they have their own thread, and the script will continue immediately. To stop an asynchronous moveTo operation, use moveTo STOP. In addition, the mouse action DOUBLE-CLICK-LEFT is bound to "_stopMotion".
Jmol 11.9.24 adds the DRAG picking style option. set pickingstyle DRAG makes the LEFT button a click-and-drag button when associated also with set PICKING select (molecule, group, chain, etc.) and set dragSelected.
Jmol 11.9.24 adds STRUCTURE (i.e. helix, strand or turn), and POLYMER to picking select option. POLYMER is distinct from CHAIN in that some chains contain more than one connected sets of groups, while a "polymer" is defined as a connected set of groups.
Jmol 11.9.24 adds the option to set a script to execute at a future time, either as an isolated event or repetitively. The command takes the form TIMEOUT name mSecDelay "script", where a name is given for future reference along with a delay in milliseconds and a script to run. If the millisecond delay is given as a negative number, then the event repeats every -(mSecDelay) milliseconds. The minimum practical value for the delay is about 100 ms. If the delay is 0 or the script is the empty string "", then any currently waiting timeout with that name is canceled. In addition, timeout name OFF cancels a timeout, and timeout OFF cancels all timeouts. All timeouts are also canceled when a new structure is loaded. The show timeouts command displays a list of all currently active timeouts.
This option, introduced in Jmol 11.9.23, turns off many memory-consuming features of Jmol that are necessary for preserving the state. It can be used in situations where memory is at a premium and there is no desire to write or save the current Jmol state.
Jmol 11.9.23 will generate a relatively compact JVXL XML "vertex-only" mesh surface file from an isosurface. A typical command, after creation of an isosurface, would be write MESH t.jvxl. Note that standard JVXL files are considerably smaller, however. (Jmol application and signed applet only.)
Jmol 11.9.23 allows reading of PDB files that contain no MODEL line and are instead simply concatentated versions of the same atoms as trajectories using the TRAJECTORY keyword. Each model must start with atom number 1 for this to work.
Jmol 11.9.22 adds a new feature for the console. If in the middle of typing a set command one starts pressing the TAB key, Jmol cycles through all possible SET options starting with whatever characters have been typed so far.
In rapid prototyping of protein models, it is sometimes necessary to add short connectors between strands and helixes to provide strength to the plastic model. Jmol 11.9.22 adds a new shape, STRUT, that creates these supports. Created especially for the folks at the Center for Biomolecular Modeling at the Milwaukee School of Engineering, these stick-like objects can be added using the CONNECT ... STRUTS or SET PICKING STRUTS commands, and they can be calculated automatically using calculate STRUTS, which utilizes an algorithm contributed by George Phillips at the University of Wisconsin. STRUTS are not measures and they are not covalent bonds. When calculating struts, three parameters are used (defaults given): set strutSpacing 6 sets the minimum spacing between struts, set strutLengthMaximum 7.0 sets the maximum length that is allowed for a strut, and set strutsMultiple FALSE when set TRUE allows multiple struts on a given atom. In addition, set strutDefaultRadius 0.3 sets the default radius for struts. (Their color by default is translucent white.)
Jmol 11.9.21 adds an INLINE option to the isosurface command, complementing the inline option for the PMESH command. Data would generally already be present in a variable. It is advisable to reset the variable after use to improve performance, however note that the state will only be preserved if the value of the variable is left unchanged.
Jmol 11.9.21 adds two new picking options. CONNECT performs like measuring distances, except bonds are created; DELETEBOND does the opposite -- deleting the bonds between selected atoms (and with set BONDPICKING TRUE, deletes bonds as they are clicked.
Jmol 11.9.21 adds a new option for isosurface allowing rendering of the actual grid of numbers (volume rendering) of the data rather than an actual isosurface. With CUTOFF 0.0, this setting delivers the entire set of data points.
Jmol 11.9.19 adds the slabByMolecule and slabByAtom options. The first removes entire molecules when they are partially clipped by a slabbing plane; the second removes whole atoms and bonds only.
Jmol 11.9.19 allows the ability to draw polygons based on a set of vertices and a set of faces. This capability allows drawing any number of flat triangular (not quadrilateral) faces with or without edges around each face. The description is somewhat like that for PMESH files and involves (a) giving the number of vertices, (b) listing those vertices, (c) giving the number of faces, and (d) listing the faces with a special syntax. Each face is described as an array indicating the three (0-based) vertex indices followed by a number from 0 to 7 indicating which edges to show a border on when the mesh option is given: 0 (no edge), 1(v0-v1 edge), 2(v1-v2 edge), 4(v2-v3 edge), and then combinations of these to give combinations of edges.
Jmol 11.9.19 adds a WITHIN option to produce the surface within a given distance of ANY atom in the set, not just the center. (isosurface WITHIN was introduced in Jmol 11.1.21 but not documented).
Jmol 11.9.18 allows for an exponential sort of fog shading. The parameter is log_2(p) where the opacity function f = [(zDepth - z) / (zDepth - zSlab)]^p. This provides a more dramatic effect of depth.
Jmol 11.9.18 adds the MEASURE() function, allowing programmatic return of measurement information. The syntax is: measure({exp1},{exp}[,{exp}[,{exp}]], min, max, format, units, "CONNECTED"). That is, two to four expressions, minimum and maximum range in Angstroms, a format expression of the sort "%a1 %a2 %5.3VALUE %UNITS", a specification of desired units, including "pm", "nm", "au", or "angstroms", and the keyword "CONNECTED" if the atoms must be connected.
Jmol 11.9.18 adds CONFIGURATION to select options. When a model has two alternative locations for some atoms, one can now simply select (or display, hide, color, etc.) the set of atoms that have no alternative location and the set of the nth alternative location using select configuration=n.
Jmol 11.9.17 introduces the ability to describe and illustrate symmetry operations. In addition, you can pick any two atoms or groups or any two positions in space and see the symmetry relations between those groups.
Jmol 11.9.17 changes the default Van der Waals radius to "AUTO" to allow non-PDB files and PDB files with H atoms to load with a slightly different look than PDB files with no H atoms. This brings Jmol's default parameter set in line with OpenBabel 2.2.] Along with this change there is a simple syntax for specifying SPACEFILL, HALO, and STAR size.
Jmol 11.9.17 adds the SCALE3D option to isosurface. This generates a 3D plot of the desired scale from a mapped plane. It can be introduced either with the original definition of the isosurface or later.
Jmol 11.9.14 adds a DGRID reader. These files are generalized representations of output from a variety of quantum mechanical calculation packages, including especially ADF.
Jmol 11.9.13/14 adds the ANISOTROPY option for all PMESH and ISOSURFACE objects. Just add a point or array after the ANISOTROPY keyword to indicate the scaling in the X, Y, and Z directions. An optional CENTER can also be defined rather than the standard {0 0 0}. The OFFSET option allows an after-the-fact repositioning capability.
Jmol 11.9.13 adds the phongExponent parameter. This is a standard parameter relating to specular reflection (the bright dot on a ball) and is related to Jmol's specularExponent as 2^(specularExponent)
Jmol 11.9.13 adds the option to not save helix/sheet/turn data to the state. Generally this information is unnecessary, and in certain situations it can be a large amount of information. The flag is generally set TRUE by default.
Jmol 11.9.12 allows specification of axis labels. Either three or six labels can be indicated. If only three axes labels are given, the axes will start at 0.
34. scales for axes, boundbox, measures, and unitcells
Jmol 11.9.12 adds optional scales to axes, boundbox, unit cells, and measures. There are three levels of ticks - major, minor, and "subminor." Only the major ticks have labels. Which of these tick levels are displayed and the distance between ticks depends upon the parameter that looks like a point given after the keyword TICKS in the AXES, BOUNDBOX, UNITCELL, or MEASURE command. For a specific axis, include "x" "y" or "z" just after TICKS. The additional optional keyword FORMAT defines the format of the labels for the major ticks. These are based on an array of strings given after the FORMAT keyword. If the array is shorter than the number of ticks, the formats in the array are repeated. The label numbers and tick separations do not have to be angstroms. For the UNITCELL command, simply use fractional coordinates for the ticks to provide a scale in unit cell coordinates. For the other commands, scaling is accomplished using the SCALE keyword followed by a general scaling number or a point indicating how much scaling to apply in each of the directions x, y, and z. For MEASURE you can also add a FIRST keyword followed by a starting value.
Jmol 11.9.11 introduces a modified Sparsh-UI gesture server interface that allows Jmol to talk to a special multi-touch driver (our first C++ component of Jmol). The interface so far allows multi-touch action only an HP TouchSmart computer (or any computer with NextWindow technology. The stand-alone Jmol application, Jmol embedded in other Java programs, and the signed applet are supported. One must first start JmolMultiTouchDriver.exe. After this small C++ program is running, all messages from the touch-screen are passed to Jmol and interpreted as "gestures." The signed applet must be started with the "multitouchSparshUI" parameter set to "true". The application must be started with the -Msparshui flag, and embedded Jmol must be passed the command option -multitouch-sparshui. Gestures include a standard two-finger spread/pinch for zoom in/out, a two-finger slide for translation, and a one-finger "flick" to start spinning.
Since Jmol 11.7.1 users have been able to draw arbitrary lines using draw LINE followed by a set of points. Starting with Jmol 11.9.10, you can draw line segments based on a set of start/stop pairs. The command was designed to allow for saving the state of the draw INTERSECTION command, but may have other practical uses.
Jmol 11.9.10 adds the option to color the mesh aspect of an isosurface differently from the isosurface itself. Just indicate the color of the mesh prior to defining the object itself.
Jmol 11.9.9 introduces two new commands, BIND and UNBIND. These commands allow customized connections between user mouse actions and Jmol actions. In addition, you can now tie a mouse action to a script of your choice, and Jmol will insert into that script the variable names _X, _Y, _DELTAX, _DELTAY, _TIME, and _MODE. Current Jmol actions that can be bound to mouse actions include: _clickFrank, _depth, _dragDrawObject, _dragDrawPoint, _dragLabel, _dragSelected, _navTranslate, _pickAtom, _pickIsosurface, _pickLabel, _pickMeasure, _pickNavigate, _pickPoint, _popupMenu, _reset, _rotate, _rotateSelected, _rotateZ, _rotateZorZoom, _select, _selectAndNot, _selectNone, _selectOr, _selectToggle, _selectToggleOr, _setMeasure, _slab, _slabAndDepth, _slideZoom, _spinDrawObjectCCW, _spinDrawObjectCW, _swipe, _translate, and _wheelZoom
Jmol 11.9.9 adds the MOUSEINFO property to getProperty. This information includes detailed information about how ALL mouse actions correlate with Jmol actions.
Jmol 11.9.9 introduces a command that lists the current Jmol action/mouse button bindings. The option provides a quick way to search for any word in the command description.
Jmol 11.9.9 represents a major upgrade in the way mouse events are handled internally. Events are "bound" to Jmol "actions" in a dynamic way. This allows for future expansion to include customized mouse action. A Java programmer using Jmol can now completely rewrite Jmol's mouse button mapping in just a few minutes. This upgrade also allows for "gestures" -- dragging motions that are bound to specific actions based on their temporal or spacial pattern. One gesture is included in Jmol 11.9.9: a swipe of the screen that starts the model spinning on an axis perpendicular to the swipe and parallel to the screen. Additional multi-touch gestures can now also be bound to specific actions. For example an iPod-like "pinch" could indicate "zoom out", or a two-finger swipe could mean "advance animation". The gesture capability is turned on using set allowGestures TRUE. It is turned off by default to be compatible with previous versions of Jmol.
Jmol 11.9.8 adds the capability to temporarily hide or display selected labels. Select the desired atoms, then issue the command label HIDE or label DISPLAY. Unlike label ON and label OFF, these options do not reset the label to the default label. Jmol 11.9.8 also changes the action of set toggleLabel to toggle labels hidden or displayed without resetting them.
Jmol 11.9.8 allows loading of a single vibration by number, starting with 1. Simply include the negative of the vibration number after the file name. (A positive number here is a model number.)
The JVXL format allows compression factors in the range 10-300 for file delivery of isosurface data. Jmol 11.9.7 is an initial attempt to define an XML standard for JVXL files. To date, the JVXL file format in its original form has been only marginally extensible -- but has been extended by use of XML-like fields. This version creates a simple XML format that allows for a wide variety of future implementation, including additional methods of ASCII-encoded compression, discretely contour-mapped plane and other surface data, pmesh triangle/vertex data storage capability, and generalized contour containers. The default writing format is now "XJVXL" for these extended types, and in this version use of ".xjvxl" in the file name of the file enables writing of all isosurface types as XML files.
Jmol 11.9.7 adds the now(i) function to show milliseconds of time since an event. Just assign now() to a variable such as x, and then later check now(x).
17. isosurface ... map CONTOUR DISCRETE and INCREMENT
Jmol 11.9.7 allows creation of specific contour levels for an isosurface, and also changes the visualization of the solid sections between the contours to be solid colors (FILL attribute of the isosurface command). The DISCRETE keyword allows any values; the INCREMENT keyword allows creation of a set of contours based on the set {from, to, step}.
Jmol 11.9.7 perfects the effect of fog -- a blending of distant areas of the model into the background. To turn on this effect, issue set zshade;. The standard SLAB and DEPTH values (default 100 and 0, respectively) determine both the clipping plane and the points where the structure appears clearest (slab value) and where it blends into the background (depth value). Note that issuing slab on is no longer necessary to enable zShading.
14. isosurface ... COLOR "color1 color2 color3..."
Jmol 11.9.7 adds the capability to specify contour colors directly, without a color scheme. Simply place a set of color names in quotes after the COLOR keyword for the isosurface. If fewer colors are given than contours, the color sequence is repeated as many times as necessary. The FILL keyword fills the spaces between the contour levels with solid colors, as for discrete contours.
13. isosurface contour DISCRETE and contour INCREMENT
Jmol 11.9.7 adds two new options for isosurface plane mappings that allow for a more GNUplot-like contouring. The first option, CONTOUR DISCRETE, accepts a set of contour level values in the form of an array. The second, CONTOUR INCREMENT, takes three numbers -- first, last, and step -- in the form of a point {from, to, step}. If the isosurface is given the FILL attribute, the lines are drawn in black, and regions between the contours are given solid colors (that is, with no color blending).
Jmol 11.9.5 adds the capability to test for sizes of several shapes, including backbone, cartoon, dots, ellipsoid, geosurface, halo, meshRibbon, ribbon, rockets, spacefill, star, strands, and trace. Settable shape sizes include all of the above except dots, ellipsoid, and geosurface.
Starting with Jmol 11.9.4, you can use write "myfile.jmol" to save a single ZIP-format file that contains all files necessary to load the model state. Drag/dropping this file into Jmol or using load "myfile.jmol" recreates the state. The file contains (1) a file JmolManifest.txt, which indicates the date of creation, Jmol version used, and the file to open, (2) a JPG image with embedded script, (3) an SPT state file, and (4) all additional files required (PDB files, JVXL files, etc.). If a different file extension is desired, the keyword ZIPALL can be used prior to the file name: write ZIPALL "myfile.zip". In addition, rather than using ZIPALL, if the keyword is "ZIP", then only files local to the file system are saved -- any remote file references starting with http:, https:, or ftp: are left as such, and those files will be accessed remotely when Jmol opens the archive. An example of a Jmol Archive Format file is data/test1.jmol. It can also be tested using the Jmol Crystal Structure Explorer, where it is invoked by a JmolButton (lower right panel). The JmolManifest method was introduced in Jmol 11.4; it can be used with this format to load specific files in specific ways. This format is under review, and comments are appreciated.
Jmol 11.9.4 can insert into a script file the path to that file. The special string $SCRIPT_PATH$ will be replaced. The path will either end with "/" or "|", depending upon whether it is into a subdirectory or a ZIP file. When the replacement is done, "$SCRIPT_PATH$/" will first be replaced by the path, then $SCRIPT_PATH$ alone will be replaced. See, for example, data/test1.txt.
Perhaps one of the most difficult aspects of symmetry is seeing that the product of two symmetry operations is still a symmetry operation. And which one? Jmol 11.9.3 allows multiplication of symmetry operations, because they are simply matrices. Combined with the capabilities of the symop() function to calculate symmetry operations from matrices, you have a very powerful symmetry operation "calculator".
Jmol 11.9.3 adds matrix mathematics and, in particular, represenation of symmetry operations as matrices. The syntax is the same as for JavaScript: [[a, b, c],[d, e, f],[g, h, i]] (3x3 matrix) or [[a, b, c, x],[d, e, f, y],[g, h, i, z], [j, k, l, w]] for a 4x4 matrix.
Jmol 11.9.3 allows extracting of symmetry operation information directly from the symop() function. The information is in the form of an array, as described below in context.
Jmol 11.9.2 adds two options to the SCRIPT and WRITE STATE commands. When reading or writing a script, the LOCALPATH keyword instructs Jmol to strip all paths beginning with "file:/" down to the indicated path. So, for example, script LOCALPATH "" "myfile.spt" indicates that all local files referenced in the state script should be read from the current default directory. Similarly, REMOTEPATH strips paths from file refrences starting with "http:", "https:", and "ftp:". LOCALPATH and REMOTEPATH are desigend specifically to be used with scripts created by Jmol in the process of defining its state, but the option can be used with scripts you write yourself. The mechanism is simply looking for instances of /*file*/"some_file_name". If this construction is found in any script read, the replacement will be made.
Jmol 11.9.2 introduces a calculation for molecular volume. This calculation depends upon what set of Van Der Waals radii one uses. "type" can be one of "Jmol", "Babel", "Rasmol" or "User". If not provided, "type" defaults to the default type specified by the command set defaultVanDerWaal. The calculation is a simple one that just adds up all the Van Der Waals volumes and subtracts off the overlap of spheres associated with bonds as described by A. Bondi (J. Phys. Chem. 68, 1964, 441-451.). The built-in Van der Waals set "Babel" most closely represents this setting.
The script c6h12.txt illustrates several advanced features of Jmol. In this script, a set of 35 cyclohexane conformations are fitted with quaternion frames on C1 and C4 carbons. A calculation is made of the similarity of each pair of quaternion frames within each model, allowing the rings to be colored based on how similar they are to a cyclohexane chair conformation. A bar graph near the bottom of the window is used to allow the user to quickly scan through conformations. The JavaScript callback for this action is created by the script itself, defining a JavaScript function on the page using the javascript command within Jmol.
The measure is calculated as
grp.property_st = 1.0 - acos(abs(q1.dot(q2)))/90
This measure is directly related to the "distance" between the quaternions on the four-dimensional hypersphere and is thus a direct measure of how well the two frames are aligned. If the frames are perfectly aligned, then this measure is 1.0; if they are completely oppositely aligned -- differing by a 180 degree rotation along any axis -- then this measure will be 0. The reason this works is that the dot product of two unit quaternions is the cosine of half their angular distance on the four-dimensional hypersphere: q1.dot(q2) = cos(theta/2), similar to how for two 3-dimensional unit vectors v1 and v2, v1.dot(v2) = cos(theta), where theta is the their angular distance on the unit sphere. We don't care about the sign of this value, because angles 0 and 180 degrees (cosines 1 and -1) for a quaternion relate to rotation angles 0 and 360 degrees, and those are the same for our purposes here. So taking the arccosine of the absolute value of the quaternion dot product returns a quaternion angle between 0 and 90, with 0 being "perfectly aligned" and 90 being "oppositely aligned." Dividing by 90 and subtracting from 1 gives a measure that is 1.0 for perfect alignment and 0.0 for opposite alignment.
Starting with Jmol 11.9.1, you can detect clicking and dragging within the applet window, and you can cancel that operation if desired. The callback function takes the form:
function myClickCallback(app,x,y,modifiers,clickCount,Ret){}
app is the applet identifier, usually "jmolApplet0". x and y are screen coordinates with [0,0] in the bottom left corner. modifiers is a set of bits indicating what keys and mouse buttons were pressed: 1(shift), 2(ctrl), 4(right), 8(alt), 16(left). If none of these bits are set, this is a "mouse-up" event. clickCount is the number of clicks. 0 here indicates the mouse was pressed (as in the initiation of a drag operation); negative numbers indicate dragging; positive numbers are standard clicks of the mouse. Ret is an array with just one element that allows returning a new modifier. Setting Ret[0]=0 cancels Jmol processing of the event.
