10.21.6. pbc.tdscf — TDHF and TDDFT with PBCs

The pbc.tdscf implements the time-dependent Hartree-Fock and time-dependent density functional theory with periodic boundary conditions. It is analogous to the tddft module.

10.21.6.2. Program reference

pyscf.pbc.tdscf.rhf.CIS

alias of pyscf.pbc.tdscf.rhf.TDA

pyscf.pbc.tdscf.rhf.RPA

alias of pyscf.pbc.tdscf.rhf.TDHF

class pyscf.pbc.tdscf.rhf.TDA(mf)[source]
gen_vind(mf)[source]

Compute Ax

class pyscf.pbc.tdscf.rhf.TDHF(mf)[source]
gen_vind(mf)[source]

Generate function to compute

[ A B][X] [-B -A][Y]

pyscf.pbc.tdscf.rhf.TDRHF

alias of pyscf.pbc.tdscf.rhf.TDHF

This and other _slow modules implement the time-dependent Hartree-Fock procedure. The primary performance drawback is that, unlike other ‘fast’ routines with an implicit construction of the eigenvalue problem, these modules construct TDHF matrices explicitly via an AO-MO transformation, i.e. with a O(N^5) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TDHF roots in a reliable fashion without any issues related to the Davidson procedure. Several variants of TDHF are available:

  • pyscf.tdscf.rhf_slow: the molecular implementation;

  • (this module) pyscf.pbc.tdscf.rhf_slow: PBC (periodic boundary condition) implementation for RHF objects of pyscf.pbc.scf modules;

  • pyscf.pbc.tdscf.krhf_slow_supercell: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points but has a overhead due to an effective construction of a supercell.

  • pyscf.pbc.tdscf.krhf_slow_gamma: A Gamma-point calculation resembling the original pyscf.pbc.tdscf.krhf module. Despite its name, it accepts KRHF objects with an arbitrary number of k-points but finds only few TDHF roots corresponding to collective oscillations without momentum transfer;

  • pyscf.pbc.tdscf.krhf_slow: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points and employs k-point conservation (diagonalizes matrix blocks separately).

class pyscf.pbc.tdscf.rks.TDDFTNoHybrid(mf)[source]
gen_vind(mf)[source]

Compute Ax

pyscf.pbc.tdscf.rks.tddft(mf)[source]

Driver to create TDDFT or TDDFTNoHybrid object

pyscf.pbc.tdscf.uhf.CIS

alias of pyscf.pbc.tdscf.uhf.TDA

pyscf.pbc.tdscf.uhf.RPA

alias of pyscf.pbc.tdscf.uhf.TDHF

class pyscf.pbc.tdscf.uhf.TDA(mf)[source]
gen_vind(mf)[source]

Compute Ax

class pyscf.pbc.tdscf.uhf.TDHF(mf)[source]
gen_vind(mf)[source]

Generate function to compute

[ A B][X] [-B -A][Y]

pyscf.pbc.tdscf.uhf.TDUHF

alias of pyscf.pbc.tdscf.uhf.TDHF

class pyscf.pbc.tdscf.uks.TDDFTNoHybrid(mf)[source]
gen_vind(mf)[source]

Compute Ax

pyscf.pbc.tdscf.uks.tddft(mf)[source]

Driver to create TDDFT or TDDFTNoHybrid object

pyscf.pbc.tdscf.krhf.CIS

alias of pyscf.pbc.tdscf.krhf.TDA

pyscf.pbc.tdscf.krhf.KTDA

alias of pyscf.pbc.tdscf.krhf.TDA

pyscf.pbc.tdscf.krhf.KTDHF

alias of pyscf.pbc.tdscf.krhf.TDHF

pyscf.pbc.tdscf.krhf.RPA

alias of pyscf.pbc.tdscf.krhf.TDHF

class pyscf.pbc.tdscf.krhf.TDA(mf)[source]
gen_vind(mf)[source]

Compute Ax

kernel(x0=None)[source]

TDA diagonalization solver

