Merge branch 'develop' into parallel_rmn_write

.github/workflows/main.yml

@@ -60,7 +60,7 @@ jobs:
         uses: codecov/codecov-action@v1
       - name: archive test results
         if: ${{ always() }}
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: test-results_parallel=${{ matrix.w90-binary-parallel }}
           path: |

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
         tutorials/tutorial\d\d[-]?\w*/.+win|
         src/.+
       )$
-- repo: https://github.com/pseewald/fprettify
+- repo: https://github.com/fortran-lang/fprettify
   rev: v0.3.3
   hooks:
   - id: fprettify

docs/docs/parameters/generate-parameter-tables.py

@@ -0,0 +1,42 @@
+import xml.etree.ElementTree as ET
+
+
+groups = {
+    'w90': [
+        'disentanglement',
+        'job',
+        'plot',
+        'system',
+        'transport',
+        'wannierise',
+    ],
+    'postw90': [
+        'berry',
+        'boltzwann',
+        'dos',
+        'geninterp',
+        'global',
+        'gyrotropic',
+        'kpath',
+        'kslice',
+    ],
+}
+
+tree = ET.parse('parameters.xml')
+root = tree.getroot()
+
+for tool in ['w90', 'postw90']:
+    for group in groups[tool]:
+        parameters = root.findall(f'./parameter[@tool="{tool}"][@group="{group}"]')
+        with open(f'{tool}-{group}-parameters.csv', 'w') as fp:
+            print('Keyword,Type,Description', file=fp)
+            for parameter in parameters:
+                name = parameter.find('name')
+                type = parameter.find('type')
+                description = parameter.find('description')
+                if 'optional_prefix' in name.attrib:
+                    print(f'[{name.attrib["optional_prefix"]}]{name.text},', end='', file=fp)
+                else:
+                    print(f'{name.text},', end='', file=fp)
+                print(f'{type.text},', end='', file=fp)
+                print(f'"{description.text}"', file=fp)

docs/docs/parameters/postw90-berry-parameters.csv

@@ -0,0 +1,31 @@
+Keyword,Type,Description
+berry,L,"Calculate Berry-type quantities"
+berry_task,S,"List of properties to compute"
+[berry_]kmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh (one or three integers)"
+[berry_]kmesh_spacing,R,"Minimum spacing between \\(k\\) points in Å\\(^{-1}\\)"
+berry_curv_adpt_kmesh,I,"Linear dimension of the adaptively refined \\(k\\)-mesh used to compute the anomalous/spin Hall conductivity"
+berry_curv_adpt_kmesh_thresh,P,"Threshold magnitude of the Berry curvature for adaptive refinement"
+kubo_freq_min,P,"Lower limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV)"
+kubo_freq_max,P,"Upper limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV)"
+kubo_freq_step,R,"Step for increasing the optical frequency in the specified range"
+kubo_eigval_max,P,"Maximum energy eigenvalue included when evaluating the Kubo-Greenwood conductivity, JDOS, shift current and spin Hall conductivity"
+[kubo_]adpt_smr,L,"Use adaptive energy smearing for the optical conductivity, JDOS, shift current and spin Hall conductivity"
+[kubo_]adpt_smr_fac,R,"Adaptive smearing prefactor"
+[kubo_]adpt_smr_max,P,"Maximum allowed value for the adaptive energy smearing (eV)"
+[kubo_]smr_type,S,"Analytical form used for the broadened delta function when computing the optical conductivity, JDOS, shift current and spin Hall conductivity"
+[kubo_]smr_fixed_en_width,P,"Energy smearing (if non-adaptive) for the optical conductivity, JDOS, shift current and spin Hall conductivity (eV)"
+sc_eta,R,"Energy broadening of energy differences in the sum over virtual states when computing shift current"
+sc_phase_conv,I,"Convention for phase factor of Bloch states when computing shift current"
+sc_w_thr,R,"Frequency threshold for speeding up delta function integration when computing shift current"
+sc_use_eta_corr,L,"Use finite-eta correction for computing shift current"
+shc_freq_scan,L,"Calculate Fermi energy scan or frequency scan of spin Hall conductivity"
+shc_method,S,"How to obtain the spin current matrix elements for SHC"
+shc_alpha,I,"The spin current direction of spin Hall conductivity"
+shc_beta,I,"The direction of applied electrical field of spin Hall conductivity"
+shc_gamma,I,"The spin direction of the spin current of spin Hall conductivity"
+shc_bandshift,L,"Rigid bandshift of the conduction bands"
+shc_bandshift_firstband,I,"Index of the first band to shift"
+shc_bandshift_energyshift,P,"Energy shift of the conduction bands (eV)"
+kdotp_kpoint,R,"\\(k\\) point for \\(k\\cdot p\\) expansion (\\(2\\pi/a\\), with \\(a\\) lattice constant in Å)"
+kdotp_num_bands,I,"Number of bands for \\(k\\cdot p\\) expansion"
+kdotp_bands,I,"Band indexes corresponding to the \\(k\\cdot p\\) bands"

