• Reading a Crystal Structure

    Loading a Crystal Structure (CRYSTAL)

    CRYSTAL file.cif [datablock.s]
CRYSTAL file.res
CRYSTAL file.ins
CRYSTAL file.16
CRYSTAL file.21
CRYSTAL file.dmain
CRYSTAL file.cube
CRYSTAL file.bincube
CRYSTAL file.struct
CRYSTAL [file.]{POSCAR,CONTCAR,vasp,CHGCAR,CHG,ELFCAR,AECCAR0,AECCAR1,AECCAR2} [at1.s at2.s ...|POTCAR]
CRYSTAL file_{DEN|PAWDEN|ELF|POT|VHA|VHXC|VXC|VCLMB|VPSP|GDEN1|GDEN2|GDEN3|LDEN|KDEN}
CRYSTAL file.OUT # (GEOMETRY.OUT, elk)
CRYSTAL file.out [istruct.i] # (file.scf.out, quantum espresso output)
CRYSTAL file.pwo [istruct.i]
CRYSTAL file.out # (file.out, crystal output)
CRYSTAL file.out # (file.out, FPLO output)
CRYSTAL file.in # (file.scf.in, quantum espresso input)
CRYSTAL file.pwi
CRYSTAL file.STRUCT_IN
CRYSTAL file.STRUCT_OUT
CRYSTAL file.gen
CRYSTAL file.xsf
CRYSTAL file.axsf [istruct.i [xnudge.r]]
CRYSTAL file.pwc
CRYSTAL file.{in,in.next_step} # (geometry.in, FHIaims input)
CRYSTAL file.{out,own} # (FHIaims output)
CRYSTAL file.frac
CRYSTAL file.cell
CRYSTAL file.geom
CRYSTAL [CIF|SHELX|21|CUBE|BINCUBE|WIEN|ABINIT|ELK|QE_IN|QE_OUT|CRYSTAL|XYZ|WFN|WFX|
         FCHK|MOLDEN|GAUSSIAN|SIESTA|FPLO|XSF|GEN|VASP|PWC|AXSF|DAT|PGOUT|ORCA|DMAIN|
         FHIAIMS_IN|FHIAIMS_OUT|FRAC|CELL|GEOM] ...
CRYSTAL
 SPG [hall.i|ita.i HM|spg.s]
 CELL a.r b.r c.r alpha.r beta.r gamma.r [ANG|ANGSTROM|BOHR|AU]
 CARTESIAN [scal.r]
   [BOHR/AU]
   [ANGSTROM/ANG]
   x1.r y1.r z1.r
   x2.r y2.r z2.r
   x3.r y3.r z3.r
 ENDCARTESIAN/END
 NEQ x.r y.r z.r at.s [ANG|ANGSTROM] [BOHR|AU]
 atom.s x.r y.r z.r [ANG|ANGSTROM] [BOHR/AU]
 atnumber.i x.r y.r z.r [ANG|ANGSTROM] [BOHR/AU]
 ...
 SYMM exprx.s, epxry.s, exprz.s
