XMakemol instructions: version 5.0x

Matthew P. Hodges

1  Overview

XMakemol is an application for the visualization and manipulation of atomic, molecular and other chemical systems. It is written in ANSI C and uses the Xlib library for rendering and also the Xt and Motif toolkits for the user interface. XMakemol is distributed under the GNU GENERAL PUBLIC LICENSE (Version 2, June 1991) which means that it is free in the sense that you have the freedom to obtain and modify the source and to redistribute it. To my knowledge, no copy of XMakemol has ever been sold, so you probably obtained it at no cost. A copy of the license should have been included in the distribution, in the file COPYING. If not you can download it from http://www.gnu.org/copyleft/gpl.html.
XMakemol is principally controlled by the mouse using menus and pop up dialog boxes with buttons, scrollbars etc. In addition, some dialogs have text fields which require information to be inputed from the keyboard. The main window of the application is split into menus at the top, the canvas in the middle and an area at the bottom in which messages appear.
The manual will cover invocation then all the menu entries then some miscellaneous features, mainly dealing with the methods of interacting with the system on the canvas.

2  Invocation

Various options are available from the command line. These are as follows:
Usage: xmakemol [options]
       -a          Switch off atoms
       -b          Switch off bonds
       -h          Switch on hydrogen bonds
       -c <colour> Set the canvas colour
       -e <colour> Set the bounding box colour
       -f <file>   Read file on startup
       -G          Switch on GL rendering [If OpenGL support compiled in]
       -u          Print usage information
       -v          Print version information

The -a, -b and -h options toggle the default behaviour and as such might be useful. The -c and -e options allow the user to control the background and bounding box colours in case the defaults are not liked. The -f option allows a file to be specified to be read in on starting the program. The -u options echos the above text to standard output and the -v option prints the version and Copyright information and politely reminds the user that "XMakemol comes with ABSOLUTELY NO WARRANTY". The -G option switches on rendering using OpenGL primitives, and is only available if support for OpenGL has been compiled in.
As for any X application, other options can be specified for example -geometry, -bg.

3  Menus

3.1  File

The menu entries under File deal with the reading and writing of files and quitting the application.

3.1.1  Open

Choose a file to be read by XMakemol . The file must be in XYZ syntax an example of which follows:
  1 Energy = -594.0315361957     
Ar      0.86540     -0.41643      2.29667
Ar     -1.78146     -2.11666      0.23641
Ar      1.11998     -0.42506     -1.45518
Ar     -1.52687      1.63520      0.24505
  2 Energy = -594.0315361957     
Ar      0.86540     -0.41643      2.29667
Ar     -1.78146     -2.11666      0.23641
Ar      1.11998     -0.42506     -1.45518
Ar     -1.52687      1.63520      0.24505

The file is set into "frames" of which there are two in the above example. The structure of each frame is as follows. The first line contains the number of atoms in the frame (M) and the second line contains a comment, which may be empty. The next M lines contain the type of atom followed by the three Cartesian coordinates. It used to be the case (prior to version 4.16) that all frames had to have the same value of M. This is no longer the case. Note that details of each type of atom are held in the elements file (see § ) which contains atomic masses radii and specified colours.
In addition to the basic syntax, it is possible to declare vectors (default maximum of three per atom):
Water (axes on oxygen displayed using vectors)
O    0.0  0.0  0.0    atom_vector 1 0 0 atom_vector 0 1 0 atom_vector 0 0 1
H    0.77 0.0 -0.59
H   -0.77 0.0 -0.59

and ellipses:
All ellipses should look the same
O    -4.0 0.0 0.0 ellipse 1.0 2.0 2.0  0.0 90.0  0.0
O     0.0 0.0 0.0 ellipse 2.0 1.0 2.0  0.0 90.0 90.0
O     4.0 0.0 0.0 ellipse 2.0 2.0 1.0  0.0  0.0  0.0

where the ellipse keyword must be followed by three numbers describing the x, y and z axis dimensions and three Euler angles (a, b and g). The convention used for the Euler angles is: rotation of g about Z; rotation of b about Y; rotation of a about Z, where X, Y and Z are global axes.

3.1.2  Save

Choose a file to save to. The following file types are available:

3.1.3  Merge

Merge the current Cartesian coordinates with those in another file. This only works for single-frame files.

3.1.4  Print

Convenient dialog to enable printing of PostScript rendering of the canvas (black and white, or colour).

3.1.5  Quit

Quit the application; no offers will be made to save any data under any circumstances.

3.2  Control

The menu entries under Control provide a number of pop up dialogs for controlling various aspects of frames.

3.2.1  Frames

The frames dialog controls the animation of multiple-frame files. At the top, the frame number and corresponding comments are displayed. If the comment is empty, this is also indicated.
Next, there are a number of buttons which do the following:
The speed of the animation can be controlled with the scale bar marked with "Select speed".
If the "Centre each frame" button is activated, then when ever the frame is changed, the centre of mass is moved to the origin. This can be useful if an animation involved large displacements of the centre of mass resulting in the atoms leaving the field of view.
Finally, a frame can be selected by number in the "Select frame" text field.

3.2.2  Animate

The animate dialog allows a frame to be rotated by a specified angle by a specified number of times about a specified axis. The animation is started with the "Start" button and can be stopped with the "Stop" button. An indication of the progress of the animation is given in the message area. Such animations can be saved by clicking on the "Save" button followed by selecting a filename.

3.2.3  Measure

The Measure dialog shows the distances and angles between selected atoms. Atoms are selected and de-selected using [mouse-3] and a selected atom is indicated on the canvas by being stippled. Up to four atoms can be pushed on to and popped off the stack. The selections can be cleared using the "Unselect all atoms" button. Each selected atom is labelled A-D and these labels also appear on the canvas. The atom number (see § ) is also displayed in the dialog.

