Methods for showing orbitals in Jmol/JSmol web pages

Generating orbital data

• I have used Jmol to show orbital models generated by ab initio calculations using Gaussian.   Jmol can show orbitals calculated using other software, but I am not qualified to comment on this
• Jmol can read Gaussian cube files, but, for my relatively small molecules, I have preferred to do a Natural Bond Orbital analysis in Gaussian.   Besides calculating NBOs, NAOs etc., this also can output a file of delocalised molecular orbitals
• Jmol can read any of the files representing sets of orbitals, produced by NBO in Gaussian, and because the data required for surface display are generated in Jmol, the files to be served are much smaller than the corresponding cube files would be

Using NBO analysis in Gaussian to generate orbital data for Jmol

• To run a NBO job in Gaussian, use the pop=NBOread keyword, and for the NBO section at the end of the input file, put
  $NBO
  RESONANCE
  PLOT
  archive file=filestem
  $END
  where filestem has between 4 and 8 characters


• The RESONANCE keyword is necessary for organic molecules with 'delocalised' bonding and, it would appear, for most inorganic molecules
• The NBO software will write a series of files with names filestem.nn where nn are two-digit numbers
  filestem.36 is for preorthogonal natural bond orbitals, which I think are best for showing orbital overlaps in a model
  filestem.32 is for preorthogonal natural atomic orbitals, if, e.g. for teaching purposes, you want to show the atomic orbitals from which the MOs are made
  filestem.40 is for delocalised molecular orbitals
• Besides reading one or more of these, Jmol always needs the files filestem.31 and filestem.46 as well, so these files also should be copied into your web page directory and permitted read to others
  filestem.31 contains the molecular geometry and basis set information which Jmol will use in calculating the orbitals required.
  filestem.46 contains orbital labelling information


• The NBO package built in to Gaussian does not itself produce the file filestem.46.   Rather than purchasing more up to date NBO software, a perl script 'nbolabel' is available to generate the file from the NBO output files
• This was written by Dr. J.P. Hagon of Newcastle University, England, who has kindly permitted me to publish it, with the usual provisos that neither he nor the University accept any liability for any harm it may cause.   I have used nbolabel for several years without any problems.   It may be examined at
  https://www.staff.ncl.ac.uk/bruce.tattershall/jmolapps/nbolabel   and copied from there
• The script was written to run in a Linux system supporting the perl language
• In a directory containing the Gaussian output files, give the command
  nbolabel --prefix=filestem --logfile=gaussian_output
  where 'filestem' is as used for your Gaussian NBO run and gaussian_output is the full name of the output log file from the run
• Because nbolabel simply writes one extra file, the orbital numbering in the other files still corresponds to the Gaussian log file.   You can use the detailed and informative NBO listing in the NBO section of the log file to identify which PNBO corresponds to which orbital number, when selecting them for display using Jmol
• The numbering of the MOs in filestem.40 is the same as in the main part of the Gaussian log file, where the number of the HOMO and hence of the LUMO is easily determined.   MOs below or above those respectively are most easily identified by inspection of their Jmol model in the standalone Jmol application

Loading the orbital information into Jmol

• The requisite orbitals file is loaded with a Jmol script command similar to that used for loading a geometry file, e.g. "load 'filestem.40'" instead of "load 'filestem.xyz'"
• This will load the geometry of the molecule as well as the set of data for, in this example, delocalised MOs
• Note that the initial orientation of the model will be different from that obtained if 'filestem.xyz' from the same calculation, but saved using e.g. Molden, had been loaded.   If you wish to load such a .xyz file in order to provide an easy way, using the Jmol menu, for users to save the atomic coordinates of your model, as well as an option to show orbitals using the NBO files method, then two different .spt script files should be used to set the orientations (and the appearances) to be the same or different as desired

Showing an orbital in Jmol

