JIMP - The Interactive Molecule Program

For versions prior to JIMP.v117, all four environment variables are required.
MOPLOT_DIR=C:\jimp\moplot
FENHALL_DIR=C:\jimp\fenhall
JIMP_DIR=C:\jimp\jimp
PATH=%PATH%;%MOPLOT_DIR%\bin;%FENHALL_DIR%\bin;%JIMP_DIR%\bin

For example, after opening the dialog box in the Control Panel, one sets the environment variable for JIMP_DIR by:

• clicking "New..."
• typing "JIMP_DIR" in the text box for "Variable Name"
• typing "C:\jimp\jimp" in the text box for "Variable Value"
• clicking "Ok"

Note: Add environment variables under the "User variables for...". (Do not add the variables under "System variables".)

For version JIMP.v117, only these three environment variables are required and the MOPLOT_DIR and FENHALL_DIR environment variables are set the same as the JIMP_DIR environment variable.
MOPLOT_DIR=C:\jimp
FENHALL_DIR=C:\jimp
JIMP_DIR=C:\jimp

For example, after opening the dialog box in the Control Panel, one sets the environment variable for JIMP_DIR by:

• clicking "New..."
• typing "JIMP_DIR" in the text box for "Variable Name"
• typing "C:\jimp" in the text box for "Variable Value"
• clicking "Ok"

These examples assume that the archive was unzipped in the directory "\jimp" on the C drive. However, one could unzip this archive on the desktop of the administrator account, which for Windows 2000 would make the path "C:\Documents and Settings\Administrator\Desktop\jimp". Or one could create a directory in the "Program Files" directory (open explorer, go to the "Program Files" directory, add a new directory: File->New->Folder, change the name to jimp, cut and paste the zip file into this new directory, and unzip archive). This directory location would make the path "C:\Program Files\jimp".

Note: JIMP.v117 also requires version 1.0.3705 of Microsoft .NET Framework. This prerequisite might require one to upgrade windows and/or install .NET Framework 1.0 Service Pack 2. One can also determine which version of .Net one has installed.

If one has POV-Ray, modify the povray.bat file so that the part in quotation marks is the full path to "pvengine.exe".

========================
Linux
========================

Unzip the archive.

% tar -xzvf jimp*linux*.gz
(where the % represents your prompt)

In one's startup script such as .bashrc or .bash_profile, one needs to add an environment variables so that JIMP can find the programs that it needs. Using bash syntax this may look like the following.

export JIMP_DIR=~/jimp/jimp


For the settings to take effect one needs to source the file.

% . .bashrc

As one may have noticed, the instructions on how to install JIMP assume that the user does not have any root privileges. To make the program available to all users on a system, we would suggest unzipping the archive the /usr/local/ directory, then creating symbolic links to the executables in /usr/local/bin/.

Simple as this is, there are a few concerns specific to JIMP that must be taken into consideration. As JIMP is currently set up, it is assumed that one will be working with one molecule at a time, and when a molecule is opened, it is automatically added as a layer in the currently selected window.

If one intends for the molecule to be in its own window, first, one must create a new window. New windows are created with and empty layer by default, so it is a good idea to remove that layer. Now one may open the intended file into its own window.

Currently, there are four file formats supported by JIMP. For each one, I will describe briefly their features and limitations as imposed by JIMP.

This format is specific to JIMP. The intent of the format is to store all of the data available to JIMP in a manor that is compact.

MSI files are used by the company Accelrys, which was formerly named MSI, or Molecular Simulations Incorporated. The reason for its support is that the program Cerius² is used extensively in our lab.

Currently, JIMP can read the connectivity information and basic atom properties from the format. The amount of information that can be stored in one of these files is much larger than that, but oh well. It may be better supported in the future.

XYZ files are simply the coordinates of the atoms in XYZ format (in units of angstroms), i.e. four columns, the first column giving the element followed by three columns for the X, Y, and Z coordinates (in free format).

Currently, JIMP does not provide any connectivity when an XYZ file is opened, but JIMP can calculate it based on (scaled) van der Waals radii, namely through "Calculate->Clean->Calc Bonding"

PDB files are widely used for storing protein structures. The format gets its name from The Protein Data Bank, which is an organization that provides a huge collection of protein structures free of charge. We suggest that users check out the PDB molecule of the month feature.

