Command-Line Usage

Xatu can be used either as a standalone executable with input files or as a C++ library (API). This section covers the command-line interface (CLI) usage of the xatu binary.

Basic Command

The program expects at least one file describing the system and a second file describing the excitonic properties.

For tight-binding .model files, the command to execute is

xatu [OPTIONS] systemfile.model [excitonfile]

For Wannier90 hamiltonians _tb.dat, the command to execute is

xatu --w90 [filling] [OPTIONS] systemfile.model [excitonfile]

and have a mandatory [filling] parameter, that is the number of filled bands.

For DFT CRYSTAL hamiltonians .outp, the command to execute is

xatu --dft [ncells] [OPTIONS] systemfile.model [excitonfile]

You may optionally specify the number of unit cells to read.

Flags [OPTIONS] can be passed to modify the behavior and output of the simulation.

Available Options

-h, --help Print a help message and exit.

-n, --states nstates Number of exciton states to be written in .states, .eigval files and in the terminal (default: 8).

-t, --encut nstates Overrides -n flag. Print excitons up to the energy cuttof value (defaults to 8 exciton states).

-p, --precision decimals Set the number of decimal places for energy output (default: 6).

-d, --dft [ncells] Indicate that the system file is in CRYSTAL output format. You may optionally specify the number of unit cells to read.

-w, --w90 [filling] Indicate that the system file is in Wannier90 output format. You must specify the number of filled bands.

-eck, --energy / --eigenstates / --kwf Flags to write exciton outputs:

  • -e: energies

  • -c: eigenvectors

  • -k: reciprocal-space densities

-r, --rswf [holeIndex] [-r ncells] Write real-space wavefunction amplitudes. The hole index and number of unit cells can be specified.

-s, --spin Compute the total spin of each exciton. Assumes spin is part of the basis.

-a, --absorption Compute the optical conductivity using the Kubo formalism. Requires kubo_w.in input file in working directory.

-m, --method diag | davidson | sparse Choose BSE solver. Options: * diag: full diagonalization (default) * davidson: iterative Davidson method * sparse: sparse Lanczos method

-b, --bands kpointsfile Diagonalize the Bloch Hamiltonian at k-points specified in a file. Does not compute excitons.

-f, --format model | hdf5 Specify format of the system file. Defaults to model. Note: HDF5 support requires compilation with HDF5=1.

Examples

Run with default output for 8 exciton states:

xatu system.model exciton.config

Run with custom number of states and output eigenstates and absorption:

xatu -s 10 -kace system.model exciton.in

Run with DFT input and extract real-space amplitudes:

xatu -d 3 -r 2 -r 10 system.dft exciton.in