class pyscf.pbc.tdscf.krhf.TDHF(mf)[source]
gen_vind(mf)[source]

[ A B ][X] [-B* -A*][Y]

kernel(x0=None)[source]

TDHF diagonalization with non-Hermitian eigenvalue solver

This and other _slow modules implement the time-dependent Hartree-Fock procedure. The primary performance drawback is that, unlike other ‘fast’ routines with an implicit construction of the eigenvalue problem, these modules construct TDHF matrices explicitly via an AO-MO transformation, i.e. with a O(N^5) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TDHF roots in a reliable fashion without any issues related to the Davidson procedure. Several variants of TDHF are available:

  • pyscf.tdscf.rhf_slow: the molecular implementation;

  • pyscf.pbc.tdscf.rhf_slow: PBC (periodic boundary condition) implementation for RHF objects of pyscf.pbc.scf modules;

  • pyscf.pbc.tdscf.krhf_slow_supercell: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points but has a overhead due to an effective construction of a supercell.

  • pyscf.pbc.tdscf.krhf_slow_gamma: A Gamma-point calculation resembling the original pyscf.pbc.tdscf.krhf module. Despite its name, it accepts KRHF objects with an arbitrary number of k-points but finds only few TDHF roots corresponding to collective oscillations without momentum transfer;

  • (this module) pyscf.pbc.tdscf.krhf_slow: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points and employs k-point conservation (diagonalizes matrix blocks separately).

pyscf.pbc.tdscf.krhf_slow.get_block_k_ix(eri, k)[source]

Retrieves k indexes of the block with a specific momentum transfer. Args:

eri (TDDFTMatrixBlocks): ERI of the problem; k (tuple, int): momentum transfer: either a pair of k-point indexes specifying the momentum transfer vector or a single integer with the second index assuming the first index being zero;

Returns:

4 arrays: r1, r2, c1, c2 specifying k-indexes of the ERI matrix block.

k34=0,c1[0]

k34=1,c1[1]

k34=nk-1,c1[-1]

k34=0,c2[0]

k34=1,c2[1]

k34=nk-1,c2[-1]

k12=0,r1[0]

Block r1, c1

Block r1, c2

k12=1,r1[1]

k12=nk-1,r1[-1]

k12=0,r2[0]

Block r2, c1

Block r2, c2

k12=1,r2[1]

k12=nk-1,r2[-1]

pyscf.pbc.tdscf.krhf_slow.vector_to_amplitudes(vectors, nocc, nmo)[source]

Transforms (reshapes) and normalizes vectors into amplitudes. Args:

vectors (numpy.ndarray): raw eigenvectors to transform; nocc (tuple): numbers of occupied orbitals; nmo (int): the total number of orbitals per k-point;

Returns:

