Compute Canada

Crystal

Please note: The FAQ pages at the HPCVL website are continuously being revised. Some pages might pertain to an older configuration of the system. Please let us know if you encounter problems or inaccuracies, and we will correct the entries.

This is an introduction to the usage of Crystal 98, a programing package that performs ab-initio calculations of the Hartree-Fock or Kohn-Sham DFT type on periodic systems. This FAQ is meant to get users of the HPCVL SunFire 6800 cluster started in the usage of Crystal. It does not replace study of the manual.

What is Crystal?

Crystal 98 is a programming package that is able to perform ab-initio calculations on periodic systems. It can be used to perform such calculations for systems that are periodic in zero (molecules), one (polymers), two (slabs, surfaces), and three (crystals) dimensions. Crystal performs self-consistent field calculations using either a Hartree-Fock, or a Kohn-Sham one-particle model Hamiltonian. The calculations are performed in a basis set of Bloch (ie, fully delocalized) orbitals, which are in term built from local atom-centered Gaussian-type basis functions (GTO's).

Crystal makes full use of the crystal symmetry, ie, the space group of the system under consideration. This means that for 3D systems 230 space groups can be specified, for 2D systems, it is 80 layer groups, for 1 D systems, 99 rod groups, and for 0D systems the familiar 45 point groups.

It is furthermore possible to derive slabs or clusters from crystalline structures, and to introduce defects and distortions into a structure.

Crystal also includes a properties package that allows the computation of a variety of bulk properties that are relevant for solid-state research. These include:

  1. Charge and spin densities
  2. X-ray structure factors
  3. multipole expansions
  4. Electrostatic potentials, electric fields, EFG's
  5. Band structure, density of states
  6. DFT correlation and exchange energies
  7. Hyperfine electron/nuclear spin interaction (isotropic and anisotropic), Fermi contact terms
  8. Electron momentum distributions, Compton profiles, reciprocal form factors

For a complete list of capabilities of Crystal, consult the Crystal manual (.pdf). Crystal 98 (1.0) was produced by V.R. Saunders, R. Dovesi, C. Roetti, M. Caus€, N.M. Harrison, R. Orlando, and C. M. Zicovich-Wilson.

Where is the program located?

The program resides in /opt/crystal98. It is split up into four main parts named integrals, scf, scfdir and properties. In the /opt/crystal98/test_cases directory, you also find some test examples, which are useful to get an idea of the input format for the program. You are not allowed to copy the executable or any part of the distribution onto your local machine.

How do I set my account up for running Crystal?

No special setup is needed to run Crystal. It is advisable to make a symbolic link from the executables in /opt/crystal98/bin to a subdirectory that is in your PATH (eg, $HOME/bin). This saves the typing of the full directory path when calling Crystal, or the inclusion of the Crystal directory in your PATH.

How do I run Crystal?

Before you gain access to Crystal, you have to read the existing license agreement and sign a statement that you have done so (see last section ). Crystal is run in two or three steps by redirecting standard input to an input file, and standard output to a log file. It produces a series of additional output in files that correspond to Fortran units (ie, by default they are named fort.*. Caution needs to be exercised when submitting more than one Crystal job at the same time: the jobs have to be started in different directories to avoid that the output of one job overwrites the output of another. A Crystal run typically consists of three steps:

  1. Calculation of the necessary integrals: integrals < test.12 > test.out
  2. Self-consistent field calculation: scf >> test.out
  3. Properties calculation: properties < test.3 >> test.out

Two separate input files (in our example), test.12 and test.3 are required. The first specifies the system, symmetry and method to be used. The second lists the properties requested. The first two program calls to integrals and scf) may be replaced by a single call to scfdir:

scfdir < test.12 > test.out

This program calculates all required matrix elements on the fly whenever needed, and should be used if one is low on disk space and/or memory. However, this option will, of course, lead to considerably longer execution times.

It is important to remember to rename those fort.* files that are needed (for example, to calculate further properties using the wave function), and to delete the others. Failure to do so wastes disk space (some of those files are rather large), or leads to loss of results when the next calculation overwrites the files of the previous one.

As with other software on HPCVL machines, you are not allowed to run production jobs interactively. Rather, you have to submit them to a load-balancing software called GridEngine. For general information about this software, please refer to our GridEngine FAQ. The process of submission is very simple. You produce a small script file (let's call it "crystal.sh") that includes the above program calls and submit it with the following command:

qsub crystal.sh

The GridEngine will put your job into a queue and submit it when the required resources become available. In the script file, you will to give the name of the input and output, as well as the email address to which notification has to be sent. The script file should reside in the same directory as the input and output files, and it should be submitted from that directory to avoid problems.

Can I run Crystal in parallel?

Yes, Crystal offers the possibility to run in parallel employing the MPI (message passing interface). However, there are currently problems with our implementation. As a result, the usage of Crystal is restricted to sequential execution at this time. Please Check this FAQ later for an update.

Where can I get further information?

Crystal is not a simple program to run. The format of the input files is not very intuitive, and it is usually necessary to run a series of test jobs before "getting it right". The theory underlying Crystal is rather involved, and should be studied before using the program. The best introduction into the theoretical background is probably given in C. Pisani, R.Dovesi and C.Roetti, "Hartree-Fock ab-initio of crystalline systems" Lecture Notes in Chemistry, Vol. 48, Springer Verlag, Heidelberg, 1988.

It is pretty much impossible to use the program efficiently without reading the User's Manual, which is available here in PDF format. There is a Crystal homepage with information about the program, including its capabilities, reference to basis sets, literature and even an FAQ .

In the Crystal program, memory is allocated statically, which means that all arrays in the program are dimensioned at compile time. A a consequence, it is very well possible that a recompilation of the source code is necessary for larger compilations. The present compilation of Crystal is "standard size", which can handle 150 atoms, 700 atomic orbitals, and 300 shells per unit cell. Especially for highly symmetric compounds and large molecular crystals, these limitations can be felt very quickly. If you need a recompiled version of Crystal, please contact HPCVL. If you encounter problems with running Crystal (or other software on HPCVL machines), HPCVL offers user support. Since some of our support people are solid-state physicists and theoretical chemists, it is possible that we can even help you specifically with Crystal. If not, we can try to direct you to people who can.

Are there licensing issues with Crystal?

Yes. Crystal is a licensed program and cannot be copied freely. HPCVL holds a license for the software and academic users of HPCVL are allowed to use it on HPCVL machines only. The source code for Crystal is not accessible for the general user, and all alterations require the permission of the authors of the code. The code has to be referenced in publications. For details, please see the license agreement . As with all licensed software on HPCVL, people who want to use Crystal, will have to sign a statement that they have read and understood the license terms and will abide by them. Please download a copy of the license and of the statement , read the former, sign the latter, and submit it to us. You will then be included in a special Unix group that is able to access the software.