           **** PROGRAM INSTRUCTION ***
  
 # VASPBERRY (Ver 1.6.3), by Hyun-Jung Kim. 2026. Sep. 30.                      
                                                                                
                                                                                
                    
  
 *Native WAVECAR workflow: make serial
   build/vaspberry --task chern --wavecar WAVECAR \
     --mesh 12,12 --bands 1:18
   build/vaspberry --task kubo --bands 18 \
     --curvature-csv curvature.csv
   build/vaspberry --task kubo-pairs --pairs-csv pairs.csv
   build/vaspberry --help
   build/vaspberry-gfortran remains a compatibility alias.
  
   The Fukui-Hatsugai-Suzuki (FHS) method is referred to
   below as the Fukui method.
 *Tasks (--task NAME; default: chern / Fukui method):
   chern          Chern number via the Fukui method
                  Full periodic 2D mesh required.
   spin-kubo      approximate spin-sector local curvature
     --bands 1:N; arbitrary k list/path by default
     --sum-bands N: sum within source bands 1:N (default all)
     Explicit --mesh NX,NY additionally estimates integrals
     Writes SPIN_KUBO.csv and SPIN_KUBO_SPECTRUM.csv
   spin-chern     projected-spin Chern numbers
                  via the Fukui method
     --bands 1:N --mesh NX,NY --spin-axis z
     --outcar OUTCAR (default); --spin-axis x|y|z|a,b,c
     --energy-gap-tol 1e-8 (eV); --spin-gap-tol 1e-6
     Writes SPIN_CHERN/BERRY/SPECTRUM.csv; pseudo metric
   z2             FH n-field Z2 invariant (-z2 1; limits below)
   kubo           Berry curvature from the Kubo formula
                  Evaluated at the supplied k points.
                  (-kubo 2; kubo-line is a synonym)
                  No integer expectation on a path.
   kubo-integral  legacy integration diagnostic (-kubo 1)
   kubo-pairs     all source-band pairs; --pairs-csv needed
                  Omit --bands; no occupation weighting.
                  Source occupations may vary with k.
   optical        selected-transition selectivity (-cd 1)
   spectrum       broadened transition spectrum (-cd 2)
                  Not a calibrated absolute optical rate.
   wavefunction   requires --wavefunction-band N (-wf N)
                  Existing Gamma-only reconstruction.
   velocity       velocity expectation (-vel 1)
   --task rejects conflicting legacy task options.
   FH = Fukui-Hatsugai n-field method for the Z2 invariant.
  
 *Readable aliases (each takes a separate value):
   --wavecar PATH            -f PATH
   --mesh NX,NY              -kx NX -ky NY
   --bands FIRST:LAST or N   -ii FIRST -if LAST or -is N
   --spinor auto|1|2         -s auto|1|2 (default auto)
   --output PREFIX          -o PREFIX (not a directory)
   --curvature-csv PATH     -kubo_csv PATH
   --pairs-csv PATH         -kubo_pairs PATH
   --per-band 0|1          individual Kubo bands (default 0)
   Selected ranges use the whole subspace by default.
   Default trace CSV: KUBO.csv.
   Applies to --task kubo + selected range, or --bands.
   Pure legacy -kubo -ii/-if keeps individual bands.
   Omitted bands keep inference and individual output.
   Specify --bands explicitly for the new range rule.
   --wavefunction-band N    -wf N
   --kpoint N               -k N
   --real-grid NX,NY,NZ     -ng NX,NY,NZ
   --imaginary 0|1          -im 0|1
   --theta DEG --phi DEG    -theta DEG -phi DEG
   --help [TOPIC]          short overview or topic help
   Legacy band selectors remain accepted.
  
 *Outputs and reusable results:
   CSV options name exact files; parent dirs must exist.
   Kubo CSV exports refuse existing files.
   Legacy DAT files may be replaced: use a fresh cwd.
   --output is a legacy label, not an output directory.
   Pairs -> import-pairs -> pair-hall -> plot_hall.py.
   Reference and output names: docs/NATIVE_COMMANDS.md.
  
 *LIMITATION : -This program is ONLY for 2D system.
             : -It tries to find the VBM for first KPT,
             :  it may result in some problem when you
             :  dealing with metallic states. 
             :  Be careful!
 *NOTE1 The x,y,z components of each G value are given
        in terms of the ig values and the components 
        of the recip. lattice vectors according to:
         ig1*b1_x + ig2*b2_x + ig3*b3_x,
         ig1*b1_y + ig2*b2_y + ig3*b3_y, and
         ig1*b1_z + ig2*b2_z + ig3*b3_z, respectively,
        with
         ig1=ig(1,iplane),
         ig2=ig(2,iplane), and
         ig3=ig(3,iplane),
        where iplane=1,2,...,nplane(k,ispin) is an 
        index incrementing the plane waves for specific
        k and spin values
  
 *NOTE2 The energy eigenvalues are complex, as provided
        in the WAVECAR file, but the imaginary part is 
        zero (at least for cases investigated thus far)
  
 *Syntax: build/vaspberry-gfortran -f file
 *        -kx nx -ky ny -ii ni -if nf
 *   (or) build/vaspberry-gfortran -f file
 *        -kx nx -ky ny -is n
  
              ### POSSIBLE OPTIONS ###
  -h               : Print help overview and stop
  -f filename      : File name to be read
                   : Default: WAVECAR
  -kx(ky) kx(ky)   : k-point grid of your system
  -s auto|1|2      : infer components from WAVECAR (default)
                   : 1 or 2 asserts the detected layout
                   : checks every spin/k; does not infer SOC
  -ii(if) ni(nf)   : Once specified, berry curvature 
                   : for multiband (from ni-th to nf-th
                   : state) states will be evaluated,
                   : unless '-cd' is not 1.
                   :  Default -cd 0 -> -ii  1  -if VBM 
                   :          -cd 1 -> -ii VBM -if CBM
  -is n            : if specified, berry curvature for
                   : single band (n-th band) will be 
                   : evaluated.
  -o filename      : Print Berry curvature distribution
                   : to the 'filename.dat'             
                   :  Default : BERRYCURV.dat          
  -kp np           : Print Berry curvature distribution
                   : with extended BZ with 'np x np'-BZ
                   :  Default : 2              
  -skp 1(or 0)     : Specify whether special K-points 
                   : will be printed in the SKP.dat 
                   : You may specify the points by hand
                   : into the source code, the routine,
                   : 'write_special_kpoint'
                   :  Default : 0
  -ne  ne          : Specify total number of electrons
                   : Usual insulating cases, you don't
                   : need to specify it, program will 
                   : find total number of electrons,
                   : but for semimetallic system, it 
                   : may be more clear to put by hand
  -cd  1(or 0)     : Calculate spin- and k-resolved
                   : degree of optical polarization,
                   : degree of circular polarization,
                   : between valence & conduction band
                   : If set to '1', Berry cuvature will
                   : not be evaluated
                   : You may set -ii and -if together,
                   : defining VBM & CBM, respectively
                   :  Default : 0
   or -cd 2        : If -cd is set to 2, total spectrum
      -ien init_e  : with respect to the enery will be 
      -fen fina_e  : evaluated. In this case, 
      -nediv ndiv  : -ien and -fen tag should be set by
      -sigma sigma : hand. Otherwise, default value, 
                   : -ien  0  -fen 10 -nediv 1000 will 
                   : be applied. The output contains
                   : degree of circular polarization 
                   : with respect to photon energy 
                   : for each k-point. Here, -sigma tag
                   : sets a gaussian broadning factor
   or -cd 3        : If -cd is set to 3, total spectrum
      -klist lfile : with respect to the energy will be
      -sw sw_file    evaluated. Same functionality with
                     -cd 2, but instead calculate in   
                     order of kpoints list provided in 
                     lklist file with -klist option
                     The spectral weight with unfolded
                     band structure file (sw_file) 
                     also should be be provided with 
                     option -sw .
                     Note: use sw_file generated by
                           VaspBandUnfolding
      -atlist afile: 'afile' contains information for
                   : atom_projected band structure file
                   : name. Total number of atom to be 
                   : highlighted, and atom indices
                   : It works with -cd 2 and 3 only.
                   : EX)  in afile, it read as follows
                     DOS_atom_projected.dat 
                     6   # total atom in system   
                     3   # total atom to read     
                     1 2 5   # atom indices to read
  *** Angle resolved CD calculations: *****************
  * -theta theta   : angle along z-axis describing
  *					 the direction of the injecting light
  *					  Default: 0
  * -phi   phi     : angle along x-axis describing
  *					 the direction of the injecting light
  *					  Default: 0
  *					 
  *					 Example:
  * 				  Light from z-axis(surface normal):
  * 				   (theta,phi) = (0.0,0.0)
  * 				  Light from x-axis 
  * 				   (theta,phi) = (90.0,0.0)
  * 				  Light from y-axis 
  * 				   (theta,phi) = (90.0,90.0)
  *****************************************************
  -kubo  1(or 0)   : Calculate spin- and k-resolved
          (or 2)   : Berry curvature using Kubo formula
                   : for nn-th band
                   : If it is set by 2, line-mode is
                   : assumed so that the result will
                   : not be sorted over the BZ. 
                   : Note: nn can be ranged by
                   : -ii and -if tag 
                   :  ex) -kubo 1 -ii 19 -if 22 
                   :  => from 19 to 22 th eigenstate
                   :     will be calculated and the
                   :     result will be printed out to
                   :     BERRYCURV_KUBO.EIG-NN.DAT and
                   :     total Berry curvature (19-22)
                   :     is in BERRYCURV_KUBO.DAT
                   :  Default : -kubo 0 (no calc.)
                   : Standard -2 Im normalization.
                   : Bare momentum from pseudo WAVECAR;
                   : no PAW/nonlocal velocity terms.
                   : Isolated bands and k/NBANDS
                   : convergence are required.
                   : -kubo 2 has no BZ curvature integral.
                   : Pre-1.3 Kubo values divide by 2;
                   : never divide new outputs again.
  -kubo_pairs PATH : Export all unordered source-band
                   : pair numerators (yz,zx,xy), eV2 A2.
                   : No gap division or occupations.
                   : Requires -kubo 2; omit band ranges.
                   : Separate from -kubo_csv/bundle.
                   : PATH must be new; a final PASS
                   : marker means export completed.
  Selected Kubo range: trace of the full selected space.
                   : Excludes internal transitions;
                   : internal degeneracies are allowed.
                   : External gaps must exceed 1e-5 eV.
                   : --task kubo --bands FIRST:LAST.
                   : --curvature-csv changes KUBO.csv.
                   : --per-band 1 requests each band.
                   : Each band gap must exceed 1e-5 eV.
                   : Empty external space gives zero
                   : in the truncated WAVECAR basis.
  -kubo_csv PATH   : Opt-in band/bundle CSV, full
                   : precision, omega_z_A2 normalized.
                   : Band: spin,k,band,E,min_gap.
                   : Bundle: spin,k,min_external_gap;
                   : band range and source NBANDS.
                   : omega_z_A2 is in both schemas.
                   : Used only with -kubo 1 or 2.
                   : PATH must not already exist.
  -ixt np -fbz f   : **For the special purpose
                   : Read file 'f' and extend data to
                   : np x np periodic field. Note that
                   : -ixt option should be used with 
                   :'-fbz filename_of_.dat_file' option
  -vel 1 -is n     : **For the special purpose
                   : Calculate velocity expectation 
                   : vaule (v_x, v_y) of n-th state
  -z2  1           : Fukui-Hatsugai n-field Z2 index
                   : For a 2D, nonmagnetic, gapped,
                   : time-reversal-symmetric SOC run.
                   : Use a converged CHGCAR in an
                   : ICHARG=11 run with ISYM=-1 and
                   : a full, even Gamma-centered mesh
                   : with Nx,Ny >= 4 and kz=0 modulo G.
                   : Requires ISPIN=1 two-component spinors
                   : occupied bands 1:NE, NBANDS>NE,
                   : and each of four 2D TRIM once.
                   : Example (12x12, NE=10):
   ./build/vaspberry-gfortran -f WAVECAR -o NFIELD \
     -z2 1 -kx 12 -ky 12 -s 2 \
     -ii 1 -if 10
                   : PASS writes NFIELD.dat and
                   : Z2_FIELD.csv. Report z2_invariant
                   : only for result_status=PASS; the
                   : top/bottom half-BZ parities must
                   : agree. Check denser even meshes.
                   : Rejected/preflight runs may keep
                   : Z2_FIELD.invalid.csv; NFIELD.dat
                   : needs the final PASS CSV.
  -hf  1           : Rejected for Z2 full-mesh safety.
  -wf nb -k nk     : **For the special purpose
   -ng nx,ny,nz    : Calculate real-space wavefunction
   -im 1           : output will be written in 
   -ishift rx,ry,rz: PARCHG-W-K$k-E$wf-(IM)-SPIN$ispin
                   : nb and nk : index of band & kpoint
                   : -ng option determins nx,ny,nz grid
                   :  for the cube: default=nbmax
                   : -im option: plot imaginary?
                   : -ishift: shift origin with respect
                   :  to the direct coord. rx,ry,rz
  
 *VALLEY TRANSPORT POSTPROCESSING:
  Use the opt-in Python tools.
  Legacy output formats are unchanged.
  python3 tools/vaspberry_transport.py -h
  python3 tools/wavecar_fukui.py -h
  A full uniform 2D BZ is required for transport.
  Line-mode data are for plotting only.
  Do not use a line for BZ integration.
  A CBM-only result is an incremental contribution.
  Total sigma_xy also needs the valence manifold.
  
 * default: -f WAVECAR -kx 12 -ky 12 -ii 1 -if VBM -kp 2
 * here, VBM is valence band maximum
  
 *Compilation: see Makefile and docs/BUILD.md.
  GNU: make serial; make mpi
  Intel: make ifx; make ifx-mpi
  Classic: make ifort; make ifort-mpi (manual only)
 *WAVECAR compatibility:
  Full-complex RTAG=45200. Builds use byte RECL.
  Intel targets retain -assume byterecl.
  Native input detects byte or word4 producer RECL;
  logical RECL and physical byte stride are reported.
  Invalid, ambiguous or truncated layouts are rejected
  before allocation. No source file is rewritten.
  Kubo CSVs stage to PATH.partial. Final PATH appears
  only after every spin/row and file close succeeds.
  Trace V2 and band V3 declare expected source counts
  and end with result_status=PASS.
