Tables for
Volume F
Crystallography of biological macromolecules
Edited by E. Arnold, D. M. Himmel and M. G. Rossmann

International Tables for Crystallography (2012). Vol. F, ch. 18.6, pp. 515-516   | 1 | 2 |

Section 18.6.6. Modules and procedures

A. T. Brunger,a* P. D. Adams,b W. L. DeLano,c P. Gros,d R. W. Grosse-Kunstleve,b J.-S. Jiang,e N. S. Pannu,f R. J. Read,g L. M. Riceh and T. Simonsoni

aHoward Hughes Medical Institute, and Departments of Molecular and Cellular Physiology, Neurology and Neurological Sciences, and Stanford Synchrotron Radiation Laboratory (SSRL), Stanford University, 1201 Welch Road, MSLS P210, Stanford, CA 94305, USA,bThe Howard Hughes Medical Institute and Department of Molecular Biophysics and Biochemistry, Yale University, New Haven, CT 06511, USA,cGraduate Group in Biophysics, Box 0448, University of California, San Francisco, CA 94143, USA,dCrystal and Structural Chemistry, Bijvoet Center for Biomolecular Research, Utrecht University, Padualaan 8, 3584 CH Utrecht, The Netherlands,eProtein Data Bank, Biology Department, Brookhaven National Laboratory, Upton, NY 11973–5000, USA,fDepartment of Mathematical Sciences, University of Alberta, Edmonton, Alberta, Canada T6G 2G1,gDepartment of Haematology, University of Cambridge, Wellcome Trust Centre for Molecular Mechanisms in Disease, CIMR, Wellcome Trust/MRC Building, Hills Road, Cambridge CB2 2XY, England,hDepartment of Molecular Biophysics and Biochemistry, Yale University, New Haven, CT 06511, USA, and iLaboratoire de Biologie Structurale (CNRS), IGBMC, 1 rue Laurent Fries, 67404 Illkirch (CU de Strasbourg), France
Correspondence e-mail:

18.6.6. Modules and procedures

| top | pdf |

Modules exist as separate files and contain collections of CNS commands related to a particular task. In contrast, procedures can be defined and invoked from within any file. Modules and procedures share a similar parameter-passing mechanism for both input and output. Modules and procedures make it possible to write programs in the CNS language in a manner similar to that of a computing language, such as Fortran or C. CNS modules and procedures have defined sets of input (and output) parameters that are passed into them (or returned) when they are invoked. This enables long collections of CNS language statements to be broken down into modules for greater clarity of the underlying algorithm.

Parameters passed into a module or procedure inherit the scope of the calling task file or module, and thus they exhibit a behaviour analogous to most computing languages. Symbols defined within a module or procedure are purely local variables.

The following example shows how the unit-cell parameters defined above (Fig.[link] are passed into a module named `compute_unit_cell_volume' (Fig.[link], which computes the volume of the unit cell from the crystal lattice parameters using well established formulae (Stout & Jensen, 1989[link]): [\tt\eqalignno{ \hbox{@compute\_unit\_cell\_volume } &\hbox{(cell} = \&\hbox{crystal\_lattice.unit\_cell\semi} &\cr &\quad \hbox{volume} =\$\hbox{cell\_volume\semi)} &\cr&&\rm{(}}]The parameter `volume' is equated to the symbol [`\$\hbox{cell}\_\hbox{volume'}] upon invocation in order to return the result (the unit-cell volume) from this module. Note that the use of compound parameters to define the crystal lattice parameters (Fig.[link] provides a convenient way to pass all required information into the module by referring to the base name of the compound parameter (`&crystal_lattice.unit_cell') instead of having to specify each individual data element.


Figure | top | pdf |

Use of compound parameters within a module. This module computes the unit-cell volume (Stout & Jensen, 1989[link]) from the unit-cell geometry. Input and output parameter base names are in bold. Local symbols, such as cabg.1, are defined through `evaluate' statements. The result is stored in the parameter `&volume' which is passed to the invoking task file or module.

Fig.[link] shows another example of a CNS module: the module named [`\hbox{phase}\_\hbox{distribution'}] computes phase probability distributions using the Hendrickson & Lattman formalism (Hendrickson & Lattman, 1970[link]; Hendrickson, 1979[link]; Blundell & Johnson, 1976[link]). An example for invoking the module is shown in Fig.[link]. This module could be called from task files that need access to isomorphous phase probability distributions. It would be straightforward to change the module in order to compute different expressions for the phase probability distributions.


Figure | top | pdf |

Example of (a) a CNS module and (b) the corresponding module invocation. Input and output parameters are in bold. The module invocation is performed by specifying the `@' character, followed by the name of the module file and the module parameter substitutions. The ampersand (&) indicates that the particular symbol (e.g. `&fp') is substituted with the specified value in the invocation statement [e.g. `fobs' in the case of `&fp' in (b)]. The module parameter substitution is performed literally, and any string of characters between the equal sign and the semicolon will be substituted.

A large number of additional modules are available for crystallographic phasing and refinement. CNS library modules include space-group information, Gaussian atomic form factors, anomalous-scattering components, and molecular parameter and topology databases.


Blundell, T. L. & Johnson, L. N. (1976). Protein Crystallography, pp. 375–377. London: Academic Press.
Hendrickson, W. A. (1979). Phase information from anomalous-scattering measurements. Acta Cryst. A35, 245–247.
Hendrickson, W. A. & Lattman, E. E. (1970). Representation of phase probability distributions for simplified combination of independent phase information. Acta Cryst. B26, 136–143.
Stout, G. H. & Jensen, L. H. (1989). X-ray Structure Determination, p. 33. New York: Wiley Interscience.

to end of page
to top of page