next up previous contents
Visit our: CCMS Home Page
Send us your comments on this user guide: CCMS Comment Form
Next: NonWindow-based Applications
Up: Table of Contents
Previous: Chapter 5-2 Window-based Applications



Searches for heavy atom sites.




xhercules searches for heavy atom sites by calling hercules. This is a brute-force application of Patterson correlation methods. It is slow, but extremely robust.

Main Window


The XtalView crystal keyword accesses the crystal information file.


The current working directory.

Fin file

Fin file with merged native and derivative data.

Solution File

NONE for the first round, then solution file output from xheavy or xpatpred for the second round.

Correlation Map

The correlation map file (output in xcontur or xfit format).

Resolution Limits

Set the resolution maximum and minimum limits in Angstroms on diffraction data.

Search Grid

The search grid should be 1/4 to 1/6 resolution in Angstroms.

X Bounds in Fractional

Set the minimum and maximum bounds of x in fractions of unit cell (x asymmetric unit).

Y Bounds in Fractional

Set the minimum and maximum bounds of y in fractions of unit cell (y asymmetric unit).

Z Bounds in Fractional

Set the minimum and maximum bounds of z in fractions of unit cell (z asymmetric unit).

Occupancy of Search Atom

Search for Top Hit


Stops running hercules.

Top Hit

Displays the top of the search.

Append to Solution File

Writes the top hit to the solution file.

To search for an initial site enter NONE for the solution file and select Search for Top Hit. You can put this initial site into a solution file using xpatpred. Then, to search for a second site, enter the new solution file instead of NONE and run another search. The atom data in the solution file is in the same format as that used by xheavy.

To guess an occupancy for the second site relative to the first, examine the Patterson map. It's not very sensitive to the occupancy, so numbers like 1, .75, .5, or .25 are sufficient. Use xpatpred to display the predicted Patterson positions. To do this, enter the site and then write out a prediction file. Read this file into xcontur as a labels file. The vectors are put into the volume as 0-1, 0-1, 0-1, so they won't show up on negative sections. For multiple site solutions, pay particular attention to the cross-peaks. The search volume should be the asymmetric volume of the Patterson map. The input format only allows for rectangular limits on asymmetric units. This may cause some redundant computation in high symmetry space groups. For single sites there will be extra symmetry due to the fact that both hands and all origin shifts are valid interpretations of the Patterson map. For a second site there is a two-fold ambiguity due to the hand choice. You can reduce the search volume accordingly. If not, note that there will be several equivalent hits (They will all give identical predictions with xpatpred). The solution can then be read directly into xheavy for refinement.

If you want to use the PHASES package from Furey, then xheavy can rewrite the solution into a file that's more or less ready to use depending on the PHASES version you use. hercules writes an fsfour style map that may be examined with xcontur. To get the coordinates in xcontur, click on the peaks. Sites are added to the solution file as they are found and the program is rerun. The peaks can be entered into xpatpred and displayed on the Patterson map to verify their correctness.

xhercules only takes a .fin file, not a .df file. You can split off part of the data in a .df file to form a .fin file with awk. If you do this, you can extract the first entry in the .df file with the command:

awk '{print $1, $2, $3, $4, $5, $6, $7}' < file.df > file.fin

You can extract the second entry with the command:

awk '{print $1, $2, $3, $8, $9, $10, $11}' < file.df >

(For information about .fin and .df file formats, see Chapter 3.)


xtalview(1), hercules(1)



Merges and scales two data files.


xmerge data1.fin data2.fin


data2.fin is merged and scaled to data1.fin. The data in file 2 is scaled to match that in file1. The data in data1.fin is referred to as f1 and the data in data2.fin is referred to as f2.

crystal info needed: cell.


The data is scaled into n bins based on sin(theta)/lambda2. Two scaling methods are available: single and anisotropic. In single scaling, a single parameter is used to scale the data in each bin such that:


If Bijvoet pairs exist, they are averaged for scaling purposes.

In anisotropic scaling, first single parameter scaling is done and then a 6-parameter scaling is done such that the scaling parameter is a function of the three crystal indices. This helps minimize errors due to differential absorption, for example. The formula used for the scale factor "s" at each h,k,l is:

s = h*h*a11 + k*k*a22 + l*l*a33 + h*k*a12 + h*l*a13 + k*l*a23