Amplitudes with the following shape: (# of roots, 2 (x or y), # of kpts, # of occupied orbitals, # of virtual orbitals).

This and other _slow modules implement the time-dependent Hartree-Fock procedure. The primary performance drawback is that, unlike other ‘fast’ routines with an implicit construction of the eigenvalue problem, these modules construct TDHF matrices explicitly via an AO-MO transformation, i.e. with a O(N^5) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TDHF roots in a reliable fashion without any issues related to the Davidson procedure. Several variants of TDHF are available:

  • pyscf.tdscf.rhf_slow: the molecular implementation;

  • pyscf.pbc.tdscf.rhf_slow: PBC (periodic boundary condition) implementation for RHF objects of pyscf.pbc.scf modules;

  • pyscf.pbc.tdscf.krhf_slow_supercell: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points but has a overhead due to an effective construction of a supercell;

  • (this module) pyscf.pbc.tdscf.krhf_slow_gamma: A Gamma-point calculation resembling the original pyscf.pbc.tdscf.krhf module. Despite its name, it accepts KRHF objects with an arbitrary number of k-points but finds only few TDHF roots corresponding to collective oscillations without momentum transfer;

  • pyscf.pbc.tdscf.krhf_slow: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points and employs k-point conservation (diagonalizes matrix blocks separately).

pyscf.pbc.tdscf.krhf_slow_gamma.vector_to_amplitudes(vectors, nocc, nmo)[source]

Transforms (reshapes) and normalizes vectors into amplitudes. Args:

vectors (numpy.ndarray): raw eigenvectors to transform; nocc (tuple): numbers of occupied orbitals; nmo (int): the total number of orbitals per k-point;

Returns:

Amplitudes with the following shape: (# of roots, 2 (x or y), # of kpts, # of kpts, # of occupied orbitals, # of virtual orbitals).

This and other _slow modules implement the time-dependent Hartree-Fock procedure. The primary performance drawback is that, unlike other ‘fast’ routines with an implicit construction of the eigenvalue problem, these modules construct TDHF matrices explicitly via an AO-MO transformation, i.e. with a O(N^5) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TDHF roots in a reliable fashion without any issues related to the Davidson procedure. Several variants of TDHF are available:

  • pyscf.tdscf.rhf_slow: the molecular implementation;

  • pyscf.pbc.tdscf.rhf_slow: PBC (periodic boundary condition) implementation for RHF objects of pyscf.pbc.scf modules;

  • (this module) pyscf.pbc.tdscf.krhf_slow_supercell: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points but has a overhead due to an effective construction of a supercell.

  • pyscf.pbc.tdscf.krhf_slow_gamma: A Gamma-point calculation resembling the original pyscf.pbc.tdscf.krhf module. Despite its name, it accepts KRHF objects with an arbitrary number of k-points but finds only few TDHF roots corresponding to collective oscillations without momentum transfer;

  • pyscf.pbc.tdscf.krhf_slow: PBC implementation for KRHF objects of pyscf.pbc.scf modules. Works with an arbitrary number of k-points and employs k-point conservation (diagonalizes matrix blocks separately).

pyscf.pbc.tdscf.krhf_slow_supercell.vector_to_amplitudes(vectors, nocc, nmo)[source]

Transforms (reshapes) and normalizes vectors into amplitudes. Args:

vectors (numpy.ndarray): raw eigenvectors to transform; nocc (tuple): numbers of occupied orbitals; nmo (tuple): the total numbers of AOs per k-point;

Returns:

Amplitudes with the following shape: (# of roots, 2 (x or y), # of kpts, # of kpts, # of occupied orbitals, # of virtual orbitals).

pyscf.pbc.tdscf.krks.tddft(mf)[source]

Driver to create TDDFT or TDDFTNoHybrid object

pyscf.pbc.tdscf.kuhf.CIS

alias of pyscf.pbc.tdscf.kuhf.TDA

pyscf.pbc.tdscf.kuhf.KTDA

alias of pyscf.pbc.tdscf.kuhf.TDA

pyscf.pbc.tdscf.kuhf.KTDHF

alias of pyscf.pbc.tdscf.kuhf.TDHF

pyscf.pbc.tdscf.kuhf.RPA

alias of pyscf.pbc.tdscf.kuhf.TDHF

class pyscf.pbc.tdscf.kuhf.TDA(mf)[source]
gen_vind(mf)[source]

Compute Ax

kernel(x0=None)[source]

TDA diagonalization solver

class pyscf.pbc.tdscf.kuhf.TDHF(mf)[source]
gen_vind(mf)[source]

Compute Ax

kernel(x0=None)[source]

TDHF diagonalization with non-Hermitian eigenvalue solver

pyscf.pbc.tdscf.kuks.tddft(mf)[source]

Driver to create TDDFT or TDDFTNoHybrid object

This and other proxy modules implement the time-dependent mean-field procedure using the existing pyscf implementations as a black box. The main purpose of these modules is to overcome the existing limitations in pyscf (i.e. real-only orbitals, davidson diagonalizer, incomplete Bloch space, etc). The primary performance drawback is that, unlike the original pyscf routines with an implicit construction of the eigenvalue problem, these modules construct TD matrices explicitly by proxying to pyscf density response routines with a O(N^4) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TD roots. Several variants of proxy-TD are available:

  • pyscf.tdscf.proxy: the molecular implementation;

  • (this module) pyscf.pbc.tdscf.proxy: PBC (periodic boundary condition) Gamma-point-only implementation;

  • pyscf.pbc.tdscf.kproxy_supercell: PBC implementation constructing supercells. Works with an arbitrary number of k-points but has an overhead due to ignoring the momentum conservation law. In addition, works only with time reversal invariant (TRI) models: i.e. the k-point grid has to be aligned and contain at least one TRI momentum.

  • pyscf.pbc.tdscf.kproxy: same as the above but respect the momentum conservation and, thus, diagonlizes smaller matrices (the performance gain is the total number of k-points in the model).

This and other proxy modules implement the time-dependent mean-field procedure using the existing pyscf implementations as a black box. The main purpose of these modules is to overcome the existing limitations in pyscf (i.e. real-only orbitals, davidson diagonalizer, incomplete Bloch space, etc). The primary performance drawback is that, unlike the original pyscf routines with an implicit construction of the eigenvalue problem, these modules construct TD matrices explicitly by proxying to pyscf density response routines with a O(N^4) complexity scaling. As a result, regular numpy.linalg.eig can be used to retrieve TD roots. Several variants of proxy-TD are available:

  • pyscf.tdscf.proxy: the molecular implementation;

  • pyscf.pbc.tdscf.proxy: PBC (periodic boundary condition) Gamma-point-only implementation;

  • (this module) pyscf.pbc.tdscf.kproxy_supercell: PBC implementation constructing supercells. Works with an arbitrary number of k-points but has an overhead due to ignoring the momentum conservation law. In addition, works only with time reversal invariant (TRI) models: i.e. the k-point grid has to be aligned and contain at least one TRI momentum.

  • pyscf.pbc.tdscf.kproxy: same as the above but respect the momentum conservation and, thus, diagonlizes smaller matrices (the performance gain is the total number of k-points in the model).

pyscf.pbc.tdscf.kproxy_supercell.assert_scf_converged(model, threshold=1e-07)[source]

Tests if scf is converged. Args:

model: a mean-field model to test; threshold (float): threshold for eigenvalue comparison;

Returns:

True if model is converged and False otherwise.

pyscf.pbc.tdscf.kproxy_supercell.get_sparse_ov_transform(oo, vv)[source]

Retrieves a sparse ovov transform out of sparse oo and vv transforms. Args:

oo (ndarray): the transformation in the occupied space; vv (ndarray): the transformation in the virtual space;

Returns:

The resulting matrix representing the sparse transform in the ov space.

pyscf.pbc.tdscf.kproxy_supercell.k2s(model, grid_spec, mf_constructor, threshold=None, degeneracy_threshold=None, imaginary_threshold=None)[source]

Converts k-point model into a supercell with real orbitals. Args:

model: a mean-field pbc model; grid_spec (Iterable): integer dimensions of the k-grid in the mean-field model; mf_constructor (Callable): a function constructing the mean-field object; threshold (float): a threshold for determining the negative k-point index; degeneracy_threshold (float): a threshold for assuming degeneracy when composing real-valued orbitals; imaginary_threshold (float): a threshold for asserting real-valued supercell orbitals;

Returns:

The same class where the Cell object was replaced by the supercell and all fields were adjusted accordingly.

pyscf.pbc.tdscf.kproxy_supercell.ko_mask(nocc, nmo)[source]

Prepares a mask of an occupied space. Args:

nocc (Iterable): occupation numbers per k-point; nmo (Iterable): numbers of orbitals per k-point;

Returns:

The mask where True denotes occupied orbitals. Basis order: [k, orb=o+v]

pyscf.pbc.tdscf.kproxy_supercell.minus_k(model, threshold=None, degeneracy_threshold=None)[source]

Retrieves an array of indexes of negative k. Args:

model: a mean-field pbc model; threshold (float): a threshold for determining the negative; degeneracy_threshold (float): a threshold for assuming degeneracy;

Returns:

A list of integers with indexes of the corresponding k-points.

pyscf.pbc.tdscf.kproxy_supercell.orb2ov(space, nocc, nmo)[source]

Converts orbital active space specification into ov-pairs space spec. Args:

space (ndarray): the obital space. Basis order: [k, orb=o+v]; nocc (Iterable): the numbers of occupied orbitals per k-point; nmo (Iterable): the total numbers of orbitals per k-point;

Returns:

The ov space specification. Basis order: [k_o, o, k_v, v].

pyscf.pbc.tdscf.kproxy_supercell.ov2orb(space, nocc, nmo)[source]

Converts ov-pairs active space specification into orbital space spec. Args:

space (ndarray): the ov space. Basis order: [k_o, o, k_v, v]; nocc (Iterable): the numbers of occupied orbitals per k-point; nmo (Iterable): the total numbers of orbitals per k-point;

Returns:

The orbital space specification. Basis order: [k, orb=o+v].

pyscf.pbc.tdscf.kproxy_supercell.sparse_transform(m, *args)[source]

Performs a sparse transform of a dense tensor. Args:

m (ndarray): a tensor to transform; *args: alternating indexes and bases to transform into;

Returns:

The transformed tensor.

pyscf.pbc.tdscf.kproxy_supercell.split_transform(transform, nocc, nmo, tolerance=1e-14)[source]

Splits the transform into oo and vv blocks. Args:

transform (numpy.ndarray): the original transform. The basis order for the transform is [real orb=o+v; k, orb=o+v]; nocc (Iterable): occupation numbers per k-point; nmo (Iterable): the number of orbitals per k-point; tolerance (float): tolerance to check zeros at the ov block;

Returns:

oo and vv blocks of the transform.

pyscf.pbc.tdscf.kproxy_supercell.supercell_response(vind, space, nocc, nmo, double, rot_bloch, log_dest)[source]

Retrieves a raw response matrix. Args:

vind (Callable): a pyscf matvec routine; space (ndarray): the active space: either for both rows and columns (1D array) or for rows and columns separately (2D array). Basis order: [k, orb=o+v]; nocc (ndarray): the numbers of occupied orbitals (frozen and active) per k-point; nmo (ndarray): the total number of orbitals per k-point; double (bool): set to True if vind returns the double-sized (i.e. full) matrix; rot_bloch (ndarray): a matrix specifying the rotation from real orbitals returned from pyscf to Bloch functions; log_dest (object): pyscf logging;

Returns:

The TD matrix.

pyscf.pbc.tdscf.kproxy_supercell.supercell_response_ov(vind, space_ov, nocc, nmo, double, rot_bloch, log_dest)[source]

Retrieves a raw response matrix. Args:

vind (Callable): a pyscf matvec routine; space_ov (ndarray): the active ov space mask: either the same mask for both rows and columns (1D array) or separate ov masks for rows and columns (2D array). Basis order: [k_o, o, k_v, v]; nocc (ndarray): the numbers of occupied orbitals (frozen and active) per k-point; nmo (ndarray): the total number of orbitals per k-point; double (bool): set to True if vind returns the double-sized (i.e. full) matrix; rot_bloch (ndarray): a matrix specifying the rotation from real orbitals returned from pyscf to Bloch functions; log_dest (object): pyscf logging;

Returns:

The TD matrix.

pyscf.pbc.tdscf.kproxy_supercell.supercell_space_required(transform_oo, transform_vv, final_space)[source]

For a given orbital transformation and a given ov mask in the transformed space, calculates a minimal ov mask in the original space required to achieve this transform. Args:

transform_oo (ndarray): the transformation in the occupied space; transform_vv (ndarray): the transformation in the virtual space; final_space (ndarray): the final ov space. Basis order: [k_o, o, k_v, v];

Returns:

The initial active space. Basis order: [k_o, o, k_v, v].