qtcad.atoms.wavefunction module

class qtcad.atoms.wavefunction.Wavefunction(coeff: ndarray, atom_num: int, tb_orbs: str, tb_spin: bool, tb_params_name: str | Tuple[str, ...])

Bases: Wavefunction

Atomistic tight-binding wavefunction.

Attributes:

  • coeff (Numpy.ndarray) – Vector containing the coefficients of the wavefunction in the tight-binding basis.

  • atom_num (int) – Number of atoms in the atomic structure over which the wavefunction is defined.

  • tb_orbs (str) – Atomic orbital basis set used in the tight-binding model, which may either be “sp3” for an \(sp^3\) basis, “sp3s*” for an \(sp^3s^{\star}\) basis, or “sp3d5s*” for an \(sp^3d^5s^{\star}\) basis.

  • tb_spin (bool) – Whether a spin component is included in the tight-binding basis. If False, it is assumed the basis is composed of the atomic orbitals only. If True, it is assumed the basis is twice as large and is composed of the tensor products of the atomic orbitals with the spin up and spin down states.

  • tb_params_name (str or tuple of str) – If a str, name of the tight-binding model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. If a tuple, names of the tight-binding model parameter sets ordered according to precedence; if multiple parameter sets are available for a given atom or pair of atoms, the parameter set is set to the available parameter set whose name first appears in the tuple. The parameter set names include “Niquet”, “Boykin”, “Vogl”, “Klimeck_cb”, “Klimeck_vb”, and “Kim”.

  • orb_num (int) – Number of atomic orbitals per atom.

  • basis_size (int) – Number of tight-binding basis states per atom.

__init__(coeff: ndarray, atom_num: int, tb_orbs: str, tb_spin: bool, tb_params_name: str | Tuple[str, ...]) → None
Parameters:

  • coeff (Numpy.ndarray) – Vector containing the coefficients of the wavefunction in the tight-binding basis.

  • atom_num (int) – Number of atoms in the atomic structure over which the wavefunction is defined.

  • tb_orbs (str) – Atomic orbital basis set used in the tight-binding model, which may either be “sp3” for an \(sp^3\) basis, “sp3s*” for an \(sp^3s^{\star}\) basis, or “sp3d5s*” for an \(sp^3d^5s^{\star}\) basis.

  • tb_spin (bool) – Whether a spin component is included in the tight-binding basis. If False, it is assumed the basis is composed of the atomic orbitals only. If True, it is assumed the basis is twice as large and is composed of the tensor products of the atomic orbitals with the spin up and spin down states.

  • tb_params_name (str or tuple of str) – If a str, name of the tight-binding model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. If a tuple, names of the tight-binding model parameter sets ordered according to precedence; if multiple parameter sets are available for a given atom or pair of atoms, the parameter set is set to the available parameter set whose name first appears in the tuple. The parameter set names include “Niquet”, “Boykin”, “Vogl”, “Klimeck_cb”, “Klimeck_vb”, and “Kim”.

add_spin_to_orbital_state(spin: bool, in_place: bool = False) → Wavefunction | None

Add a spin component to the wavefunction if it is expressed in a spin-less atomic orbital tight-binding basis.

In more technical terms, this method computes the tensor product of the orbital state with a spin state. This method does not alter the wavefunction if the spin component is already included in the basis, namely if tb_spin is True.

Parameters:

  • spin (bool) – Spin component to be added to the orbital state; True for spin up (+) and False for spin down (-).

  • in_place (bool, optional) – Whether the wavefunction is modified in place. If False, a new Wavefunction object is returned. Default: False.

Returns:

None or qtcad.atoms.wavefunction.Wavefunction – Wavefunction object containing the spin component added to the orbital state if in_place is False.

get_prob_on_atoms() → ndarray

Compute the probabilities (associated with the wavefunction) of finding an electron on each atom of the atomic structure.

Returns:

Numpy.ndarray – Vector whose elements are the probabilities of finding an electron on each atom of the atomic structure; the atoms are ordered as in the attribute atom_species of the qtcad.atoms.atoms.Atoms object on which the wavefunction is defined.

get_prob_on_basis_states(verbose: bool = False) → ndarray