Where a is found by a least-squares fitting procedure. The
fitting procedure may fail if too few data are used. In this case, you have two
choices: decrease the number of bins to put more data in each bin, or use
single-parameter scaling.

Fin File 1

The "standard" data set, as the second fin file is scaled to this one. Normally, use your best native data here.

Fin File 2

The fine file containing the data to be scaled to fin file 1. Normally derivative or mutant data.

Output File

The merged and scaled data. The name should indicate which data was used to make this file. (See example below.)

Output Type

You can output your data in either fin or df format. fin format merges f1 and f2 (Bijvoets = f+ and f-) in the input fin file so that the output fin file also has only two fields. All fields are preserved in a df file so that Bijvoet information is preserved for both input files. Since df files can always be turned into a fin file with xdftofin, this is the more useful of the two options.


Reflections in common means that the reflection must be in both file1 and file2. All reflections are all of those in file1 and those in common in file2. If a reflection is in file2 but not in file1, it is not used or output.

Number of bins

The data is divided into bins based on sin(theta)/lambda squared. This slider sets the number of bins, with 10 as the default. Note that dividing by the square does not put equal numbers of reflections into the bins, as would sin(theta)/lambda cubed, but provides a better distribution in reciprocal space. If there are too few reflections in a bin, the number of bins should be decreased to put more reflections in each bin. For anisotropic scaling, about 500 reflections per bin are good, with 50 being a good minimum. Too many bins will decrease the signal by scaling away any differences, and too few may not adequately scale the two data sets.

Note: On sliders, if you edit the number with the keyboard, be sure to hit <CR> (Return) to register the new value.

Sigma Cut

The data is excluded from the scaling equations if its amplitude is less than sigma cut times the sigma of the amplitude. This usually makes little difference, because these data are weak anyway.

Scaling Type

Sets the scaling method used, as explained above. Anisotropic scaling is actually single scaling followed by anisotropic scaling. If there are too few reflections for anisotropic scaling, you will get errors. In this case, decrease the number of bins or use single scaling.


Two results are graphed in the graphics window: delta, the abs(f1 - s*f2) (dashed line), and the R-factor abs(f1 -f2*s)/f1 (solid line) for each shell. For a heavy-atom derivative, the delta should start high and decrease with resolution. If it starts to increase, this may mean that the derivative is non-isomorphous past this resolution. The R-factor should smoothly change with each bin. If not, use fewer bins.

History File

The history file contains, in addition to the normal information, a list of the scale, r-factor, and abs delta for each resolution bin.


To scale a native data set to a derivative data set:

xmerge ccpnat4.fin ccppt1.fin ccpnat4pt1.df

You can use this file as input to xfft to make a Patterson map,
which can be contoured with xcontur.

In some instances, you may wish to scale data in a single fin file to itself. For example, you may wish to scale Bijvoet pairs. In this case, you must first split the file and then remerge and scale. For example, to scale unscaled.fin to scaled.fin (remember, a fin file is records of h,k,l,f+,s(f+),f-,s(f-)), you can use the following commands:

awk '{print $1,$2,$3,$4,$5,$4,$5}' unscaled.fin >

awk '{print $1,$2,$3,$6,$7,$6,$7}' unscaled.fin >

xmerge unscaled_fp.fin unscaled_fm.fin scaled.fin


The xmin is set as default, but once other options are chosen the xmin button doesn't toggle and will sometimes crash your machine. (This happens in xstat also.)


xtalview(1), xcontur(1), xfft(1)



Merges fin and PHASE files. Phases derivatives and mutants.


xmergephs fin_file phs_file


The data in fin_file is phased with the phases in phs_file and the resultant structure factors are written out in another phase file. The phase file can be either a .phs file, an XPLOR phase file, or a TNT hkl file. Options are available for using isomorphous or Bijvoet differences.


Quits the application.


The directory.

Fin File to Phase

The fin file to be phased (h k l f1 sigma(f1) f2 sigma(f2)).

Phase File

The file with phases to be used for phasing the fin file can be either a .phs file, an XPLOR format file with the entry FCALC=, or a TNT hkl format file. The phase is normally expected to be in degrees, although if you use xfft in the next-step radians are acceptable.

Output Phase File

