XBSA Manual

XBSA - X windows Ball-and-Stick Program by M. Methfessel Nov. 1995 with small additions by Jan Labanowski, 1997

This manual is based in large part on the original README file written by the original author: Michael Methfessel, methfessel@ihp-ffo.de, Institute for Semiconductor Physics, PO Box 409, D-15204 Frankfurt (Oder), Germany. Jan Labanowski (jkl@ccl.net) introduced some new commands and written the HTML version of the manual. If in doubt, look up the original README file

The XBSA program is a derivative of the original XBS program and contains few extensions which allow animation of a series of frames and option to query geometry (distances, angles, and coordinates). It displays Ball and Stick figures of molecules under X-window system. It is fairly portable, small, and what is more important, it comes with the source code which is available under GNU Public License. Therefore it is free, and without many restrictions -- except, you cannot resell it, but you can modify it, and redistribute it for free. If you do not see a binary for your machine in the bin directory (or if the binary does not work) try to compile it. The (instructions (file INSTALL) are provided in the source directory (./xbsa/src).

File Formats

XBS uses its own format for representing molecules. It is simple and much more flexible than other formats in use. You have more flexibility to highlight specific atoms or bonds with different colors by editing the input file. The utility (written by Jan Labanowski) is provided to convert the popular XYZ XMol format to the format required by XBS

The XBS may use one or two files with the same base name, but different extensions, .bs, and .mv respectively. It is called as:
xbsa filename
where filename is a file name without extension. The .bs file always needs to be present. It contains the following sections:

atom coordinates,
atom specifications (symbol, radius, and color for each atom),
list of different bonds
optionally list of commands to modify the program action.

Example:

* ch3ohv.OUT   -113.54919315
atom   C      0.050065    0.665047    0.000000
atom   O      0.050065   -0.767876    0.000000
atom   H     -0.912101   -1.005927    0.000000
atom   H      1.090132    0.995415    0.000000
atom   H     -0.439468    1.081620    0.886605
atom   H     -0.439468    1.081620   -0.886605
 
spec   C   0.495   0.18  0.31  0.31
spec   O   0.405   0.80  0.36  0.36
spec   H   0.375   0.97  0.97  1.00
 
bonds  C   O   0.150   2.250   0.15   0.50
bonds  C   H   0.109   1.635   0.11   0.50
bonds  O   H   0.105   1.575   0.11   0.50

Lines which start with asterisk * are treated as comments and you can also use empty lines for better readability. While units of length are assumed to be Angstroms, they actually need not be, if you use other units consistently. Also, the symbols need not be chemical element symbols, but all symbols need to be defined in the .bs file.

Lines starting with atom tag have a general format:
atom symbol X Y Z
and provide atom symbol and Cartesian coordinates for each atom in the molecule.

Lines with spec tag have a format:
spec symbol color
and provide information how atoms with a given symbol should be displayed. The first number is the radius of a ball for a given atom symbol. The last portion of the line provides color for this atom. The color can be specified as a degree of white (0 - white, 1 - black), the triple of numbers representing RGB (Red, Green, Blue) components of color, or the official X11 windows color name as given in /usr/lib/X11/rgb.txt on your system). So the entry for oxygen, O, in the above example could have been also as:

spec   O   0.405   0.80

which would be a gray oxygen atom, or

spec   0   0.405   IndianRed

which represents the same color as

spec   O   0.405   0.80  0.36  0.36

original entry.

The bonds lines have a general format of:
bond symbol1 symbol2 min max radius color
and entries denote:

symbol1, symbol2 -- the atom symbols which form the bond. Note that by denoting some atoms with special symbols, you can create special effects for them even if there are other bonds between these elements in the molecule,
min bond length, max bond length -- only bonds whose length is within this range are displayed,
radius of a cylinder representing the bond,
color -- specified in the same manner as for atom specs as described above.

The XBSA program checks if the file name.bs exists, and if not, program exits with error. Then it checks if the name.mv (move file) is present. The name.mv contains additional frames which can be used for animation. Its format is much simpler than the name.bs. The frames are represented by the list of Cartesian coordinates in exactly the same order as in the name.bs file but without any other information. Each frame begins from the line starting with the word frame followed by optional comment. You can list several triples of Cartesian coordinates on the same line, or each number on a separate line. For example, the 2 frames which corresponds to the .bs example above could be:

frame    * ch3ohv.5 step 1
   0.0717     0.6629     0.0000 
   0.0349    -0.7571     0.0000
  -0.8753    -1.1941     0.0000
   1.0858     1.0819     0.0000
  -0.4589     1.0730     0.8671
  -0.4589     1.0730    -0.8671
frame    * ch3ohv.5 step 2
   0.0912     0.6609 
   0.0000     0.0213    -0.7473     0.0000
  -0.8422    -1.3639     0.0000     1.0819     1.1600     0.0000
  -0.4765     1.0652     0.8496    -0.4765
   1.0652    -0.8496

XBSA command line options

There are several options which can be entered on the command line:

