Provided by: c2x_2.40+ds-1_amd64 bug

NAME

       c2x - converts various crystal formats including density grid data

SYNOPSIS

       c2x [-OPTIONS] [--FORMAT] [--OPERATION] infile [outfile]

DESCRIPTION

       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.

OPTIONS

       -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).

       -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 -.

       --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.  -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.

       -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.

       -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.

       -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.

       -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.

       -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.

COMBINING OPERATIONS

       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.

FORMATS

       The following output formats are recognised.

       --abinit
              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.

       --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

       --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.

       --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.

OPERATION

       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
              call spg_get_dataset() and keep symmetry ops

NOTES

       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.

       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.

EXAMPLES

       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

VIEWERS

       The following viewers have been used during the development of c2x: Avogadro, FermiSurfer,
       gabedit, Jmol, pymol, VESTA, VMD and XCrysDen.

BUGS

       None known.

       Please report others to MJR.

ACKNOWLEGEMENTS

       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/

SEE ALSO

       babel(1)
       https://www.c2x.org.uk/

                                                                                           c2x(1)