The output is written to this file. The f1 and f2 fields in the fin file are written out as h k l f1 f2 phi unless otherwise specified (see below).

Swap f1 and f2 (isomorphous Fourier)

If f1 is the native FP in your fin file, and f2 is the derivative FPH, then f1 and f2 should be swapped so that the output is h k l FPH FP phi. Then make an fo-fc Fourier map, which will show the positions of the heavy atoms if protein phases are used (double-difference Fourier).

You may also want to swap mutant data that has been merged with native data to make an Fmutant-Fnative difference Fourier.

Add 90 to phase (Bijvoet Fourier)

If the fin file contains Bijvoet differences (h k l f+ sigma(f+) f- sigma(f-)) and the input phases were in degrees, then a Bijvoet-difference Fourier can be made by adding 90 to the phase and swapping f1 and f2. Centric reflections will be handled correctly if they have 0.0 in the f- position. If you have used xtalview the whole way and started with an XENGEN mu file, then they will be correct. If f+ is equal to f-, then the reflections will be output; however, since their difference is zero they will not contribute to the Fourier.


Click here when you are ready to go. The program can take quite a long time if the two input files have a different sort order as the program searches for matches in indices between the two programs. Note that if you have equivalent indices that are not numerically the same (e.g., h k l and -h -k l) the merge will fail!


The aforementioned problem causes the program to not find a match if the indices are equivalent but not identical.





Predicts Patterson peaks from a list of sites.




xpatpred allows you to enter and edit a set of sites and output these in a form displayable by xcontur. The sites can be written out in a solution file and refined using xheavy. Different origin choices can be selected, allowing a rapid way to try all possible origins and visually choose the correct one.


The symmetry operators must be present in the crystal data file in the symm record.

Solution File

The solution file can be loaded or saved. This file is a unique format to xtalview that is reminiscent of the pdb file, in that each record starts with a key word. The solution files can be shared with xheavy in order to refine the heavy atom sites. When a solution is written out, any origin choice is added to it, and when it is read back in, the origin is reset to 0,0,0. Coordinates are fractional in solution files.

Prediction File

This file is a list of labels that can be read into xcontur with the load labels option under Files. The labels are in fractional coordinates (in u,v,w). The label indicates which sites it is derived from in its name. (I.e., pt1-pt1 is a self-vector of the site pt1, and pt1-pt3 is a cross-vector between pt1 and pt3). The labels are transformed so that they are between 0 and 1. They are generated by looping through all symmetry operators in a pairwise fashion. It is not guaranteed that all possible symmetry-related labels will be generated, so if a peak is not labeled a symmetry-related one should be checked.

Site List

The sites are listed in a scrolling list. Clicking on a site selects it and places its values in the fields below so it can be edited. Insert takes the information in the individual fields and places it in the scrolling list at the end. Replace replaces the currently highlighted line with the data in the fields. Be careful to first select a line to be replaced, and then edit it (if you forget, you can insert a new line and then delete the line it was supposed to replace.) Delete removes the highlighted line--the data is lost forever. (Solutions can be saved often, however.) Each line contains the atom label, x, y, z, origin choice, atom-type, occupancy, and B-value. There are 8 origin choices of adding 0.5 or not to x,y,z. B-value and occupancy are not directly used in this program.

Label, x, y, z, B-value, occupancy, atom-type

These are text fields that can be used to change or enter data. To replace data in the scrolling list, select the line, edit it, and then replace it.


Gives the current working directory.

Load Solution

This option allow you to read a solution file into the site list.

Save Solution

This option allows you to write the solution file into the current site list.

Write Prediction Button

This option writes the Prediction file using the current site list. The format is a labels file for xcontur. You can then read this file into xcontur and display the labels on your Patterson map to confirm the cross-vectors.


This is a pull-down list of 8 choices. First, select the line to be changed, select the origin, and then replace the line. To see the effect in xcontur, write out the prediction and reread it in xcontur. Usually, this is used to find the relative origin of a second choice while holding the first constant. Self-vectors will be unaffected by an origin choice, but the cross-vectors are dependent upon the relative origin choice. With 2 sites, only 4 of the choices will make a difference, the other two being hand choices and not detectable with a Patterson map. With 3or more sites, all 8 choices may make a different pattern of cross-peaks.