-hh long help
-geo WIDTHxHEIGHT+/-XOFF+/-YOFF is analogous to the standard xview option available in Xwindow system. It provides the size if the window in pixels (WIDTH and HEIGHT) and offsets (in pixels) of the window on the screen(XOFF and YOFF). Positive XOFF specifies the distance of the left edge of the window from the left edge of the display. Negative XOFF is the distance of right edge of the window from the right edge of the display. Positive YOFF is the distance of the top edge of the window from the top edge of the display, and negative YOFF gives distance from the bottom of the distance to the bottom of the window.
-sc x scales the initial image by x (you can resize it later) which can be smaller or larger than 1.0.
-t title provides the title (displayed on its upper frame) for the window. If title contains spaces, be sure to embrace it with single or double quotes.
-color Use color for display (it is a default).
-bw Use black and white, and shades of gray to represent color.
-rv Reverse colors given in the atom/bond type definitions.
-autocolor Choose own colors (i.e., disregard colors from your input file and use colors which are automatically assigned by XBSA.

XBSA keyboard commands

There are two modes for entering commands in XBSA:

Input line mode which allows you to enter longer commands and parameters. This mode is initiated by a keystroke i on the keyboard. When you strike i the prompt will appear in the window asking for input. If you are in the line input mode, you can also retrieve the previous commands by using keypad cursor keys. The following keyboard commands implemented:

help topic
provides help on a given topic (if available).

inc n
change the rotation increment to n degrees (default increment is 90 degrees, i.e., orthogonal views).

time n
enter time (in milliseconds) for how long each frame should stay on the screen during animation (default is 200 ms).

pos x y
move the molecule by x and y pixels at current view (negative values move left/down, positive right/up). To return to original position type pos 0 0.

dpos x
set shift increment to x when using keypad 2468 keys.

dist d
set distance from the molecule to the observer (i.e., plane of the screen). Has effect only when perspective is requested with the p keystroke.DO NOT MAKE IT TOO SMALL OR YOU WILL NEED TO REBOOT THE COMPUTER -- YOU HAVE TO BE OUTSIDE THE MOLECULE, OR PROGRAM WILL TRY TO PAINT ALL UNIVERSE AND WILL CRASH THE XMANAGER!!!

rfac fac
scale all atomic radii by a factor fac (e.g., 0.5 or 1.5).

bfac fac
this scales the diameter of cylinders representing bonds by the factor suppled (e.g., 0.5 or 1.0).

scale fac
scales the plot, but this time the factor is given in %, i.e., scale 50 will make the molecule occupy 50% of the page, and scale 100 will make it occupy the whole page.

gramp slope midpoint
available only in b/w mode, assigns different shades of gray depending on the distance of the atom from the observer.

light x y z
provides position of light source. The atoms closer to the light source a lighter, and the ones further from it are darker

step n
every n-th frame will be shown during frame scan with [ and ] keystrokes or animations with C or A.

dup x y z
duplicates all atoms shifted by increments x, y, and z.

cut x y z a b
planar cat. The atoms which are contained between planes at position a and b along vector given by x, y, and z are deleted.

frm n
go to frame n.

color pat color
query the color (if color is not given), or change the color by providing color. For example
color C*
will list the color chosen for carbon atoms, and
color C* blue (or color C* 0 0 1)
will change all carbon atoms to the blue color.

save fname
save current settings in files fname.bs and fname.mv (if more than one frame). The fname.mv include all the information about modification made to the molecule interactively.

update fname
read in the fname.bs and fname.mv (if present) replacing the previous molecule data. The updateaccepts options, e.g.: update +rv will switch off reversing, update -rv will switch reversing on, and update -bw will read but the file but switch to a black and white mode.

print fname
saves the PostScript picture of current view of the molecule in the file fname.ps. The PostScript picture can be annotated automatically by XBSA by providing option -T, e.g., print -T mymol, or you can place your own title for the picture by using the -t 'my own title' option, e.g.,
print -t 'This is the famous water molecule' h2o
which will place the picture and your text in the h2o.ps file. You can print several frames to the same file (e.g. different orientations or an orthogonal view in different color/wireframe representation (keystroke l), however, after you are done with printing to a file, you need to close the file with a close command. When you print to the closed print file again, you will overwrite its original contents -- be careful.

close
close the print file. When you print to this file again after closing it, its contents will be overwritten.
Keystroke mode in which certain active keys perform specific functions (KP means a key on the keypad).
- i -- activate input line
- h -- show/hide help screen (tip: to read help you may need to shrink your molecule with - or move it around).
- space -- show/hide information about settings and molecule.
- cursor -- cursor arrows on the keypad rotate molecule out of plane (up/down, left/right). You can change rotation increment by using inc d command.
- , . -- rotate molecule in plane.
- + - -- enlarge/shrink your molecule (zoom).
- KP: 8 6 4 2 -- translate molecule up, right, left, down by using keypad keys in numerical keypad mode.
- KP: 7 -- shift molecule to home position.
- KP: * -- set home position (you can return to it by KP:7).
- r -- redraw the screen.
- n -- toggle atom numbers, symbols, no symbols.
- c -- show/hide XYZ coordinates of atoms
- N -- show/hide bond lengths.
- w -- wire/ball mode.
- g -- gray/bw.
- b -- show/erase bonds.
- l -- bonds as cylinders/lines.
- p -- perspective (off, pseudo, true)
- a -- show/hide axes (100-X, 010-Y, 001-Z)
- s -- line shadows on/off
- x -- pixmap buffer.
- d D -- distance to screen (d -- far, D -- closer)
- ] [ -- step frames forward and backwards.
- A -- animate 1,2,..N,1,2,3...
- C -- animate 1,2,..N,N-1,N-2...
- < > -- animate backwards or forward -- useful with A type animation.
  < -- N,N-1,N-2...2,1,N,N-1...
  > -- 1,2,3...N-1,N,1,2,3...
- { } -- to to first/last frame.
- \ | -- mark(\) frame, goto(|) to marked frame.
- U -- update from currently opened input file.
- Q -- quit.