shnitsel.analyze.spectra#

Functions#

_calculate_fosc(energy_interstate, dip_trans_norm)

Internal function to actually calculate the oscillator frequency for energies and transition dipoles.

calculate_fosc(energy_interstate, dip_trans_norm)

Function to obtain a dataarray containing the oscillator strength as a dataarray.

get_fosc(…)

Function to calculate the strength of the oscillator for state-to-state transitions.

apply_gauss_broadening(delta_E, fosc[, agg_dim, ...])

Applies a gaussian smoothing kernel to the fosc data.

get_fosc_gauss_broadened(…)

Function to get the broadened spectrum of the interstate energy and oscillator strength data to plot

get_spectrum_at_time(…)

Function to calculate a gaussian-smoothed spectrum of an interstate dataset at one specific point in time and for one specific state transition

get_spectra(…)

Function to calculate (gauss-broadened) spectra at multiple (or all) points in time

get_spectra_groups(spectra[, state_selection])

Group spectra results into spectra involving the ground state or only excited states.

Module Contents#

_calculate_fosc(energy_interstate, dip_trans_norm)#

Internal function to actually calculate the oscillator frequency for energies and transition dipoles.

Parameters:

  • energy_interstate (DataArray) – The Array of Energies in the system.

  • dip_trans_norm (DataArray) – The array of associated norm of transition dipoles in the system.

Returns:

The resulting oscillation frequency (f_osc) array.

Return type:

DataArray

Notes

We use the following unitless form of f_osc: $$f_{osc} = frac{2}{3} frac{m_e}{hbar^2} cdot Delta E cdot frac{mu^2}{e^2}$$

calculate_fosc(energy_interstate, dip_trans_norm)#

Function to obtain a dataarray containing the oscillator strength as a dataarray.

Parameters:

  • energy_interstate (DataArray) – The array of inter-state energies (delta_E) in the system.

  • dip_trans_norm (DataArray) – The array of associated transition dipoles in the system with their norm calculated across the direction dimension.

Returns:

The resulting datarray of oscillator strength f_osc

Return type:

DataArray

get_fosc(data: shnitsel.data.dataset_containers.trajectory.Trajectory | shnitsel.data.dataset_containers.frames.Frames | shnitsel.data.dataset_containers.inter_state.InterState) → xarray.DataArray#
get_fosc(data: shnitsel.data.tree.tree.ShnitselDB[shnitsel.data.dataset_containers.trajectory.Trajectory | shnitsel.data.dataset_containers.frames.Frames | shnitsel.data.dataset_containers.inter_state.InterState]) → shnitsel.data.tree.tree.ShnitselDB[xarray.DataArray]

Function to calculate the strength of the oscillator for state-to-state transitions.

If provided a simple data type like a Trajectory of Frames, will extract InterState information from it. If provided a hierarchical tree structure, will map calculation over data entries. Uses energy delta and dip_trans_norm, i.e. the norm of the transition dipole for calculation and will only yield results if those are available. Otherwise, the function call will fail.

Parameters:

data (Trajectory) –

Frames | InterState |TreeNode[Any, Trajectory | Frames | InterState]

The data from which interstate information can be deduced (transition dipoles and energy deltas). Alternatively, the interstate information can be provided directly. The data can also be supplied in a hierarchical tree format. In that case, the operation will be applied to data entries in the tree structure.

Returns:

Either the array of fosc values for simple input structures or the tree structure with the fosc results for individual data entries after mapping over the tree.

Return type:

xr.DataArray | TreeNode[Any, Trajectory | Frames | InterState]

apply_gauss_broadening(delta_E, fosc, agg_dim=None, *, width_in_eV=0.5, nsamples=1000, min_energy_range=0, max_energy_range=None)#

Applies a gaussian smoothing kernel to the fosc data.

Aggregation is performed along the agg_dim dimension.

