Parameter Settings for Calculating GaAs EPC Matrix

[3532564593]

Dear Professor Zhong,

I have a question regarding the parameter settings in HamEPC, specifically for the final step of calculating the EPC (Electron-Phonon Coupling) matrix of GaAs. I’ve attached a figure below for reference – could you clarify the key parameters involved in this calculation?

Best regards,
Jiaxin Han

[QuantumLab-ZY]

Below is a comprehensive guide to the configuration parameters:

1. basic: (basic inputs)

• cal_mode: 'epc'

  • Meaning: calculation mode. Possible values are 'mobility', 'superconduct', 'band', 'phonon', 'epc' (the program uses this to decide which blocks to read next and which initialization functions to call).
  • Here 'epc' indicates that an electron–phonon coupling (EPC) related calculation will be performed (it will call _initial_phonon / _initial_epc / _initial_dispersion, etc.).

• graph_data_path_uc: ./demo/graph_data.npz

  • Meaning: path to a .npz file that contains the graph data related to the tight-binding / Hamiltonian (the program loads this via np.load in _initial_basic and expects a 'graph' field containing pos, Hon, Hoff, Son, Soff, Mon, Moff, cell, cell_shift, etc.).
  • Format/requirements: the graph saved in the npz is an object (scripted/serialized); see the code for how graph_data is accessed (e.g., graph_data.pos, graph_data.Hon). It must be readable by np.load(..., allow_pickle=True).

• nao_max: 13

  • Meaning: maximum number of orbitals per atom (number of atomic orbitals), used for reshaping/constructing matrix shapes. Used to set the dimensions of H/S and other unit-cell matrices.
  • Type: integer.

• Ham_type: siesta

  • Meaning: the source/format type of the Hamiltonian. The code supports 'openmx', 'honpas', 'siesta' (this affects electron counting, matrix parsing, etc.).
  • Type: string.

• outdir: './epc_results/'

  • Meaning: output directory where the program will write results (e.g., epc.dispersion, a2f.dat).
  • Type: string (relative or absolute path).

2. phonon: (related to phonopy / force constants)

• supercell_matrix: [[2, 0, 0], [0, 2, 0], [0, 0, 2]]

  • Meaning: phonopy's supercell_matrix, defines how many times the unit cell is expanded into a supercell (here a 2x2x2 supercell).
  • Type: 3x3 integer matrix (usually diagonal with expansion factors).

• primitive_matrix: [[1, 0, 0], [0, 1, 0], [0, 0, 1]]

  • Meaning: primitive matrix specifying the transformation from the unit cell to the primitive cell (identity means the unit cell is already primitive).
  • Type: 3x3 integer matrix.

• unitcell_filename: ./demo/POSCAR

  • Meaning: unitcell file for phonopy.load (usually a VASP POSCAR or another format supported by phonopy), used to construct the phonon object.
  • Requirement: the path must be valid or phonopy.load will fail.

• force_sets_filename: ./demo/FORCE_SETS

  • Meaning: path to the force (force sets) file read by phonopy, used to build the dynamical matrix (force constants). Usually generated by DFT calculations.
  • Format: phonopy FORCE_SETS standard format.

3. epc: (EPC-specific file paths)

• grad_mat_path: ./demo/grad_mat.npy

  • Meaning: path to a numpy file storing the gradient matrix (the derivatives of the electronic Hamiltonian with respect to atomic displacements, i.e., the electron–phonon coupling matrix elements).
  • Expected data structure / layout (shapes accessed by the program):
    • The code accesses grad_mat like self.grad_mat[i_m, i_n, :, :, ia, k]
    • Therefore a typical shape for grad_mat is (ncells_cut, ncells_cut, nao, nao, natoms_uc, 3)
      • ncells_cut: number of cells after applying cell_range_cut filtering in _initial_epc
      • nao: nao_max or the actual number of occupied orbitals
      • natoms_uc: number of atoms in the unit cell
      • 3: three Cartesian displacement components
  • Note: the program performs heavy memory accesses / parallel reads on grad_mat; the file must match the generation script exactly.

• mat_info_rc_path: ./demo/mat_info_rc.npy

  • Meaning: stores mapping information for the supercell / reduced cell (mat_info_rc), loaded in _initial_epc as self.mat_info_sc.
  • Typical fields in mat_info_rc (used directly by the code):
    • 'cell_shift_array': array of all cell shift vectors (shape: (ncells, 3))
    • 'cell_index_map': cell index map
    • 'p2s_indices', 's2u_list': atom index mappings between primitive / supercell representations
    • 'cell_shift_of_each_atom', etc.
  • This information is used to fold/index the global gradient matrix onto the reduced cell and to construct phase factors.

