Coherent 2D Spectrum

Quantarhei provides a set of classes for calculating and representing coherent two-dimensional (2D) electronic and vibrational spectra. The main workflow begins with TwoDResponseCalculator, which computes the nonlinear optical response of a molecular system and stores the results in a TwoDResponseContainer. The container can then be converted into a TwoDSpectrumContainer (where the pulse-field convolution is applied), from which individual TwoDSpectrum objects are retrieved for plotting and analysis.

The class representing 2D spectrum. It is obtained by the chain:

Option 1) — Impulsive spectrum only —

TwoDSpectrumCalculator.calculate() -> TwoDSpectrumContainer

TwoDSpectrumContainer.get_TwoDSpectrum() -> TwoDSpectrum

Option 2) — Allows convoluting with the fields

TwoDResponseCalculator.calculate() -> TwoDResponseContainer

TwoDResponseContainer.get_TwoDSpectrumContainer # here the fields get convoluted -> TwoDSpectrumContainer

TwoDSpectrumContainer.get_TwoDSpectrum -> TwoDSpectum

TwoDResponseCalculator.

class quantarhei.spectroscopy.twodspect.TwoDSpectrum

Bases: DataSaveable, Saveable

A single two-dimensional Fourier-transform spectrum.

Stores the 2D spectral data indexed by (omega_1, omega_3) at a fixed waiting time t2. The data may be rephasing, non-rephasing, or the total sum of both.

dtypes = {'signal_DC': 'double_coherence_signal', 'signal_NONR': 'nonrephasing_2D_signal', 'signal_REPH': 'rephasing_2D_signal', 'signal_TOTL': 'total_2D_signal'}

set_axis_1(axis: Any) → None

Sets the x-axis of te spectrum (omega_1 axis)

set_axis_3(axis: Any) → None

Sets the y-axis of te spectrum (omega_3 axis)

set_data_type(dtype: str = 'total_2D_signal') → None

Set the data type for this 2D spectrum.

Parameters:

dtype (str, optional) – Type of data stored in this object. Must be one of the values in TwoDSpectrum.dtypes. Default is qr.signal_TOTL.

Raises:

Exception – If dtype is not a recognised data type.

get_spectrum_type() → Any

set_data(data: ndarray, dtype: str = 'total_2D_signal') → None

Set the data of the 2D spectrum.

Parameters:

• data (numpy.ndarray) – 2D array of spectral values (float or complex).

• dtype (str, optional) – Type of the data stored. Recognised values are qr.signal_REPH for rephasing spectra, qr.signal_NONR for non-rephasing spectra, and qr.signal_TOTL for the total spectrum (sum of both). Default is qr.signal_TOTL.

Raises:

Exception – If dtype is unknown or the axes have not been set yet.

add_data(data: ndarray) → None

Sets the data of the 2D spectrum

overlay_pulses(lab: Any) → None

Use labsetup class to overlay pulse spectra over this 2D spectrum

set_t2(t2: float) → None

Sets the t2 (waiting time) of the spectrum

get_t2() → float

Returns the t2 (waiting time) of the spectrum

log_params(params: Any = None) → None

Store custom information about the spectrum

This can be used e.g. for storage of parameters of the system for which the spectrum was calculated

get_log_params() → Any

get_value_at(x: float, y: float) → Any

Returns value of the spectrum at a given coordinate

get_cut_along_x(y0: float) → DFunction

Returns a DFunction with the cut of the spectrum along the x axis

get_cut_along_y(x0: float) → DFunction

Returns a DFunction with the cut of the spectrum along the y axis

get_cut_along_line(point1: list, point2: list, which_step: str | None = None, step: float | None = None) → DFunction

Returns a cut along a line specified by two points

get_diagonal_cut() → DFunction

Returns cut of the spectrum along the diagonal

get_anti_diagonal_cut(point: Any) → None

get_max_value(dpart: str = 'real_part') → float

Maximum value of the real part of the spectrum

get_min_value(dpart: str = 'real_part') → float

Minimum value of the real part of the spectrum

get_area_integral(area: Any, dpart: str = 'real_part') → Any

Returns an integral of a given area in the 2D spectrum

get_area_max(area: Any, dpart: str = 'real_part', loc: list | None = None) → Any

Returns a max value in a given area in the 2D spectrum

normalize2(norm: float = 1.0, dpart: str = 'real_part', nmax: list | None = None, use_max: bool = False) → None