Compute the probabilities (associated with the wavefunction) of finding an electron on each type of basis state \((s+\), \(s-\), \(x+\), \(x-\), \(y+\), \(y-\), \(z+\), \(z-\), \(yz+\), \(yz-\), \(xz+\), \(xz-\), \(xy+\), \(xy-\), \((x^2-y^2)+\), \((x^2-y^2)-\), \((3z^2-r^2)+\), \((3z^2-r^2)-\), \(s^{\star}+\), \(s^{\star}-)\).

This method falls back on qtcad.atoms.schrodinger.Wavefunction.get_prob_on_orbitals() if tb_spin is False.

Parameters:

verbose (bool, optional) – Whether the probabilities are printed. Default: False

Returns:

Numpy.ndarray – Vector whose elements are the probabilities of finding an electron on each type of basis state ordered as \(\{s+\), \(s-\), \(x+\), \(x-\), \(y+\), \(y-\), \(z+\), \(z-\}\) for an \(sp^3\) basis, \(\{s+\), \(s-\), \(x+\), \(x-\), \(y+\), \(y-\), \(z+\), \(z-\), \(s^{\star}+\), \(s^{\star}-\}\) for an \(sp^3s^{\star}\) basis, and \(\{s+\), \(s-\), \(x+\), \(x-\), \(y+\), \(y-\), \(z+\), \(z-\), \(yz+\), \(yz-\), \(xz+\), \(xz-\), \(xy+\), \(xy-\), \((x^2-y^2)+\), \((x^2-y^2)-\), \((3z^2-r^2)+\), \((3z^2-r^2)-\), \(s^{\star}+\), \(s^{\star}-\}\) for an \(sp^3d^5s^{\star}\) basis.

get_prob_on_chemical_species(atoms: Atoms, verbose: bool = False) → dict

Compute the probabilities (associated with the wavefunction) of finding an electron on each chemical species in the atomic structure.

Parameters:

  • atoms (qtcad.atoms.atoms.Atoms) – Atomic structure on which the wavefunction is defined.

  • verbose (bool, optional) – Whether the probabilities are printed. Default: False

Returns:

dict – Dictionary containing the probabilities of finding an electron on each chemical species in the atomic structure.

get_prob_on_orbitals(verbose: bool = False) → ndarray

Compute the probabilities (associated with the wavefunction) of finding an electron on each type of atomic orbital \((s\), \(x\), \(y\), \(z\), \(yz\), \(xz\), \(xy\), \(x^2-y^2\), \(3z^2-r^2\), and \(s^{\star})\).

Parameters:

verbose (bool, optional) – Whether the probabilities are printed. Default: False

Returns:

Numpy.ndarray – Vector whose elements are the probabilities of finding an electron on each type of atomic orbital ordered as \(\{s\), \(x\), \(y\), \(z\}\) for an \(sp^3\) basis, \(\{s\), \(x\), \(y\), \(z\), \(s^{\star}\}\) for an \(sp^3s^{\star}\) basis, and \(\{s\), \(x\), \(y\), \(z\), \(yz\), \(xz\), \(xy\), \(x^2-y^2\), \(3z^2-r^2\), \(s^{\star}\}\) for an \(sp^3d^5s^{\star}\) basis.

get_prob_on_spin_states(verbose: bool = False) → ndarray

Compute the probabilities (associated with the wavefunction) of finding an electron on the spin up and spin down states.

This method returns an empty array if tb_spin is False.

Parameters:

verbose (bool, optional) – Whether the probabilities are printed. Default: False

Returns:

Numpy.ndarray – 2-element vector whose elements are the probabilities of finding an electron on the spin states, ordered as spin up and spin down.

normalize() → None

Normalize the wavefunction by dividing it by its norm.

save(path: str, verbose: bool = True) → None

Save the wavefunction to a file.

Parameters:

  • path (str) – Path to the file in which to save the wavefunction; all file extensions are accepted.

  • verbose (bool, optional) – Whether messages regarding the file path and size are printed. Default: True.

qtcad.atoms.wavefunction.load(path: str) → Wavefunction

Load a wavefunction from a file.

Parameters:

path (str) – Path to the file from which to load the wavefunction.

Returns:

qtcad.atoms.wavefunction.Wavefunction – Wavefunction object loaded from the file.