Crystallographic Fortran 90 Modules Library (CrysFML): a simple toolbox for crystallographic computing programs.

Juan Rodríguez-Carvajal¹ and Javier González-Platas²

(1) Laboratoire Léon Brillouin (CEA-CNRS), CEA/Saclay, 91191 Gif sur Yvette Cedex, France, E-mail: juan@llb.saclay.cea.fr - WWW: http://www-llb.cea.fr/fullweb/powder.htm and (2) Departamento de Física Fundamental II, Universidad de la Laguna, Tenerife, Spain, E-mail: jplatas@ull.es

Abstract

We describe in this paper a short introduction to the Crystallographic Fortran Modules Library (CrysFML). This set of modules has been, and is still being developed, by us to facilitate the design an the elaboration of crystallographic computing programs. The whole library is written in a subset of Fortran 95 (F-language) for which free compilers are available. The source code is available to those academic groups interested in cooperative scientific software development.

Introduction

There is presently a huge amount of academic crystallographic programs that are available to the scientific community through the CCP4 and CCP14 web sites [1]. The programs are distributed mainly in the form of executable codes. Source codes are not distributed in many cases. We are aware of only two general sets of computing procedures that are freely distributed and are similar to the system described in this paper. The first is the Cambridge Crystallographic Subroutines Library (CCSL) that has been developed mostly by P.J. Brown and J.C. Matthewman with contributions, mainly for powder diffraction, of W.I.F. David, J.B. Forsyth, J.H. Matthewman and J.P. Wright [2]. The second, Computational Crystallography Toolbox (cctbx), by R.W. Grosse-Kunstleve et al. [3] is quite recent and several publications have appeared in Journal of Applied Crystallography (see [3] and references therein).

To our knowledge CCSL is presently the most complete set of crystallographic procedures that are freely available. CCSL is written mostly in Fortran 77, but the style of programming is still quite close to old Fortran 66. Many manipulations of array procedures written in CCSL are now obsolete if one uses the modern Fortran 90/95 language. The same is true for some machine dependent procedures that are implemented in CCSL. There are several main programs based in CCSL that are mostly used by the neutron crystallographic community. As we will see below the aim of CCSL is similar to ours. CCSL was developed in order to facilitate the development of crystallographic computing programs by the users of special diffraction techniques (polarized neutrons, for instance). The main drawback of CCSL, if one looks from one the modern programming paradigms (structured or object oriented programming), is the lack of modularity and the excessive intricacy of the procedures. The use of common blocks and equivalence statements is the way of communicating global variables between independent subroutines and functions.

The case of cctbx is in some sense the opposite extreme. There are still many useful procedures for crystallographic computing that need to be developed, but the whole library is written following the object oriented programming (OOP) paradigm. The programming language is C++. We have no experience using this toolbox, so we cannot make positive or negative statements about it.

We will not discussed in this paper the advantages and drawbacks of the different programming languages, but we have to say that seven years ago we were faced to the alternative between Fortran 90 and C++ in order to continue the development of several computing programs. After a period of hesitation and trials we decided clearly to work in Fortran 90 for the following reasons:

1. Simplicity and clarity of the syntax and the new facilities for global array manipulation. This is important for the common scientist that may write programs occasionally. This makes programming in Fortran more natural and problem solving oriented.
2. Availability of many OOP techniques in modern Fortran: user-defined types, encapsulation, overload of procedures and functions. We consider the lacking features (e.g. inheritance and class methods) of less importance for scientific computing than those already available. In any case these lacking features will be easily implemented (simplifying the code) as soon as they become available in the forthcoming new standard Fortran 200x (see reference [4]).
3. The powerful implicit interface provided by encapsulating all functions and subroutines in modules, allowing to catch many errors at compile time, if one uses the intent attribute for procedure arguments. We may consider that Module Oriented Programming (MOP) as an alternative/complement to OOP.
4. Efficiency of the generated executable codes compared to C++ programs of similar complexity.
5. Compatibility with legacy code and availability of a huge amount of free mathematical subroutines and functions. The criticism of many people fanatic of the OOP paradigm about the lack of re-usability of procedures written by following the structured programming paradigm is clearly not adequate. The major parts of mathematical software systems (LAPACK for instance) that are still in use, and in the kernel of many well-known packages, are written in Fortran 77.