• Once the set of MO or NBO data has been loaded, Jmol needs to generate a rotatable 3D model to add to the model of the geometry
• I find two kinds of model are useful to me: a surface with a particular value of the wavefunction, coloured differently for positive and negative lobes, or a 2D contour plot in a plane through the molecule
• Surfaces quickly show the user the directions in which lobes of the orbital 'point', but do not show how the wavefunction varies in value e.g. with distance from a nucleus, whereas a contour plot in a plane shows the variation of the value of the wavefunction, but only in one preselected direction.   Either for showing overlaps of NBOs or for showing MOs for teaching purposes, I feel that having both is the best solution
• I make the surfaces semi-transparent so that the contour plot and the ball-and-stick (or whatever) model of the geometry may be seen through the surfaces

Orbital surfaces

• For surfaces, Jmol provides a command 'mo' which may simply be followed by the number of the orbital to be shown.   In the console of the Jmol standalone application, one may simply give the command
  mo 9
  and the ninth orbital in the loaded set will be shown.   A large set thus may be explored very easily.   The same may be done using the console of a Jmol_S or a JSmol web page, if a set of orbitals has been loaded, and if the user is familiar with Jmol commands
• Further 'mo' commands may be used, before or after selecting the orbital, to define the appearance of the surface
• Thus, the sequence of commands
  mo cutoff 0.04; mo nomesh fill translucent 0.5; mo colour blue red;
  mo 9
  will produce a surface at wavefunction value 0.04, without a mesh appearance, semi-transparent, and with opposite sign lobes blue and red, for orbital number 9 in the list


• One important restriction of the Jmol mo command is that only one orbital may be shown at a time.   If one wishes to show the overlap of two or more PNBOs e.g. to illustrate 'lone pair repulsion', or any kind of non-bonded electronic interaction, the orbital data must be loaded two or more times consecutively using first a 'load' command and then one or more 'load append' commands with the same file to be loaded
• This will generate two or more models in successive animation frames.   Then give a frame command before each mo command, e.g.
  frame 1; mo 72;
  frame 2; mo 73;
  then show both superimposed by giving the command
  frame all;

Orbital contours on a plane

• Showing contours on a plane is slightly more complicated, because the very versatile 'isosurface' Jmol command is used and the plane must be defined before the contours can be drawn on it
• There are several ways to define the plane in Jmol.   For a small, symmetrical molecule it may be sufficient to define the plane in terms of the molecular axes.   Thus
  axes molecular
  isosurface one plane 'yz' contour 21 mo 9
  isosurface one colorscheme 'bw'
  will define a surface as the molecular yz plane on which are drawn 21 contours to represent the values of mo number 9 in that plane
• If the orbital has nodes intersecting the plane, the number of contours used should be odd
• Normally one would orientate the model using the .spt file which loads it, so that the isosurface plane corresponds to the plane of the screen in the initial view.   Like MO surfaces, the contour plane is attached to the geometric model so that it turns with the molecular model if this is rotated by the user using the mouse
• The plane is infinitely thin, so the contours will disappear from view if the model is turned so that the user would see it edgeways on
• Unlike the Jmol command 'mo', which in one frame may refer to only one orbital at a time, there is no restriction (except speed and memory issues) on the number of isosurfaces which may be defined for a frame.   Consequently they are given names, here 'one' in the present example, so that they may be modified subsequently
• Note that the plane parameter and the contour parameter and the mo parameter must all be together in the same command, so that Jmol knows that this is a contour plot on a plane rather than either a coloured plane or an orbital surface
• Here the contours are coloured black on white (note the USA English spelling in the command).   This shows well through semitransparent orbital surfaces, the colours of which reveal the sign of the wavefunction in various regions instead of this information being represented by the colour of the contours
• If the contour plot is desired to stand alone, it may be coloured to show change of sign across nodes, using
  isosurface one colorscheme 'bwr'
  instead.   This shows contours varying from blue through white to red.   Blue is negative and red is positive


• If one wishes to show orbital overlap, then a plane might be defined as passing through two of the atoms involved and through a third selected so that the plane shows the desired contour overlap.   Thus, I have used
  plane (atomno=4) (atomno=5) (atomno=1)
  where atoms 4 and 5 were the ones with overlapping orbitals, and atom 1 happened to be in the right place to make the plane bisect both the positive and negative lobes of the two lone pair orbitals involved
