CCP4 Suite (CCP4: Basic)


ccp4 - introduction to the CCP4 Program Suite


program [ -n ] [ -v level ] [ -d file ] [ -e file ] [ -i ] [ -nohtml ] [ -nosummary ] [ <logical name> <file name> ... ]


program is the name of the CCP4 program being run. This documentation outlines the general concepts common to running most CCP4 programs. For specific details of how to run individual programs you are referred to the specific documentation for those programs.

The contents of this documentation are:

Specifying input and output files

When running CCP4 programs, input and output data files are normally specified by associating the file names with the logical names. Logical names are alphanumeric, and can include underscores.

The usual format of a program invocation is

<program name> [ <logical name> <file name> ] ...

where "< >" indicates placeholders and "[ ]" indicates optional repeated items i.e. zero or more occurrences (here and elsewhere in the documentation).

A concrete example is

fft hklin native-Fs.mtz mapout

File extensions are optional and if omitted default values will be used. Some common logical names with default extensions are

HKLINinput MTZ reflection file (.mtz)
HLKOUToutput MTZ reflection file (.mtz)
MAPINinput map file (.map)
MAPOUToutput map file (.map)
XYZINinput coordinate file (.pdb)
XYZOUToutput coordinate file (.pdb)

In some cases more than one file corresponding to the same type of entry in $CINCL/default.def is required e.g., several input reflection files. In this case they are typically specified as HKLINn, for instance, where n is a sequence number. The rules for matching logical names with the default specifications given above then apply to the prefix of the name which matches the entries in the files $CINCL/environ.def and $CINCL/default.def.

(For information on default.def and environ.def, see the section on details of logical name processing.)

Input files that do not exist are reported and the program stops processing. Output files that already exist will also cause the program to stop unless the environment variable CCP4_OPEN is set to `UNKNOWN', when they will be truncated to zero, overwritten and a warning message displayed.

Some file extensions are also treated as special cases and if you use them then you may experience unexpected behaviour - see the section on warnings.

Keyworded input

Most CCP4 programs take `keyworded' input to set their parameters.

These have a leading keyword followed, possibly, by arguments which might be numbers or strings or keyword/value pairs of the form


Such arguments are separated by spaces, tabs, commas or `=' characters. The details of the input expected is given in the documentation for each program, however there are some general rules:

Command line options

Do not read the global files default.def and environ.def.
-v level
Verbose output; the amount depends on the value of level, which may have a value between 0 and 9, higher values giving more information. This mainly affects output from the CCP4 library routines. The Logical_name / File_name assignments are displayed as they are processed along with other debug information. The default value is 1. Choose 0 if you want to suppress some output, or 2 or higher if you want extra output.
-d file
Use the next argument to specify an alternative to the default.def file.
-e file
Use the next argument to specify an alternative to the environ.def file.
Print CCP4 library version, program name and program version to standard output, and exit.
Suppresses the writing of HTML tags in the program output. This is an alternative to setting the CCP_SUPPRESS_HTML environment variable.
Suppresses the writing of summary tags in the program output. This is an alternative to setting the CCP_SUPPRESS_SUMMARY environment variable.

Appendix: Details of logical name processing

[The gory details in this section can be skipped by casual users.]

The programs normally read two initialisation files (held in the directory pointed to by environment variable CINCL):

These steps are performed by the CCP4 preprocessor functions CCPFYP and ccp4fyp (for Fortran and C programs respectively). For more information on these, see the documentation for CCPLIB.


f2mtz hklin xylose.hkl hklout xylose.mtz <<EOF
LABOUT H   K  L   F  SIGF   FreeRflag 
CTYPE  H   H  H   F  Q      X 

Alternatively, if the keywords are in the file keywords then it is possible to simply use:

f2mtz hklin xylose.hkl hklout xylose.mtz <keywords

See also the example scripts in the directory $CEXAM/unix/runnable.




Documentation for the program you want to run, via the index of programs.


If a file name ends in .lib, .bes , .prt or .dic and is not a full path name (i.e. with the full directory specified in front of the file name, such as ./ or /foo/bar.baz) then the environment variable $CLIBD will be prepended to the file name. This can cause files to be written in an unexpected directory.

A solution is to write (say) SYMOP ./my_symop.lib, or to use a different extension.

If a file name ends in .scr, and is not the full path name then the environment variable $CCP4_SCRATCH will be prepended to the file name. The extension scr will in all cases be replaced by the process number to give the file a (reasonably) distinct name.