Parameters:

  • delta_E (xr.DataArray) – Values used for the x-axis, presumably $E_i$

  • fosc (xr.DataArray) – Values used for the y-axis, presumably $f_mathrm{osc}$

  • agg_dim (DimName, optional) – Dimension along which to aggregate the many Gaussian distributions, by default None, which means, no automatic mean calculation is applied.

  • width_in_eV (float, optional) – the width of the Gaussian distributions used, by default 0.5 eV

  • nsamples (int, optional) – number of evenly spaced x-values over which to sample the distribution, by default 1000

  • max_energy_range (float, optional) – The minimum x-value used for the energy-spectrum, by default 0.0

  • max_energy_range – the maximum x-value, by default 3 standard deviations beyond the pre-broadened maximum

  • min_energy_range (float)

Return type:

xarray.DataArray

get_fosc_gauss_broadened(interstate_data: shnitsel.data.dataset_containers.inter_state.InterState | shnitsel.data.dataset_containers.trajectory.Trajectory | shnitsel.data.dataset_containers.frames.Frames | xarray.Dataset, width_in_eV: float = 0.5, nsamples: int = 1000, max_energy_range: float | None = None) → xarray.DataArray#
get_fosc_gauss_broadened(interstate_data: shnitsel.data.tree.tree.ShnitselDB[shnitsel.data.dataset_containers.inter_state.InterState | shnitsel.data.dataset_containers.trajectory.Trajectory | shnitsel.data.dataset_containers.frames.Frames | xarray.Dataset], width_in_eV: float = 0.5, nsamples: int = 1000, max_energy_range: float | None = None) → shnitsel.data.tree.tree.ShnitselDB[xarray.DataArray]

Function to get the broadened spectrum of the interstate energy and oscillator strength data to plot a nice and smooth spectrum.

Width of the smoothing kernel is given in eV and the energy is assumed to be in eV or will be converted to eV.

Parameters:

  • interstate_data_source (InterState | Trajectory | Frames | xr.Dataset | TreeNode[Any, InterState | Trajectory | Frames | xr.Dataset]) –

    Interstate dataset or source for such data with energy_interstate and fosc information.

    If provided as Frames or Trajectory, must provide energy and dip_trans data. If provided as tree, operation will be mapped over data.

  • width_in_eV (float, optional) – Width of the gaussian smoothing kernel in eV, by default 0.5

  • nsamples (int, optional) – Number of samples/steps in the range of the energy spectrum, by default 1000

  • max_energy_range (float | None, optional) – Maximum of the energy range to consider for the spectrum, by default None

Returns:

Resulting broadened spectrum statistics either of the dataset input or mapped over the entire input tree

Return type:

xr.DataArray | TreeNode[Any, xr.DataArray]

get_spectrum_at_time(interstate_data: shnitsel.data.tree.tree.ShnitselDB[shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset], t: float, sc: shnitsel.core.typedefs.StateCombination, rel_cutoff: float = 0.01) → shnitsel.data.tree.tree.ShnitselDB[xarray.Dataset] | None#
get_spectrum_at_time(interstate_data: shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset | Sequence[shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset], t: float, sc: shnitsel.core.typedefs.StateCombination, rel_cutoff: float = 0.01) → xarray.DataArray | None

Function to calculate a gaussian-smoothed spectrum of an interstate dataset at one specific point in time and for one specific state transition

_extended_summary_

Parameters:

  • interstate_data (InterState | xr.Dataset | Sequence[InterState | xr.Dataset ] | TreeNode[Any, InterState | xr.Dataset]) – An InterState dataset with fosc and energy data. Alternatively, a sequence of Interstate data or a hierarchical set of interstate data.

  • t (float) – The time at which to evaluate the spectrum

  • sc (StateCombination) – State combination identifier. Provided as a tuple (from, to) of state indices.

  • rel_cutoff (float, optional) – Relative cutoff threshold. Values below the max of the resulting spectrum times this scale will be ignored, by default 0.01

