3.1. Tutorial

To use H-wave in wave-number space (UHFk), you need to prepare input files:

  1. an input parameter file,

  2. interaction definition files,

before running the program. For the latter, you can use the outputs of external programs such as RESPACK, or you may create the files using the StdFace library.

In the following, we provide a tutorial based on a sample in docs/tutorial/Hubbard/UHFk directory. The interaction definition files can be generated using StdFace library. See Generation of interaction files using StdFace library section for the details.

3.1.1. Create a parameter file

We prepare an input parameter file that contains basic parameters as well as settings on inputs and outputs. A sample file can be found in docs/tutorial/Hubbard/UHFk directory by a filename input.toml. The content of the file is as follows:

[log]
  print_level = 1
  print_step = 10
[mode]
  mode = "UHFk"
[mode.param]
  # 2Sz = 0
  Ncond = 16
  IterationMax = 1000
  EPS = 8
  Mix = 0.5
  RndSeed = 123456789
  # ene_cutoff = 1.0e+2
  T = 0.0
  CellShape = [ 4, 4, 1 ]
  SubShape = [ 2, 2, 1 ]
[file]
[file.input]
  path_to_input = ""
  # initial = "green_init.dat.npz"
[file.input.interaction]
  path_to_input = "./"
  Geometry = "geom.dat"
  Transfer = "transfer.dat"
  CoulombInter = "coulombinter.dat"
[file.output]
  path_to_output = "output"
  energy = "energy.dat"
  eigen = "eigen"
  green = "green"

The file is written in TOML format, and organized by the following sections.

[log] section

This section contains settings on log outputs. print_level sets the verbosity of the standard output, and print_step sets the interval of the outputs.

[mode] section

This section contains settings on calculation mode and basic parameters. We choose mode to be either the coordinate space UHF (UHFr) or the wave-number space UHF (UHFk). The calculation parameters are specified in [mode.param] subsection.

[file] section

[file.input] subsection contains settings on the directory for the input files by path_to_input, and the filename for the initial configuration by initial. If the latter is not specified, a random configuration will be generated.

[file.input.interaction] subsection contains a list of files associated with the geometry information and the interactions distinguished by the keywords.

[file.output] subsection contains filenames for the physical observables such as the energy by energy, for the eigenvalues and eigenvectors of the Hamiltonian by eigen, and for the one-body Green’s functions by green. If they are not specified, the corresponding data will not be outputted.

See Parameter files section for the details.

3.1.2. Create interaction definition files

You need to prepare data files on the geometry information of the lattice, and the coefficients of the interactions required to construct the Hamiltonian. The association between the types of information and the filenames is provided in [file.input.interaction] section.

Geometry

The file associated with Geometry provides the geometrical information of the lattice. An example of the file is shown below.

  1.000000000000   0.000000000000   0.000000000000
  0.000000000000   1.000000000000   0.000000000000
  0.000000000000   0.000000000000   1.000000000000
1
    0.000000000000000e+00     0.000000000000000e+00     0.000000000000000e+00

It contains the primitive vectors (lines 1–3), the number of orbitals (line 4), and the Wannier centers of the orbitals (line 5 onwards).

Transfer, CoulombIntra, CoulombInter, Hund, etc

The file associated with Transfer contains the coefficients of Hamiltonian corresponding to the transfer term of the electron systems. The coefficients of the two-body interaction terms are stored in the files associated with the respective keywords. The defined types include CoulombIntra, CoulombInter, Hund, Ising, Exchange, PairLift, and PairHop, in accordance with the coordinate-space UHF. These files are written in Wannier90(-like) format, as exemplified below.

Transfer in wannier90-like format for uhfk
1
9
 1 1 1 1 1 1 1 1 1
  -1    0    0    1    1  -1.000000000000  -0.000000000000
   0   -1    0    1    1  -1.000000000000  -0.000000000000
   0    1    0    1    1  -1.000000000000   0.000000000000
   1    0    0    1    1  -1.000000000000   0.000000000000