Not all the origin choices are valid in every space group. The possible origins are listed in the International Tables for Crystallography. The origin choices given are valid for orthorhombic space groups. However, if an incorrect origin is chosen it will either make no difference (e.g., adding 0.5 to y in monoclinic makes no difference) or it will cause the self vector not to match and so will be detectable. Other origin choices will have to be entered by hand unless they are added to a future version.


xtalview(1), xcontur(1), xheavy(1)



Reformats XPLOR phase files.


xplortophs [xplor.fcalc.file] [xtalview.phs]

This program scans an XPLOR phase file and reformats it for XtalView. The XPLOR file is generally produced with the XPLOR script fcalc.inp.





Imports/exports fin files from/to other formats and reformats fin files.


xprepfin in out


This is the main entry point for data into xtalview. It is really set up for XENGEN mulist files (the output of makemu -f).


Exit xprepfin.


The directory.

Input File

The input file can be either a fin or XENGEN mulist.

Other Formats

Select a non-XtalView format from which to read in data: Raxis (hkl fobs sigma Bijovet_difference), XDS format with F's, XDS format with I's.

To read in data from non-XtalView formats, select Other in the format list, select one of the other formats in the menu, and then press Apply. To add another format, read the instructions in the file $XTALVIEWHOME/data/OtherFormats. Essentially, you write a filter program that reads your format in and writes out .fin format on standard out. You then add a line to the OtherFormats file specifying the menu label and the program name of the filter.

Input Format

Set this to the correct type.

Use Data

There are 6 options for switching the input to make the output:.

  1. As is. No change to input.

  2. Avg f1 and f2. If f1 and f2 exist, then they are averaged. If one is missing, then the output is set to the other one.

  3. F1 then F2. If F1 exists, then use it first; otherwise, take F2.

  4. F2 then F1. If F2 exists, then use it first; otherwise, take F1.

  5. F1. Always use F1 if it exists.

  6. F2. Always use F2 if it exists.

Switch F1 and F2

Select SWITCH to do this. This operation is done after Use Data:.

Data Are...

This controls how some operations behave. If the data are Bijvoet pairs, then when the indices are switched it may be necessary to reverse the Bijvoet pair. Also, when a centric reflection is output, Bijvoet pairs are averaged, placed in the first field, and the second field is set to zero since centrics do not have an anomalous scattering signal. Obviously, this should not be done to isomorphous pair data.

Reduce Indices

The data indices are reduced to produce a unique value, the reflections are sorted on h, k, l, and any duplicates are merged. Unfortunately, the algorithm used does not always put the data in the quadrant you desire.

Output Format

Select the desired format from the three choices.

Output File

The name of the output file goes here.


When you are ready, click here.


There should be more formats supported, which the developer plans to add later.





Resolution filter.


xresflt [file filtered file]

Any file beginning with records beginning with h k l can be filtered. The proper crystal must be entered. The data between the two limits is output.

Resolution Limits

Limit1: 0-1000

Limit 2: 0-10

These two limits set a range between which your data will be output. Data outside this resolution range is not written out. The order of the limits is not important.





A reciprocal space viewer for examining completeness of data, differences between data sets, and intensity patterns.

Note: xrspace works best on color displays.


xrspace [file]


Use xrspace to do the following:

xrspace reads the environment variables CRYSTAL and CRYSTALDATA. If CRYSTAL is present, then this is used to set the crystal type, or it can be manually entered after the program starts. CRYSTALDATA is the default directory to look for the info file of CRYSTAL. When looking for the info file of the crystal type, it first checks the current directory and the $CRYSTALDATA/crystal.

Database Requirements

xrspace looks for the keywords cell and symm in the database/info file. If cell is present, it is read and placed in the Unit Cell field. It can be manually overwritten if desired. The symmetry operators are read from the line symm, which should be entered in the format used in the International Tables, Vol. I. xrspace converts these symmetry operators to Patterson symmetry by adding a center of symmetry.


cell 48.5 76.3 92.1 90.0 104.0 90.0

symm x,y,z; -x,y+1/2,z;


The application presents a window that is divided into three main areas: the control panel, a message window, and a canvas where the data is displayed as specified by the control panel settings. The control panel is meant to be read from top to bottom. Messages are printed in the textpane at the bottom. Note that the textpane has the ability to save output by means of its pop-up menu. The data is displayed on a color display coded by a heatscale to represent intensity--as the data increases in intensity, it goes from black to red to yellow to white. The width of a spot is proportional to F and its area is proportional to I.