docs/docs/parameters/postw90-boltzwann-parameters.csv

@@ -0,0 +1,27 @@
+Keyword,Type,Description
+boltzwann,L,"Calculate Boltzmann transport coefficients"
+[boltz_]kmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh (one or three integers)"
+[boltz_]kmesh_spacing,R,"Minimum spacing between \\(k\\) points in Å\\(^{-1}\\)"
+boltz_2d_dir,S,"Non-periodic direction (for 2D systems only)"
+boltz_relax_time,P,"Relaxation time in fs"
+boltz_mu_min,P,"Minimum value of the chemical potential \\(\\mu\\) in eV"
+boltz_mu_max,P,"Maximum value of the chemical potential \\(\\mu\\) in eV"
+boltz_mu_step,R,"Step for \\(\\mu\\) in eV"
+boltz_temp_min,P,"Minimum value of the temperature \\(T\\) in Kelvin"
+boltz_temp_max,P,"Maximum value of the temperature \\(T\\) in Kelvin"
+boltz_temp_step,R,"Step for \\(T\\) in Kelvin"
+boltz_tdf_energy_step,R,"Energy step for the TDF (eV)"
+boltz_tdf_smr_fixed_en_width,P,"Energy smearing for the TDF (eV)"
+boltz_tdf_smr_type,S,"Smearing type for the TDF"
+boltz_calc_also_dos,L,"Calculate also DOS while calculating the TDF"
+boltz_dos_energy_min,P,"Minimum value of the energy for the DOS in eV"
+boltz_dos_energy_max,P,"Maximum value of the energy for the DOS in eV"
+boltz_dos_energy_step,R,"Step for the DOS in eV"
+[boltz_]smr_type,S,"Smearing type for the DOS"
+[boltz_]adpt_smr,L,"Use adaptive smearing for the DOS"
+[boltz_]adpt_smr_fac,R,"Adaptive smearing prefactor"
+[boltz_]adpt_smr_max,P,"Maximum allowed value for the adaptive energy smearing (eV)"
+[boltz_]fixed_en_width,P,"Energy smearing (if non-adaptive) for the DOS (eV)"
+boltz_bandshift,L,"Rigid bandshift of the conduction bands"
+boltz_bandshift_firstband,I,"Index of the first band to shift"
+boltz_bandshift_energyshift,P,"Energy shift of the conduction bands (eV)"

docs/docs/parameters/postw90-dos-parameters.csv

@@ -0,0 +1,14 @@
+Keyword,Type,Description
+dos,L,"Calculate the density of states and related properties"
+dos_task,S,"List of properties to compute"
+dos_energy_min,P,"Lower limit of the energy range for computing the DOS (eV)"
+dos_energy_max,P,"Upper limit of the energy range for computing the DOS (eV)"
+dos_energy_step,R,"Step for increasing the energy in the specified range (eV)"
+dos_project,I,"List of WFs onto which the DOS is projected"
+[dos_]kmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh (one or three integers)"
+[dos_]kmesh_spacing,R,"Minimum spacing between \\(k\\) points in Å\\(^{-1}\\)"
+[dos_]adpt_smr,L,"Use adaptive smearing for the DOS"
+[dos_]adpt_smr_fac,R,"Adaptive smearing prefactor"
+[dos_]adpt_smr_max,P,"Maximum allowed value for the adaptive energy smearing (eV)"
+[dos_]smr_fixed_en_width,P,"Energy smearing (if non-adaptive) for the DOS (eV)"
+[dos_]smr_type,S,"Analytical form used for the broadened delta function when computing the DOS"