One of us (JRC) started many years ago to work with CCSL and realized that it was more easy to re-design progressively a new library using Fortran 90 to encapsulate similar procedures in modules than to modify the whole CCSL. We have then developed a set of Fortran 95 modules, Crystallographic Fortran Modules Library (CrysFML), which may be used (in the Fortran 95 sense) in crystallographic and diffraction computing programs. The scope of the new library is identical to that of CCSL, except that, at present, it is not so complete as it is CCSL. Modern array syntax and new features of Fortran 95 are used through the modules. We take advantage of all OOP techniques already available in Fortran and we have used, in our practice, a subset of Fortran 95 called F for which free compilers are available for most of the current operating systems [5]. We aim to preserve the efficiency, the simplicity and the adequacy of modern Fortran for numerical calculations. CrysFML has never been communicated to the scientific community but a preliminary account was presented in a poster [6] and a short talk in the computer fayre at the last International Union of Crystallography meeting in Geneva. The present status of CrysFML will be summarized in this paper.

Structure of CrysFML

The present CrysFML contains procedures for reading files of many different formats, string utilities for handling the reading in interpreted free format, generation and reading of CIF files, mathematical modules, modules for generating space groups from their Hermann-Mauguin or Hall symbols for whatever setting. More generic space groups with non-conventional lattice centring vectors can also be built using user-defined generators. Reflection handling modules may be used for generating reflections in selected regions of reciprocal space and for calculating structure factors, etc.

The documentation is written within the source code using special comment symbols and rules. A document, in HTML format, containing the description of all modules and procedures can be generated using the program get_doc based itself on CrysFML. An example of the generated document is seen in Figure 1.

Figure 1: Starting page of the documentation written automatically in HTML by a Fortran program that gets the information from the source code comments.

As an example of the style used to write the modules we give in Figure 2 a part of the source code constituting the starting lines of the module Crystallographic_Symmetry. One can see easily how the dependencies and accessibility of the different procedures and variables within a module are defined.

Figure 2: Header of the module Crystallographic_Symmetry, showing the modules it uses and all the public types and procedures available to other modules using it.

The structure of CrysFML is quite simple:

1. On top of the hierarchy there are generic mathematical modules (e.g. Math_gen, Math_3D, Random_Gener, FFT_Harm, FFT_Gen, Optimization_LSQ, Optimization_SAN…) that may be used by other more specialized modules.
2. Other highly generic modules are concerned with the manipulation of string characters. In particular the module String_Utilities and the module Free_Format_Reading are quite useful for the use indicated by their own names.
3. A small module defining the way the messages are passed to the screen or windows, IO_messages, with generic subroutines that adopt different aspects depending on the use or not of third party graphical libraries.
4. Chemical and scattering data modules.
5. Modules related with symmetry: Symmetry_tables and Crystallographic_Symmetry
6. Crystallographic modules: Crystal_types, Reflection_utilities, Atoms_Modules, Structure_Factors, Propagation_vectors, etc.
7. Specialized modules: Peak_Shapes, IO_Formats, etc.
8. Candidates: a set of modules that are being considered to form part of the library in future developments after debugging.

In spite of the internal dependencies of modules in CrysFML, the user is not obliged to use all the modules, or even to create a unique library. There are many standalone modules. One can easily take modules for a particular purpose and disregard the remaining modules.

Making programs using CrysFML

