\documentstyle[a4,12pt]{article}\pagestyle{plain}\textwidth 15cm\topmargin -2.0cm\oddsidemargin 0.5cm\renewcommand{\baselinestretch}{1.00} % "single" line spacing\textheight 24cm\pagenumbering{arabic}\parindent 1cm\parskip 6pt\raggedbottom\begin{document}\begin{center}\noindentVersion: \today\vspace{1.0cm}\noindent{\Large \bf JACKAL 1992}\vspace{0.5cm}\noindent{\large by Jeremy Karl Cockcroft}\vspace{0.5cm}\noindentDepartment of Chemistry, University of Durham,\\South Road, Durham DH1 3LE, UK.\vspace{1.0cm}{\bf Historical Note}\end{center}\noindentThe program is based on the concepts of an earlier program called SCHAKALby Egbert Keller from the Crystallographic Institute at the University ofFreiberg in Germany ({\em J.\ Appl.\ Cryst.\ } 1989, {\bf 22}, 19-22).The new program name is the direct Englishtranslation of the German word Schakal.The original program was used extensively at the Institut Laue Langevin (ILL),Grenoble, on both ahigh-resolution raster colour terminal and on a 3-colour pen plotter.The new program was written from scratch using Fortran to generatethe PostScript code now in common use for many graphical output devices.The program was developed at ILL by the author whilst employed by the MaxPlanck Institut f\"uer Festk\"orperforschung, Stuttgart. This version wasfurther developed at the University of Durham.\begin{center}{\bf Introduction}\end{center}\noindentJACKAL is designed to draw {\em ball and stick} crystal structureson modern graphical output devices using PostScript.PostScript is ahigh-level, device-independent,graphics language developed by Adobe Systems Incorporatedwhose primary purpose is to describe theappearance of text, graphical shapes, and sampled images on thedisplayed or printed page.JACKAL takes advantage of the fact that PostScriptgraphics operators place objects on the current page such that each new objectobscures any objects already on the page.This eliminates the need for costlyhidden lining routines conventionally used to draw crystal structures:Every atom is drawn on the current page starting from the atom furthestfrom the eye with the result that the atoms closest to the view pointnaturally obscure those more distant.Thus JACKAL was easily developed for drawing ball and stick crystalstructures since itrequired the development of only two graphical objects, namely a shadedsphere and a shaded cylindrical rod, to draw any crystal structure.The current version of JACKAL is not interactive in the sense thatthe it produces a PostScript file which may be subsequently viewedeither on a device capable of displaying PostScriptor by outputting on a PostScript laser printer.However, it is envisaged that later versions could have the PostScriptoutput piped directly into a display window.\pagebreak[4]\begin{center}{\bf Running JACKAL}\end{center}\noindentThe program JACKAL should be installed on a common area on the VAXand then accessed by including theprogram name as a command in the users LOGIN.COM file: \begin{center}{\tt \$ JACKAL :== \$Diskname:[Directory]JACKAL}\end{center}Before running the program it is necessary to create a data file containing allthe crystallographic data needed for drawing the structure.Lattice and symmetry information may be used to generate atomic positions fromthe unique crystallographic positions and a box may be specified so as togenerate several unit cells of data.\begin{center}{\bf Data File Format}\end{center}\noindentAn example data file for the NaCl structure is given below:\begin{verbatim}TITLE Test NaCl StructureCELL    5.00000  5.00000  5.00000  90.0000  90.0000  90.0000ATOM  Na         0.00000   0.00000   0.00000ATOM  Cl         0.50000   0.00000   0.00000LATT  C FTEXT  Only space group generators are required...SYMM  -X,Y,ZSYMM  Y,Z,XSYMM  Y,X,ZBOX -0.001 1.001 -0.001 1.001 -0.001 1.001END\end{verbatim}The data file is keyworded  and free formatted within each line using space ortab characters for the delimiter.Each line starts with a key word and anyline beginning with the word {\tt TEXT} is taken as a comment line.The input data must be given in the order{\tt TITLE}{\tt CELL}{\tt ATOM}{\tt LATT}{\tt SYMM}{\tt BOX}{\tt END}.Each atom should be given a separate line starting with the keyword{\tt ATOM}. Likewise, each symmetry operator should be given a separateline starting with the keyword {\tt SYMM}. Input is not case sensitive.The variables following eachkeyword are listed below.\noindent\hangindent 1.5cm{\tt TITLE}-- a line of commentary to identify the data.\noindent\hangindent 1.5cm{\tt TEXT}-- extra lines of commentary.\noindent\hangindent 1.5cm{\tt CELL}-- 6 reals corresponding to {\em a, b, c} (in \AA),$\alpha$, $\beta$, $\gamma$ (in $^\circ$).\noindent\hangindent 1.5cm{\tt ATOM}-- atom label of up 6 characters followed by 3 reals for the atom's$x$, $y$, and $z$ coordinates.The atom label is normally formed from the element name(e.g Na) and optionally followed by the atom numberwith or without brackets (e.g. Na(2), Na3A).\noindent\hangindent 1.5cm{\tt LATT}\noindent\hangindent 1.5cm{\tt SYMM}-- Symmetry operator as specified in the International Tables for X-rayCrystallography. Use fractions for the translational part of symmetryoperators which must be multiples of $\frac{1}{24} ^{th}$.\noindent\hangindent 1.5cm{\tt BOX}-- 6 reals indicating the limits in -$x$ to +$x$,-$y$ to +$y$, and-$z$ to +$z$, for thegeneration of multiple unit cells. The values may be fractional and may evencorrespond to less than 1 unit cell. The {\tt BOX} command is optionaland is best omitted when drawing an individual molecule from a complete listof its coordinates.\noindent\hangindent 1.5cm{\tt END}-- simply marking the end of the file. Everything after this will be ignored.\pagebreak[4]\begin{center}{\bf Getting Started with JACKAL}\end{center}\noindentOnce a data file has been created, JACKAL may be run. It is assumed that thedata file will be created as output from another program (e.g. from aleast-squares fit) though it can be created by hand.For the beginner it is recommended that JACKAL is run interactively indialogue mode. More experienced users will normally generate their PostScriptplot files by running JACKAL within a command file. A typical beginners terminaldialogue is show below:\noindent\begin{verbatim}$ JACKAL              JACKAL-III version 1.20 Mar 92 (J.K.C.)The program requires a file containing a list of atom x,y,zcoordinates. The default file type is .XYZGive name of atom file (<CR> = PROFIL.XYZ)-> MYLIST.XYZTITLE Test NaCl StructureGive plot title (<CR> = none)->  NaClTotal number of atoms is   27Total number of bonds is    0Give commands (HELP is available)->  PLOT   Writing plot file...->  END   Output is in PostScript file P789.PSCPU time :     1.09     Elapsed time :     2.40  \end{verbatim}\noindentIt can be seen from the above examplethat the program first requests the data filename followed by a title. This title may be left blank. The program then enterscommand mode in which a series of drawing instructions may be given. The minimumset of commands is {\tt PLOT} followed by {\tt END}.The complete list of commands aredescribed in the next section and may be obtained in dialogue mode by typing{\tt HELP} at any time. The program also generates a file JACKAL.LISwhich lists all of the input atoms plus those generated by the program.Each atomis assigned a number which may be used in some of the drawing commands in orderto identify individual atoms.\pagebreak[4]\begin{center}{\bf Drawing Commands}\end{center}\noindentAll of the drawing commands described below are chosen to start with uniqueinitial letters enabling the command parser to search only the first characterof each input string. This lets the user abbreviate all commands tosingle letters whilst at the same time command files may be self commented bywriting the commands in full.Thus {\tt R}, {\tt ROT},{\tt ROTATE}, {\tt RZXCWK } etc.are all equivalent.All commands are non case-sensitive.Thus {\tt R x 90}, {\tt roT X 90},{\tt Rotate x 90}, etc.are all equivalent.Blank command lines are ignored as arelines beginning with an exclamation mark ({\tt !})or a percent sign ({\tt \%}). This allows comments to beinserted into the a command file. The drawing commands are listed below inalphabetical order.\noindent\hangindent 1.5cm{\tt ADD BOND atom atom distance1 distance2}\\This command causes extra bonds to be added that were not calculatedwhen the initial data file was read in. The command requires the names of twoatoms and one or two distance values in {\AA}ngstroms. The atom names may beeither generic (e.g. Na), specific (e.g. Na(4B)), or by number (e.g. \#10).The values determine theminimum and maximum limits for bonding. If only one value is specified, then itis taken as the maximum value with the minimum value being set to zero.Bond limits do not apply when both atoms are given by number.The maximum number of bonds per atom stored is 12.If any more are generated, only the first 12 are kept and no warning message isgiven.\noindent\hangindent 1.5cm{\tt DEFINE BACKGROUND r g b}\\This command allows the paper (background) colourto be redefined to suit the user. The default is white unless{\tt GENERATE INVERSE\_VIDEO} is used.See {\tt DEFINE COLOUR} for the definition of r g b.This command should be used with care.\noindent\hangindent 1.5cm{\tt DEFINE COLOUR n r g b}\\This command allows the default colour table to be redefined to suitthe user. It is also useful for those colour output devices whichhave a different colour balance to that used at ILL.The four variables are the number of the colour, n, and its correspondingcolour in terms of the proportion of red, green, and blue light from whichthe colour is composed. The latter are reals in the range 0 to 1.Any of the colours 1 to 24 except white (1) and black (2) can be redefined.\noindent\hangindent 1.5cm{\tt DEFINE OUTPUT pagesize (or xcm ycm xmargin ymargin (L))}\\This command allows the default page size to be changed.Either specify one of the standard sizes belowor the page size in cm for $x$ and $y$ together with margins andorientation (optional).Standard sizes are A4 (= 21 $\times $ 29.7 cm),A4L (= A4 landscape), A3 (= 29.7 $\times $ 42 cm), A3L (= A3 landscape),T (= 21 $\times $ 24.7 cm for overhead transparancies),TL (= T landscape),S (= 21 $\times $ 31.5 cm for 35 mm slides),and SL (= S landscape).\noindent\hangindent 1.5cm{\tt END}\\This command must be the last one given so as to close the plot file.The program then exits.\noindent\hangindent 1.5cm{\tt GENERATE AXES ABC x y BOX}\\This command instructs the program to display the axes directions of the unitcell in the bottom left-hand corner of the plot. If {\tt ABC} is given, thenall the axes will be labelled. To omit any label, simply omit its character fromthe string (e.g. to omit {\em c} type only {\tt AB}).\noindent\hangindent 1.5cm{\tt GENERATE BLACK\_WHITE}\\By default, JACKAL generates a PostScript file containing colour commands.While this may be output on a black and white device, better effects areobtained by instructing the program to generate a file without colour.\noindent\hangindent 1.5cm{\tt GENERATE COLOUR}\\Since this is the default drawing mode, this command simply resets the mode tocolour after a {\tt GENERATE BLACK\_WHITE} command.\noindent\hangindent 1.5cm{\tt GENERATE DASHES atom atom}\\This command generates dashed bond between the atoms (if bonded).\noindent\hangindent 1.5cm{\tt GENERATE FRAME}\\A picture frame suitable for overhead transparencies is generated by default.This command simply resets the drawing mode to this defaultafter a {\tt KILL FRAME} command.\noindent\hangindent 1.5cm{\tt GENERATE INVERSE\_VIDEO}\\The PostScript default is to generate black (or colour) on a white backgroundwhile on many terminals it is common to generate white (or colour) on a blackbackground. This command sets the drawing modeso as to obtain the latter effect. Thiscommand only effects black and white drawing instructions. Also, by default thepicture frame is not drawn in this mode.\noindent\hangindent 1.5cm{\tt GENERATE LOGO}\\A program logo is generated by default in the bottom right-hand corner of thepicture.This command simply resets the drawing mode to this defaultafter a {\tt KILL LOGO} command.\noindent\hangindent 1.5cm{\tt GENERATE OUTLINE}\\This is the fastest drawing mode and is recommended when trying to determine thebest view of the structure. The balls are simply drawn as circlesand the sticks are non-shaded.\noindent\hangindent 1.5cm{\tt GENERATE POLYHEDRA}\\This changes the drawing mode to polyhedral representation. The faces of thepolyhedra are determined by examining the atom bond list. If A is bonded to Band C and B is bonded to C, then the atoms A, B, and C are represented bya triangle instead of balls. Atoms not forming part of a polyhedra are drawnas ball and stick. Currently, the faces of the polyhedra are grey thoughthis will change shortly.\noindent\hangindent 1.5cm{\tt GENERATE SHADED}\\This is the default drawing mode in which all balls and sticks are shownilluminated a light source.This command simply resets the drawing mode to this defaultafter a {\tt GENERATE OUTLINE} command.\noindent\hangindent 1.5cm{\tt GENERATE UNIT\_CELL}\\This command generates the unit cell outline. If there exists an atom at theorigin or the unit cell edge, then it imperfections in the drawing may beobserved due to the fact that no hidden lining is attempted.\noindent\hangindent 1.5cm{\tt KILL ATOM atom (atom ...)}\\The {\tt BOX} command at the end of the input data file may generate someunwanted atoms that spoil the picture. They may be removed using this command.The command requires one or more atom names or atom numbers as an argument.Atoms specified by number must be preceded by a hash character {\tt \#}).If a generic name is given, then {\em all} atoms of that type will bedeleted. Note that the program simply marks the atoms as non-drawable afterthis command and it does not remove them from the atom list internally. This hasthe desirable consequence that the atoms are not resequenced with a new numberafter this command. As many atoms as will fit on one input line of 80 charactersmay be given in a single command.\noindent\hangindent 1.5cm{\tt KILL BOND atom atom}\\This command is used to delete unwanted bonds from the picture. As with the{\tt ADD ATOM} command, only generic or specific atom names may be used asarguments for this command. This command deletes {\em all} bonds betweenthe specified atoms. It may be followed by the {\tt ADD ATOM} commandso as to generate only those bonds which are desiredinstead of those auto-generated by the program.\noindent\hangindent 1.5cm{\tt KILL FRAME}\\This command deletes the picture frame generated for overhead transparencies.\noindent\hangindent 1.5cm{\tt KILL INVERSE\_VIDEO}\\By default the background colour for the picture is white.This command simply resets the drawing mode to this defaultafter a {\tt GENERATE INVERSE\_VIDEO} command.\noindent\hangindent 1.5cm{\tt KILL LOGO}\\This command deletes the program logo from the bottom right-hand corner of theplot. Thus any acknowledgement to the program may be removed for those whodesire it!\noindent\hangindent 1.5cm{\tt KILL UNIT\_CELL}\\By default no unit cell is drawn.This command simply resets the drawing mode to this defaultafter a {\tt GENERATE UNIT\_CELL} command.\noindent\hangindent 1.5cm{\tt LIGHT angle1 angle2}\\The illumination for the structure defaults to a light shone normalto the display. The light may be rotated to another position using thiscommand with the two arguments, theta and phi, respectively. The anglesmust be given in degrees. Theta is defined as a rotation about they axis in the display plane and is limited to the range$\pm$~80$^\circ$. Phi is a rotation about the z axis normal to the displayplane. For both rotations, a positive angle corresponds to an anticlockwiserotation when viewed down the axis.\noindent\hangindent 1.5cm{\tt MAGNIFY value}\\The initial scale for the drawing is set at 1\,cm/{\AA}. This commandmay be used to increase or decrease the size of the picture. The argument isa single real in the range 0.001 to 1000.0. Multiple calls of the commandto not cause multiple rescalings since only the last value used is stored.\noindent\hangindent 1.5cm{\tt MAGNIFY BOND value}\\The default stick thickness is set at 0.15\,{\AA}. This value may be rescaledusing this command.\noindent\hangindent 1.5cm{\tt MAGNIFY LABELS value}\\The default font size for labels and text (excluding the title text)is 15 points. This value may be rescaledusing this command.\noindent\hangindent 1.5cm{\tt MAGNIFY RADII value}\\This command takes one real argument which rescales all ball radii by the samevalue. Its value defaults to 1.0 if unspecified.\noindent\hangindent 1.5cm{\tt NEW\_FILE}\\This command allows another data file to be read in. This is useful if twodrawings are required on the same output. If {\tt PLOT} has not been given as acommand, the program assumes that the original data file was given in errorand a new title will be requested. If two structures are required on the sameoutput, then it is necessary to translate them so as to avoid superposition(see {\tt TRANSLATE}).\noindent\hangindent 1.5cm{\tt PLOT}\\This command is essential to obtain a picture. Following this command, thestructure is drawn using the current parameters.Following this command, all parameters are reset to their initial state andthe initial data is lost.\noindent\hangindent 1.5cm{\tt QUIT}\\This command may be used to end an interactive dialogue session without a plotfile being produced. Alternatively, the user may use $\hat{ }$Z.\noindent\hangindent 1.5cm{\tt ROTATE X value}\\This commands rotates the structure about the x-axis in the plane of thedisplay. The rotation origin is taken as the point in the centre of the boxdefined by the {\tt BOX} command in the data file. The argument is a real valuein degrees and acts anticlockwise about the axis. The {\tt ROTATE} and{\tt TRANSLATE} commands are decoupled and act independently of each other.Rotations are carried out in the order given by the user and are notcommutative.\noindent\hangindent 1.5cm{\tt ROTATE Y value}\\Similar to the {\tt ROTATE X} command, butrotating the structure about the y-axis in the plane of thedisplay.\noindent\hangindent 1.5cm{\tt ROTATE Z value}\\Similar to the {\tt ROTATE X} command, butrotating the structure about the z-axis normal to the plane of thedisplay.\noindent\hangindent 1.5cm{\tt SET BOND n}\\This command allows the default bond colour (equal to 22) to be overwritten.All bonds are drawn the same colour.The argument for this command must be an integerin the range 1 to 24 (see Jackal Colour Table).\noindent\hangindent 1.5cm{\tt SET COLOUR atom n}\\This command allows the default atom colours to be overwritten. The commandrequires an atom name and an integer colour number. The latter should be in therange 1 to 24 (see Jackal Colour Table). The atom name may be eithergeneric, specific, or even its atom number preceded by the hash character(e.g. \#27). Only one atom name or number may be specified per command.\noindent\hangindent 1.5cm{\tt SET DARKNESS value}\\This command allows the shading of the balls to be varied. The non-illuminatedside of the sphere is black when the darkness value is set to 0.0 and is equalto the full colour of the sphere when set to 1.0, these two valuesdetermining the limits of the argument of this command. The default valueis 0.25. The 3-D effect is greatest when the value is zero at the expense of adarkish picture and is completely lost when the value is unity.\noindent\hangindent 1.5cm{\tt SET FONT\_SIZE value}\\This command allows the point size of character text to be specified. It effectsthe size of labels drawn with the {\tt WRITE LABEL} command andalso {\tt WRITE TEXT} and{\tt WRITE CENTRED} text strings.The latter may be written with different pointsizes with a {\tt SET FONT\_SIZE} command before each command.\noindent\hangindent 1.5cm{\tt SET RADIUS atom value}\\This command allows the default atomic size to be overwritten.The program draws balls whose radius is 25% of the atomic size.The command requires an atom name (e.g. Br or Br(2c)) or number (e.g. \#17)and a real value in {\AA}ngstroms specifying the atomic radius.\noindent\hangindent 1.5cm{\tt TRANSLATE xcm ycm}\\The two real arguments of thiscommand translate the structure shown in the picture by $x$ and $y$ cm,respectively. If drawn, the axes, picture frame, and logo remainin the same position.\noindent\hangindent 1.5cm{\tt VIEW zcm}\\Normally, the picture will draw the crystal structure as viewed from infinity.When the structure is viewed from a close distance, the perspective changes. The{\tt VIEW} command specifies the distance in cm of the eye from thepicture plane. Reasonable perspective effects are achieved with values in therange 30 to 100 cm. A value of zero is taken as infinity.\noindent\hangindent 1.5cm{\tt WRITE CENTRED xcm ycm text}\\Often extra text is required on the picture. The {\tt WRITE COMMANDS} and{\tt WRITE TEXT} commands allow extra text strings to be drawn on the pictureafter the {\tt PLOT} command. Both require two real values specifying theposition on the picture where text is to be displayed. For the{\tt WRITE CENTRED} command, the x value specifies where the centre of thestring is to appear in the picture. The text can contain any charactersincluding spaces although left and right round brackets () must be matched.All text strings (including the title string) may contain sub- andsuper-scripted characters. These are indicated by preceding the character withan underscore (\_) or circumflex ($\hat{ }$) for sub- and super-scripts, respectively,(e.g. give YBa\_2Cu\_3O\_7\_-\_x to obtain YBa$_2$Cu$_3$O$_{7-x}$).The font size for the text may be changed with the {\tt MAGNIFY LABELS} command.Since each {\tt WRITE TEXT } or {\tt WRITE CENTRED} command is carried outimmediately, different text strings may be written in different sizes byspecifying a new font size before each command (see Examples).\noindent\hangindent 1.5cm{\tt WRITE LABELS xcm ycm (atom)}\\This command writes each atom's label on each ball using the current font size.The two real values (which may be zero) specifythe distance in cm that the labelshould be moved relative to the centre of the ball in the $x$ and $y$directions, respectively. The atom name is an optional argument and may bespecific (e.g. Se(1)) or generic (e.g. Se). However, for the latter case,all the atoms specified by their generic name will be written with their fullspecific label.\noindent\hangindent 1.5cm{\tt WRITE NUMBERS value value}\\This command writes each atom's number on each ball using the current font size.The two real values (which are optional) specifythe distance in cm that the numbersshould be moved relative to the centre of the ball in the $x$ and $y$directions, respectively.\noindent\hangindent 1.5cm{\tt WRITE TEXT value value text}\\This command is the same as {\tt WRITE CENTRED} except that the text is writtenleft-justified starting at the point $x$,\,$y$~cm.\begin{center}{\bf JACKAL Colour Table}\end{center}\noindentJACKAL has a predefined colour table consisting of 24 colours suitable for usewith the Textronix Colour Phaser printer. These are illustrated at the end ofthis manualwith the darkness factor set to 0.25and with both light angles equal 45$^\circ$.Different effects may be achieved my varying these values.\begin{center}{\bf JACKAL Examples}\end{center}\noindentIn order to illustrate usage of JACKAL, several example command files are givenwith their pictures they generate on succeeding pages.\noindent\begin{center}{\em Example 1}\end{center}\begin{verbatim}$ JACKALYBACU.XYZExample 1ROTATE X -90ROTATE Y 180ROTATE Y 15ROTATE X 15GENERATE UNIT_CELLGENERATE AXES ABCADD BONDS Cu O 2.5SET BOND 10SET RADIUS Y 2.0SET RADIUS Cu 1.7MAGNIFY 1.2KILL FRAMEGENERATE BLACK_WHITEGENERATE OUTLINEMAGNIFY LABELS 0.7MAGNIFY RADII 1.5WRITE LABELSVIEW 50PLOTMAGNIFY LABELS 1.5WRITE CENTRED 10.5 4.5 YBa_2Cu_3O_7END\end{verbatim}\noindent\begin{center}{\em Example 2}\end{center}\begin{verbatim}$ JACKALYBACU.XYZExample 2LIGHT 45 45ROTATE X -90ROTATE Y 180ROTATE Y 15ROTATE X 15GENERATE UNIT_CELLGENERATE AXES ABCADD BONDS Cu O 2.5SET BOND 10SET COLOUR Cu 8SET RADIUS Y 2.0SET RADIUS Cu 1.7MAGNIFY 1.2MAGNIFY RADII 1.0KILL FRAMEVIEW 50PLOTMAGNIFY LABELS 0.8WRITE TEXT 16.5 21.6 Cu(1), O(4)WRITE TEXT 16.5 19.4 Ba,O(1)WRITE TEXT 16.5 17.2 Cu(2), O(2), O(3)WRITE TEXT 16.5 15.1 YWRITE TEXT 16.5 13.2 Cu(2), O(2), O(3)WRITE TEXT 16.5 10.5 Ba,O(1)WRITE TEXT 16.5  8.2 Cu(1), O(4)MAGNIFY LABELS 1.5WRITE CENTRED 10.5 4.5 YBa_2Cu_3O_7END\end{verbatim}\end{document}