docs/docs/parameters/postw90-geninterp-parameters.csv

@@ -0,0 +1,4 @@
+Keyword,Type,Description
+geninterp,L,"Calculate bands for given set of \\(k\\) points"
+geninterp_alsofirstder,L,"Calculate also first derivatives"
+geninterp_single_file,L,"Write a single file or one for each process"

docs/docs/parameters/postw90-global-parameters.csv

@@ -0,0 +1,18 @@
+Keyword,Type,Description
+kmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh (one or three integers)"
+kmesh_spacing,R,"Minimum spacing between \\(k\\) points in Å\\(^{-1}\\)"
+adpt_smr,L,"Use adaptive smearing"
+adpt_smr_fac,R,"Adaptive smearing prefactor"
+adpt_smr_max,P,"Maximum allowed value for the adaptive energy smearing (eV)"
+smr_type,S,"Analytical form used for the broadened delta function"
+smr_fixed_en_width,P,"Energy smearing (if non-adaptive)"
+num_elec_per_state,I,"Number of electrons per state"
+scissors_shift,P,"Scissors shift applied to the conduction bands (eV) (deprecated)"
+num_valence_bands,I,"Number of valence bands"
+spin_decomp,L,"Decompose various properties into up-spin, down-spin, and possibly spin-flip parts"
+spin_axis_polar,P,"Polar angle of the spin quantization axis (deg)"
+spin_axis_azimuth,P,"Azimuthal angle of the spin quantization axis (deg)"
+spin_moment,L,"Determines whether to evaluate the spin magnetic moment per cell"
+uHu_formatted,L,"Read a formatted `seedname.uHu` file"
+spn_formatted,L,"Read a formatted `seedname.spn` file"
+berry_curv_unit,S,"Unit of Berry curvature"

docs/docs/parameters/postw90-gyrotropic-parameters.csv

@@ -0,0 +1,17 @@
+Keyword,Type,Description
+gyrotropic,L,"Calculate gyrotropic quantities"
+gyrotropic_task,L,"List of properties to compute"
+[gyrotropic_]kmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh (one or three integers)"
+[gyrotropic_]kmesh_spacing,R,"Minimum spacing between \\(k\\) points in Å\\(^{-1}\\)"
+gyrotropic_freq_min,P,"Lower limit of the frequency range for optical rotation (eV)"
+gyrotropic_freq_max,P,"Upper limit of the frequency range for optical rotation (eV)"
+gyrotropic_freq_step,P,"Step for increasing the optical frequency in the specified range"
+gyrotropic_eigval_max,P,"Maximum energy eigenvalue included when evaluating the interband natural optical activity"
+gyrotropic_degen_thresh,P,"threshold to exclude degenerate bands from the calculation"
+[gyrotropic_]smr_type,S,"Analytical form used for the broadened delta function"
+[gyrotropic_]smr_fixed_en_width,P,"Energy smearing (eV)"
+[gyrotropic_]band_list,I,"list of bands used in the calculation"
+gyrotropic_box_center,R,"Center of the integration box, defined (in reduced coordinates) by three real numbers"
+gyrotropic_box_b1,R,"First basis vector, defined (in reduced coordinates) by three real numbers"
+gyrotropic_box_b2,R,"Second basis vector, defined (in reduced coordinates) by three real numbers"
+gyrotropic_box_b3,R,"Third basis vector, defined (in reduced coordinates) by three real numbers"

docs/docs/parameters/postw90-kpath-parameters.csv