Normalizes the spectrum to the given maximum.

Normalizes the spectrum to the maximum of a given part of the spectrum. Parts are real, imaginary or absolute values. Normalization is to a supplied norm. If nmax is not specified, use_max is not taken into account. If nmax is a list-like object, the maximum of the current spectrum is appended to it. If use_max is set to False we use the first element of the list-like object nmax as the maximum of the present data.

Parameters:

• norm (float) – Norm to which we normalize. Default value is 1.

• dpart (string) – Part of the spectrum we normalize against.

• namx (list-like or None) – If nmax is a list-like object, the maximum of the current spectrum is appended to it.

• use_max (bool) – If use_max is set to False we use the first element of the list-like object nmax as the maximum of the present data.

devide_by(val: float | int) → None

Devides the total spectrum by a value

Parameters:

val (float, int) – Value by which we devide the spectrum

zeropad(fac: int = 1) → None

shift_energy(dE: float, interpolation: str = 'linear') → None

Shift the spectrum in both frequency axis by certain amount

The shift is specified as the energy that has to be added to the 2D spectrum to shifted to its expected position. As a result we have a new spectrum

S(E_3, E_1) = S(E_3-dE, E_1-dE)

Because of the negative sign above, we have to change the sign of dE as a first thing in the code. This is for user convenience.

get_PumpProbeSpectrum() → Any

Returns a PumpProbeSpectrum corresponding to the 2D spectrum

plot(fig: Any = None, window: list | None = None, stype: str | None = None, spart: str = 'real_part', vmax: float | None = None, vmin_ratio: float = 0.5, colorbar: bool = True, colorbar_loc: str = 'right', cmap: Any = None, plot_type: str = 'both', Npos_contours: int = 10, positive_contour_color: Any = 'k', negative_contour_color: Any = 'k', zero_contour_color: Any = 'b', zero_contour: bool = True, show_states: Any = None, text_loc: list | None = None, fontsize: str = '20', label: Any = None, show: bool = False, show_diagonal: Any = None, xlabel: str | None = None, ylabel: str | None = None, axis_label_font: Any = None) → None

Plots the 2D spectrum

Parameters:

• fig (matplotlib.figure) – Figure into which plotting will be done. This is used e.g. when making a movie using moview writter (may be obsolete). If fig is None, we create a new figure object.

• window (list) – Specifies the plotted window in current energy units. When axes are x and y, the window is specified as window=[x_min,x_max, y_min,y_max]

• spart ({part_REAL, part_IMAGINARY, part_ABS}) – part of the spectrum to be plotted, constants such as part_REAL are defined at the highest import level of quantarhei.

• plot_type ({'both', 'image', 'contour'}) – Whether to plot the image with contour overlay (‘both’), only the image (‘image’), or only the contour lines (‘contour’).

• positive_contour_color (color) – Color used for positive contour levels.

• negative_contour_color (color) – Color used for negative contour levels.

• zero_contour_color (color) – Color used for the zero contour.

• zero_contour (bool) – If True, draw the zero contour line.

• vmax (float) – max of the plotting range in the z-direction. If vmax is None, maximum of the real part of the spectrum is used to determine the values of vmax

show() → None

Show the plot of 2D spectrum

By default, plots are not shown. It is waited until explicit show() is called

savefig(filename: str) → None

Saves the fige of the plot into a file

trim_to(window: list | None = None) → None

Trims the 2D spectrum to a specified region

Parameters:

window (array) – Spectral window to which the present 2D spectrum should be trimmed. The window is specified as an array [w1_min, w1_max, w3_min, w3_max], where w1_min is the lower bound of the w1 axis (the x-axis), w1_max is the upper bound of the w1 axis and similarly for the w3 axis (y-axis) of the spectrum.

Class holding a set of TwoDSpectra

Class Details

class quantarhei.spectroscopy.twodcontainer.TwoDResponseContainer(t2axis: Any = None, keep_pathways: bool = False, keep_stypes: bool = True)

Bases: Saveable

Class holding a set of TwoDSpectra

Parameters:

• t2axis (TimeAxis) – object holding waiting times at which spectra are calculated

• keep_pathways (bool) – if set True, the container will keep all types of Liouville pathways stored separately

• keep_stypes (bool) – if se t True, the container will keep rephasing and non-rephasing spectra stored separately

use_indexing_type(itype: Any) → None