Returns:

  • xr.DataArray – The Gauss-broadened spectrum of the provided data system. If broadening across trajectories could not be performed, just returns the fosc array. If a sequence of interstate data was provided, aggregation will be performed across the spectra of the different datasets.

  • TreeNode[Any, xr.DataArray] – Hierarchically mapped data, where spectrum calculation was performed across flat groups. If a hierarchical tree set was provided, the data will be grouped and aggregation performed across the spectra of data within the same group

  • None – If the spectrum could not be calculated for whatever reason. Most likely due to missing data for the spectrum calculation.

Raises:

ValueError – Unsupported type provided.

get_spectra(interstate_data: shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset | Sequence[shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset], state_selection: shnitsel.filtering.state_selection.StateSelection | None = None, times: Iterable[float] | Literal['all'] | None = None, rel_cutoff: float = 0.01) → shnitsel.core.typedefs.SpectraDictType#
get_spectra(interstate_data: shnitsel.data.tree.tree.ShnitselDB[shnitsel.data.dataset_containers.inter_state.InterState | xarray.Dataset], state_selection: shnitsel.filtering.state_selection.StateSelection | None = None, times: Iterable[float] | Literal['all'] | None = None, rel_cutoff: float = 0.01) → shnitsel.data.tree.tree.ShnitselDB[shnitsel.core.typedefs.SpectraDictType]

Function to calculate (gauss-broadened) spectra at multiple (or all) points in time

Uses strength of oscillator (fosc) and energy deltas (energy_interstate) to calculate a smoothened spectrum across the energy phase space. The times at which the spectrum is calculated and the list of state transitions to consider can be controlled via the parameters.

Parameters:

  • interstate (InterState | xr.Dataset | Sequence[InterState | xr.Dataset] | TreeNode[Any, InterState | xr.Dataset]) – The data source for interstate data that needs to provide interstate energy differenses and fosc data, which can be derived from energy_interstate and dip_trans. If the necessary data is not provided, an error will be raised. If a sequence is provided, state selection defaults will be generated from the first data set in the selection. If a hierarchical tree is provided, data will be grouped and the spectra calculation will be mapped over the data within each group.

  • state_selection (StateSelection, optional) – State combination selection provided either as a StateSelection instance or, by default will consider all state combinations.

  • times (Iterable[float] | Literal['all'] | None, optional) – Specific times at which the spectrum should be calculated or all if the spectrum should be extracted at all times, by default None, which means that a set of times will be chosen automatically. (Note: will currently be initialized as [0,10,20,30] in arbitrary time units)

  • rel_cutoff (float, optional) – Factor for the cutoff of broadened/smoothened spectrum relative to maximum to be considered, by default 0.01

Raises:

ValueError – Unsupported type provided.

Returns:

  • SpectraDictType – The resulting spectrum as a mapping from (t,sc) pairs to the resulting, broadened spectrum. The first item in the key is the time at which the spectrum was extracted. The second item is the state combination descriptor for which it was calculated.

  • TreeNode[Any, SpectraDictType] – If a hierarchical input is provided, the spectra results will be provided in hierarchical structure with one result for every grouped set of data.

get_spectra_groups(spectra, state_selection=None)#

Group spectra results into spectra involving the ground state or only excited states.

_extended_summary_

Parameters:

  • spectra (SpectraDictType) – The Spectral calculation results, e.g. from calc_spectra(). Indexed by (timestep, state_combination) and yielding the associated spectrum.

  • state_selection (StateSelection | None, optional) – The selection of states to consider as ground and active states, by default None. If not provided, all state transitions with state ids above 1 will be considered excited all others ground state transitions. If provided, the excited state combinations will be extracted using state_selection.excited_state_transitions() with default parameters.

Returns:

First the spectra involving the ground state Second the spectra involving only excited states.

Return type:

tuple[ SpectraDictType, SpectraDictType]