Schakal 88B/V16 Tutorial

A manual for SCHAKAL 88B/V16 beginners.

by Egbert Keller

Kristallographisches Institut der Universität Hebelstr. 25 / D-7800 Freiburg i. Br.

Copyright (c) 1990 by Albert-Ludwigs-Universität Freiburg. i.Br.

This manual may be read by people who want to get a first impression of SCHAKAL 88B/V16. This manual is not thought to be a substitute for the other manuals distributed with SCHAKAL 88, namely the "general SCHAKAL 88 manual" (distributed in file MANUAL.TXT) and the "SCHAKAL 88B/V16 manual" (distributed in file MANV.TXT).

It is assumed here, that SCHAKAL has been installed correctly and that the original distributed SCHAKAL.INI file is present in the same directory as the SCHAKAL.EXE file.

Table of Contents

  1. Introduction
  2. Starting and Loading
  3. Some Important commands
  4. Rotations and On-screen Rotations
  5. Using Distributed Command Files for the Screen
  6. Making Plotter Drawings
  7. Using Distributed Command Files for the Plotter

1. Introduction

The following is a description of a SCHAKAL 88B/V16 session. The distributed data set EX1.DAT is used as a demonstration example. Below, all input which should be given by the user, is (with a few exceptions) written left-justified and surrounded by two blank lines. Any input has to be terminated by a <RETURN>, of course. Such <RETURN>s, however, have only been accounted for in the following text, if they are the only input of a certain line (i.e., for "plain" <RETURN>s). User's input should be carefully given as specified, because there is a certain probability, that a faulty command will unpredictably influence parts of the residual session (however, a faulty command can not cause any "damage"). Mistakes in input may be corrected using the <BACKSPACE> or the arrow keys, before the line in question is sent to the program by a <RETURN>.

As has already been done in this introductory text, special keys of the keyboard are generally specified within this manual by their names, given in capital letters and surrounded by two brackets, e.g. <ESC>, <LEFT ARROW>, etc.

2. Starting and Loading

To run SCHAKAL, you should be within the directory containing SCHAKAL.EXE. Start the program by typing


First, the program displays a title page containing the copyright phrase and the name of the licenced user for about 10 seconds. Then, the program requests for a <RETURN>:


This will lead to a change of the background colour (from black to light bluish grey) and to the automatic input of the initializing command file SCHAKAL.INI (if it will be found within the directory).

The procedures contained in SCHAKAL.INI will end up with the display of the SCHAKAL "test drawing". It displays in its right part a column showing the 13 main colours of "13/1" mode. This mode is characteristic for "device no. 1", which is the default graphics device after startup (see IV.1. in the SCHAKAL 88B/V16 manual).

The 13 colours column is surrounded by a white and a black column. The first row displays colour no. 1 (grey), the second one colour no. 2 (red) and so on.

In the upper left corner of the screen you will see a white ">", which is the SCHAKAL 88B/V16 prompt. If this (non-blinking) prompt appears, SCHAKAL is ready for input of a command. If you type two or three <RETURN>s, more prompts will appear in the first column of the screen. Now, input some arbitrary printable characters, e.g.


The message "Label ERROR" appears in the first row of the screen (as "qwert" is not an allowed command input line to SCHAKAL). You see, that text written by you is displayed with brown colour. Text output by the program is and will be written in white (or, sometimes, red or blue colour). Note: These colours cannot be modified by you.

As a first action, you will have to load information about the geometry of a molecular or crystallographic model into the program. This information is usually contained in a data set which is stored in a file (an "input file", see chapter II. in the "general SCHAKAL 88 manual"). Within this tutorial, we will work with the distributed data set in input file EX1.DAT.