Sets the type of indices used to identify spectra

Parameters:

itype (string, ValueAxis, TimeAxis, FrequencyAxis) – Type of indexig. If itype is a string, it should have values either ‘integer’ or ‘string’ in which case the specra will be stored by integer index or by string (as in dictionary). If itype is a ValueAxis (TimeAxis, FrequencyAxis), spectra will be indexed by the values in the axis object.

set_spectrum(spect: Any, tag: Any = None) → Any

Stores spectrum with a tag (time, index, etc.)

Stores the spectrum according to present indexing scheme

Parameters:

• spect (TwoDSpectrum) – Object holding the spectrum; when not tag is specified for a spectrum which as its t2 time set, the tag is set to t2 time.

• tag ({int, string, ValuesAxis, TimeAxis, FrequencyAxis}) – Tag which will be used for retrieval of the spectrum from the container.

get_spectrum_by_index(indx: int) → Any

Returns spectrum by integet index

The integer index is assigned to all spectra in the order they were saved to the container. They can be retrieved in this order

Parameters:

indx (int) – Index of the spectrum to be retrieved

get_response(tag: Any) → Any

Same as get_spectrum, but the name more sense for a response container

get_spectrum(tag: Any) → Any

Returns spectrum corresponing to time t2

Checks if the time t2 is present in the t2axis

Parameters:

t2 (float) – Waiting time for which spectrum should be returned

set_data_flag(flag: Any) → None

Sets data flag for all spectra in the container

get_TwoDSpectrumContainer(stype: Any = 'total_2D_signal') → Any

Returns a container with specific spectra

get_nearest(val: float) → Any

length() → int

Returns the length of the container

get_spectra(start: Any = None, end: Any = None) → list[Any]

Returns a list of the calculated spectra

Returns all spectra or an interval of spectra when start and end are specified

Parameters:

• start (int) – Index of the first spectrum to be returned

• end (int) – Index of the last spectrum to be returned

get_PumpProbeSpectrumContainer(skip: int = 0) → Any

Converts this response container into PumpProbeSpectrumContainer.

Each stored TwoDResponse already contains enough spectral information to be projected onto the pump-probe axis. This method performs that projection for every stored waiting time.

get_integrated_area_evolution(times: Any, area: Any, dpart: Any = 'real_part') → Any

Returns the integrated area of the 2D spectra as a function of their index

get_point_evolution(x: float, y: float, times: Any) → Any

Tracks an evolution of a single point on the 2D spectrum

Parameters:

• x (float) – x coordinate in the 2D spectrum (usually omega_1 axis)

• y (float) – y coordinate in the 2D spectrum (usually omega_3 axis)

• times (ValueAxis) – Times (usually waiting t_2 times) in which spectra are taken

global_fit_exponential(guess: Any = None) → Any

Global fit of the data with exponentials

fft(ffttype: str = 'complex-positive', window: Any = None, offset: float = 0.0, dtype: Any = None, dpart: Any = 'complex', tag: Any = None) → Any

Fourier transform in t2 time

This method performs FFT on the container data determined by the value of the dtype argument. The new container is created and the storage resolution of its components is set off. This means that the container and its spectra have no idea about what data they store. Even when plotting the spectra, one has to set plotting of the total spectrum.

Parameters:

• ffttype (string) – Specifies the type Fourier transform we perform

• window (DFunction) – Windowing function for the data. Default is None

trimall_to(window: Any = None) → None

Trims all spectra in the container

Parameters:

window (list of floats) – Window, specified by four float number, to which all spectra in the container should be trimmed

amax(spart: Any = 'real_part') → Any

Returns maximum amplitude of the spectra in the container

make_movie(filename: str, window: Any = None, stype: Any = 'total_2D_signal', spart: Any = 'real_part', cmap: Any = None, Npos_contours: int = 10, vmax: Any = None, vmin_ratio: float = 0.5, xlabel: Any = None, ylabel: Any = None, axis_label_font: Any = None, start: Any = None, end: Any = None, frate: int = 20, dpi: int = 100, show_states: Any = None, show_states_func: Any = None, label: Any = None, label_func: Any = None, text_loc: Any = None, progressbar: bool = False, use_t2: bool = True, title: str = 'Quantarhei movie', comment: str = 'Created with Quantarhei') → None

Creates a movie out of the spectra in the container

Parameters:

Npos_contours (int) – Nomber of positive value contours in the plot

class quantarhei.spectroscopy.twodcontainer.TwoDSpectrumContainer(t2axis: Any = None, dtype: Any = 'total_2D_signal')

Bases: TwoDResponseContainer

set_data_flag(flag: Any) → None

Sets data flag for all spectra in the container

get_TwoDSpectrumContainer(stype: Any = 'total_2D_signal') → Any

Returns a container with specific spectra

get_PumpProbeSpectrumContainer(skip: int = 0) → Any

Converts this container into PumpProbeSpectrumContainer

normalize2(norm: float = 1.0, each: bool = False, dpart: Any = 'real_part') → Any

Normalize the whole container of spectra

Normalization of the whole container so that the maximum value of the spectrum is equal to the norm.

Parameters:

• norm (float) – Value to which we normalize the spectra

• each (bool) – If False, we normalize the global maximum of the container, i.e. a maximum accross whole spectra. if True, each spectrum is normalized individually against its own maximum.

• dpart (string) – Part of the spectrum from which the maximum is calculated, it can be part_REAL, part_IMAGINARY or part_ABS. The values of these constants are defined in the highest level of namespace in Quantarhei.

fft(ffttype: str = 'complex-positive', window: Any = None, offset: float = 0.0, dtype: Any = None, dpart: Any = 'complex', tag: Any = None) → Any

Fourier transform in t2 time

This method performs FFT on the container data determined by the value of the dtype argument. The new container is created and the storage resolution of its components is set off. This means that the container and its spectra have no idea about what data they store. Even when plotting the spectra, one has to set plotting of the total spectrum.

Parameters:

• ffttype (string) – Specifies the type Fourier transform we perform

• window (DFunction) – Windowing function for the data. Default is None

unitedir(dname: str) → Any

class quantarhei.spectroscopy.twodcalculator.TwoDResponseCalculator(t1axis: Any, t2axis: Any, t3axis: Any, system: Any = None, responses: Any = None, dynamics: str = 'secular', relaxation_tensor: Any = None, rate_matrix: Any = None, relaxation_theory: str | None = None, rate_matrix_time_dependent: bool = False, relaxation_cutoff_time: float | None = None, rate_matrix_options: dict[str, Any] | None = None, population_propagator: Any = None, density_matrix_propagator: Any = None, density_matrix_trajectory: Any = None, population_time_axis: Any = None, population_dynamics_mode: str | None = None, include_nonsecular_remainder: bool = True, dipole_normalization_tol: float = 1e-12, effective_hamiltonian: Any = None, twodtype: str = '2DES', gamma_factor: float | None = None, population_factors: Any = None, jump_order: int = 0, jump_time_graining: int = 1, jump_kernel_cutoff: float = 0.0, jump_kernel_zero_cutoff: float = 0.0)

Bases: object

Calculator of the 2D spectrum

Enables setting up parameters of 2D spectrum calculation for later evaluation. The method calculate returns TwoDResponseContainer with a 2D spectrum.

Parameters:

• twodtype ({"2DES", "F-2DES"}) – Type of 2D spectrum to calculate. "F-2DES" currently supports the gamma_factor fluorescence-detected approximation.

• gamma_factor (float) – Fluorescence-detected 2D weighting factor. ESA contributions are weighted by gamma_factor - 1.

• population_factors (tuple) – Reserved for state-resolved fluorescence-detected 2D spectra. This mode is not implemented yet because it requires state-resolved ESA responses.

property t1axis: Any

property t2axis: Any

property t3axis: Any

property system: Any

bootstrap(rwa: float = 0.0, pad: int = 0, lab: Any = None, verbose: bool = False, write_resp: bool | str = False, keep_resp: bool = False, **kwargs: Any) → None

Sets up the environment for 2D calculation write_resp takes a string, creates a directory with the name of the string and saves the respoonses and time axis as a npz file

keep_resp saves the responses as a list of dictionaries. The list goes through the time points in t2.

reset_t2_time() → None

Resets the population time of the calculations

calculate_next() → Any

Calculate next population time of a 2D spectrum

calculate_one(tc: int) → Any

Calculate one population time

calculate() → Any

Returns 2D spectrum

Calculates and returns TwoDResponseContainer containing 2D spectrum based on the parameters specified in this object.

reset_evaluation_functions(fcions: list[Any]) → None

Resets the evaluation functions used by the reseponse functions