It contains a comment (line 1), the number of orbitals (line 2), the number of cells nrpts of the rectangular cuboid that accommodates translation vectors (line 3), the multiplicity factors (nrpts elements, with 15 elements per line), and the elements of the coefficient matrix.

Each element of the matrix consists of translation vector \(r_x, r_y, r_z\), indices of orbitals \(\alpha, \beta\), and the real and imaginary part of the coefficient.

3.1.3. Run

Once you prepare all the input files, you can perform the calculation by running H-wave with the input parameter file (input.toml in this tutorial) as an argument.

$ hwave input.toml

The calculation starts with the logs as shown below:

2022-12-02 13:48:11,641 INFO qlms: Read definitions from files
2022-12-02 13:48:11,641 INFO qlms.read_input: QLMSkInput: read Gemoetry from ./geom.dat
2022-12-02 13:48:11,641 INFO qlms.read_input: QLMSkInput: read interaction Transfer from ./transfer.dat
2022-12-02 13:48:11,641 INFO qlms.read_input: QLMSkInput: read interaction CoulombInter from ./coulombinter.dat
2022-12-02 13:48:11,641 INFO qlms: Get Hamiltonian information
2022-12-02 13:48:11,641 INFO qlms: Get Green function information
2022-12-02 13:48:11,667 INFO qlms.uhfk: Show parameters
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Cell Shape     = (4, 4, 1)
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Sub Shape      = (2, 2, 1)
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Block          = (2, 2, 1)
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Block volume   = 4
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Num orbit      = 1
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Num orbit eff  = 4
2022-12-02 13:48:11,668 INFO qlms.uhfk:     nspin          = 2
2022-12-02 13:48:11,668 INFO qlms.uhfk:     nd             = 8
2022-12-02 13:48:11,668 INFO qlms.uhfk:     Ncond          = 16
2022-12-02 13:48:11,669 INFO qlms.uhfk:     T              = 0.0
2022-12-02 13:48:11,669 INFO qlms.uhfk:     E_cutoff       = 100.0
2022-12-02 13:48:11,669 INFO qlms.uhfk:     Mix            = 0.5
2022-12-02 13:48:11,669 INFO qlms.uhfk:     RndSeed        = 123456789
2022-12-02 13:48:11,669 INFO qlms.uhfk:     IterationMax   = 1000
2022-12-02 13:48:11,669 INFO qlms.uhfk:     EPS            = 1e-08
2022-12-02 13:48:11,669 INFO qlms.uhfk:     strict_hermite = False
2022-12-02 13:48:11,669 INFO qlms.uhfk:     hermite_tol    = 1e-08
2022-12-02 13:48:11,669 INFO qlms: Start UHF calculation
2022-12-02 13:48:11,670 INFO qlms.uhfk: Start UHFk calculations
2022-12-02 13:48:11,670 INFO qlms.uhfk: step, rest, energy, NCond, Sz
2022-12-02 13:48:11,671 INFO qlms.uhfk: initialize green function with random numbers
2022-12-02 13:48:11,673 INFO qlms.uhfk: 0, 0.015588886, -139.86928, 16, 1.732e-14 
2022-12-02 13:48:11,684 INFO qlms.uhfk: 10, 0.00043101981, 91.751578, 16, -1.029e-11 
2022-12-02 13:48:11,690 INFO qlms.uhfk: 20, 0.00097917933, 92.129093, 16, -0.0001693 
2022-12-02 13:48:11,694 INFO qlms.uhfk: 30, 0.0002328601, -0.49699902, 16, -2.492e-09 
2022-12-02 13:48:11,697 INFO qlms.uhfk: 40, 8.9087396e-07, -2.2626401, 16, -2.354e-14 
2022-12-02 13:48:11,699 INFO qlms.uhfk: UHFk calculation succeeded: rest=9.905239155412216e-09, eps=1e-08.
2022-12-02 13:48:11,699 INFO qlms: Save calculation results.
2022-12-02 13:48:11,699 INFO qlms.uhfk: save_results: save energy in file output/energy.dat
2022-12-02 13:48:11,699 INFO qlms.uhfk: save_results: save eigenvalues and eigenvectors in file output/eigen.dat
2022-12-02 13:48:11,699 INFO qlms.uhfk: save_results: save green function to file output/green.dat
2022-12-02 13:48:11,700 INFO qlms: All procedures are finished.
--------------------------------------------------------------------------------
Statistics
  function                         :  total elapsed  : average elapsed : ncalls
