shnitsel.analyze.spectra ======================== .. py:module:: shnitsel.analyze.spectra Functions --------- .. autoapisummary:: shnitsel.analyze.spectra._get_fosc shnitsel.analyze.spectra.get_fosc shnitsel.analyze.spectra.assign_fosc shnitsel.analyze.spectra.broaden_gauss shnitsel.analyze.spectra.ds_broaden_gauss shnitsel.analyze.spectra.get_spectrum shnitsel.analyze.spectra.calc_spectra shnitsel.analyze.spectra.get_spectra_groups shnitsel.analyze.spectra.sep_ground_excited_spectra shnitsel.analyze.spectra.spectra_all_times Module Contents --------------- .. py:function:: _get_fosc(energy_interstate, dip_trans_norm) Internal function to actually calculate the oscillator frequency for energies and transition dipoles. :param energy_interstate: The Array of Energies in the system. :type energy_interstate: DataArray :param dip_trans_norm: The array of associated norm of transition dipoles in the system. :type dip_trans_norm: DataArray :returns: The resulting oscillation frequency (f_osc) array. :rtype: DataArray .. rubric:: 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}$$ .. py:function:: get_fosc(energy_per_or_interstate, dip_trans_norm) Function to obtain a dataarray containing the oscillator strength as a dataarray. :param energy_interstate: The array of per- or inter-state energies in the system. If provided as a per-state energy, inter-state barriers will automatically be calculated. :type energy_interstate: DataArray :param dip_trans_norm: The array of associated transition dipoles in the system with their norm calculated across the direction dimension. :type dip_trans_norm: DataArray :returns: The resulting datarray of oscillator strength f_osc :rtype: DataArray .. py:function:: assign_fosc(ds) Function to calculate oscillator strength fosc and create a new dataset with this variable assigned. :param ds: Dataset from which to calculate fosc :type ds: xr.Dataset :returns: Dataset with the member variable fosc set :rtype: xr.Dataset .. py:function:: broaden_gauss(delta_E, fosc, agg_dim = 'frame', *, width_in_eV = 0.5, nsamples = 1000, xmin = 0, xmax = None) Applies a gaussian smoothing kernel to the fosc data. Aggregation is performed along the `agg_dim` dimension. :param delta_E: values used for the x-axis, presumably $E_i$ :param fosc: values used for the y-axis, presumably $f_\mathrm{osc}$ :param agg_dim: dimension along which to aggregate the many Gaussian distributions, by default 'frame' :param optional: dimension along which to aggregate the many Gaussian distributions, by default 'frame' :param width_in_eV: the width of the Gaussian distributions used, by default 0.5 eV :param optional: the width of the Gaussian distributions used, by default 0.5 eV :param nsamples: number of evenly spaced x-values over which to sample the distribution, by default 1000 :param optional: number of evenly spaced x-values over which to sample the distribution, by default 1000 :param xmax: the maximum x-value, by default 3 standard deviations beyond the pre-broadened maximum :param optional: the maximum x-value, by default 3 standard deviations beyond the pre-broadened maximum .. py:function:: ds_broaden_gauss(interstate, width_in_eV = 0.5, nsamples = 1000, xmax = None) 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. :param interstate: Interstate dataset with `energy_interstate` and `fosc` information. :type interstate: InterState :param width_in_eV: Width of the gaussian smoothing kernel in eV. Defaults to 0.5 eV. :type width_in_eV: float, optional :param nsamples: Number of samples/steps in the range of the energy spectrum. Defaults to 1000. :type nsamples: int, optional :param xmax: Maximum of the energy range to consider for the spectrum. Defaults to None. :type xmax: float | None, optional :returns: Resulting broadened spectrum statistics. :rtype: xr.DataArray .. py:function:: get_spectrum(data, t, sc, rel_cutoff = 0.01) Function to calculate a gaussian-smoothed spectrum of an interstate dataset :param data: An InterState dataset with fosc and energy data :type data: InterState :param t: The time at which to evaluate the spectrum :type t: float :param sc: State combination identifier. Possibly an index or a tuple (from, to) of states. :type sc: tuple[int, int] :param rel_cutoff: Relative cutoff threshold. Values below the max of the resulting spectrum times this scale will be ignored. Defaults to 0.01. :type rel_cutoff: float, optional :returns: The Gauss-broadened spectrum of the provided `data` system. If broadening across trajectories could not be performed, just returns the fosc array. :rtype: xr.DataArray .. py:function:: calc_spectra(interstate, times = None, rel_cutoff = 0.01) Function to calculate spectra :param interstate: An InterState transformed Dataset. :type interstate: InterState :param times: The times at which the spectrum should be calculated. Defaults to None. If None, will be initialized as [0,10,20,30] :type times: Iterable[float]|None, optional :param rel_cutoff: Factor for the cutoff of broadened/smoothened spectrum relative to maximum. Defaults to 0.01. :type rel_cutoff: float, optional :returns: Returns a `dict` of DataArrays indexed by `(time, statecomb)` tuples. :rtype: SpectraDictType .. py:function:: get_spectra_groups(spectra) Group spectra results into spectra involving the ground state or only excited states. :param spectra: The Spectral calculation results, e.g. from `calc_spectra()`. Indexed by (timestep, state_combination) and yielding the associated spectrum. :type spectra: SpectraDictType :returns: First the spectra involving the ground state SpectraDictType: Second the spectra involving only excited states. :rtype: SpectraDictType .. py:function:: sep_ground_excited_spectra(spectra, excited_transitions = None) Function to split Spectra into two groups. Can specify which state combinations should be grouped into `excited` transitions. If not provided a `excited_transitions` set, will assume all transitions not involving the ground state to be 'excited'. :param spectra: The spectral results, e.g. from `calc_spectra()` :type spectra: SpectraDictType :param excited_transitions: An optional set specifying all state transitions that should be filtered as 'excited. Defaults to None. :type excited_transitions: set[tuple[int, int]] | None, optional :returns: First the spectra not involving excited state transitions SpectraDictType: Second the spectra involving only excited state transitions :rtype: SpectraDictType .. py:function:: spectra_all_times(inter_state) Function to calculate the spectra at all times. Does not return a dict with only the relevant (t,sc) combinations as above but instead a full xr.DataArray with a time dimension that has spectrum data for all times within the dataset averaged across trajectories. :param inter_state: The InterState transformed Dataset. :type inter_state: xr.Dataset :raises ValueError: If required variables or dimensions are missing :returns: The resulting spectra across all times. :rtype: xr.DataArray