• The full sequence of commands was
  frame 1; isosurface one plane (atomno=4) (atomno=5) (atomno=1) contour 21 mo 72
  frame 2; isosurface two plane (atomno=4) (atomno=5) (atomno=1) contour 21 mo 73
  isosurface one colorscheme 'bw'; isosurface two colorscheme 'bw'


• You will see that two identical planes are used, and contours for one orbital (in this case a PNBO) are written on each
• Frames are used only because they were set up for showing the corresponding orbital surfaces using the Jmol 'mo' command.   They could be used for selectively switching both surface plot and contour plot for a particular orbital on or off at the same time, allowing a complex overlap situation to be built up piece by piece by the user clicking Jmol buttons

Letting the user know what is happening

• Letting Jmol read data for a whole set of orbitals, and then calculate surfaces or contours for one or more of them, is useful if the set of orbitals is relatively small and if the user is to display one at a time.   The time taken by Jmol to do the calculation is acceptable for Java Jmol_S, but for a browser which does not have the Java plugin, and consequently is using the JSmol HTML5 option, the delay is noticeable and, for contours on a plane, in particular, may be unacceptable


• The user should at least be told what they are waiting for, as follows
  set echo bottom centre; echo Calculating surfaces, please wait; refresh
• When the calculation has been done, the message is removed, as follows
  echo; refresh
  where echo without an argument erases the previous message

A real web page showing the loading of a set of orbital data and calculation of surfaces

• Preferably using Chrome as your browser, the following link should show, in a separate window, the real web page from which was taken the above example of showing a single orbital at a time from a loaded set
  https://www.staff.ncl.ac.uk/bruce.tattershall/teaching/chy135/co2mo/showjmol.php?use=HTML5&filestem=co2&basis=MO&orbital=sigma_C(2p)O(2p)&orbno=9&winno=1
  
• Displaying the page source will show how it was done
• The JavaScript in the body section of the html script starts by defining JavaScript functions
• function loadstructure is where the set of MO data from a NBO .40 file is read in
• function showmos is where the orbital surface is created


• Jmol has a disadvantage of running scripts in parallel, so the showmos function cannot be called until the data from the .40 file has been read in
• To achieve this, function loadstructure starts off by defining a callback function which Jmol will call automatically when loading of the .40 file (and the other NBO files which go with it) is complete
• This callback function is called structloadedfun, and is the first function to be defined in this JavaScript script
• In structloadedfun, the user is told what is happening, as suggested above, then the showmos function is called, then the message is switched off again


• Because calculating contour plots on a plane is slow in JSmol, doing so is postponed until the user clicks a Jmol radio button to request a contour plot, when it will be done using a Jmol function (rather than a JavaScript function) called showcontours
• The showcontours Jmol function is defined in advance in a JavaScript Jmol.script call towards the end of the structloadedfun callback function


• The complications of using a callback function to delay surface creation until the data has been loaded can be avoided by using pre-stored surfaces, as discussed in the following section
• The page source for the example at the end of this page is consequently a lot simpler

Using pre-stored surfaces or contour plots

• If only a few of the possible orbitals are to be shown, a good solution to the problem of calculation time is to save the calculated surfaces to individual files, then read them back in at the time of the user's web session
• This saves time for the user, at the expense of server storage and, if it is limited, the user's download allowance.   However, storage, download time and volume can be saved by compressing files with gzip.   Jmol input files generally may be compressed, and Jmol will detect this automatically and uncompress them, even if their names do not end in .gz

Stored orbital surfaces

• To store an orbital surface, the .jvxl file format is used
• It is easiest to do this in the Jmol standalone application, rather than using the Jmol_S Java web applet or the JSmol HTML5 web applet if these have already been set up to show non-stored surfaces.   This is because either is very annoyingly subject to cache problems in respect to any files read, other than the page source .html or .php file which loads the applet itself.   If you are showing more than one orbital at a time, it is also very easy to become confused about which frame Jmol is using, while using the console to store surfaces


