sk_builder.matrix_constructors

Helper functions for generating matrix representations.

This module provides functions implementing the building blocks for the construction of Hamiltonian.

@private

Copyright © 2022-2024 HQS Quantum Simulations GmbH. All Rights Reserved.

def get_alloy_shifts( sk_params: dict, sample: numpy.ndarray, species_id_to_str: dict[int, str]) -> numpy.ndarray:

Get level shifts for alloys.

Currently we have a very simple method implemented, which uses constant shifts provided by the Slater-Koster parameters.

NOTE: This is very simplistic, but implementing this better requires some actual research ...

Arguments:
  • sk_params (dict): Dictionary with Slater-Koster parameters.
  • sample (np.ndarray): Numpy array containing specific sample (species defined by integers).
  • species_id_to_str (dict[int, str]): Dictionary mapping species indices to names names.
Returns:

np.ndarray: Species dependent level shifts.

def get_alloy_shifts_distribution( sk_params: dict, distribution: numpy.ndarray, species_id_to_str: dict[int, str]) -> numpy.ndarray:

Get level shifts for alloys.

Currently we have a very simple method implemented, which uses constant shifts provided by the Slater-Koster parameters.

NOTE: This is very simplistic, but implementing this better requires some actual research ...

Arguments:
  • sk_params (dict): Dictionary with Slater-Koster parameters.
  • distribution (np.ndarray): Numpy array containing distribution for each atom.
  • species_id_to_str (dict[int, str]): Dictionary mapping species indices to names names.
Returns:

np.ndarray: Species dependent level shifts.

def get_diagonal_sample( sk_params: dict, sample: numpy.ndarray, species_id_to_str: dict[int, str], verbose: bool = False) -> numpy.ndarray:

Return diagonal of Hamiltonian.

Arguments:
  • sk_params (dict): Dictionary with Slater-Koster parameters.
  • sample (np.ndarray): Numpy array containing specific sample (species defined by integers).
  • species_id_to_str(dict[int, str]): Dictionary mapping species indices (int) to species symbol (str).
  • verbose (bool): Flag triggering output. Defaults to False.
Returns:

np.ndarray: Diagonal of Hamiltonian.

def get_diagonal_distribution( sk_params: dict, distribution: numpy.ndarray, species_id_to_str: dict[int, str], verbose: bool = False) -> numpy.ndarray:

Return diagonal of Hamiltonian.

Arguments:
  • sk_params (dict): Dictionary with Slater-Koster parameters.
  • distribution (np.ndarray): Numpy array containing distribution for each atom.
  • species_id_to_str(dict[int, str]): Dictionary mapping species indices (int) to species symbol (str).
  • verbose (bool): Flag triggering output. Defaults to False.
Returns:

np.ndarray: Diagonal of Hamiltonian.

def get_off_diagonals_sample( sk_params: dict, uc_pos: numpy.ndarray, lattice_vectors: numpy.ndarray, size: tuple[int, ...], boundary_phases: tuple[complex, ...], bond_matrices: dict[tuple[int, ...], scipy.sparse._coo.coo_array], species_id_to_str: dict[int, str], sample: numpy.ndarray, k_point: numpy.ndarray, region: str = 'all', precision: int = 4, verbose: bool = False) -> list[sk_builder.models.OffDiagonalContribution]:

Return list of components for offdiagonal contributions to Hamiltonian.

Based on an explicit sample the off-diagonal contributions to the Hamiltonian are clustered into identical bonds to allow for an efficient computation using an operator implementation.

NOTE: Bloch boundary phases are only applied across periodic dimensions.

NOTE: Identical bonds are determined using k-means clustering where the optimal number of clusters is determined using the silhouette score (upper limit for number of clusters is determined by the number of distinct bonds specified by the user). The precision parameter is used to round the displacement vectors identified by the clustering algorithm ("cluster centers") to the given decimal precision.

Arguments:
  • sk_params (dict): Dictionary holding Slater-Koster parameters.
  • uc_pos (np.ndarray): Position of atoms within unit cell.
  • lattice_vectors (np.ndarray): Lattice vectors spanning the unit cell.
  • size (tuple[int, ...]): Number of unit cells along each lattice vector.
  • boundary_phases (tuple[complex, ...]): complex(1) for periodic dimensions, otherwise complex(0) (hard-wall).
  • bond_matrices (dict[tuple[int, ...], SPM.coo_array]): Abstract (sparse) connectivity (bond) matrix between atoms in unit cells shifted by a tuple of (t1, t2, t3) representing a translation.
  • species_id_to_str (dict[int, str]): Mapping species id (int) to species symbol (str)
  • sample (np.ndarray): Linear random sample of species ids (alloy configuration).
  • k_point (np.ndarray): k-point determining Bloch boundary phases for periodic dimensions.
  • region (str): Can be 'all', 'bulk' or 'boundary'. Defaults to 'all'.
  • precision (int): Number of decimal places to round distances. Defaults to 4.
  • verbose (bool): Flag triggering output. Defaults to False.