JIMP is designed primarily to work with small molecules, but it also has some basic functionality for visualizing proteins. Properties such as heterogens, alternate atom positions, connectivity, and backbones of multiple subunits are supported (Check under "Edit->Protein Subunit Properties").

Okay, so I lied, there are five formats... the fifth is JWS. However, JWS (JIMP Work Space) files are not exactly new, they are an extension to JML files. JWS files save the information about the current workspace, i.e., the current information and settings for the open molecules and locations of surface files for all of the layers in a workspace (or window).

A word of caution: currently JWS files save the absolute path for file locations, not the relative path; i.e., if one moves files that were saved into a JWS file, the JWS file format will not open correctly.

For simply rotating the view, one drags the mouse while holding the RMB. In order to rotate the view around the direction of one's view, do the same thing, but make sure that when one first presses the RMB that the mouse is in a corner of the window that contains the molecule that one wishes to rotate.

To zoom in or out, hold Ctrl+LMB while moving the mouse forward or backward.

It is a bit to remember, but holding Alt+Shift+LMB while moving the mouse will translate the view up, down, left, and right.

Here is a summary of keypad/mouse combinations:

• LMB+drag --> select
• Ctrl^A --> select all
• Alt^A --> changes to atom selection mode
• Alt^B --> changes to bond selection mode
• Shift+LMB+click --> toggle selection

• Ctrl+LMB+drag --> zoom view
• RMB+drag --> rotate view for all
• Ctrl+RMB+drag --> rotate selected
• Shift+RMB+drag --> rotate view for layer
• Alt+Shift+LMB+drag --> translate view for all
• Ctrl+Shift+RMB+drag --> translate selected
• Alt+Shift+RMB+drag --> translate view for layer

• Ctrl^R --> reset view
• Ctrl^D --> shortcut for "Sketch"
• Ctrl^Z --> undo
• Ctrl^A --> select all

• Ctrl^C --> copy selection
• Ctrl^X --> cut selection
• Ctrl^V --> paste selection
• backspace --> delete selection

• Ctrl^M --> opens "Move atom/view/layer menu"

• Ctrl^N --> opens new window
• Ctrl^W --> close window (does not save, nor does it prompt one to save)
• Ctrl^S --> saves window (to current format)
• Alt+Ctrl^S --> saves current workspace (to .jws format)

• Ctrl^Q --> quits program

1. Saving a file or workspace does not save the background color, which defaults to black.
2. In sketch mode, the default atom type is carbon. To end drawing, right click once. To increase the bond order, redraw over bond and click on the first atom. Hold down Ctrl while clicking to increment the bond order by one-half. While the bond will not continue to display after "four bonds", the bond order does not cycle back to "zero", it will continue to increase. The bond order can also be adjusted under "Edit-->Bond Properties".
3. Comments on the "Smart Selector":
   • It is accessed through "Calculate->Select"
   • It has features of "Add", "Remove", "And", and "Toggle".
   • "Add" adds atoms to the current selection list.
   • "Remove" removes atoms from the current selection list.
   • "And" combines Actions of the selection lists.
   • "Toggle" toggles the selection from the current selection.
   • To select a range of element types, use "to" between element types, e.g., "H to C" selects all atoms of the periodic table between hydrogen and carbon. ALL is a valid entry to select all atoms of periodic table. Individual elements may be entered and separated by commas, e.g., "H, O" selects all hydrogen and oxygen.
   • To select a range of atom ID's, use "to" between the numbers, e.g., "1 to 5" selects atoms with ID's between 1 and 5.
   • To select atoms within a radius of the center of currently selected atoms, enter a distance in angstroms.
   • To select atoms connected to the currently selected atoms, click "Connected".
   • To select all atoms of a bonded fragment (not a Fenske-Hall fragment), select an atom (or a set of atoms) and click "Fragment".

• First, give atoms and bonds volume (see above)
• Add atom labels, bond distance labels, etc. as desired using the "Atom Properties" and "Bond Properties" dialogs
• Orient the molecule in the desired locale (this screen capture is WYSIWYG, What You See Is What You Get).
• Add any desired fields, such as orbitals (including solid, lined, and dotted isosurfaces).
• Open "Calculate->Grab Screen"
• Set the desired resolution (in pixel width and height)
• Type the desired file name in "Title:" and set the desired file location by clicking "Dir"
• Click "Grab"

