c2x - converts various crystal formats including density grid
data
c2x [-OPTIONS] [--FORMAT] [--OPERATION] infile
[outfile]
c2x converts primarily a CASTEP .check file to various
output formats, additionally extracting densities (charge, spin, band or
psi) and forces. It can also read CASTEP .cell files and PDB files, Onetep
.dat files, and several input and output files from Abinit, Quantum Espresso
and VASP, with some support for Siesta too. It is a sort of Babel with
support for gridded data and .check files, and the ability to transform
cells and perform simple analysis (integration, interpolation, dipole moment
calculation, band parity identification).
It may have been compiled to give access to symmetry functions
from spglib too.
An input file whose name ends '.pdb' is assumed to be in pdb
format, ending in '.cif' is assumed to be in cif format, ending in '.res' is
assumed to be in shelx97, ending '.cub' or '.cube' is assumed to be in cube
format, ending '.in' is assumed to be an Abinit or Quantum Espresso input
file, ending '.xml' is assumed to be a Quantum Espresso output file, ending
in '.xsf' is assumed to be in xsf format, and ending in '.xv' or 'XV' is
assumed to be in Siesta's XV format. Input files ending CHG, CHGCAR, POSCAR,
CONTCAR, LOCPOT or WAVECAR are assumed to be in VASP 5.x format. Input files
ending in DEN, POT or WFK are assumed to be in Abinit format. Otherwise, if
the first byte is either zero, 10 or 30 it is assumed to be a .check file,
else it is assumed to be a .cell file. It can also read .orbitals files
(which are identical to .check files in format), and .castep_bin files
(which lack wavefunctions). Furthermore, it can read .chdiff files and
.cst_esp files. In these cases it needs a .cell or a .check file as well in
order to obtain unit cell information.
- -a
- rotate as though outputing in abc format, i.e. place a along x axis, b in
xy plane, and abc form a right hand set. Useful if one wants a dx file
consistent with a pdb file. See also -3.
- -A
- accumulate (sum) bands requested by -b= or -B=.
- -b[=range]
- include specified bands as psi (real).
- -B[=range]
- include specified bands as densities (psi*conjg(psi)).
- -c
- include charge density (units electrons per cubic Angstrom).
- --calc
- evaluate next arg with arithmetic parser and exit.
- --constants
- report internal conversion constants and exit.
- -C
- find "compact" (near-cubic) set of cell vectors.
- -d
- read also a corresponding .chdiff file, and output its contents. The
filename given must still be that of a .cell or .check file, as a .chdiff
file contains no axes.
- -D=[x,y,z]
- if charge density read (-c), calculate dipole moment about fractional
co-ordinates x,y,z, or 0.5,0.5,0.5 if co-ordinates not given. Assumes
density has been read as eA^-3.
- -Da=[x,y,z]
- as above, but also report post-hoc energy correction for slab geometry for
the a axis being the non-periodic axis. Valid values of a: a, b and
c.
- -Dm=[x,y,z]
- as above, but also report post-hoc energy correction for a molecule in a
cubic box, or for a molecule in a tetragonal box if dipole moment is
parallel to c.
- -e
- read also a corresponding .cst_esp file, and output its contents. The
filename given must still be that of a .cell or .check file, as a .cst_esp
file contains no axes.
- -e=tol
- set symmetry tolerance to given number of Angstroms.
- -E[=[-][mu]]
- calculate electrostatic potential, assuming that an electron density has
been read (implies -c). Ions are treated as Gaussian blobs of charge of
extent exp(-mu^2r^2). If the ionic charge differs from the atomic number,
a further localised smoothing of the atomic potential occurs, unless the
first character after the = is -. With -E=0, a bare Coulomb potential is
used.
- -f
- calculate first failure start of k-point set.
- --formats
- list supported formats.
- --frame=N
- extract single frame from series of time steps. Frames are numbered from
zero, and negative numbers represent offsets from the end of the sequence,
so --frame=-1 will extract the final frame. --gap print band gap in
eV. -H shift atoms by half a grid cell. For use with xplor data
format, see below.
- -i=nx,ny,nz
- Fourier interpolate onto specified grid size. New grid may be coarser or
finer than original. Any dimension given as zero is replaced by old grid
size. If reading wavefunction, any grid truncation is done after
transforming back to real space and converting to density etc.
- -I[=range]
- report whether bands have inversion, and parity under inversion. If
combined with -b or -B, the last range given is used.
- -k[=range]
- include given kpoints for bands (default range is 1).
- -l
- if k-points are to be included in a .cell file, explicitly list them
rather than using the MP generation parameters.
- -L
- output in abc format assuming that abc describes a left-handed set of
axes. Do not use this unless you understand why you should not!
- -m[=a,b,c]
- assume input is molecule, not crystal. Try to avoid outputing a cell,
shift if some co-ordinates are negative, or if a,b,c given shift by those
numbers of FFT grid cells.
- -m=(a,b,c)
- assume input is molecule, not crystal. Try to avoid outputing a cell,
shift atoms by fractional co-ordinates given.
- -n
- discard symmetry information, and, if output is XSF, discard forces. Give
twice to discard k-points too.
- -N
- normalise by reducing fractional coords to 0<=x<1. In conjunction
with -m, do output a cell.
- -O
- print band occupancies and evalues to stderr.
- -P
- find primitive cell with own internal algorithm, not spglib.
- -P=p1:p2:nn
- output data as line of nn points from p1 to p2. Express p's as either
fractional co-ordinates in the form (x,y,z), or an atom position as, e.g.,
Si3 for silicon atom number 3, or simply Si for the first Si atom. Using a
0 (zero) for a p is equivalent to (0,0,0), and the three cell axes
"(0,0,0):(1,0,0):ngx+1" (etc.) can be specified as a, b and c.
Each co-ordinate is passed to the arithmetic parser, so 1/3 is acceptable
for a third, etc.
- -P=p1:rl:nn
- output data with cylindrical averaging. p1 is the centre of the cylinder,
rl (literal "r", followed by a length, suffixed by "B"
if Bohr) is the radius, and nn the number of points. The axis of the
cylinder must be the c axis, and alpha and beta must be 90 degrees. Data
are averaged over c and theta. Append "w" to number of points to
weight samples by two pi times radius, or "a" to weight and
accumulate.
- -P=p1:Rl:nn
- output data with spherical averaging. p1 is the centre of the sphere, Rl
(literal "R", followed by a length, suffixed by "B" if
Bohr) is the radius, and nn the number of points output. The number of
points for sampling around the spherical surface is chosen to give a
similar point separation to that along the line. A length of zero will set
the length to the maximum possible given the periodicity. Data are
averaged over theta and phi. Append "w" to number of points to
weight samples by four pi times radius squared, or "a" to weight
and accumulate.
- -q
- calculate post hoc energy correction for charged isolated system. Implies
-c.
- -q[abc]
- calculate post hoc energy correction for charged 2D system. The axis given
(a, b or c) is the aperiodic one. Implies -c.
- -Q
- sort the atoms on output in descending atomic order
- -Q2
- sort the atoms on output in ascending atomic order
- -R
- don't attempt to rescale densities, but output them raw. Charge density
becomes electrons per unit cell if reading from Castep, for instance. Also
do not attempt to adjust radius to maintain bond length on nanotube
creation.
- -R=x
- rescale grid data by factor x, not whatever factor (if any) would normally
be used. If the factor is suffixed by an "x", do include c2x's
usual conversion factor too.
- -s
- include spin density.
- --sym_list
- list symmetry elements found in input, without calling SPGlib.
- -S[=range]
- include specified spins or spinors for bands (default range is -, and the
spins are numbered 0 and 1).
- -t=(x1,y1,z1)(x2,y2,z2)[(x3,y3,z3)]
- rotate co-ordinate system so that the first vector becomes the second.
First vector given in relative co-ordinates. If third axis given, it is
used as the rotation axis. Else the rotation axis will be perpendicular to
the two axes given.
- --tricubic
- when interpolating, using tricubic (spline) interpolation in place of
trilinear interpolation. Slower, might not preserve monotonicity, but does
keep first derivative continuous.
- -T=(x1,y1,z1)(x2,y2,z2)[(x3,y3,z3)]
- rotate co-ordinate system so that the first vector becomes the second. All
vectors given in absolute co-ordinates. If third axis given, it is used as
the rotation axis. Else the rotation axis will be perpendicular to the two
axes given.
- -u
- use atomic units (Bohrs) when writing .cell files and 1D data. Scale
densities from A^-3 to Bohr^-3 when writing .cube files.
- -U
- scale densities from Bohr^-3 to A^-3 when reading .cube files.
- -v
- be verbose. Far too much output can be generated if specified more than
twice.
- --version
- print version information. If preceeded by -v, also print internal
conversion factors.
- -w
- weight bands by occupancies, or sqrt(occ) if not calculating density.
- -w=k
- weight bands by k-point weight, but not occupancy.
- -W
- weight bands by occupancies and k-point weight, or sqrt thereof if not
calculating density.
- -x=(x1,x2,x3)(y1,y2,y3)(z1,z2,z3)
- expand unit cell to new cell specified in terms of the old cell axes. Each
co-ordinate is passed to the arithmetic parser, so 'sqrt(3)/2' etc is
acceptable.
- -x=ixjxk
- expand cell with a trivial tiling.
- -X=(x1,x2,x3)(y1,y2,y3)(z1,z2,z3)
- expand unit cell to new cell specified in absolute co-ordinates.
- -X[abc]=x
- change given axis/axes to new length by inserting / removing vacuum around
the origin. Removing non-existent vacuum will produce nonsense. Length may
be suffixed with B (for Bohr) or nm.
- -y=i,j[:x]
- make nanotube. The input cell must have c perpendicular to the ab plane,
and c as the nonperiodic direction of the sheet to be rolled. The
circumference is then defined by the vector i*a+j*b. The vector along the
tube's length found automatically, and the size of the cell perpendicular
to the tube's length is given by the optional parameter x, which may be
suffixed with B (for Bohr) or nm.
- -z=p1
- print to stdout data at given point, and set output type to null. For
specification of p1, see -P= option.
- -Z=p1
- ditto, but assume that data represents an electron density in A^-3, and
also output Perdew Zunger 81 XC energy.
- -3
- when moving from a left hand set of axes to a right hand set, rather than
exchanging the 2nd and 3rd axes, preserve the 3rd and exchange the 1st and
2nd. This transformation is required if the input is cartesian and left
handed, and an abc output is requested. Specifying this flag twice will
cause the 1st and 3rd axes to be exchanged.
The following options expect multiple input files to be given, and
perform the specified operation.
- --add
- Add datasets element-wise.
- --diff
- Subtract datasets element-wise.
- --mask
- Multiply datasets element-wise. Although it is assumed that one dataset
will be a mask of ones and zeros, it need not be so.
- --merge
- Merge datasets. The expected use is merging an atoms-only format with a
density-only format to create an output containing both atoms and
density.
- --mult
- Alternative for --mask.
- --sub
- Alternative for --diff.
- --sum
- Alternative for --add.
When merging, if files contain conflicting data, the one on the
right usually has precidence.
When performing operations on grids, the grids must be the same
size. The use of -i may assist. In all cases, the cells must be the
same.
The following output formats are recognised. (See the output of
the --formats option for the complete list. Most are also recognised
for input provided that their filenames have the expected suffix.)
- --abinit
- Abinit .abi file (for Abinit version 9 and beyond).
- --abinit8
- Abinit .in file. The output is insufficient to be a valid input file to
Abinit, but can easily be made so.
- --bands
- CASTEP .bands file, no sorting of bands.
- --bxsf
- XCrysDen / FermiSurfer file for plotting Fermi surfaces. A
symmetry-reduced kpoint set will be expanded. (Not accepted as
input.)
- --ccp4
- CCP4 density map format. Note no atomic positions can be recorded in this
format, and c2x will always produce a right-hand set of axes unless the
input is a lhs and the option -L is given.
- --cell
- CASTEP .cell, cartesian cell, fractional co-ordinates.
- --cell_abc
- CASTEP .cell, abc cell, fractional co-ordinates.
- --cell_abs
- CASTEP .cell, cartesian cell, absolute co-ordinates.
- --cell_abc_abs
- CASTEP .cell, abc cell, absolute co-ordinates.
- --chgcar
- VASP 5.x chgcar output.
- --cif
- a very basic and rigid format which may be compatible with some
CIF-reading software.
- --cml
- Chemical Markup Language.
- --cube
- Gaussian cube. Atoms and at most one data set.
- --dx
- Data Explorer. Data set only.
- --denfmt
- CASTEP formatted density
- --elk
- Elk elk.in format.
- --fdf
- Siesta. If a density has been read, a corresponding .RHO file will be
written.
- --gcoeff
- An ASCII wavefunction coefficient representation
- --gcoeff_sorted
- The same, sorted by |g|
- --gnu
- Gnuplot command file for 1D data.
- --npy
- Numpy array, single dataset, as doubles with -15, else single
precision.
- --null
- Null output. Throw away all output, but still write some useful
information the input to stderr.
- --one
- Onetep .dat, very similar to .cell. Also one_abc, one_abs, and
one_abc_abs.
- --pdb
- PDB
- --pdbn
- PDB, but label the atoms with element symbol and number within that
species, e.g. C8, H24, Ca2, rather than just with element symbol. The
whole string can contain no more than four characters, so * is used for
the numeric part if it would not otherwise fit.
- --py
- a python dictionary, compatible with the Atoms data structure from
ASE.
- --pya
- a python ASE Atoms data structure.
- --qe
- Quantum Espresso. Non colinear spins not supported.
- --qef
- Ditto, atoms in fractional co-ordinates.
- --shelx
- a subset of the SHELX97 format.
- --vasp
- VASP 5.x output (poscar or chg).
- --xplor
- Xplor format. Data set only. The grid used in this format is offset by
half a grid cell compared to Castep, and as interpolating is inexact, this
program does not in this case. Also the grid axes are described in terms
of a, b, c, alpha, beta, gamma, so information about orientation in space
is lost. To produce a compatible pdb file of atomic co-ordinates, specify
-Hc when creating the pdb file.
- --xsf
- XCrysDen format. Default. The only format in which multiple data sets are
supported.
- --xv
- Siesta's .XV format (positions only, velocities written as zero). Will
also write a .RHO file if grid data have been read.
- --xyz
- XYZ format. Atoms only, no unit cell.
Where a range is required, it can be specified as a single
integer, two integers separated by a hyphen (all integers in the given
range), or a comma-separated list of any of these elements. Only for the xsf
output format is a range including more than a single integer
meaningful.
If c2x has been compiled with spglib, the following spglib
operations are available.
- --int
- call spg_get_dataset() and report international symbol
- --list
- call spg_get_dataset() and list symmetry ops
- --point
- call spg_get_dataset() followed by spg_get_pointgroup()
- --primitive
- call spg_find_primitive(), equivalent to
spg_standardize_cell(to_primitive=1, no_idealize=0). This may rotate the
cell to a standardised orientation.
- --primitive_nr
- call spg_standardize_cell(to_primitive=1, no_idealize=1), so primitive no
rotation
- --refine
- call spg_refine_cell()
- --schoen
- call spg_get_schoenflies()
- --snap
- call spg_standardize_cell() then expand back to a snapped version of the
original cell
- --snap_tr
- ditto, but include any translation introduced by spglib
- --standardise
- call spg_standardize_cell(no_idealize=1)
- --std_ideal
- call spg_standardize_cell(no_idealize=0)
- --symmetry or
--symm
- call spg_get_dataset() and keep symmetry ops
For the pdb formats, just the unit cell and atomic positions are
read or written. For the dx and xplor formats, just a single data set is
written. For the Gaussian cube format atomic positions and at most one data
set are recorded, and for the XCrysDen format the unit cell, atomic
positions, forces, and any number of data sets are recorded.
When reading a .geom file and writing a format containing a single
frame, the last frame is written, unless the --frame option is given.
When reporting symmetry operations, all co-ordinates are
fractional.
Note that the pdb format offers a very low precision for storing
co-ordinates, and, because it stores the unit cell in abc format, and the
atoms in absolute coordinates, a rotation is likely to be required to place
a on the cartesian x axis, etc. If so, it will be done
automatically. The same is true for the abc varients of the cell format and
for the Xplor and cif file formats. This rotation can be specified
explicitly for other formats. Additionally the axes must form a right-handed
set. If this is not the case, two axes will be interchanged. By default,
b and c are exchanged, but the flag -3 will cause
a and b to be exchanged instead.
The cif reader reads little more than c2x's cif output. It is very
basic, and will fail to read correctly a large number of valid cif files.
There is currently no intention to produce a proper cif reader.
When outputting psi it is assumed that it is possible to make psi
real by unwinding any phase produced by the k-point, and then multiplying
all points by the same arbitrary complex constant. If this is not so, the
band was probably nonsense anyway. The final choice of a factor of -1 is
arbitrary. This scheme produces nonsense if one attempts to plot a
degenerate band.
When doing the conversions resulting from -x, a new grid will be
chosen of similar density to the old, and the data interpolated onto the new
using trilinear interpolation. Extrapolating psis (rather than densities) is
meaningless except at gamma, for the phase due to the k point is not
considered.
Densities by default are in Angstroms**-3, and psis in
Angstroms**-1.5, save that .RHO files are written in Bohr**-3 as
expected.
To extract the charge density in xsf format
- c2x -c input.check output.xsf
To extract the first four bands as psi at the second k-point in
xsf format
- c2x -b=1-4 -k=2 input.check output.xsf
To convert a check file to a pdb file
- c2x --pdb input.check output.pdb
To convert a cell to something containing two repeat units in the
a and b directions, and one in the c direction
- c2x --cell -x='(2,0,0)(0,2,0)(0,0,1)' in.cell out.cell
or, from c2x version 2.30,
- c2x --cell -x=2x2x1 in.cell out.cell
Assuming the above cell was a 3.5A cube, the same in absolute
co-ordinates
- c2x --cell -X='(7,0,0)(0,7,0)(0,0,3.5)' in.cell out.cell
To change a cell containing one layer of bulk in the c direction
to one containing four layers, and sufficient vacuum to make a total length
of 30A
- c2x --cell -x=1x1x4 -Xc=30 in.cell out.cell
The following viewers have been used during the development of
c2x: Avogadro, FermiSurfer, gabedit, Jmol, pymol, VESTA, VMD and
XCrysDen.
None known.
Please report others to MJR.
If you wish to cite, please do so as "C2x: a tool for
visualisation and input preparation for Castep and other electronic
structure codes", MJ Rutter, Computer Physics Communications, vol 225
pages 174-179 (2018). http://dx.doi.org/10.1016/j.cpc.2017.12.008
Details of spglib can be found at
https://atztogo.github.io/spglib/