@@ -0,0 +1,5 @@
+Keyword,Type,Description
+kpath,L,"Calculate properties along a piecewise linear path in the BZ"
+kpath_task,L,"List of properties to evaluate"
+kpath_num_points,I,"Number of points in the first kpath segment"
+kpath_bands_colour,S,"Property used to colour the energy bands along the path"

docs/docs/parameters/postw90-kslice-parameters.csv

@@ -0,0 +1,9 @@
+Keyword,Type,Description
+kslice,L,"Calculate properties on a slice in the BZ"
+kslice_task,S,"List of properties to evaluate"
+kslice_corner,R,"Position of the corner of the slice"
+kslice_b1,R,"First vector defining the slice"
+kslice_b2,R,"Second vector defining the slice"
+kslice_2dkmesh,I,"Dimensions of the uniform interpolation \\(k\\)-mesh on the slice (one or two integers)"
+kslice_fermi_level,P,"This parameter is not used anymore. Use fermi_energy instead"
+kslice_fermi_lines_colour,S,"Property used to colour the Fermi lines"

docs/docs/parameters/w90-disentanglement-parameters.csv

@@ -0,0 +1,15 @@
+Keyword,Type,Description
+dis_win_min,P,"Bottom of the outer energy window"
+dis_win_max,P,"Top of the outer energy window"
+dis_froz_min,P,"Bottom of the inner (frozen) energy window"
+dis_froz_max,P,"Top of the inner (frozen) energy window"
+dis_froz_proj,L,"To activate projectability disentanglement"
+dis_proj_min,P,"Lower threshold for projectability disentanglement"
+dis_proj_max,P,"Upper threshold for projectability disentanglement"
+dis_num_iter,I,"Number of iterations for the minimisation of $\\Omega_{\\mathrm{I}}$"
+dis_mix_ratio,R,"Mixing ratio during the minimisation of $\\Omega_{\\mathrm{I}}$"
+dis_conv_tol,R,"The convergence tolerance for finding $\\Omega_{\\mathrm{I}}$"
+dis_conv_window,I,"The number of iterations over which convergence of $\\Omega_{\\mathrm{I}}$ is assessed."
+dis_spheres_num,I,"Number of spheres in k-space where disentaglement is performed"
+dis_spheres_first_wann,I,"Index of the first band to be considered a Wannier function"
+dis_spheres,R,"List of centres and radii, for disentanglement only in spheres"

docs/docs/parameters/w90-job-parameters.csv

@@ -0,0 +1,17 @@
+Keyword,Type,Description
+postproc_setup,L,"To output the `seedname.nnkp` file"
+exclude_bands,I,"List of bands to exclude from the calculation"
+select_projections,I,"List of projections to use in Wannierisation"
+auto_projections,L,"To automatically generate initial projections"
+restart,S,"Restart from checkpoint file"
+iprint,I,"Output verbosity level"
+length_unit,S,"System of units to output lengths"
+wvfn_formatted,L,"Read the wavefunctions from a (un)formatted file"
+spin,S,"Which spin channel to read"
+devel_flag,S,"Flag for development use"
+timing_level,I,"Determines amount of timing information written to output"
+optimisation,I,"Optimisation level"
+translate_home_cell,L,"To translate final Wannier centres to home unit cell when writing xyz file"
+write_xyz,L,"To write atomic positions and final centres in xyz file format"
+write_vdw_data,L,"To write data for futher processing by w90vdw utility"
+write_hr_diag,L,"To write the diagonal elements of the Hamiltonian in the Wannier basis to `seedname.wout` (in eV)"

docs/docs/parameters/w90-plot-parameters.csv

