qstack.spahm.compute_spahm

Eigenvalue SPAHM computation.

qstack.spahm.compute_spahm.ext_field_generator(mol, field)[source]

Generate external electric field Hamiltonian gradient function.

Creates a function that computes derivatives of the external field interaction Hamiltonian (H_ext) with respect to nuclear coordinates for each atom.

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • field (numpy ndarray or None) – 3-component uniform electric field vector (∇φ) in atomic units. If None, treated as zero field.

Returns:

Function field_deriv(iat) that takes atom index and returns

3D array (3, nao, nao) of dH_ext/dr[iat] - external field Hamiltonian gradient for atom iat.

Return type:

callable

qstack.spahm.compute_spahm.get_guess_orbitals(mol, guess, xc='pbe', field=None, return_ao_dip=False)[source]

Compute MO energies and vectors using an initial guess Hamiltonian.

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • guess (callable or str) – Guess Hamiltonian method function (from get_guess) or ‘huckel’.

  • xc (str) – Exchange-correlation functional name. Defaults to ‘pbe’.

  • field (numpy ndarray, optional) – 3-component uniform electric field vector (∇φ) in atomic units. Defaults to None.

  • return_ao_dip (bool) – If True, also returns AO dipole integrals. Defaults to False.

Returns:

Depending on return_ao_dip: - If False: (e, v) where:

  • e (numpy ndarray): 1D array (nao,) of orbital eigenvalues.

  • v (numpy ndarray): 2D array (nao, nao) of MO coefficients.

  • If True: (e, v, ao_dip) where ao_dip is 3D array (3, nao, nao) of AO dipole integrals

    if field is not None, else None.

Return type:

tuple

Raises:

NotImplementedError – If field is specified with Hückel guess.

qstack.spahm.compute_spahm.get_guess_orbitals_grad(mol, guess, field=None)[source]

Compute guess Hamiltonian eigenvalues and their nuclear/field gradients.

Calculates orbital energies and their derivatives with respect to both nuclear coordinates (for geometry optimization/force calculations) and electric field (for response properties).

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • guess (tuple) – Pair (hamiltonian_func, gradient_func) from get_guess_g().

  • field (numpy ndarray, optional) – 3-component uniform electric field (∇φ) in atomic units. Defaults to None.

Returns:

(e, de_dr, de_dfield) where: - e (numpy ndarray): 1D array (nao,) of orbital eigenvalues in Eh. - de_dr (numpy ndarray): 3D array (nao, natm, 3) of eigenvalue gradients in Eh/bohr. - de_dfield (numpy ndarray or None): 2D array (nao, 3) of eigenvalue derivatives

w.r.t. electric field in Eh/a.u., or None if field is None.

Return type:

tuple

qstack.spahm.compute_spahm.get_spahm_representation(mol, guess_in, xc='pbe', field=None)[source]

Compute the ε-SPAHM molecular representation.

Reference:

A. Fabrizio, K. R. Briling, C. Corminboeuf, “SPAHM: the spectrum of approximated Hamiltonian matrices representations”, Digital Discovery 1 286-294 (2022), doi:10.1039/d1dd00050k

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • guess_in (str) – Guess method name (e.g., ‘LB’, ‘SAD’, ‘core’, ‘GWH’).

  • xc (str) – Exchange-correlation functional name. Defaults to ‘pbe’.

  • field (numpy ndarray, optional) – 3-component uniform electric field (∇φ) in atomic units. Defaults to None.

Returns:

SPAHM representation consisting of occupied orbital eigenvalues. - Closed-shell: 1D array of shape (n_occupied,) in Eh. - Open-shell: 2D array of shape (2, n_alpha) for alpha and beta orbitals (padded by zeros).

Return type:

numpy ndarray

qstack.spahm.compute_spahm.get_spahm_representation_grad(mol, guess_in, field=None)[source]

Compute SPAHM representation and its nuclear/field gradients for force/response calculations.

Calculates the SPAHM descriptor (occupied orbital energies) along with derivatives needed for molecular dynamics, geometry optimization, and response properties.

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • guess_in (str) – Guess method name with gradient support (‘core’ or ‘lb’).

  • field (numpy ndarray, optional) – 3-component uniform electric field (∇φ) in atomic units. Defaults to None.

Returns:

(spahm, spahm_grad, spahm_field_grad) where: - spahm (numpy ndarray): SPAHM representation - occupied orbital energies in Eh.

Shape: (n_occ,) for closed-shell or (2, n_alpha) for open-shell.

  • spahm_grad (numpy ndarray): Nuclear gradients of SPAHM in Eh/bohr.

    Shape: (n_occ, natm, 3) or (2, n_alpha, natm, 3).

  • spahm_field_grad (numpy ndarray or None): Electric field gradients in Eh/a.u.

    Shape: (n_occ, 3) or (2, n_alpha, 3), or None if field is None.

Return type:

tuple