zkit.io.tdm

Read transition-dipole-moment (TDM) data from TDSEZ static HDF5 output.

The TDSEZ binary writes the FULL transition-dipole matrices between every converged eigenstate into static/EigenData_<prefix>.h5 as the datasets

tdm_x, tdm_y, tdm_z (shape (N*N, 2), row-major [re, im] per element)

where element [i*N + j] holds ⟨i|D_α|j⟩. These are the complete Hermitian matrices at double/complex precision — the optimal machine-readable form (the legacy static/TDMInfo_<prefix>.txt is human-facing text and drops small / zero / diagonal entries, so it is unsuitable for programmatic use).

This module complements the eigen reader (zkit.io.eigen.read_eigen()): read the HDF5 EigenData file with either helper and combine the spectrum/energies with the TDM matrices.

zkit.io.tdm.read_tdm(path)

Read the full transition-dipole matrices from a TDSEZ EigenData HDF5.

Parameters:

path (str | Path) – Path to static/EigenData_<prefix>.h5 (the same file that carries

Return type:

Dict[str, ndarray]

spectrum / psi_* / run_metadata).

Returns:

Keys "tdm_x", "tdm_y", "tdm_z" (each an

Parameters:

path (str | Path)

Return type:

Dict[str, ndarray]

(N, N) complex np.ndarray of ⟨i|D_α|j⟩), present only for the spatial axes actually assembled by the run. If no TDM datasets are found, an empty dict is returned (e.g. the file predates this feature). :rtype: dict

zkit.io.tdm.tdm_of_state(path, source_state, axes=None)

Return the dipole TDM out of eigenstate source_state for every axis.

The result is the source_state-th row of the requested TDM matrix/matrices, i.e. the vector [⟨source_state\|D_α\|0⟩, ⟨source_state\|D_α\|1⟩, ..., ⟨source_state\|D_α\|N-1⟩] of transition dipoles from state source_state into all other eigenstates.

Parameters:

  • path (str | Path) – EigenData HDF5 path (passed to read_tdm()).

  • source_state (int) – Source eigenstate index (0-based).

  • axes (str | List[str] | None) – Which axes to return. One of "x", "y", "z", a list of

Return type:

Dict[str, ndarray]

those, or None (default → all axes present in the file).

Returns:

Mapping axis -> (N,) complex ndarray (the row of that TDM matrix).

Parameters:

  • path (str | Path)

  • source_state (int)

  • axes (str | List[str] | None)

Return type:

Dict[str, ndarray]

If axes is a single string the dict still uses that string as key. :rtype: dict

Raises:

  • IndexError – If source_state is out of range for the stored TDM matrices.

  • KeyError – If a requested axis has no TDM dataset in the file.

Parameters:

  • path (str | Path)

  • source_state (int)

  • axes (str | List[str] | None)

Return type:

Dict[str, ndarray]

zkit.io.tdm.tdm_magnitude_of_state(path, source_state, axes=None)

Convenience: |⟨source_state|D_α|j⟩| (Euclidean norm over the requested axes) per j.

Returns an (N,) real array giving the total dipole-transition magnitude out of state source_state into every other state, summed in quadrature over the requested axes.

Parameters:

  • path (str | Path)

  • source_state (int)

  • axes (str | List[str] | None)

Return type:

ndarray