Returns:

list[OffDiagonalContribution]: List of off-diagonal contributions to the Hamiltonian.

Raises:
  • ValueError: If inconsistencies are detected -> Should never happen, indicates bug!
def get_off_diagonals_distribution( sk_params: dict, uc_pos: numpy.ndarray, lattice_vectors: numpy.ndarray, size: tuple[int, ...], boundary_phases: tuple[complex, ...], bond_matrices: dict[tuple[int, ...], scipy.sparse._coo.coo_array], species_id_to_str: dict[int, str], distribution: numpy.ndarray, k_point: numpy.ndarray, number_discretized_joint_probabilities: int, region: str = 'all', precision: int = 4, verbose: bool = False) -> list[sk_builder.models.OffDiagonalContribution]:

Return list of components for offdiagonal contributions to Hamiltonian.

Based on the distribution for each species the off-diagonal contributions to the Hamiltonian are clustered into identical bonds to allow for an efficient computation using an operator implementation. Furthermore, in contrast to the implementation for an explicit sample, the joint distribution for bonds a clustered employing k-means to discretize the probability joint distribution for all bonds to keep the number of terms in the off-diagonal contribution to the Hamiltonian as low as possible. The upper limit for the number of discretized joint probabilities can be controlled by the user.

NOTE: Bloch boundary phases are only applied across periodic dimensions.

NOTE: Identical bonds are determined using k-means clustering where the optimal number of clusters is determined using the silhouette score (upper limit for number of clusters is determined by the number of distinct bonds specified by the user). The precision parameter is used to round the displacement vectors identified by the clustering algorithm ("cluster centers") to the given decimal precision.

Arguments:
  • sk_params (dict): Dictionary holding Slater-Koster parameters.
  • uc_pos (np.ndarray): Position of atoms within unit cell.
  • lattice_vectors (np.ndarray): Lattice vectors spanning the unit cell.
  • size (tuple[int, ...]): Number of unit cells along each lattice vector.
  • boundary_phases (tuple[complex, ...]): complex(1) for periodic dimensions, otherwise complex(0) (hard-wall).
  • bond_matrices (dict[tuple[int, ...], SPM.coo_array]): Abstract (sparse) connectivity (bond) matrix between atoms in unit cells shifted by a tuple of (t1, t2, t3) representing a translation.
  • species_id_to_str (dict[int, str]): Mapping species id (int) to species symbol (str)
  • distribution (np.ndarray): Numpy array containing distribution for each atom.
  • k_point (np.ndarray): k-point determining Bloch boundary phases for periodic dimensions.
  • number_discretized_joint_probabilities (int): Maximum number of discretized joint probabilities for clustering analysis.
  • region (str): Can be 'all', 'bulk' or 'boundary'. Defaults to 'all'.
  • precision (int): Number of decimal places to round distances. Defaults to 4.
  • verbose (bool): Flag triggering output. Defaults to False.
Returns:

list[OffDiagonalContribution]: List of off-diagonal contributions to the Hamiltonian.

Raises:
  • ValueError: If inconsistencies are detected -> Should never happen, indicates bug!
def get_translation( translation: tuple[int, ...], size: tuple[int, ...], boundary_phases: tuple[complex, ...], bloch_phases: numpy.ndarray, bulk: complex = (1+0j), region: str = 'all') -> tuple[scipy.sparse._coo.coo_array, numpy.ndarray]:

Return matrix for given translation.

Arguments:
  • translation (tuple[int, ...]): Translation along each direction.
  • size (tuple[int, ...]): Linear size along each direction
  • boundary_phases (tuple[complex, ...]): (Bloch) boundary phase jump along each direction.
  • bloch_phases (tuple[complex, ...]): Lattice vectors doted into k point wave vector.
  • bulk (complex): Complex phase associated to all bulk strides. Defaults to 1.
  • region (str): Can be 'boundary', 'bulk' and 'all'. Defaults to 'all'.
Returns:

tuple[SPM.coo_array, np.ndarray]: Tuple of SPM.coo_array: Sparse matrix representing translation. np.ndarray: array containing shifts in lattice vectors for each bond.