• Thus, suppose that you wish to store ready-made surfaces to represent PNBO orbitals 72 and 73 for your model called 'filestem'
  Start the Jmol standalone application in whichever Linux or Windows Java-equipped machine you have installed it, then, using right mouse click, open the Jmol console and give the commands
  background white
  load filestem.36
  write filestemorb.xyz
  mo 72
  mo cutoff 0.02; mo nomesh fill translucent 0.5; mo colour blue red;
  write mo filestems72.jvxl
  mo 73
  write mo filestems73.jvxl


• In the third line of this, the geometric structure is written to the directory in which you open Jmol, as an .xyz file.   You may use a .mol file if you prefer, but you do need to store a geometry corresponding to the data in the NBO file, to which the stored surfaces may be attached
• Notice that when you create the second MO surface, it replaces the first, inheriting the set up properties such as cutoff, because there is only one frame and for it only one mo command at a time is valid.   You are simply replacing the definition of which orbital number to use, while leaving the rest of the mo structure intact
• For the isosurface names I have used 's' followed by the orbital number for surfaces, and will use 'c' followed by the orbital number for contours on a plane.   The files being stored have names made up of filestem concatenated with the name of the isosurface.   In this way I have tried to keep track of what I am doing


• Now test the saved files, as follows
  zap
  load filestemorb.xyz
  isosurface s72 filestems72.jvxl
  isosurface s73 filestems73.jvxl
  isosurface s72 translucent 0.8
  isosurface s73 translucent 0.8


• Notice that the two isosurfaces both belong to the same frame.   All of the properties of the orbital surfaces appear to be stored and correctly read back, except for the translucency, which needs to be replaced with a higher value in order to reproduce the original appearance
• The data part of .jvxl files is already highly compressed, so they do not need to be further compressed using gzip
• While using the Jmol standalone application, it is useful to experiment with rotate commands after a reset command, to find the way to the most informative orientation of the molecule and its orbital surfaces.   You may then use these rotation angles in a .spt script file to load filestemorb.xyz
• Because of the cache problems mentioned above, test out and perfect the .spt file you create, in the Jmol standalone application, before calling it in a script to control the Jmol applet
• In Linux, remember to permit all of the created files read to group and others before you try to read them in a web page

Stored orbital contours on a plane

• To store a contour plot on a plane through the molecule, the .jvxl format could be used, as for orbital surfaces, but the resultant isosurface is still slow to restore
• It is better to use the .pmesh format and to compress the resultant file using gzip


• Continuing the above example, in the Jmol standalone application, give the commands
  zap
  load filestem.36
  isosurface c72 plane (atomno=4) (atomno=5) (atomno=1) contour 21 mo 72
  isosurface c72 colorscheme 'bw'
  write isosurface filestemc72.pmesh
  isosurface delete
  isosurface c73 plane (atomno=4) (atomno=5) (atomno=1) contour 21 mo 73
  isosurface c73 colorscheme 'bw'
  write isosurface filestemc73.pmesh


• Notice that the 'write isosurface' command does not seem to take an isosurface name, so after storing the first isosurface it is best to delete it before starting to construct the second
• The .pmesh files are rather sparse and large, so it is best to compress them.   If you are using Linux to store your web files, then use gzip.   In the present example, the Linux commands
  gzip filestemc7?.pmesh
  mv filestemc72.pmesh.gz filestemc72.pmesh
  mv filestemc73.pmesh.gz filestemc73.pmesh
  will replace the two files with compressed versions of themselves.   Note that Jmol does not need the .gz filename extension to tell it that the files are compressed


• To test the saved files, give the following commands in the Jmol standalone application console
  zap
  load filestemorb.xyz
  isosurface c72 filestemc72.pmesh
  isosurface c73 filestemc73.pmesh

Seeing it in action

• Chrome is the recommended browser for viewing this link