Quit Button

Click to quit. You have one chance to change your mind.


This button currently does nothing.


Check that the correct crystal is entered here. A corresponding database file should be in the directory $CRYSTALDATA--typically ~/xtal_info. If it needs to be changed, click on this field to move the cursor here and type in the new crystal and hit <CR>. If at any time you want to force-read the crystal file (for instance, you just edited it and fixed something), hit <CR>.

Unit Cell

The proper unit cell should be displayed here. You can manually type in any cell and override the one found in the database file.


The current directory.


The current input file, either entered from the command line or manually.

Read Button

Clicking this button causes the file to be input.

Type Setting

Click on the appropriate file type: .fin [a fin file (ih,ik,il,f1,s1,f2,s2)]; .mu [an XENGEN mulist file from the makemu command]; .df [a "double fin file" (ih,ik,il,f1+,s1+,f1-,s1-,f2+,s2+,f2-,s2-)]; or .urf [an urefls XENGEN file from integrate].


Not operative.

Display Data

This switches between f1 and f2 or |f1-f2| (Delta). Useful for looking at merged heavy atom datasets or for anomalous differences.

Planes of

This sets the sectioning direction. You can use the three principal directions or the major diagonals.


This slider sets the plane level (i.e., if the plane direction is h and the level is 0, then the 0kl plane is displayed).


This sets the number of planes that will be displayed. Normally they are drawn on top of each other; however, see Offset of Vertical Axis.

Spot Size

Scales the size of all the spots up and down. Set this so that spots do not overlap.


This controls a ring which is drawn at the specified resolution. It does not control the maximum resolution of the screen that is set by the limits of the input data.


Controls whether symmetry is used to generate symmetry-related spots or if only the unique data is displayed.

Offset of vertical Axis

This lets you offset planes so that they are not drawn on top of each other. Try x=2 and y=3 and make the spot size smaller for a orthographic display of several planes (slab > 1).


Redraws the screen. After first reading the data, this must be clicked. Most of the other buttons and sliders redraw automatically. Pay attention to the message at the bottom of the window (left footer). If it doesn't say, "Ready for new input," just wait patiently: the screen is redrawing.


Sends PostScript output to a printer or file. Type the name of the printer or file in the Printer field.



xrspace works best on a color display, although it can also be used in black-and-white.





XtalView front-end for the mkskel skeletonization program (mkskel is part of the University of North Carolina GRINCH skeletonization package).


xskel input-file ridgeline-file


xskel creates ridgeline files by calling mkskel. A phase file is used as the input. The output skeletonization that was produced by mkskel from the electron density map is renamed as a ridgeline file with a .bones extension.

XtalView can read in the ridgeline file, or you can use grinchbones to convert it to a vu object.

Main Window


The XtalView crystal keyword accesses the crystal information file.

Unit Cell

This read only field verifies the selected crystal's unit cell parameters.


The current working directory.

Defaults Menu Button

A defaults file of parameters can be loaded and saved in the current directory.

Input Phase File

An XtalView phase (.phs) file. Electron density will be FFT'd from this phase file and converted for input to mkskel. This field can be filled either from the command line as the first argument, or by selecting a file name in the file list, or by typing the file name in.

Ridge Lines File

The output ridgelines file produced from mkskel skeletonization (ASCII, binary, or "edges" format). This field can be filled either from the command line as the first argument, or by selecting a file name in the file list, or by typing the file name in.

Map Type

Selects one of the options for map coefficient type.

Map Bounds in Fractions of the Unit Cell

Sliders are used to enter the fractional bounds of the volume to be skeletonized. If the bounds are outside the slider values interrupt the program, hand-edit the .mi file, then run it through xskel.


Optional resolution filter to be applied to input phases.

Minimum Density

Lower this value to see more ridgeline contours than the default minimum density includes. Note: XtalView maps are always scaled such that rms or sigma equals 50.

Maximum Density

The output ridgelines will be given values from 1 to 29 corresponding to the min and max entered here.

Make Ridgelines

Writes a shell script and starts mkskel in the background.


Stops running mkskel.