def get_off_diagonal_term( get_off_diagonal_matrices: Callable[[], tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]], phases: numpy.ndarray, id_from: numpy.ndarray, id_to: numpy.ndarray, linear_size: int, displacement: numpy.ndarray) -> sk_builder.models.OffDiagonalContribution:

Constructs a term for the off-diagonal contribution to the Hamiltonian.

This is a driver routine, use by get_off_diagonal_term_sample and get_off_diagonal_term_distribution, to construct a contribution to the off-diagonal of the Hamiltonian. The get_off_diagonal_matrices function provides the necessary matrices for a given bond.

Arguments:
  • get_off_diagonal_matrices (Callable[[], tuple[np.ndarray, np.ndarray, np.ndarray]]): Generator for matrices describing the bond.
  • phases (np.ndarray): Array of phases for each bond.
  • id_from (np.ndarray): Array of "from" indices for each bond.
  • id_to (np.ndarray): Array of "to" indices for each bond.
  • linear_size (int): Number of atoms in the sample.
  • displacement (np.ndarray): Displacement vector of the bond.
Returns:

OffDiagonalContribution: Contribution to the off-diagonals of the Hamiltonian.

def get_off_diagonal_term_sample( sk_params: dict, name_from: str, name_to: str, displacement: numpy.ndarray, phases: numpy.ndarray, id_from: numpy.ndarray, id_to: numpy.ndarray, linear_size: int) -> sk_builder.models.OffDiagonalContribution:

Constructs a term for the off-diagonal contribution to the Hamiltonian.

The term is characterized by the species from which the bond originates, the species to which it leads and the displacement between the locations of the two atoms.

The phases and "from" / "to" indices run over all equivalent bonds, fitting the characteristics described above.

Arguments:
  • sk_params (dict): Dictionary holding Slater-Koster parameters.
  • name_from (str): Species name from which the bond originates.
  • name_to (str): Species name to which the bond leads.
  • displacement (np.ndarray): Displacement vector of the bond.
  • phases (np.ndarray): Array of phases for each bond.
  • id_from (np.ndarray): Array of "from" indices for each bond.
  • id_to (np.ndarray): Array of "to" indices for each bond.
  • linear_size (int): Number of atoms in the sample.
Returns:

OffDiagonalContribution: Contribution to the off-diagonals of the Hamiltonian.

def get_off_diagonal_term_distribution( sk_params: dict, species_id_to_str: dict[int, str], joint_probability: numpy.ndarray, displacement: numpy.ndarray, phases: numpy.ndarray, id_from: numpy.ndarray, id_to: numpy.ndarray, linear_size: int) -> sk_builder.models.OffDiagonalContribution:

Constructs averaged term for the off-diagonal contribution to the Hamiltonian.

The term is characterized by joint probability of the species from which the bond originates and to which it leads and the displacement between the locations of the two atoms.

The phases and "from" / "to" indices run over all equivalent bonds, fitting the characteristics described above.

Arguments:
  • sk_params (dict): Dictionary holding Slater-Koster parameters.
  • species_id_to_str (dict[int, str]): Mapping species id (int) to species symbol (str)
  • joint_probability (np.ndarray): Joint probabilities for finding specific species on the bond of size (# species)^2.
  • displacement (np.ndal contributionrray): Displacement vector of the bond.
  • phases (np.ndarray): Array of phases for each bond.
  • id_from (np.ndarray): Array of "from" indices for each bond.
  • id_to (np.ndarray): Array of "to" indices for each bond.
  • linear_size (int): Number of atoms in the sample.
Returns:

OffDiagonalContribution: Contribution to the off-diagonals of the Hamiltonian.

def parse_bond_matrices( bond_matrices: dict[tuple[int, ...], scipy.sparse._coo.coo_array], get_translation: Callable[[tuple[int, ...]], tuple[scipy.sparse._coo.coo_array, numpy.ndarray]], lattice_vectors: numpy.ndarray, pos: numpy.ndarray, distribution: Optional[numpy.ndarray] = None) -> tuple[int, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]:

Parsing bond matrices and translations to get ingredients for operator analysis.

Arguments:
  • bond_matrices (dict[tuple[int, ...], SPM.coo_array]): Dictionary of bond matrices.
  • get_translation (Callable[[tuple[int, ...]], tuple[SPM.coo_array, np.ndarray]]): Function turning translation tuple into "expansion" matrix for given translation.
  • lattice_vectors (np.ndarray): Lattice vectors.
  • pos (np.ndarray): Positions of atoms.
  • distribution (Optional[np.ndarray], optional): Probability distribution of atomic species for each atomic position. Defaults to None.
Returns:

tuple[int, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]: Ingredients for operator analysis.