Ubuntu Manpage: c2x - converts various crystal formats including density grid data

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

--calc evaluate next arg with arithmetic parser and exit.

--constants
report internal conversion constants and exit.

--cubic
equivalent to --simpson --tricubic

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

--div replace a vector dataset with its (scalar) divergence.

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

--fbz calculate first Brillouin zone

--fft use FFT interpolation to move gridded data between different unit cells, and with -z.

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

-F calculate the potential, then its gradient, to give an electric field.

--gap print band gap in eV.

--grad replace a scalar dataset with its (vector) gradient.

--grad2
replace a scalar dataset with the result of the Laplacian operator.

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

--ibz calculate irreducible Brillouin zone.

-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 only reduced (symmetry inequivalent) atoms in cif output, or with the --fbz or --ibz options,
reduce k-points to the relevant zone, adjusting weights appropriately.

-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 (scalar or vector).

--simpson
use Simpson's rule for accumulating/integrating, not trapezium rule.

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

--vec2force[=[species[,species]:]r[i][f]]
convert vector field to "forces" on each atom. Use value of vector at atom, unless =r given, when
average over a sphere of radius r (Angstroms, unless suffixed with B for Bohr). If i given,
integrate rather than average. If f given, use finer grid for averages/integrals. The f may be
repeated. If species given, limit "forces" to given atomic species. See also --cubic.

--version
print version information. If preceeded by -v, also print internal conversion factors.

--vmod replace vector grid data by its scalar modulus.

-w weight bands by occupancies, or sqrt(occ) if not calculating density.

-w=k weight bands by k-point weight, but not occupancy.

--widths
calculate band widths naively. Makes sense only if bands do not cross.

-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)[:n1xn2xn3]
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. Optionally also specify new grid size
for gridded data, else this is calculated automatically.

-x=ixjxk
expand cell with a trivial tiling.

-X=(x1,x2,x3)(y1,y2,y3)(z1,z2,z3)[:n1xn2xn3]
expand unit cell to new cell specified in absolute co-ordinates. Optionally also specify new grid
size for gridded data, else this is calculated automatically.

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

--jmol_recip
Jmol output for Brillouin zones (with --fbz or --ibz only).

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

--verts
raw list of vertices for Brillouin zones (with --fbz or --ibz only). Also --verts_frac for
vertices in fractional coordinates.

--vmd_recip
VMD output for Brillouin zones (with --fbz or --ibz only).

--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. On reading, will also read a FORCE_STRESS if present. Note that
FORCE_STRESS has no prefix.

--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 or --symm
              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,
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.

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/