To load this input file, we use the 'LOAD DATA' command in its abbreviated form 'L D' (Note: SCHAKAL 88 doesn't distinguish between upper case and lower case letters, thus, capital letters are used within this manual only for sake of readability):

l d

The screen is erased and, in the upper row of the screen, the program requests for the name of the input file containing the data set. We will give the file name as 'EX1' and not as 'EX1.DAT'. The reason is, that the SCHAKAL.INI file contains a 'ZET FNAME 1' command, which told the program, to add automatically the suffix .DAT to any input file name specified.


The screen is erased and some information about the data set will be output by the program. At the same time, the program requests for a <RETURN> which, when given, will cause another erasure of the screen.

3. Some Important Commands

Information on the different commands you can use, and their syntax, can be received on-line with the 'HELP' command:


It is self-explanatory. You may look at some of the commands, but please don't try them just now (otherwise the following might be obsolete). With input of an "n", or several <RETURN>s, you will come back to the ">" prompt.

Now, to obtain a coarse, but fast, drawing of the EX1 molecule, use the 'XQT QUICK' command:

x q

A drawing of the ball-and-stick model (the default model type) appears. The time needed to calculate the drawing is displayed in the upper right corner of the screen. This information will be output after execution of any 'XQT...' or 'WRITE...' command. It is not cumulative!

The EX1 molecule is an organo-iron cluster molecule. To prove it, we use the 'WRITE LABEL' command, which will make the program label the different atoms with their "names":

w l

The message "Label Position Storage has been cleared !!" appears in the first row of the screen. An optimization procedure is performed which determines more or less reasonable positions for the different labels; the relatively fast default optimization level 12 is used. The procedure is finished with the message: "Label Pos.: 41 optimized, 0 read from LPS".

The O32 label exceeds the lower border of the screen area. The reason is, that the size of the 'XQT QUICK' drawing has been calculated by the program to make optimum use of the drawing area (caused by a plain 'MAGNIFY MODEL' command in the SCHAKAL.INI file). On the other hand, the optimization routine doesn't care for the screen area border lines. We could have avoided the O32 accident by giving 'MAGN MODEL 0 1.5' before 'X Q'. In this case, the program, when calculating the scale factor, would have accounted for an empty borderline strip of 1.5 cm instead of the default 1.0 cm. However, it's more convenient now to simply neglect this O32 problem.

The molecule has been displayed with default colours: white (colour no. 0) for H, grey (1) for C, red (2) for O, green (3) for N, blue (4) for Fe, and brown (6) for the bond sticks. With the 'LIST ATOMS' command we can check for these assignments:

l a Fe

The screen is erased and some information on the 4 iron atoms of the molecule are printed. The C column contains the colour number (4). The program requests for a <RETURN>, which will make you ready for the input of the next command. You may try 'l a Fe1', 'l a # (H C', and 'l a #1-#8'. Finally, try the following 'LIST BONDS' command, which yields some information on the iron-iron bonds.

l b Fe=Fe

To prepare the molecule for the tasks of the following chapter, we will change the display colour for some of the bonds by means of some 'CHANGE COLOUR' commands, typing:

c c 5 Fe=Fe
c c 12 C=C (C1=C
c c 9 C=O

With the first command, you assign yellow colour (no. 5) to the iron- iron bonds; the program answers "5B" which means that 5 bonds matched the description "Fe=Fe" (this answer had been given also to the 'LIST BONDS' command above, but had been erased immediately afterwards). With the second command (it uses "negative selection"), you assign greyish green colour (no. 12) to all C-C bonds except the bonds to C1, i.e., all C-C bonds of the phenyl ring (answer: "6B"). With the third command, you assign cyan colour (no. 9) to all C-O bonds (answer: "12B"). Another 'XQT QUICK' will display the results:

x q

By the way, you may erase the screen anytime by yourself with the 'KILL SCREEN' command, but use it in the form 'k s 1' !! (a plain 'k s' would switch the normal automatic screen erasing off):

k s 1

Finally, we want to make two drawings of some higher quality. With 'XQT', you first may generate an outline drawing of the molecule:


To generate a shaded drawing, you have to use the 'GEN SHADING' command (which switches to "shaded drawings"), and the 'SET LIGHT' command to position an imaginary light source; these (and many other) settings might then be checked by means of the 'LIST PARAM' command:

g s
s l 45 45
l p

As you see, the field 'Repres.Type:' shows a "Shad" (for shading) and the field 'Light Pos.:' displays the two '45' values. With another <RETURN> you will cause another erasure of the screen. The shaded drawing is now made with an 'XQT BLANK' (which will draw the molecule in pure black), followed by a plain 'XQT':

x b 4 4

When some of the atoms/bonds have been drawn, you may stop drawing with an <ESC> (if the drawing is already complete, repeat the last two commands, to try it). After appearance of the prompt you may repeat the whole thing, this time using a concatenated form of the two 'XQT commands:

<ESC>        (wait for ">" prompt)
x b 4 4 : x

4. Rotations and On-screen Rotations

The default orientation of the EX1 molecule is not a very attractive one. You may change it by means of 'ROTATE..', 'ALIGN..' or 'ORIENT' commands. For example, you may align the molecule in a way, that the best plane defined by the four iron atoms is oriented parallel to the drawing plane. This is done by means of the 'DEFINE PLANE' and 'ALIGN PLANE' commands:

d p Fe : a p
x q

To make better use of the drawing area, you finally may rotate the molecule 90 degrees about the Z axis (see fig.1) and decide then, to add another rotation about the X axis:

r z 90
x q
r x -90
x q

As you will have already noticed, rotations caused by 'ROTATE' and 'ALIGN' commands are not performed on-screen. However, with the 'ORIENT' command, you may switch to on-screen rotations mode (make sure that "NUM lock" is switched off at the keyboard!):


The screen is erased and a wire model appears, displaying the different default and modified bond colours. We easily recognize the yellow Fe butterfly, the cyan C-O bonds, and the greenish phenyl hexagon among the other (brown) bonds.

Press the <RIGHT ARROW> key once. The molecule begins to rotate about the Y-Axis (see fig. 1). Pressing the <LEFT ARROW> key once will stop the rotation. We try it again, but keep the <RIGHT ARROW> key pressed down, observing, that the rotation becomes increasingly faster. We can slow it down by switching to the <LEFT ARROW> key and keeping it pressed. The rotation stops finally; then the molecule starts to rotate the other way around, again becoming increasingly faster.

When the rotation is rather fast, leave the <LEFT ARROW> key and press the <UP ARROW> key once, immediately followed by one pressing of the <DOWN ARROW> key. This will stop the rotation.

Now, press the 'X' key. On-screen rotation mode is left and an 'XQT QUICK' drawing appears. The molecule is displayed in the orientation it had, when you left on-screen rotation mode. However, as the scale factor caclulated by the program is different for on-screen rotations as compared to "static" drawings, the size and position of the molecule will probably be different. With another


you may go back to on-screen rotation mode and play with the arrow keys. Note that <SHIFT LEFT ARROW> and <SHIFT RIGHT ARROW> cause rotations about the Z-Axis and that <SHIFT UP ARROW> and <SHIFT DOWN ARROW> increase or decrease the default rotation speed. You may leave on-screen rotation mode with 'X' or <ESC>, even while the molecule is still rotating.

Note: You may save any interesting orientation either by means of the information given by a 'LIST ORIENT' command, or, more simple, by a 'KEEP DATA' command.

5. Using Distributed Command Files for VGA

In order to have a common defined orientation for the following tasks, we will now reload the EX1.DAT file, once more using the 'LOAD DATA' command:

l d

You just type <RETURN> as an answer to the program's file name request. The program will now use the "input file" you specified the last time, i.e. EX1.DAT. With

x q

you will reproduce the drawing you got the first time within this session. To move the molecule to the orientation it has in fig.s 7 to 12, and to give some other commands described in chapter IV.18. of the "general SCHAKAL 88 manual", we use the distributed command file 'EX1.SCF'. It is loaded with the help of the 'USE COMMANDFILE' command:

u c
x q

Again, we answer to the program's question by 'EX1' and not by 'EX1.SCF', as a 'ZET FNAME' command in the SCHAKAL.INI file told the program to add the extension .SCF to any command file name. You cannot answer by a plain <RETURN>, as no command file name had been specified by you previously (the program would search for a file 'SCHAKAL.SCF' in this case). The final 'XQT QUICK' displays the modifications performed by 'EX1.SCF': the molecule has been reoriented, perspective has been switched on, the bond stick thicknesses have been modified, bond colours have been modified (the same way you did above), and one bond stick has been broken into four fractions.

With the help of another command file ('QQ.SCF'), we substitute the 'XQT QUICK' drawing by another relatively fast (but actually slower) drawn picture of higher quality:

u c
QQ    (wait until drawing is finished)
w h

The last command ('WRITE HEIGHT'), causes labelling of the different atoms by the Cartesian Z values (in pm); the larger the number, the nearer is the position of the corresponding atom.

Now we will make some other shaded drawings, this time with the help of command files 'Smn.SCF'. Let's begin with command file 'S11.SCF':

u c

The program generates a drawing shaded in "Random Mode A" (see chapter IV.2. in the "SCHAKAL 88B/V16 manual") and completed by dark outlines. The imaginary light source is still positioned (see above). Look at the time information in the upper right corner: it reads only a few seconds. This is, because the 'S11.SCF' command file contains several 'XQT..' commands and the time displayed now refers only to the execution of the last one.

Shading in the slower, but more regular, "Matrix Mode B" (without dark outlines added), is coded in file 'S12.SCF':

u c

Up to now, you were working in SCHAKAL's 13/1 mode of the VGA card (= "device" no. 1). With a 'GEN DEVICE 2' command you can switch to 5/3 mode (= "device" no. 2). 5/3 mode means, that you can use only 5 "main colours", but with three colour steps per main colour, which allows a smoother shading of atom surfaces. You can inspect the new colour map by an 'XQT TEST':

g d 2
x t

The highest quality of shading can be achieved using "Matrix Mode B" while in 5/3mode. Thus, let's do it again:

u c

You now use the file S22.SCF (instead of S12.SCF), as you now are in 5/3 mode (= "device" no. 2; in all the Smn.SCF files, the first digit (m) corresponds to the "device" number). Note, that C-O bonds now are drawn in blue and phenyl-C-C-bonds in red. The reason is, that the high colour numbers 9 (cyan) and 12 (greyish green) have automatically been reduced to 4 (blue) and 2 (red), because the number of main colours is limited to 5 now.

Perhaps you will find the yellow colour of the iron-iron bonds too pale. You may modify this colour (no. 5) by a 'SET HUE' command, e.g. by assigning a hue of 160 (yellow-orange) and a medium saturation of 60 to it. Also, you may modify the background colour by a 'SET BACKGR' command, creating a light version (step 3 of 9) of colour no. 11 (greyish red).

s h 5 160 60
s b 11 3

Instead of changing the hue of colour no. 5 you of course could also change the colour no. of the iron-iron bonds (e.g. to 3 = green) and redraw them:

c c 3 Fe=Fe
x x Fe=Fe

Especially for atoms, you also might change the "darkening function" by a 'CHANGE DARKF' command. The following will redraw the iron atoms using a "darker" darkening function (no. 5, see fig. 6):

c d 5 Fe
x x Fe

Finally let's cancel some of the last six commands by switching back to the default values:

s h 5 180
c c 5 Fe=Fe
c d 1 Fe

Now, let's try the shading game for the space-filling model. With a 'GEN CUPS' command, you switch to the space-filling model:

g c
u c

This drawing will require considerably more time than the previous ones. In the first row, the program displays a message: " *** Warning: Perspc. cup model may show faulty shadows", because we still have perspective on (it had been switched on by a 'SET VIEWDIST 27' in 'EX1.SCF'). Shaded cup models should preferably be drawn without perspective (see chapter IV.15. in the "general SCHAKAL 88 manual"), but this time, we make an exception.

After that, you also may try 'S23.SCF', which generates a pseudo-transparent surface of the cup model superimposed to the "solid" ball-and-stick model:

u c

Pseudo-transparency may also be used to distinguish more "important" parts of a molecule from less important ones. Let's assume that the four Fe atoms and the phenyl hexagon form the "important" part of the EX1 molecule. You give these atoms the "special group" name "" with the 'DEFINE ' command. The rest is done by the 'S24.SCF' command file:

d  Fe C2-C7
u c

6. Making Plotter Drawings

In order to generate a plotter drawing, you first have to switch to "device no. 3" by a 'GEN DEVC 3' command and specify the name of a "plotter file", where the program will store HPGL commands (HPGL = Hewlett Packard Graphics Language).

g d 3

According to the 'ZET FNAME 5' command in SCHAKAL.INI, the name of the plotter file will be expanded to 'PLOT1.PLT' by the program. After you have erased the program's message by <RETURN>, the background colour has changed to white (to simulate the white plotter paper). The background cannot be modified by a 'SET BACKGR' command as long as you don't switch to another "device". Also, the 'KILL SCREEN' and 'SET HUE' commands won't work now (to try it, use 'K S 1' and not a plain 'K S'!).

First, we generate a simple outline drawing with the commands 'GEN OUTLINES' (we still are in shading mode) and 'XQT':

g o

While the HPGL commands are sent to 'PLOT1.PLT', the corresponding drawing is generated in parallel (= "monitored") on the screen. The drawing we see on the screen, is rather reduced in size as compared to the drawing we later will generate on the paper plotter, i.e., the whole MET A3 area of the plotter paper (40.19 cm x 27.46 cm) appears shrinked to the white area of the screen.

Outlines have been drawn in black; this is the default for "device no. 3" (but only for outlines and inscription, not for shading!). To obtain individually coloured outlines would have required a previously given 'SET COLOUR -2' command.

At this point, you might become aware of the fact (e.g. from chapter IV.13. in the "general SCHAKAL 88 manual"), that for line drawings and scale factors > 2 it is advisable to use a line width > 1.

So let's restart from the beginning. But what to do now with the incomplete drawing already present? 'KILL SCREEN 1' doesn't work here; instead we give a 'USE PLOTTERFILE' command.

u p

A new HPGL file is opened, and, as you answered <RETURN> to the file name request, it is the same file ('PLOT1.PLT') as the last time. I.e., the file is reopened which erases the information up to now stored in it. Thus, for HPGL files, the 'USE PLOTTERFILE' command has the same effect as the 'KILL SCREEN 1' command for devices no. 1 or 2.

Now, you may redraw the outlines with a line width of, say, 1.5, using the 'BROADEN ALL' command:

b a 1.5

After the drawing is complete, you might continue with atom labelling. This time, we don't use the default "optimization level" 12 as above, but level 25 (which is the highest level for mixed inside/outside labelling); furthermore, wie choose an "italic" font style. Both modifications are performed by the 'SET WRITPAR' command. We also switch to "variable" (i.e., bound to the general scale factor) character size by an appropriate 'MAG INSCR' command:

s w 25 2
m i 1.2
w -l H

The last command uses another kind of "negative selection", i.e., Hydrogen atoms will not be labelled. It will probably take its time, until the first atom is started to be labelled. Note, that label positions inside atom circles are influenced by the still positioned light source (see above)! Finally, you might add some shading to the drawing. With the 'GEN GRIDS 11' command, you switch to partial line shading, with 'SET GRID 8' you choose a line density of 8 / cm:

g g 11
s g 8

When watching the formation of the drawing, you recognize, that you forgot some commands: you wanted the shading in black, too, you didn't want "foreign" shadows (which overlap labels) and you forgot to move the "north pole" direction of grids/lines shading. By typing <ESC> once, you can stop drawing. With the 'KILL XQT' command (which works only for "device no. 3"), you may cancel the last drawing action:

<ESC>    (wait until ">" prompt appears)
k x

The screen is erased, and the screen drawing is redrawn, but without the part generated by the last 'x' command. This part is also erased within the HPGL file 'PLOT1.PLT'. Now you may give the missing commands 'SET COLOUR', which switches to black colour only, 'SET SHADOW 1', and 'SET POLE' (the following shows a concatenated form of the three commands). An 'XQT' will complete the drawing.

s c; p 90 135; s 1

After the drawing is finished, it's wise, to reset at once some of the default parameters:

s c -1; s

7. Using Distributed Command Files for Plotter

This was rather complicated stuff! However, a similar plotter drawing may be obtained in a much easier way by means of the distributed command file S31.scf. It will also not label the Hydrogen atoms. This time we will use a negative view distance by means of the 'SET VIEW' command (see 'S V', general SCHAKAL 88 manual).

s v -27
u p
u c

Again, labelling of the first atom will take its time.

While "device no. 3" is on, it is also possible to receive some written information by the program. You may, for example, use the 'LIST PARAM' command once more:

l p

After the second erasure of the screen (caused by the <RETURN>), the program will read the active HPGL file and will re-visualize it on the screen. Note: in some cases (e.g. input of special command files), such a re-visualization may not occur. In such a case you can always force re-visualization by a 'LIST PARAM' or 'LIST ATOMS' command!

Finally, you may generate another HPGL file by means of the command file S33.scf. As this will be a coloured drawing, you first should change the colour of the phenyl ring bond sticks, as for the plotter the colour no. 12 means an overlay of colours 1 (black) and 2 (red), which is not very reasonable. An overlay of 2 (red) and 4 (blue), however, will appear as a kind of violet colour.

s v 27
c c 24 C=C (C1=C
u p
u c

At this point, you might leave "device no. 3" and go back to "device no. 1". However, you should be aware of the fact, that the last HPGL file is still open. You could return later to "device no. 3" and add some more details to the present drawing. In this special case, however, we close the file by another 'USE PLOTTERFILE' command and specification of the dummy file 'PLOT4':

u p
g d 1
x q

In order to check for the exisiting HPGL files, we will use the 'ZET DOS' command as an interface to DOS:

z d
dir *.plt

It's wise, to use the 'ZET DOS' command only when "device" no. 1 or 2 are on because, depending on the action you call by the DOS command, SCHAKAL's colour map may be confused afterwards. In such a case, use a 'GEN DEVC -1' or 'GEN DEVC -2' command to rebuild the colour map (if you gave a 'ZET DOS' command accidentally while "device" no. 3 was on, and the colours are messy, try to repair it by a 'g d -1; d 3' command).

With another 'XQT QUICK' you may clear the screen and then leave SCHAKAL using the 'END' command:

x q

If your computer is connected to a plotter which understands HPGL language (preferably a hp7475 plotter or a similar one), you may now copy one of the HPGL files to this plotter, e.g. by

copy PLOT1.PLT com1:

0.3 mm pens should be used preferably. For the coloured drawing in PLOT3.PLT, the pen colour order should be as follows: black, red, green, blue, yellow, brown.

About copying an HPGL file to a matrix or laser printer, see the end of chapter IV.1. in the "SCHAKAL 88B/V16" manual.


HTML-Formatierung: Burkhard Kirste, 1993/10/11