The ridgeline code mkskel was written by Tom Williams, and is supplied with Xtalview with permission from the author and the Computer Science Department, University of North Carolina at Chapel Hill.





Analyzes statistics on .fin, .df, or .phs files.


xstat [file.fin | file.df | file.phs]


The xstat application creates plots that display features of various types of fin files. The data in the input file is partitioned into a number of bins, and then plotted as an x-y plot according to the type of plots you request.

The graphical user interface for xstat includes the following elements.


Exit xstat.


The name of the crystal.


The directory containing the input file.

Input File

The input file can be a fin, df(1+2,3+4), df(1,2), df(3,4), or a phase file.

Number of bins

The number of bins in which to sort the data in the input file.

What to graph

Six types of plots are available with xstat. Click on one or more of the following buttons to choose the type of plot.

Graph It

Press this button when you have selected one or more types of graphs and xstat will pop up canvases for viewing the plots.


On the popup window for the plots are menu buttons for plot properties and for printing a plot. Beside the properties button is a text entry line. The items on the properties button all use the text entry line for input of a number or text label to be written on the plot.

The properties menu items are:

Set Xmin

Set the lower limit on X for the plot's x-axis.

Set Xmax

Set the upper limit on X for the plot's x-axis.

Set Ymin

Set the lower limit on Y for the plot's y-axis.

Set Ymax

Set the lower limit on Y for the plot's y-axis.

Set # X divisions

Set the number of labeled tick marks for the plot's x-axis.

Set # Y divisions

Set the number of labeled tick marks for the plot's y-axis.

Set # X minor divisions

Set the number of minor tick marks for the plot's

Set # Y minor divisions

Set the number of minor tick marks for the plot's y-axis.

Set X label

Set the text label for the X axis.

Set X label Size (points)

Set the X label size in points.

Set Y label

Set the text label for the Y axis.

Set Y label Size (points)

Set the Y label size in points.

Set Title

Set the text label for the plot title.

Set Title Size (points)

Set the Title size in points.

Beside the print menu button is a text entry line containing the name of a printer or the name of a file in which to store a PostScript version of a plot. The print menu items are:

Print to postscript printer

Send the plot to a PostScript printer.

Print to postscript file

Send the PostScript for the plot to a file.


The xmin is set as default, but once other options are chosen the xmin button doesn't toggle and will sometimes crash your machine. (This happens in xmerge also.)





This is the top-level application for xtalview; it used to start other applications and allows you to create and edit crystals and projects.




xtalmgr is used to start the other xtalview applications.

It allows creating, editing and deleting crystals.

Projects can be organized using the project feature--all data related to the same project can be grouped into a project.

File filters are used to help the user weed through the usual forest of files.

Autonaming can be used to make up a sensible name for an output file from one or two input files.

A history of commands is kept to simplify repetitive actions and to keep track of what you've done.

Environment Variables

xtalmgr needs the environment variable XTALVIEWHOME and CRYSTALDATA. It sets the variables PWD and CRYSTAL as it operates.

Main Window


Quits after asking if that's what you really want.


The name/title/label of the current project is listed here. This is followed by an Edit button that pops up the Project Edit window. A pull-down setting button is at the end of the line that lets you set the current project from the list of all defined projects.


The current crystal. Use the Edit button to edit the crystal database file. Use the pull-down setting button to set the crystal from the list of defined crystals.


The current directory. Entering <CR> will change to that directory and update the file listings.


A pull-down menu that contains all the window-based applications available. Setting one of these updates the command line and the file filters. If a filename can be added on the command line, the appropriate filter will be set and all the files matching it will be listed. If no file argument is needed, then the filter is left blank and no files are listed.


These are non-window-based programs that can be used as filters and to provide some functions not available in the window-based applications. All the options should be specified on the command line as no other method is provided for entering data.


The current command line is displayed here. xtalview applications are set up so that the command arguments are almost always optional filenames for the input[s] and output. It follows all the usual UNIX conventions. To generate the command line, do the following:

  1. Select an application.
  2. Select input and output arguments.
  3. Press Add Args.
  4. Press Run Command.
The command can also be set by picking a line in the history window.

List Files

Push this button to list all the files in the current directory using the file filters.

Auto Name Output

Push this button to have the program make up a name for the output file based on the input arguments. If one input argument is specified, the name is made by substituting the default extension for the output with the input. If two have been specified, the name is made by concatenating the two input files sans extension and adding the output extension.