4. dispersion: (high-symmetry path / band projections)

• high_symmetry_points:

  • Example contents:
    • [0.500, 0.000, 0.500]
    • [0.000, 0.000, 0.000]
    • [0.500, 0.500, 0.500]
  • Meaning: a sequence of high-symmetry k-points in fractional coordinates (with respect to reciprocal-lattice basis), typically used to draw band/phonon paths (e.g., Γ, X, L).
  • Format: each point is [kx, ky, kz]; values usually in [0,1) or -0.5..0.5, representing components relative to the lattice basis. (In the code, _get_hsk_path will use these as nodes for the k-point path passed to kpoints_generator.)

• high_symmetry_labels: ["X", "Γ", "L"]

  • Meaning: labels corresponding to high_symmetry_points for plotting annotations.
  • Note: the program formats these labels into LaTeX-style strings when plotting (rf'${lb}$').

• nks_path: 200

  • Meaning: number of k-points inserted between each pair of high-symmetry nodes (i.e., how many sample points between two nodes) used to generate a continuous path for plotting dispersion.
  • Type: integer (larger => denser path but more computation).

• dispersion_select_index: "4,5"

  • Meaning (depending on cal_mode):
    • In the cal_mode == 'epc' branch, dispersion_select_index must specify two integers: the initial-band index and the final-band index used in EPC calculations (the input is human-friendly 1-based? the code will subtract 1 to convert to 0-based).
    • In your example "4,5": the program will parse this to np.array([int(each)-1 ...]) -> [3,4], i.e., initial state is band 4 (internal index 3) and final state is band 5 (internal index 4).
  • Details:
    • In other modes ('band' or 'phonon') it can also be used to select which bands/branches to plot; range syntax ("1-10" or "4,5", etc.) is supported and the code tries to parse into integer arrays / intervals.

• epc_path_fix_k: [0.0, 0.0, 0.0]

  • Meaning: the fixed electronic k-point (fractional coordinates) used in EPC path calculations. In EPC_cal_path this is used as the initial k_fix (the program converts fractional to Cartesian and then uses k_fix + q).
  • In your example this is the Γ point ([0,0,0]).

Additional notes (how the program uses these / units)

• k / q are usually provided in fractional coordinates; the program converts between fractional and Cartesian using _frac2car / _car2frac together with self.graph_data.lat_per_inv and self.graph_data.latt. Some constructions omit a 2π factor or leave it to Hamcts (note the source code comment “2*pi constant is missed.” — be cautious when using these).
• Energies: the code internally computes many energies in Hartree and converts at input/output points; for example, _phonon_cal returns frequencies that are multiplied by Hamcts.PHONOPYtoHARTREE; final outputs for plotting EPC convert to meV (epcs * Hamcts.HARTREEtoMEV).
• Meaning of grad_mat elements: grad_mat stores dH/dR (the derivative of the Hamiltonian with respect to atomic displacement) and is the core data for EPC calculations; it must correspond to the basis/projection form of the Hamiltonian you used (siesta/openmx, etc.).
• mat_info_rc provides cell_shift mappings: the program uses arrays such as self.nbr_shift_of_cell_sc when computing phase factors (see EPC_cal_path for phase calculations).

Common issues / notes

• All file paths must be readable: graph_data.npz, grad_mat.npy, mat_info_rc.npy, POSCAR, FORCE_SETS, etc., must exist and be readable on the running (master) node.
• grad_mat and mat_info_rc must be generated to match the grid / orbital ordering of graph_data exactly, otherwise EPC results will be incorrect (phase and index correspondences are very sensitive).
• dispersion_select_index is entered using 1-based human indexing (the program internally subtracts 1), but you must ensure you selected the correct bands (CBM/VBM indices may be inferred from graph_data.num_electrons in _initial_basic).
• If you want the code to auto-generate a high-symmetry path (so you don’t fill in high_symmetry_points manually), omit those fields in the config; the program will attempt to generate a path using pymatgen’s KPathSeek (some structures may fail and raise an error).

[3532564593]

Thank you for the detailed explanation, I’ve clearly grasped all the parameter settings and can proceed smoothly now.