Let us discuss two simple examples of programs of general crystallographic interest using the module Crystallographic_Symmetry and the module Reflection_utilities. First of all the user should be aware of the existence in CrysFML of the Fortran type called Space_Group_Type, which is the most important defined type in symmetry modules. The definition is given in Figure 3.

Figure 3 : Generic space group type. One can define arrays of space groups and work globally with the user defined symbols derived from Space_Group_Type.

From the large number of procedures existing in Crystallographic_Symmetry one of the most useful is the subroutine Set_Spacegroup. Apart from the simplest cases described in the caption of Figure 4, one may call the subroutine providing user-defined generators in the array of strings gen. One can make a call to the subroutine as follows:

! Declarations omitted

Ngen=3

Gen(1)="y,-x, z"

Gen(2)="-x,-y,-z"

Gen(3)="x+1/2, y+1/2, -z"

Call Set_Spacegroup(Spacegen,Spacegroup,Gen,Ngen,"GEN"

On output the object Spacegroup of type Space_Group_type is filled with all possible information obtained from the list of given generators.

Figure 4: Header of the subroutine Set_Spacegroup. Only two arguments are needed in the most simple cases. The string SpaceGen may contain the Hermann-Mauguin (H-M) symbol, the Hall symbol or simply the number of the space group. The object Spacegroup is provided by a call to the subroutine.

An example of a simple program that gives as output the information contained in the object Spacegroup is given in Figure 5. The program uses the module Crystallographic_Symmetry, but only three public procedures. In the declaration part it is defined the string spg_symb that may contain the number of the space group, the H-M or the Hall symbol. The object SPG will hold all the information concerning the space group. The program has an infinite loop in which it is asked to enter a space group, if nothing is given (pressing the "enter" key) the program exits from the loop and stops.

Figure 5: Code of a program calling symmetry procedures of CrysFML.

The argument full in procedure write_spaceg means that all detailed information in asked to be output in the screen. One may change the instruction to write directly to an already opened file. For instance writing:

Call write_spaceg(SPG,iunit=3,full=.true.)

directs the output to the file connected with logical unit 3. An example of the output of the above simple program is given is figure 6. The answer to the question asked by the program was "15" (without quotes). It may be noticed that all the important information is output. Not only the alphanumeric form of the symmetry operators is given but also the symmetry symbol (kind of symmetry element: axis, plane, … and its localisation in the space) associated with the operator. To get this symbol, an internal call to the subroutine Symmetry_Symbol (deriving the symmetry symbol from the symmetry operator) is performed in write_spaceg when the argument full is present. The output of the Wyckoff positions is only possible, at present, when the space group is in one of the standard settings. It is not possible to derive algorithmically the order of Wyckoff positions as it is given in the International Tables of Crystallography. For that reason the corresponding information for the standard setting is described within the module Symmetry_Tables.

Figure 6: Example of output of the program in Figure 5.

This example shows how simple is to write a useful non-trivial program by using CrysFML.

Let us consider another example. Suppose that we want to write a procedure to list all possible space groups compatible this a list of "observed" reflections obtained from a Le Bail fit of a powder diffraction pattern. It is quite easy to see how to do that by reading the code in Figure 7.

Figure 7: Program providing a list of all the possible space groups that are compatible with a set of "observed" reflections.

Part of the program has been omitted for simplicity and to save space. The code is sufficiently clear to understand the procedure. The important points are:

1. Read hkl in the array hkl(:,:), intensity, sigma, Bragg angle and fwhm
2. Establish a criterion for consider reflections good for checking taking into account the possible overlap and a threshold in intensity. The integer array good(:) has a component equal to zero if the corresponding reflection is not good for checking.
3. After making use of the module symmetry_tables set up the array spgr_info, which has components of type spgr_info_type: structure containing the number of the space group, the H-M and Hall symbols and additional information to obtain the asymmetric unit in real space.
4. Tell to the program if centred space groups have to be checked (logical variable check_cent) and set the indices to check in the loop over space groups. These indices depend on the crystal system and are available from the symmetry_tables module.
5. Use the logical function HKL_absent from Reflection_Utilities, to test the possible groups.

The code above is a minimal test. If needed, one can refine the procedure and generate a hierarchy of space groups and figures of merit.

Computing programs currently using CrysFML

All multipattern versions of FullProf are based on CrysFML. The source code of FullProf was re-written completely during 1997, and progressively its dependency on CrysFML has increased.

Other public programs using CrysFML are FOURIER, GFOURIER and EdPCR. These programs work on Windows and Linux and are already distributed via the LLB Web site. The first two programs are dedicated to i) the Fourier analysis of diffraction data and ii) EdPCR, a new (still under development) Graphic User Interface (GUI) to the FullProf input control file (.PCR extension).