Add Args

This adds the arguments to the command line by concatenating to the end and adding a semi-colon.

Run Command

This causes the command line to be sent to the operating system and executed. Errors will be output in the original window used to start xtalmgr.


This pops up the History window, which is a scrolling list of commands previously entered. If one is selected, it will be placed on the command line for editing/rerunning.

Input Argument 1

The current value of the first input argument. You can set this by selecting a filename in the list below it.

Input Argument 2

The current value of the second input argument. You can set this by selecting a filename in the list below it. If more than two input arguments are desired, you can type them here or directly on the command line.

Output Argument

The current value of the output argument. You can set this by selecting a filename in the list below it.


This is the filter that will be used in listing the files in the scrolling list below. To list all files, set this to "*." The filters are set automatically when an application is chosen.

Project Editor Pop-up


This is an arbitrary name useful to you in identifying a project.


The name of the directory where this project will live.


The default crystal for this project. This can be changed later if more than one crystal is being used in a single project.


This button replaces the current project with the information in the Edit window.


This creates a new project and adds it to the list.


The current project is deleted from the list. There is no undo.

Note: The project list is recorded to disk after all operations so that if xtalmgr should stop suddenly, or if the system crashes, the list will be current upon restarting xtalmgr.

Crystal Editor popup


The current name of the crystal. This is used as a filename and so cannot contain a space, MUST NOT begin with a "-" and shouldn't contain special characters such as ><,:;][{}()&*$|?~.


A title for this crystal that makes sense to you, such as "e. coli. miraclease E.C. P212121 form" or something equally imaginative and informative. This is used for your information only.

Unit Cell

Six floats describing the unit cell in Ångstroms and degrees. The order is a,b,c,alpha,beta,gamma. No assumptions are made; enter all six values. A note on accuracy: Whatever accuracy you enter here will be preserved. Although later applications will only report the cell to hundredths accuracy, they will actually use the accuracy entered here.

Space group

The name of the space group is entered here. If <CR> is entered on this line, a search through the database of all 230 spacegroups is made. The name should then be in lower case and subscripts should be entered as simple numbers; i.e., P212121 would be entered as p212121. If the search is successful, then the symmetry operators will be updated.

Space Group#

This is used to search for a space group based on the entry number in the International Tables for Crystallography. All 230 spacegroups are in a table. If you enter a value with the keyboard, be sure to press <CR> to enter it.

Find Space Group by Number

Press this button when the Space Group # field is set to find the symmetry operators and name for this space group.


The symmetry operators are listed here. It is recommended that you use search by number or name to enter this line for the sake of accuracy and formatting. The format is each symmop in lower case, as listed in the International Tables for Crystallography, separated by semi-colons and ending with a period (i.e., x,y,z; -x,y,-z.). The unitary operator x,y,z is always included.

Other Fields

These are fields that are used for special purposes. You can enter information for your own use that can be accessed by linking xtalview library routines with your program. Each field is a keyword followed by data. See Chapter 4, "Programming XtalView," for further information.


The keyword for this field.


The data for this line. There cannot be a new-line character in the line or it will be split into two lines when written out.

Replace Field

This replaces the selected line in the scrolling list with the data in the keyword and data fields.

Create Field

A new line is appended to the scrolling list.

Delete Field

You will never be bothered by the selected line again. There probably is little reason to use this, as old fields never hurt. (The first field encountered with the correct keyword is used to extract the data in question; if a field with the same keyword occurs later, it will be ignored.)

Scrolling List

This is the list of all of the records that don't match the special ones above (title, unit cell, space group, symmetries). Selecting one with the mouse puts its information into the keyword and data fields.

Update This Crystal

All the information in the window is written into the crystal file named in crystal. If the crystal file does not currently exist, it is created.


Three files are used to store information for xtalmgr. The data on applications are stored in $XTALVIEWHOME/data/applications. It is not meant to be user-edited. New applications are installed by entering in this file in a special format. The project data is stored in the file $CRYSTALDATA/projects. It can be edited using the project editor window, but in times of crises or for reordering the lines it can be edited. The first lines give a description of the file format. Crystal information is kept in the file $CRYSTALDATA/crystals. It is a simple list of crystal filenames. All the filenames should actually exist in $CRYSTALDATA. The only way to delete a crystal from the list is with an editor.