The thickness of the line produced from "Field Properties->Line/Point Size" is the actual pixel width produced in the screen capture. If one desires thicker lines or larger dots, increase this value.

The dialog to create scene files (#.pov) and ray-traced images (#.png) with POV-Ray [Persistence-of-Vision Ray-tracer] (of any resolution) is located under "Calculate->Povray". One must have POV-Ray installed to create the PNG file, but the scene file is created regardless.

• First, give atoms and bonds volume (see above)
• Add atom labels, bond distance labels, etc. as desired using the "Atom Properties" and "Bond Properties" dialogs
• Orient the molecule in the desired orientation, however this rendering is not WYSIWYG.
• Add any desired fields, such as orbitals. (Sorry, solid fields only.)
• Open "Calculate->Povray"
• Set the desired resolution (in pixel width and height)
• Type the desired file name in "Title:" and set the desired file location by clicking "Dir"
• Click "Render"
• Answer "Yes" or "No" to complete the full resolution rendering. The scene file is generated regardless of the answer.

Shortlist of commands to run the SCF calculations:

1. Build or open a molecule
2. Run SCF on the molecule (or cluster)
3. View and analyze results "by hand" and with the JIMP interface to MOPLOT2
4. Possibly perform a fragment analysis (see section below)

HINT: Always translate your molecule to the origin (select all and use "Calculate->Move->Move to" with Position at 0 0 0) and rotate your molecule so that the highest order rotational axis (from the point group symmetry of the molecule) is aligned with the z-axis in cartesian space (The z-axis is perpendicular to the screen after one has reset the view with Ctrl^R). These actions will make the interpretation of the molecular orbitals easier.

Running an SCF on a molecule (or cluster):

• Open the Fenske-Hall dialog box "Calculate->Fenske-Hall"
• Click "Base Dir" and change to the top level directory in which the directory named in "Title" will be created. Under "Basic" at "Title:", enter the name of the directory in which all of the results (Fenske-Hall and MOPLOT2) will be stored.
• Under "Additional", enter the charge and number of unpaired electrons for the entire molecule (or cluster). (The format for the charge must be the sign followed by an integer, i.e., it must be -2 for a dianion.)
• Click the "Run" button at the top of the dialog box.
• Details of the progression of the calculation are printed to the terminal in which JIMP was started.
• Further details of the calculation are written to the output file (output.txt) in the "Title" directory, which also contains the Fenske-Hall input file (input.fhi) and the converged eigenvectors file (vector.vec). The "orbital-contrib" file contains a short summary of the calculation results (that were also printed to the JIMP console).

HINT: The output from Fenske-Hall will be put into a directory under the base directory (either previously set or defaulted to JIMP_DIR). The name of this directory will be the one from the set title. In order to change these options from their default settings, 1) change the title (from "untitled", the default directory name) by selecting the text and typing to replace it and 2) click the "Base dir" button and change the base directory to the desired one.

Once these options have been set, simply clicking the "Run" button at the top of the dialog box will perform an SCF with the entered (and default) settings.

HINTS for SCF CONVERGENCE: One could increase the number of cycles, but this will not necessarily lead to convergence. More specifically, several parameters affect convergence:

1. The number of SCF cycles (default = 15)
2. Damping between SCF cycles (default = 0.65)
3. Extrapolation limit, the population deviation set in the "extrapolation limit" must be achieved before extrapolation turns on (default = 0.2)
4. Convergence criteria for the population deviation (default = 0.001)

Several key factors to ensure SCF convergence:

1. Make sure that the geometry is reasonable (crystal structure or optimized by some external means).
2. Make sure that the charge and number of unpaired electrons is appropriate for the molecule.
3. Watch the population deviation: the extrapolation is performed after every three SCF cycles. If the oscillation is periodic every three cycles, turn off extrapolation (achieved by setting extrapolation limit = 0.0).
4. Damping decreases the oscillation between SCF cycles. Increase the value only after convergence has started.

These steps may lead to SCF convergence:

• Increase number of cycles (default = 15)
• Increase damping between cycles (default = 0.65)
• Decrease the extrapolation limit (default = 0.2)
• Decrease convergence criteria (set it to no less than 0.01)
• If the molecule has a degeneracy issue, one can "unpair" electrons