@@ -0,0 +1,37 @@
+Keyword,Type,Description
+wannier_plot,L,"Plot the WF"
+wannier_plot_list,I,"List of WF to plot"
+wannier_plot_supercell,I,"Size of the supercell for plotting the WF"
+wannier_plot_format,S,"File format in which to plot the WF"
+wannier_plot_mode,S,"Mode in which to plot the WF, molecule or crystal"
+wannier_plot_radius,R,"Cut-off radius of WF"
+wannier_plot_scale,R,"Scaling parameter for cube files"
+wannier_plot_spinor_mode,S,"Quantity to plot for spinor WF"
+wannier_plot_spinor_phase,L,"Include the “phase” when plotting spinor WF"
+bands_plot,L,"Plot interpolated band structure"
+kpoint_path,P,"K-point path for the interpolated band structure"
+bands_num_points,I,"Number of points along the first section of the k-point path"
+bands_plot_format,S,"File format in which to plot the interpolated bands"
+bands_plot_project,I,"WF to project the band structure onto"
+bands_plot_mode,S,"Slater-Koster type interpolation or Hamiltonian cut-off"
+bands_plot_dim,I,"Dimension of the system"
+fermi_surface_plot,L,"Plot the Fermi surface"
+fermi_surface_num_points,I,"Number of points in the Fermi surface plot"
+fermi_energy,P,"The Fermi energy"
+fermi_energy_min,P,"Lower limit of the Fermi energy range"
+fermi_energy_max,P,"Upper limit of the Fermi energy range"
+fermi_energy_step,R,"Step for increasing the Fermi energy in the specified range"
+fermi_surface_plot_format,S,"File format for the Fermi surface plot"
+hr_plot,L,"This parameter is not used anymore. Use write_hr instead."
+write_hr,L,"Write the Hamiltonian in the WF basis"
+write_rmn,L,"Write the position operator in the WF basis"
+write_bvec,L,"Write to file the matrix elements of the bvectors and their weights"
+write_tb,L,"Write lattice vectors, Hamiltonian, and position operator in WF basis"
+hr_cutoff,P,"Cut-off for the absolute value of the Hamiltonian"
+dist_cutoff,P,"Cut-off for the distance between WF"
+dist_cutoff_mode,S,"Dimension in which the distance between WF is calculated"
+translation_centre_frac,R,"Centre of the unit cell to which final WF are translated"
+use_ws_distance,L,"Improve interpolation using minimum distance between WFs, see Chap. [Some notes on the interpolation](notes_interpolations.md)"
+ws_distance_tol,R,"Absolute tolerance for the distance to equivalent positions."
+ws_search_size,I,"Maximum extension in each direction of the super-cell of the Born-von Karmann cell to search for points inside the Wigner-Seitz cell"
+write_u_matrices,L,"Write $U^{(\\bm{k})}$ and $U^{dis(\\bm{k})}$ matrices to files"

docs/docs/parameters/w90-system-parameters.csv

@@ -0,0 +1,17 @@
+Keyword,Type,Description
+num_wann,I,"Number of WF"
+num_bands,I,"Number of bands passed to the code"
+unit_cell_cart,P,"Unit cell vectors in Cartesian coordinates"
+atoms_cart,P,"Positions of atoms in Cartesian coordinates"
+atoms_frac,R,"Positions of atoms in fractional coordinates with respect to the lattice vectors"
+mp_grid,I,"Dimensions of the Monkhorst-Pack grid of k-points"
+kpoints,R,"List of k-points in the Monkhorst-Pack grid"
+gamma_only,L,"Wavefunctions from underlying ab initio calculation are manifestly real"
+spinors,L,"WF are spinors"
+shell_list,I,"Which shells to use in finite difference formula"
+search_shells,I,"The number of shells to search when determining finite difference formula"
+skip_B1_tests,L,"Check the condition B1 of Ref [@marzari-prb97]"
+nnkpts,I,"Explicit list of nearest-neighbour k-points"
+kmesh_tol,R,"The tolerance to control if two kpoint belong to the same shell"
+higher_order_n,I,"The order of higher-order finite difference to get b-vectors and weights"
+higher_order_nearest_shells,L,"Use the b-vectors on the nearest shells"

docs/docs/parameters/w90-transport-parameters.csv