A number of other programs are also based on CrysFML but are not yet distributed publicly in the scientific community but strongly used by people working in collaboration within our group at LLB, ILL, PSI and several Universities and National Laboratories in European Countries. A non-exhaustive list is the following:

BASIREPS: Program for calculating basis functions of irreducible representations of space groups. This program is useful for determining magnetic structures and phonon symmetry analysis. BASIREPS is presently distributed together with EdPCR.

SIMBO: Program for the analysis of the magnetic topology of an arbitrary crystal structure. Generates a formal description of the Fourier transform of the exchange interactions to be used by other programs and a file to be used by the MonteCarlo code MCMAG.

ENERMAG: Program to analyse the classical magnetic energy as a function of the exchange interactions and the point in the Brillouin Zone. It uses one of the output files of SIMBO. This program can be used to generate theoretical magnetic phase diagrams in the J-space in order to get insight into the experimentally determined magnetic structures.

SIMILAR: Program to convert settings for describing a crystallographic structure. It determines automatically the splitting of Wyckoff positions on going from a space group to one of their subgroups. Calculates subgroups of a space group, co-set decompositions, etc.

DATARED: Program for data reduction of single crystal data. It handles twinning and incommensurate magnetic and crystal structures. At present it can read data provided by several integration programs, in particular several versions of COLL5 (LLB and ILL). Prepares files to be read by FullProf when using single crystals.

Current tasks and conclusions

We hope to have demonstrated in this short and biased document the usefulness of CrysFML for rapidly writing crystallographic programs. We still have more work to do to improve the library and to increates its capabilities. Some of the remaining tasks that concern the development of CrysFML are the following:

Complete the documentation of the existing modules and make a PDF version of the manual.

Continue development of the library, implementing more modules.

Prepare a Web site for CrysFML with a protocol for downloading the library.

We expect, after putting the CrysFML in a public Web site to increase the number of informal participants on the project. For reasons related to our schedule we cannot guarantee a date for the public availability of CrysFML. In the meantime, if somebody wishes to obtain the library, send an E-mail to juan@llb.saclay.cea.fr.

References

[1] The sites of CCP4, dedicated mainly to macromolecular crystallography, and CCP14 are respectively: http://www.ccp4.ac.uk/ and http://www.ccp14.ac.uk/.

[2] P.J. Brown and J.C. Matthewman, CCSL: http://www.ill.fr/dif/ccsl/html/ccsldoc.html

[3] R.W. Grosse-Kunstleve et al., J. Appl. Cryst. 35, 126 (2002)

[4] John Reid, WG5 Convener, The new features of Fortran 2000, PDF document available directly from the Internet: ftp://ftp.nag.co.uk/sc22wg5/N1451-N1500/N1495.pdf.

[5] All free F-compilers can be downloaded from the site: ftp://ftp.swcp.com/pub/walt/F

See also http://www.fortran.com/F/compilers.html

[6] J. Rodríguez-Carvajal and J. González-Platas, Acta Cryst. A58 (Supplement), C87.

---

These pages are maintained by the Commission Last updated: 15 Oct 2021