Running a Self Consistent Field calculation with Fenske-Hall is a prerequisite to showing any Fenske-Hall molecular orbitals, because the orbitals are determined from Fenske-Hall output.

The output from Fenske-Hall will be put into a directory under the base directory that was set. The name of this directory will be the title that was selected. In order to plot any orbitals one must choose this directory by clicking on "Set Fenske-Hall output directory".

If everything was done correctly, there should now be a number of entries in the leftmost list. Before an orbital can be displayed, it must be calculated, which is done by double-clicking the orbital number in the leftmost list that one wishes to see. A new entry should now show in the rightmost list that shows which orbitals have been calculated thus far.

To actually show an orbital, simply double-click on its number in the rightmost list. Since it can take a while to calculate orbitals for large molecules, and a lot of clicking, the calculated orbitals are stored in the Fenske-Hall calculation directory for future use.

HINT: If one would like to view several molecular orbitals at once, for example several fragment MO's concurently, just add a layer, change to that layer, and open the field from the "Calculate->Moplot" menu or load the field from the "Field Properties" dialog box with "Load field".

The converter creates a JML file named gaussian_molecule.jml (the native JIMP molecule format), which may be opened to view the molecule for which the orbital was created. (Note: Currently, the converter is limited to one field per cube file, i.e., one orbital per cube file. This limitation holds even for unrestricted orbitals; one must create alpha and beta orbitals separately!).

To open the orbital file:

1. First, open the molecule from the gaussian_molecule.jml file
2. Open the "Field Properties" dialog box (from the main toolbar or "Edit->Field Properties")
3. Click "Load field" and select the orbital file (gaussian_orbital_#.fld) to open

All of the options for showing fields are changeable through "Edit->Field Properties".

One can choose to show the field as points beyond the cutoffs, as a planar slice through the field that has changing colors based on the strength of the field in that plane, or as an isosurface.

An isosurface is the 3D surface at a given value in a 4D function. It is similar in concept to the 2D lines drawn on a topographical map, which are used to show the height of terrain as a function of the longitude and latitude.

1. Assign the fragments
2. Run SCF on fragments
3. Run Fragment Analysis

• Assign the fragments
• Select atoms for the current "fragment"
• Open the "Atom Properties" dialog box (from the main toolbar or "Edit->Atom Properties") and enter the fragment number in the "Fragment:" box. Click "Apply" or "OK" (see notes below).
• Repeat for each fragment.

• Run SCF on fragments
• Open the Fenske-Hall dialog box "Calculate->Fenske-Hall"
• Under "Additional", enter the charge and number of unpaired electrons for a particular fragment (see notes below).
• Under "Fragment" at "Fragment number:", enter the number of the same particular fragment to calculate.
• Click "Run Fragment" (JIMP automatically creates fragment directories in the Title directory).
• Repeat for each fragment.

• Run Fragment Analysis
• Change the charge and number of unpaired electrons to appropriate values for the whole molecule.
• Click "Run Fragment Analysis". (Do not use the "Run" button at the top of the dialog box--this will run the SCF for the whole molecule without regard to the assigned fragment numbers.)

1. Reassigning fragment numbers:
• Select the atoms to be reassigned
• Open the "Atom Properties" dialog box and either
• Enter "-1" as the fragment number in the "Fragment:" box, then Click "Apply" or "OK". This resets the fragment number for the selected atoms.
• Enter a new number for the fragment number in the "Fragment:" box, then Click "Apply" or "OK". This reassigns the fragment number for the selected atoms.
2. The color of the atom in the fragment should change to a new uniform color for each fragment.
3. Take care when running Fenske-Hall fragment analysis with one fragment as an atom.
• In order to have an atom as a fragment in a Fenske-Hall fragment analysis simply leave the atom out of the fragment list. The program will automatically generate an atomic guess for the atom in the fragment input file.
• Also, while one can run highly charged fragments (e.g., TiCl₄ with Ti⁴⁺ as 4+ and four Cl^- as 4-), it is best to run fragments as close to neutral as possible, i.e., (1+, 1-, or 0). Of course, the sum of the charges of the fragments should equal the total charge of the molecule (or cluster).