ENDCRYSTAL/END
CRYSTAL LIBRARY label.s

    The first line of a critic2 input usually specifies the structure. Critic2 can read a large number of crystal structure formats. In the simplest usage, critic2 reads one of the common file formats like, for instance, a cif file. This is done by using:

    CRYSTAL file.s

    The extension of file.s is used to determine the appropriate reading format.

    The MOLECULE keyword can be used as a replacement for CRYSTAL in the entries above. MOLECULE is used when the structure is a gas-phase molecule. For instance, cube files calculated with Gaussian (e.g. using cubegen) can be read by critic2.

    The default distance units in the rest of the input and in the output once CRYSTAL is used are atomic units (bohr). This behavior can be changed with the UNITS keyword. The output of the CRYSTAL keyword is explained here. A detailed list of the file formats understood by critic2 follows.

    Cube Files (cube, bincube)

    Gaussian cube files read using CRYSTAL are assumed to represent a periodic system. This format is used by Quantum ESPRESSO and other programs.

    Despite their name, cube files may be used to represent non-orthogonal cells, and have become a de facto standard. They can be written by a lot of popular solid-state programs, so it is a good choice if critic2 provides no native interface to the densities written in the native format of your program.

    Critic2 can be used to convert cube files to binary format in order to save disk space and reading/writing time. Binary cube files have extension .bincube, and contain essentially the same information as the usual cube file.

    WIEN2k (struct)

    The structure of a crystal in WIEN2k is written to a file with extension .struct. WIEN2k’s struct files may or may not contain the symmetry operations (for instance, if they have been generated by the web interface but not run).

    VASP (POSCAR, CONTCAR, vasp, CHGCAR, CHG, AECCAR*, ELFCAR)

    In VASP, the crystal structure can be read from a number of files, including the POSCAR (recommended), the CONTCAR, a file with .vasp extension, the CHGCAR, and others. Depending on the version, VASP’s POSCAR and CONTCAR (and also the rest) may be missing the atomic symbols. In that case, they need to be provided by hand after the file name, either using a list of atomic symbols or the location of the POTCAR. Files that contain the word POSCAR, CONTCAR, CHG, CHGCAR, AECCAR0, AECCAR1, AECCAR2, and ELFCAR are also accepted (e.g. nacl.POSCAR or POSCAR_nacl).

    Elk (OUT)

    In elk, the geometry is written to the GEOMETRY.OUT file. Any file with extension .OUT will be assumed to be in elk’s GEOMETRY.OUT format (even though it may not be called GEOMETRY.OUT). The atomic numbers are inferred from the name of the species file. The atomic names are the symbols for those atomic numbers, with an integer suffix that corresponds to the species file for that atom (first file = 1, second file = 2, and so on).

    Quantum ESPRESSO (scf.in, scf.out, pwi, pwo)

    In addition to reading Gaussian cube files generated by Quantum ESPRESSO, the outputs (extension .scf.out or .pwo) and inputs (.scf.in or .pwi) of pw.x are also understood by critic2. By default, the last geometry in the output file is read. If an optional istruct.i integer is given, then read the structure corresponding that number (only for geometry optimization jobs).

    For Quantum ESPRESSO inputs given as file.scf.in, only the .in extension is detected.

    Crystal (out)

    Crystal outputs are read if the file has the extension .out. Critic2 will automatically detect whether the file is a crystal or a Quantum ESPRESSO output (which has the same .out extension). Currently, only periodic crystals are supported (no SLAB, POLYMER or MOLECULE). In addition, this module has been tested for crystal06 and crystal14 only.

    CIF files (cif)

    CIF files are the standard format for crystal structures in the crystallography community. The standard is published by the International Union for Crystallography (the core CIF dictionary). In critic2, CIF files are read using the ciftbx library by Sydney R. Hall. If the CIF file provides the crystal symmetry, the symmetry operations are read and used.

    CIF files can contain multiple structures in “data blocks”. The specific data block to read from a multi-block cif file can be specified with the optional argument datablock.s. For instance, to read the data_shelx block, use datablock.s = shelx. If datablock.s is not present, then the first block is read.

    SHELX res and ins Files (res, ins, 16)

    RES and INS files are generated and used by SHELX (and derivatives), a program for the interpretation of experimental single-crystal X-ray and neutron diffraction data. The INS (input) and RES (output) file format specifications are almost identical, and follow the “Alphabetical list of SHELXL instructions” document on the SHELX website. The extension .16 corresponds to a fort.16 file generated by DMACRYS, which also uses the SHELX format.

    DMACRYS/NEIGHCRYS Files (16, 21, dmain)

    DMACRYS is a program for modeling molecular crystals using rigid molecules and distributed atomic multipoles. The fort.21 file generated by NEIGHCRYS, part of the DMACRYS package can be read by critic2. It contains the initial geometry. After geometry relaxation, DMACRYS generates a fort.16 file containing the final geometry, which can also be read by critic2. In addition, critic2 can also read the initial structure from the main input file, with extension .dmain.

    Abinit (DEN, PAWDEN, ELF, LDEN, etc.)

    Abinit density files (with suffix _DEN) and PAW valence density files (_PAWDEN) are binary files that, in addition to the electron density grid, contain the structural information for the crystal. In addition, other fields also generated by abinit (in the same format) can be read, including the electron localization function (prtelf, _ELF suffix), the Laplacian of the electron density, various potentials (_POT, _VHA, _VHXC, _VXC, _VCLMB, _VPSP), the kinetic energy density, and the components of the density gradient (_GDEN1, _GDEN2, and _GDEN3).

    SIESTA (STRUCT_IN and STRUCT_OUT)

    Critic2 can read the structure file generated by siesta has extension STRUCT_OUT. In addition, the STRUCT_IN file (which has the same format) is also understood by critic2.

    FPLO (out)

    The crystal structure can be read from the output of an FPLO calculation. The extension for an FPLO output understood by critic2 is .out.

    DFTB+ (gen)

    DFTB+ reads and generates structures in the gen format. The gen format can be read using the GenFormat driver in Geometry. It is also written during geometry optimizations using OutputPrefix in Driver. The gen format can be used for crystals (in which case it should contain the lattice vectors at the end of the file) or molecules.

    See the DFTB+ example for worked out cases.

    Xcrysden (xsf and axsf)

    Xcrysden generates scalar field files with extension .xsf, which also contain the crystal structure. If the xsf file contains a crystal structure, the PRIMVEC and PRIMCOORD cards are read - everything else is ignored.

    The .axsf file is an animation file for xcrysden. It is typically generated by the dynmat.x utility in Quantum ESPRESSO and it contains the crystal structure as well as the eigenvectors corresponding to all the phonon vibrations in the crystal at the selected q-point (usually, gamma). The axsf file contains one matrix of lattice vectors (PRIMVEC) and coordinate blocks (PRIMCOORD), where is the number of atoms. Each PRIMCOORD block contains the atomic positions (the same in all blocks) and the displacement associated to the phonon eigenvectors in increasing order of frequency. The optional parameter istruct.i gives which of these PRIMCOORD blocks will be read by critic2 (default: the first block). If xnudge.r is given, then displace the atomic positions by the phonon displacement vectors times xnudge.r, in bohr. This option is useful when following the eigenvector of a phonon with imaginary frequency.

    Quantum ESPRESSO Wavefunction (pwc)

    This file is generated by the pw2critic.x utility in the PP bundle of Quantum ESPRESSO. The .pwc file contains the structural information for the system as well as the k-point information and the converged Kohn-Sham states. It is mostly used in the calculation of delocalization indices in periodic solids.

    FHIaims Inputs and Outputs (in, in.next_step, out, own)

    Crystal (and molecular) structures can be loaded from an FHIaims “geometry.in” input file. Only the atom, atom_frac, and lattice_vector keywords are parsed and interpreted. If at least one lattice_vector is present, the system is assumed to be a crystal. Alternatively, you can also load the structure from the geometry.in.next_step file written by FHIaims during a geometry optimization.

    The crystal or molecular structure can also be loaded from an FHIaims output file, which is assumed to have a .out or .own extension. In the case of a geometry optimization, the last available geometry in the output file is read.

    TINKER frac Format (frac)

    Crystal structures can be given in TINKER frac format. The .frac file must contain the cell parameters in the second line. This “complete” .frac file can be generated from an incomplete .frac file (i.e. where the cell lengths and angles are in a separate .key file) using TINKER’s utility programs. The connectivity information is discarded by critic2 and recalculated from scratch.

    CASTEP Inputs and Outputs (cell, geom)

    Crystal geometries can be read from CASTEP input (.cell) files as well as from the outputs of a geometry optimization (.geom), from where the last structure is read. The system is always assumed to be a crystal.

    Files with Other Extensions

    If the crystal structure file you want to read does not have one of the above extensions but conforms to one of these formats, you can force critic2 to read the file using that particular format. To do this, you must follow the CRYSTAL keyword with another keyword specifying the required format. The allowed keywords are:

    • CUBE: a cube file.

    • BINCUBE: a binary cube file.

    • WIEN: a WIEN2k .struct file.

    • VASP: a VASP-style (POSCAR, CHGCAR, vasp,…) structure file.

    • ELK: a GEOMETRY.OUT file from elk.

    • QE_IN: a Quantum ESPRESSO input file.

    • QE_OUT: a Quantum ESPRESSO output file.

    • CRYSTAL: a crystal output file.

    • CIF: a cif file.

    • SHELX: a shelx-style file, typically with extension .res, .ins, or fort.16.

    • DMAIN: a DMACRYS input file.

    • 21: a DMACRYS fort.21 file.

    • ABINIT: an ABINIT-style file (DEN,…)

    • SIESTA: a SIESTA STRUCT_IN or STRUCT_OUT file.

    • FPLO: an FPLO output.

    • GEN: a DFTB+ gen file.

    • XSF: an xcrysden .xsf file.

    • AXSF: an xcrysden .axsf file.

    • PWC: a .pwc file.

    • FHIAIMS_IN: an FHIaims input file (geometry.in).

    • FHIAIMS_OUT: an FHIaims output file.

    • FRAC: a TINKER .frac file.

    • CELL: a CASTEP .cell file.

    • GEOM: a CASTEP .geom file.

    Manual Specification of the Crystal Structure (CRYSTAL Environment)

    The crystal structure can be specified by hand using the CRYSTAL environment. For instance, the input for magnesium oxide (rocksalt structure) would be:

    CRYSTAL
  SPG F m -3 m
  CELL 4.213 4.213 4.213 90 90 90 ANG
  Mg 0 . 0.  0.
  O  1/2 1/2 1/2