3.2.4  Perspective

The perspective dialog contains two scale bars which control aspects of how the atoms are drawn on the canvas. The "Choose scale" simply controls the size at which atoms, bonds and so on are drawn and the "Choose depth" scale allows the depth of field to be varied. If the "Toggle depth" button is not activated, then there is no variation in the atom size with depth. Both the scale and depth are automatically set when a file is read in.

3.3  Edit

The menu entries under Edit provide a number of pop up dialogs which can alter both the properties of atoms and bonds.

3.3.1  Visible

From this dialog, the visibility of each atom can be toggled i.e. you can directly control whether or not an atom is displayed on the canvas. Individual atoms can be selected using Shift + [Mouse-3] and all invisible atoms can (temporarily) be shown with Shift + [Mouse-1]. In addition the visibility of groups of atoms can be toggled with buttons labelled for example "Toggle H atoms", "Invert selection" and "Reselect all". Each of these can work for: Rectangular regions can be drawn with Control + [Mouse-1].

3.3.2  Positions

Scale bars are available to translate the selected atoms in the X, Y and Z directions and to rotate the selected atoms about the X, Y and Z axes. As for the selection of the visible atoms, each can be toggled with Control + [Mouse-3] when the Edit->Positions dialog is open. Groups of atoms can be selected in the same way as outlined in § 3.3.1. When an atom is not selected it is drawn with a cross-hair and its position cannot be changed.

3.3.3  Atom and bond sizes

In this dialog, the size of the atoms and bonds as displayed on the canvas can be varied. There are scale bars for the atomic radius, the bond width and the hydrogen bond width. Note that the sizes of the atoms as displayed on the canvas also depend on the covalent or van der Waals radii as set in the external elements file (see § ) which is read when the first file is opened.

3.3.4  Bond factors

These two scale bars allow some control over which atoms are considered to be bonded. The algorithm which determines this information from the Cartesian coordinates uses the sum of the covalent radii of pairs of atoms. Increasing the default values will lead to more bonds and decreasing the default value will lead to fewer bonds.

3.3.5  Vector display

The vector rendering works better with OpenGL rendering, and this is recommended at present. Some customization of how the vectors look is possible.

3.3.6  Element properties

This dialog allows the convenient editing of the default element properties (colour, covalent/van der Waals radii). These can be saved, in which case the changes will be used for future xmakemol sessions.

3.3.7  GL rendering

If OpenGL support has been compiled in, then this dialog will be present. Firstly, it allows the switching of rendering between the X and OpenGL primitives. Secondly, it allows the customization of some of the OpenGL rendering.
The customizations which can currently be made are:

3.4  Track

The Track menu controls the behaviour of the mouse on the canvas and also allows some general transformations to be made to the atomic coordinates. The current mouse bindings can be found in the Help menu.

3.4.1  Rotate about local COM

If this is selected, the mouse on the canvas will control rotations of the atoms about the local centre of mass i.e.  that defined by the selected atoms.

3.4.2  Rotate about origin

If this is selected, the mouse on the canvas will control rotations of the atoms about the global origin.

3.4.3  Centre

This moves the centre of mass of the system to the origin.

3.4.4  Reflect x coordinates

Reflects the atomic coordinates about the yz plane. Plus corresponding options for reflections about the xy and xz planes.

3.4.5  Invert through centre

Invert all coordinates through the origin.

3.5  View

The View menu controls what is displayed on the canvas.

3.5.1  Atoms

Toggle whether or not atoms are displayed.

3.5.2  Bonds

Toggle whether or not bonds are displayed. Bonds can be formed between any two types of atom.

3.5.3  H-bonds

Toggle whether or not hydrogen bonds are displayed. Hydrogen bonds can be formed between any hydrogen and any non-hydrogen atoms.

3.5.4  Vectors

Toggle whether or not vectors are displayed.

3.5.5  Atom numbers

Toggle whether of not the atom numbers are displayed for each atom. These correspond to the order in which the atoms were read in.

3.5.6  Atom symbols

Toggle whether or not the atomic symbols are displayed for each atom.

3.5.7  Axes

Toggle whether or not a set of axes (x,y,z) are displayed on the canvas. These correspond to a local axis set which before any rotations is parallel to the global axes (X,Y,Z).

3.5.8  Bounding box

If enabled, a cuboid is drawn which encapsulated all visible atoms. The faces are parallel to the xy, yz and xz planes.

3.5.9  Outline

If enabled, this reduces the amount of drawing done on the canvas while the system is being rotated or translated. This can be useful for large systems for which the normal interactive response is slow. In particular, no bonds are drawn and this increases the rendering speed considerably.

3.6  Help

3.6.1  About

Displays the version and Copyright information.

3.6.2  Documentation

Gives a pointer to the online documentation.

3.6.3  Mouse

This dialog give a list of actions which the mouse has on the canvas.

3.6.4  Bugs

Details how to report bugs.

4  Miscellaneous

4.1  The elements file

The elements file is an external file, the location of which must be specified in the Makefile before building. The head of the elements file (past the copyright information) looks like this:
! Z     Symbol       Mass        Colour          Cov rad         VdW rad
  1     H            1.008       White           0.300           1.000
  2     HE           4.003       Pink            0.310           1.400

The first entry is the atomic number. The second entry is a label corresponding to what should be written in an input file (note that comparison is not case sensitive). The third entry is the atomic mass. The fourth entry is the colour which is used to paint the atom (and bonds) on the canvas. The final two entries are covalent and van der Waals radii; if there is no van der Waals radius for a given atom a value of zero should be used.

File translated from TEX by TTH, version 3.38.
On 23 Jun 2003, 15:17.