
     Cut3d_help

     HELP FILE FOR THE CUT3D CODE OF THE ABINIT PACKAGE

     This document gives information on code cut3d.

     Copyright (C) 2000-2005 ABINIT group (XG,RC,GMR,JFB,MCote) 
     This file is distributed under the terms of the
     GNU General Public License, see ~ABINIT/Infos/copyright
     or http://www.gnu.org/copyleft/gpl.txt .
     For the initials of contributors, see ~ABINIT/Infos/contributors .

     ========================================

     The reader should first consult the files 
     ~ABINIT/Infos/new_user_guide
     and ~ABINIT/Infos/abinis_help, especially the sections
     about density and potential files, 
     before looking at the present help file.

     The cut3d program allows to read data representing a 3D
     density or potential, and to analyze it or to convert
     it, or to cut it along lines or planes.

     Also, it can now (v3.2) read the _WFK file output 
     from abinis and by selecting a
     desired kpt and band, transform this band to real space 
     and output it to a file (Ground-state wfs only, not RF).

     The input 3D file that can be either 
     unformatted (the _DEN , _POT, _WFK ... files, ), or formatted.
     In the latter case, two auxiliary files are also needed
     (see below).  

     To run the code, simply type :

     cut3d

     then, answer to the questions.

     You will have to choose between different possibilities :
     1) computation of data for a point, to be specified
     2) computation of data along a line, to be specified
     3) computation of data on a 2D grid, to be specified
     4) computation of data on a 3D grid, to be specified
     5) conversion to formatted file
     6) conversion to indexed formatted
     7) conversion to Molekel format
     ...

     For option 1) you will have the possibility to specify
     a point in reduced or cartesian coordinates.
     For option 2) you will have the possibility to specify
     a line by its two end-points in reduced or 
     cartesian coordinates, or by it being perpendicular to 
     some plane.
     For option 3) and 4) many possibilities are offered, 
     including specifications thanks to points defined 
     in reduced coordinates, cartesian coordinates, 
     or atomic positions.

     For a wavefunction file, the two forms of outputs are : 
     the bare data or a Data Explorer form.
     The option 10 also produce input files to draw the molecules in Data
     Explorer using modules and macros that we (JFB and MCote) 
     have developped.  Those modules and macros could be made public.

     ---------------------------------------------

     In the formatted case, one must have three different files :

     - the formatted 3D function (for example mos.densout)
      density or potential file in ASCII format
      with nr1 x nr2 x nr3 lines of 1 float

     - a file with complementary informations about the cell, the FFT grid ...
      (always named cut.in)
      Here is an example (6 lines):

      mos.xyz                        
      11.502384 6.0558159 16.295674  unit cell parameters (=acell)
      1 0 0 0 1 0 -0.215 0 0.976     orientation of the unit cell axes (=rprim)
      54 30 75                       grid size (= nr1,nr2,nr3, all three integers)
      10                             number of atoms in the unit cell (= natom, integer)
      2                              number of atomic types (=ntypat, integer)

      The first line gives the name of the file with atomic positions (Xmol format) (=filtau)
      No comment can appear on that line, in contrast <ith the other lines.

     - the coordinate file
      (for example mos.xyz)
      Its format (similar to XMOL) is

      On the first line the number of atoms (=natom) is provided.
      Blank line
      A list of natom lines containing :
      Char (1 or 2 characters, = atom label) + 3 float (X, Y, Z cart. coord.)