ENDCRYSTAL

    There are several relevant keywords in the CRYSTAL environment. A space group can be specified with the SPG keyword, in which case only the atoms in the asymmetric unit need to be given:

    SPG [hall.i|ita.i HM|spg.s]

    The SPG keyword used inside the crystal environment builds the complete set of symmetry operations in the crystal from the space group label or the space group number. The space group names known to critic2 correspond to those given in the International Tables for Crystallography vol. A, in the Hermann-Mauguin notation (spg.s). Alternatively, the numerical ID for the space group in the Hall notation (hall.i, from 1 to 530) or the ID for the group in the ITA notation (ita.i, Hermann-Mauguin, from 1 to 230) can be given. Using the ITA numerical ID of the group requires using the HM keyword after the number. The arguments to SPG are blank- and case-insensitive. Examples spg.s labels are F m -3 m, P b a 2, P 1 n 1, and P 63 m c. When the SPG keyword is used, only the atoms in the asymmetric unit need to be given.

    The complete list of space groups available to critic2 can be retrieved using the SPG keyword outside the CRYSTAL environment. This list, along with example crystals, can also be found in the space group crystal collection. This is useful when there is a choice of origin to be made for a particular space group or if a non-standard setting is needed or in the case of rhombohedral groups for choosing the hexagonal or rhombohedral axes.

    If no SPG keyword is found in the CRYSTAL environment, then an internal routine calculates the symmetry from the atomic positions. (This behavior can be deactivated with the NOSYMM/NOSYM keyword.) In this case, all the atoms in the cell need to be given (in contrast to using SPG, in which case only the asymmetric unit needs to be given).

    There are two possible ways to input the cell parameters. In the simplest approach, the CELL keyword can be used to give the cell lengths and angles:

    CELL a.r b.r c.r alpha.r beta.r gamma.r [ANG|ANGSTROM|BOHR|AU]

    If the ANG (or ANGSTROM) keyword is used, then a.r, b.r, and c.r are in angstrom. Otherwise, cell parameters are in bohr by default (the keyword BOHR or AU can be used, but it is redundant). Using the CELL keyword lets critic2 decide on the crystallographic-to-Cartesian transformation matrix (which is not unique; critic2 always uses the Cholesky decomposition of the metric tensor, for consistency). Alternatively, one could input this matrix using the CARTESIAN keyword:

    CARTESIAN [scal.r]
  # comment
  [BOHR/AU]
  [ANGSTROM/ANG]
  x1.r y1.r z1.r
  x2.r y2.r z2.r
  x3.r y3.r z3.r