--------------------------------------------------------------------------------
  hwave.solver.uhfk._init_param    :      0.004 msec :      0.004 msec :      1
  hwave.solver.uhfk._init_lattice  :      0.004 msec :      0.004 msec :      1
  hwave.solver.uhfk._init_orbit    :      0.001 msec :      0.001 msec :      1
  hwave.solver.uhfk._check_interaction :      0.176 msec :      0.176 msec :      1
  hwave.solver.uhfk._reshape_geometry :     23.000 msec :     23.000 msec :      1
  hwave.solver.uhfk._reshape_interaction :      0.222 msec :      0.111 msec :      2
  hwave.solver.uhfk._init_interaction :     23.313 msec :     23.313 msec :      1
  hwave.solver.uhfk._show_param    :      2.149 msec :      2.149 msec :      1
  hwave.solver.uhfk.__init__       :     28.129 msec :     28.129 msec :      1
  hwave.solver.uhfk._make_ham_trans :      0.501 msec :      0.501 msec :      1
  hwave.solver.uhfk._make_ham_inter :      0.414 msec :      0.414 msec :      1
  hwave.solver.uhfk._reshape_green :      0.202 msec :      0.202 msec :      1
  hwave.solver.uhfk._initial_green :      0.494 msec :      0.494 msec :      1
  hwave.solver.uhfk._make_ham      :      6.999 msec :      0.143 msec :     49
  hwave.solver.uhfk._diag          :      3.533 msec :      0.072 msec :     49
  hwave.solver.uhfk._green         :      8.698 msec :      0.178 msec :     49
  hwave.solver.uhfk._calc_energy   :      3.960 msec :      0.081 msec :     49
  hwave.solver.uhfk._calc_phys     :      3.559 msec :      0.073 msec :     49
  hwave.solver.uhfk.solve          :     29.349 msec :     29.349 msec :      1
  hwave.solver.uhfk._deflate_green :      0.035 msec :      0.035 msec :      1
  hwave.solver.uhfk._save_green    :      0.202 msec :      0.202 msec :      1
  hwave.solver.uhfk.save_results   :      0.559 msec :      0.559 msec :      1
--------------------------------------------------------------------------------

The logs on the input files are shown, followed by the logs on the iterations of the wave-number space UHF calculation. The program will yield, according to the settings in [file.output] section, the output files energy.dat, eigen.npz, and green.npz in output directory.

See Output files of UHFk section for the details of the output files.

3.1.4. Calculate density of state (hwave_dos)

You can calculate the density of states (DOS) using the post-processing tool, hwave_dos.

hwave_dos uses the libtetrabz library to integrating over the Brillouin zone. libtetrabz can be installed by pip:

$ python3 -m pip install libtetrabz

The tool requires the input parameter file used in the calculation. The following example shows how to calculate the DOS using the sample input file:

$ hwave_dos input.toml

hwave_dos outputs the DOS file, dos.dat in the directory specified by the file.output.path_to_output of the input file. The filename can be changed by --output option:

$ hwave_dos input.toml --output dos.dat

The DOS is calculated in the energy range specified by --ene-window option. If omitted, the energy range is set to \([E_\text{min}-0.2, E_\text{max}+0.2]\) where \(E_\text{min}\) and \(E_\text{max}\) are the minimum and maximum energies obtained by hwave. The number of the energy points for the DOS calculation is specified by --ene-num option (default is 101):

$ hwave_dos input.toml --ene-window -10.0 5.0 --ene-num 201

The --plot option plots the DOS. matplotlib is required:

$ hwave_dos input.toml --plot dos.png