xtalview (XtalView) is a suite of programs for solving macromolecular crystal structures.


XtalView is a complete package for solving a macromolecular crystal structure by isomorphous replacement, including building the molecular model. It runs on Sun, DEC, and SGI computers and takes full advantage of the modern workstation environment. It has a simple but comprehensive windows based interface. XtalView maintains log files of the computations done. Standard file formats are used, which facilitates communication between XtalView and programs such as X-PLOR, TNT, and MERLOT.

XtalView is described in the book Practical Protein Crystallography, by Duncan McRee, who also designed the program.

XtalView is free for non-profit use. For-profit users should contact Duncan McRee ( concerning licensing. A binary distribution is available through CCMS' e-mail responder; source code is also available, but requires a signed license.

To receive information on obtaining XtalView software, send e-mail to, leave the SUBJECT line blank, and type get xtalview in the message.

For technical support, or any other questions, send e-mail to ccms-help at sdsc dot edu.

Setting Up the XtalView Environment

To set up your XtalView environment, follow these steps.

  1. Copy the XtalView.env file to your home directory. This file is located in the top directory of the XtalView distribution. Contact you system administrator if you don't know where XtalView is installed.

  2. Edit the XtalView.env file as follows:

    Set the XTALVIEWHOME environment variable to the location of the XtalView distribution. Make sure you use the full path name to the directory.

    Set the CRYSTALDATA environment variable to the directory where your crystal data is (or will be) located. Again, make sure you use the full path name. If this directory does not already exist, you must create it before you can use XtalView.

    Set the CRYSTAL environment variable to the name of your default crystal.

  3. Put the line source ~/XtalView.env in your .cshrc file to execute the commands in the XtalView.env file.

    XtalView requires fonts that may not be installed on non-Sun machines. These fonts are included in the XtalView distribution (in the directory $XTALVIEWHOME/fonts), but the procedure to make use of them depends on how you will be running XtalView.

    If you are running XtalView locally (i.e., not over a network):

    Execute the command $XTALVIEWHOME/bin/share/fonts. You only need to do this once each time you log in to your workstation.

    Note: the XtalView.env file must be sourced before this will work.

    If you are running XtalView remotely and the machine-independent part of the XtalView distribution is available on your local workstation:

    Before you log onto the remote machine, execute the command $XTALVIEWHOME/bin/share/fonts. You only need to do this once each time you log onto the local workstation.

    Note: The XtalView.env file must be sourced before this will work.

    If the machine-independent part of the XtalView distribution is not available on your local workstation and your local machine is a UNIX workstation:

    Copy the $XTALVIEWHOME/fonts directory and the script $XTALVIEWHOME/bin/share/fonts to the local machine. Set the XBIN and XTALVIEWFONTSDIR variables in the fonts script to the directories that hold the standard X binaries (e.g. /usr/bin/X11) and the XtalView fonts, respectively. Execute the fonts script. You only need to execute the edited script once each time you log onto the local workstation.

    If your local machine is not a UNIX workstation (e.g., it's an X terminal):

    Consult your system's documentation for information on setting up the font path. You must add the $XTALVIEWHOME/fonts directories to the font path and move any 100dpi directories to the end of the font path.

    The XtalView package is now ready for use. You can access the XtalView programs through the xtalmgr program or you can run them individually (see xtalmgr(1)).


Silicon Graphics users should read the file $XTALVIEWHOME/make_sgi4dIRIX4/README for additional instructions.


colorbyb(1), cvtpdb(1), cvtvu(1), cvtxyz(1), deh(1),deriv(1), dumpphasit(1), grinchbones(1), matrices(1),mu2fin(1), resflt(1), stfact(1), urf2xfit(1), xcontur(1),xdf(1), xedh(1), xfft(1), xfit(1), xheavy(1), xhercules(1), xmerge(1), xmergephs(1), xpatpred(1), xplortophs(1), xprepfin(1),xresflt(1), xrspace(1), xtalmgr(1)

next up previous contents
Visit our: CCMS Home Page
Send us your comments on this user guide: CCMS Comment Form
Next: NonWindow-based Applications
Up: Table of Contents
Previous: Chapter 5-2 Window-based Applications

XtalView User Guide