ENDCARTESIAN/END

    CARTESIAN reads the Cartesian coordinates of the cell vectors in some arbitrary orthonormal reference frame. Each row corresponds to a vector. Hence, the metric tensor is where is the matrix above. The coordinate transformation is . If scal.r is given, all vectors are scaled by that factor. The input units are bohr by default. The default can be changed with a UNITS keyword preceding CRYSTAL or with the BOHR/AU and ANG/ANGSTROM keywords inside the CARTESIAN environment. The CARTESIAN keyword is particularly useful for inputs based on Quantum ESPRESSO results since the matrix corresponds exactly to the CELL_PARAMETERS matrix, and scal.r can be set to celldm(1).

    The NEQ keyword can be used to specify the atomic positions. Equivalently, one can start the line with the atomic symbol or the atomic number:

    NEQ x.r y.r z.r at.s [ANG|ANGSTROM] [BOHR/AU]
atom.s x.r y.r z.r [ANG|ANGSTROM] [BOHR/AU]
atnumber.i x.r y.r z.r [ANG|ANGSTROM] [BOHR/AU]

    NEQ adds one atom to the crystal. If symmetry is used (via SPG or SYMM), then only the non-equivalent atom list needs to be given (as in the MgO example above), which decreases the number of NEQs that are necessary. Otherwise, the complete list of atoms in the cell has to be given, and the symmetry guess will reduce it to the non-equivalent atoms list. The coordinates x.r, y.r, and z.r are crystallographic (fractional) coordinates unless the ANG/ANGSTROM or BOHR/AU keywords are used. Using Cartesian coordinates requires a previous CELL or CARTESIAN command in order to convert the atomic positions to crystallographic coordinates. The atomic symbol is at.s, and the atomic number is detected from the symbol (essentially, from the beginning of it, so atoms like Cl1 or baxx2 are valid). Deuterium (D) is detected as hydrogen.

    The list of atomic positions can be extended by symmetry operations specified using the SYMM keyword. The SYMM keyword accepts three arithmetic expressions separated by commas. These expressions contain the variables x, y, and z (case insensitive), and represent symmetry operations in crystallographic coordinates. For instance:

    SYMM -X+1/2, Y+1/2, -Z+1/2

    would apply that operation to all atoms given as NEQ. If they are different from the original, the new atoms are added to the list. This keyword is useful in cases when it is difficult to pass SPG a certain non-standard setting for a low-symmetry space group, or when the space group symmetry is given in this format instead of a space group label (e.g. cif files and SHELX res files).

    The Crystal Library (CRYSTAL LIBRARY)

    A library of (simple) crystal structures is provided with critic2, and can be accessed using the CRYSTAL LIBRARY keyword:

    CRYSTAL LIBRARY NaCl

    Critic2 tries to find the “NaCl” label (case-insensitive) in an internal library file that is distributed with the code, and located in dat/crystal.dat relative to the source of the distribution. The relevant library entry in this case reads:

    STRUCTURE B1 rock_salt rocksalt NaCl
  CRYSTAL
    SPG f m -3 m
    CELL 5.6402 5.6402 5.6402 90 90 90 ANG
    NEQ 0.0 0.0 0.0 na
    NEQ 0.5 0.5 0.5 cl
  ENDCRYSTAL