@@ -0,0 +1,25 @@
+Keyword,Type,Description
+transport,L,"Calculate quantum conductance and density of states"
+transport_mode,S,"Bulk or left-lead_conductor_right-lead calculation"
+tran_win_min,P,"Bottom of the energy window for transport calculation"
+tran_win_max,P,"Top of the energy window for transport calculation"
+tran_energy_step,R,"Sampling interval of the energy values"
+fermi_energy,R,"The Fermi energy"
+tran_num_bb,I,"Size of a bulk Hamiltonian"
+tran_num_ll,I,"Size of a left-lead Hamiltonian"
+tran_num_rr,I,"Size of a right-lead Hamiltonian"
+tran_num_cc,I,"Size of a conductor Hamiltonian"
+tran_num_lc,I,"Number of columns in a left-lead_conductor Hamiltonian"
+tran_num_cr,I,"Number of rows in a conductor_right-lead Hamiltonian"
+tran_num_cell_ll,I,"Number of unit cells in PL of left lead"
+tran_num_cell_rr,I,"Number of unit cells in PL of right lead"
+tran_num_bandc,I,"Half-bandwidth+1 of a band-diagonal conductor Hamiltonian"
+tran_write_ht,L,"Write the Hamiltonian for transport calculation"
+tran_read_ht,L,"Read the Hamiltonian for transport calculation"
+tran_use_same_lead,L,"Left and right leads are the same"
+tran_group_threshold,R,"Distance that determines the grouping of WFs"
+hr_cutoff,P,"Cut-off for the absolute value of the Hamiltonian"
+dist_cutoff,P,"Cut-off for the distance between WF"
+dist_cutoff_mode,S,"Dimension in which the distance between WF is calculated"
+one_dim_axis,S,"Extended direction for a one-dimensional system"
+translation_centre_frac,R,"Centre of the unit cell to which final WF are translated"

docs/docs/parameters/w90-wannierise-parameters.csv

@@ -0,0 +1,23 @@
+Keyword,Type,Description
+num_iter,I,"Number of iterations for the minimisation of $\\Omega$"
+num_cg_steps,I,"During the minimisation of $\\Omega$ the number of Conjugate Gradient steps before resetting to Steepest Descents"
+conv_window,I,"The number of iterations over which convergence of $\\Omega$ is assessed"
+conv_tol,P,"The convergence tolerance for finding $\\Omega$"
+precond,L,"Use preconditioning"
+conv_noise_amp,R,"The amplitude of random noise applied towards end of minimisation procedure"
+conv_noise_num,I,"The number of times random noise is applied"
+num_dump_cycles,I,"Control frequency of check-pointing"
+num_print_cycles,I,"Control frequency of printing"
+write_r2mn,L,"Write matrix elements of $r^2$ between WF to file"
+guiding_centres,L,"Use guiding centres"
+num_guide_cycles,I,"Frequency of guiding centres"
+num_no_guide_iter,I,"The number of iterations after which guiding centres are used"
+trial_step,R,"The trial step length for the parabolic line search during the minimisation of $\\Omega$"
+fixed_step,R,"The fixed step length to take during the minimisation of $\\Omega$, instead of doing a parabolic line search"
+use_bloch_phases,L,"To use phases for initial projections"
+site_symmetry,L,"To construct symmetry-adapted Wannier functions"
+symmetrize_eps,R,"The convergence tolerance used in the symmetry-adapted mode"
+slwf_num,I,"The number of objective WFs for selective localization"
+slwf_constrain,L,"Whether to constrain the centres of the objective WFs"
+slwf_lambda,R,"Value of the Lagrange multiplier for constraining the objective WFs"
+slwf_centres,P,"The centres to which the objective WFs are to be constrained"

docs/mkdocs.yml

@@ -201,6 +201,7 @@ plugins:
       branch: develop
       token: !ENV ["GITHUB_TOKEN"]
   - search
+  - table-reader
   - glightbox
   - bibtex:
       # `bib_file` takes precedence over `bib_dir`, if `bib_file` is defined,

docs/requirements.txt

@@ -5,3 +5,4 @@ mkdocs-git-revision-date-localized-plugin==1.2.6
 mkdocs-git-committers-plugin-2==2.3.0
 mkdocs-bibtex==2.16.0
 mkdocs-glightbox==0.4.0
+mkdocs-table-reader-plugin==2.2.1