ENDSTRUCTURE

    Note four aliases (B1, rock_salt, rocksalt, and NaCl) are defined for the same crystal structure. The syntax in the CRYSTAL environment is exactly the same as above. The user can define their own library of crystal structures either by modifying the crystal.dat directly or by using the LIBRARY keyword:

    LIBRARY CRYSTAL /path/to/library

    where the indicated file is used instead to perform the lookup. The path can be absolute or relative to the execution directory.

    A similar library exists for molecules (molecule.dat) that can be accessed through the MOLECULE keyword. Both molecule.dat and crystal.dat are installed in the data directory by make install.

    List Space Group Types (SPG)

    The SPG keyword (used outside the CRYSTAL environment):

    SPG

    lists the space group types available to critic2. A brief extract of its output is:

    #Hall ITA   HM-short HM-long       choice  crys.-syst.  Hall-symbol
[...]
452   161   R3c      R3c            H      trigonal     [R 3 -2"c]
453   161   R3c      R3c            R      trigonal     [P 3* -2n]
454   162   P-31m    P-312/m               trigonal     [-P 3 2]
[...]

    The SPG keyword lists, in order:

    • The ID for the space group in Hall notation (from 1 to 530).
    • The ID for the space group in Hermann-Mauguin international notation (from 1 to 230).
    • The short Hermann-Mauguin label for the group.
    • The long Hermann-Mauguin label for the group.
    • The particular choice of axes/origin/setting for the group. For instance, H and R mean hexagonal and rhombohedral axes, respectively. In monoclinic groups, choice gives the privileged axis, etc.
    • The crystal system.
    • The space group type in Hall notation.

    The HM-short and HM-long labels as well as the numerical Hall ID for the group (Hall) and the ITA numerical ID (ITA) can all be used in the SPG keyword inside CRYSTAL. (Note that the latter requires using the additional HM keyword.) A similar list can be found in the space group crystal collection.

    Symmetry Options (SYM/NOSYM)

    Critic2 uses the spglib library to calculate the symmetry operations and space group label from the crystal structure description. Symmetry is not used or calculated for molecular systems. By default, if the crystal is very big (>2000 atoms per unit cell), then the automatic calculation of the symmetry is deactivated.

    The treatment of symmetry in critic2 can be controlled using the SYM and NOSYM keywords (or their equivalent spellings SYMM/NOSYMM).

    {SYMM|SYM}
{SYMM|SYM} [-1|0|1]
{SYMM|SYM} eps.r
{SYMM|SYM} CLEAR
{SYMM|SYM} RECALC
{SYMM|SYM} ANALYSIS
{SYMM|SYM} REFINE
{SYMM|SYM} WHOLEMOLS
NOSYMM|NOSYM

    Without any other keywords, the SYM keyword writes the space group information for the current crystal to the output.

    Followed by an integer, SYM controls whether the symmetry operations and space group are calculated for new structures given via CRYSTAL. If the value is 1, symmetry is always calculated, regardless of crystal size. If 0, symmetry is never calculated. If -1, calculate the symmetry if the unit cell has fewer than 2000 atoms (this is the default). NOSYM (or NOSYMM) is equivalent to SYM 0.

    Additional keywords can be used to change the symmetry of an already loaded crystal. If SYM is followed by a real number (eps.r), then the precision with which the symmetry operations are determined is set to this value. If a crystal has been loaded, then this command recalculates the symmetry using the new precision. The default eps.r is 1d-2 bohr.

    The CLEAR keyword clears all symmetry operations (that is, use space group P1). The RECALC keyword recalculates the symmetry operations. This is useful in cases where the symmetry is read from an external file, such as a cif file.

    The REFINE keyword recalculates the atomic positions using the current space-group operations to have them be exactly at the corresponding symmetry sites. For instance, “0.333” may be converted to “0.3333333” in a hexagonal crystal.

    The WHOLEMOLS keyword must be applied to molecular crystals. It eliminates symmetry operations from the space group in such a way that the asymmetric unit is composed of whole molecules. This is useful when generating .res files as input for the DMACRYS program.

    If the symmetry is recalculated for a loaded crystal (with the eps.r, CLEAR, RECALC, REFINE, or WHOLEMOLS options), then all fields are unloaded and all critical point lists are cleared.

    The ANALYSIS keyword explores different values of the precision parameter (eps.r) and outputs the calculated space group symbol for each of them. This keyword is useful when there is a crystal that may have certain symmetry but there is interference from numerical or experimental noise in the atomic positions or cell parameters. The ANALYSIS keyword does not change the crystal structure or its symmetry operations.

    Atomic Charge Options

    The Q (or QAT) keyword can be used to change the atomic charge after CRYSTAL or MOLECULE:

    {Q|QAT} at1.s q1.r [at2.s q2.r] ...

    This command changes the atomic charge (Q, QAT) of the atomic species at1.s, at2.s,…. Real numbers for the charges are acceptable. The charges (Q) are used only in the calculation the point-charge electrostatic energy using EWALD.

    Loading Multiple Crystal Structures

    Critic2 can only work with one structure at a given time. However, more than one crystal can be loaded in the same run, simply by giving a new CRYSTAL (or MOLECULE) keyword. When the second and subsequent CRYSTAL/MOLECULE keywords are read, critic2 clears all the information for the previous structure, including the structural data (cell parameters, atomic positions, etc.) as well as all the fields that had been loaded, all the critical point information, and the atomic and core density grids. Effectively, critic2 behaves as if starting a new run, except that the variables and global options are carried over. To clear the variables and set the global options to their default values, use the RESET keyword:

    RESET

    Updated: