---
title: 'WaveMixings.jl: DW Spectroscopy Toolkit'
url: https://www.emergentmind.com/topics/wavemixings-jl
type: topic
---

# WaveMixings.jl: DW Spectroscopy Toolkit

Searching arXiv for the specified paper to ground the article and citation metadata.
WaveMixings.jl is a Julia software package for performing **time-resolved nonlinear electronic spectroscopy from quasi-classical trajectories** within the **quasi-classical doorway-window (DW) approximation**. It is specifically designed for **on-the-fly simulations** in which trajectory data—typically electronic energies, transition dipole moments, and state populations or mappings generated along surface-hopping or related mixed quantum-classical dynamics—are transformed into transient spectroscopy observables. The package was developed to replace previously undocumented in-house scripts and to provide an open-source, documented, and extensible implementation of DW-based spectroscopy workflows, including **transient absorption pump-probe (TA PP)** spectra, both **integral** and **dispersed**, as well as **two-dimensional (2D)** spectra; the associated paper also reports support for **time-resolved fluorescence**, **2D-FLEX**, and **strong-field TA PP** [2509.03917].

## 1. Definition, scope, and intended role

WaveMixings.jl is presented as “an efficient numerical implementation of the quasi-classical doorway-window approximation, specifically designed for on-the-fly simulations of time-resolved nonlinear spectroscopic signals” [2509.03917]. Its stated purpose is threefold: to make earlier DW workflows accessible and reproducible, to enable efficient post-processing of large trajectory ensembles, and to provide a versatile platform for methodological development within the DW framework.

The package is positioned for systems in which ultrafast dynamics are dominated by **nonadiabatic effects**, especially near **conical intersections**, where mixed quantum-classical dynamics is often the only tractable approach for large molecules. In that setting, WaveMixings.jl takes the electronic-structure information accumulated along trajectories and assembles observable spectroscopy signals. A plausible implication is that the software is intended not merely as a downstream visualization utility but as a formal bridge between nonadiabatic dynamics simulations and experimentally comparable ultrafast observables.

The implementation emphasizes Julia-specific features, notably **multiple dispatch**, **strong typing**, and **BLAS-backed linear algebra**, which are presented as enabling generic code design, predictable behavior, and efficient execution. The package is also described as relying only on Julia standard libraries such as `LinearAlgebra.jl` and `DelimitedFiles.jl`, so that it can run from a raw Julia installation [2509.03917].

## 2. Doorway-window formalism and quasi-classical approximation

The conceptual core of WaveMixings.jl is the **quasi-classical doorway-window approximation**, introduced in the framework of third-order response theory. In this description, a nonlinear signal is factorized into a **doorway** that prepares a non-equilibrium state after the pump interaction, a field-free evolution during the population time, and a **window** that reads out the evolving state after the probe interaction.

The heterodyne-detected four-wave-mixing signal is written in DW form as
$$
S(T, T, Tt) \sim \mathrm{Re}\sum_{k=0,I,II} a_k \,\mathrm{Tr}\big[ W_k(Tt)\{ \zeta(T) D(T)\}\big].
\tag{4}
$$
Here, $D(T)$ is the doorway operator, $W_k(Tt)$ is the window operator, $\zeta(T)$ is the field-free propagator during the population time, and $k=0,I,II$ label the **GSB**, **SE**, and **ESA** channels. The sign factors are
$$
a_0=a_I=1, \qquad a_{II}=-1,
$$
which encode transmission enhancement for GSB and SE and transmission reduction for ESA [2509.03917].

The molecular Hamiltonian is written as
$$
H_{nm} = \left[K_N(R,P)+V_n(R)\right]\delta_{nm}-A_{nm}(R,P),
\tag{1}
$$
with $K_N$ the nuclear kinetic energy operator, $V_n$ the adiabatic potential energy surfaces, and $A_{nm}$ the nonadiabatic coupling operator. It is partitioned into manifolds as
$$
H= \begin{pmatrix} H_0 & 0 & 0\\ 0 & H_I & 0\\ 0 & 0 & H_{II} \end{pmatrix},
\tag{2}
$$
where $H_0$ is the ground-state manifold, $H_I$ the bright excited-state manifold, and $H_{II}$ a higher-lying probe-accessible manifold. The corresponding dipole operators are block-partitioned so that $M^+$ and $M^-$ describe upward and downward transitions between the manifolds $\{0\}$, $\{I\}$, and $\{II\}$.

To render this formalism usable for quasi-classical on-the-fly trajectory simulations, the paper states four approximations: **non-overlapping laser pulses**; **negligible nuclear motion during each pulse**; **electronic coherences evolve at fixed nuclei during coherence times**; and replacement of quantum evolution during the population time by quasi-classical trajectory evolution, with the quantum trace replaced by Monte Carlo sampling over initial conditions and stochastic surface-hopping events [2509.03917]. This defines the validity regime of the method. It also clarifies a common misconception: WaveMixings.jl does not implement exact quantum dynamics for the full spectroscopy problem, but rather a trajectory-based quasi-classical approximation with an explicitly stated domain of applicability.

## 3. Implemented observables and signal expressions

A principal function of WaveMixings.jl is the calculation of standard femtosecond observables. The package highlights **integral TA PP**, **dispersed TA PP**, and **electronic 2D spectra**, while the paper additionally discusses **2D-FLEX**, **time-resolved fluorescence**, and **strong-field TA PP** [2509.03917].

For **integral transient absorption pump-probe**, the signal is obtained by setting the second coherence delay to zero:
$$
S_{\mathrm{int}}(T,\omega_{\mathrm{pr}}) \sim \mathrm{Re}\sum_{k=0,I,II} a_k \, W_k(\omega_{\mathrm{pr}},R(T),P(T))\,D(\omega_{\mathrm{pu}},R,P)_{\mathrm{MC}}.
\tag{5}
$$
The doorway function is
$$
D(\omega_{\mathrm{pu}},R_g,P_g) = E_{\mathrm{pu}}(\omega_{\mathrm{pu}}-U_{eg}(R_g))\, |M_{ge}(R_g)|^2\, \rho_g(R_g,P_g),
\tag{6}
$$
where $E_{\mathrm{pu}}$ is the pump spectrum, $U_{eg}(R)=V_e(R)-V_g(R)$ is the transition frequency, $M_{ge}$ is the transition dipole moment, and $\rho_g$ is the ground-state vibrational Wigner distribution. The integral window functions are
$$
W_{\mathrm{int}}^{\mathrm{GSB}}(\omega_{\mathrm{pr}},R_g(T),P_g(T)) = E_{\mathrm{pr}}(\omega_{\mathrm{pr}}-U_{eg}(R_g(T)))\,|M_{ge}(R_g(T))|^2,
\tag{7}
$$
$$
W_{\mathrm{int}}^{\mathrm{SE}}(\omega_{\mathrm{pr}},R_e(T),P_e(T)) = E_{\mathrm{pr}}(\omega_{\mathrm{pr}}-U_{e(T)g}(R_e(T)))\,|M_{g\,e(T)}(R_e(T))|^2,
\tag{8}
$$
$$
W_{\mathrm{int}}^{\mathrm{ESA}}(\omega_{\mathrm{pr}},R_e(T),P_e(T)) = E_{\mathrm{pr}}(\omega_{\mathrm{pr}}-U_{e(T)f}(R_e(T)))\,|M_{e(T)f}(R_e(T))|^2.
\tag{9}
$$
These encode **GSB** as bleach of ground-state absorption, **SE** as stimulated emission from the excited manifold, and **ESA** as excited-state absorption into manifold II. The paper explicitly notes that laser polarization and orientational averaging are not explicitly treated in this implementation, so the dipole factors appear as squared magnitudes. It also gives the relation
$$
|M_{ge}(R)|^2 = \frac{3F_{ge}(R)}{2U_{eg}(R)}, \qquad |M_{ef}(R)|^2 = \frac{3F_{ef}(R)}{2U_{fe}(R)}.
\tag{10}
$$

For **dispersed TA PP**, detection-frequency resolution is retained:
$$
S_{\mathrm{dis}}(T,\omega_t) \sim \mathrm{Re}\sum_{k=0,I,II} a_k\, W_k^{\mathrm{dis}}(\omega_{\mathrm{pr}},\omega_t,R(T),P(T))\, D(\omega_{\mathrm{pu}},R,P)_{\mathrm{MC}}.
\tag{11}
$$
The window functions include a dephasing rate $v$, which controls the line shape in the frequency domain and yields Lorentzian-like factors of the form
$$
\frac{1}{v + i(\Delta U - \omega_t)}.
$$
This introduces finite linewidths and frequency dispersion in the transmitted probe [2509.03917].

For **2D spectra**, the DW signal is Fourier transformed with respect to both coherence-time variables:
$$
S_{2D}(\omega_\tau,T,\omega_t) \sim \mathrm{Re}\sum_{k=0,I,II} a_k \left(W_{2D}(R(T),P(T);\omega_t)\,D_{2D}(R,P;\omega_\tau)\right)_{\mathrm{MC}}.
\tag{16}
$$
The package includes both **non-rephasing** and **rephasing** phase-matching directions, with $a=1$ for non-rephasing and $a=-1$ for rephasing. The doorway is
$$
D_{2D}(\omega_\tau,R_g,P_g) = \rho_g(R_g,P_g)\, E_{\mathrm{pu}}(\omega_\tau-\omega_{\mathrm{pu}})\, |M_{ge}(R_g)|^2 \, \frac{1}{v+i(V_{eg}(R_g)-\omega_\tau)}.
\tag{17}
$$
The window functions are
$$
W_{2D}^{\mathrm{GSB}}(\omega_t,R_g(T),P_g(T)) = E_{\mathrm{pr}}(\omega_t-\omega_{\mathrm{pr}})\, |M_{ge}(R_g(T))|^2\, \frac{1}{v+i(U_{eg}(R_g(T))-\omega_t)},
\tag{18}
$$
$$
W_{2D}^{\mathrm{SE}}(\omega_t,R_e(T),P_e(T)) = E_{\mathrm{pr}}(\omega_t-\omega_{\mathrm{pr}})\, |M_{g\,e(T)}(R_e(T))|^2\, \frac{1}{v+i(U_{e(T)g}(R_e(T))-\omega_t)},
\tag{19}
$$
$$
W_{2D}^{\mathrm{ESA}}(\omega_t,R_e(T),P_e(T)) = E_{\mathrm{pr}}(\omega_t-\omega_{\mathrm{pr}})\, |M_{e(T)f}(R_e(T))|^2\, \frac{1}{v+i(U_{e(T)f}(R_e(T))-\omega_t)}.
\tag{20}
$$
Both doorway and window are therefore **complex-valued**, and $v$ broadens spectral features.

The paper also implements **2D-FLEX**, a fluorescence-detected 2D technique with
$$
S_{2DF}(\omega_\tau,T,\omega_t) \sim \left(W_{2DF}(\omega_t,R_e(T),P_e(T))\,D_{2DF}(\omega_\tau,R_g,P_g;\,e)\right),
\tag{21}
$$
and notes that this observable isolates excited-state dynamics and excludes GSB and ESA. The corresponding doorway and window employ Gaussian dephasing and Gaussian probe envelopes, and the signal is described as especially useful for resolving wavepacket motion in manifold I [2509.03917].

## 4. Software architecture and internal organization

WaveMixings.jl is described as a multi-module Julia package with four major functional areas [2509.03917].

The **I/O Data** module handles importing data, exporting data, filtering trajectory outputs, reading GSB/SE/ESA signal files, and adapting external dynamics output to the package’s expected structure. Direct support is presently provided for the output structure of **ZagHop**, although output from other trajectory codes can be adapted with minimal preprocessing. A specific utility named `filter_files_size` is provided to select successfully completed trajectories.

The **Constructors** functionality converts physical inputs into atomic units, generates frequency grids for pump, probe, and excitation axes, and converts axis values for plotting. This enforces a consistent internal representation in atomic units.

The **Processing** module includes functions for normalization, comparison of spectra, plotting using color-blind-friendly palettes, identifying missing values, and smoothing or interpolating spectra for visualization. These are post-processing and inspection tools rather than core formal components of the DW approximation, but they are part of the package’s stated goal of practical and reproducible workflow support.

At the center of the implementation is the **WaveMixing struct**, which stores data and associated signal calculations. The paper states that this struct has strongly typed functions for observables such as `gsb`, `gsb_strong`, and `gsb_dispersion`, with analogous functions for SE and ESA. For 2D spectroscopy, dedicated doorway and window functions include `gsb_door_r2d`, `gsb_door_nr2d`, and `gsb_wind_2d`. This organization suggests a separation between physical channel definitions and observable assembly, although the paper’s explicit claim is that these functions can be called with minimal code.

## 5. Computational workflow from trajectories

The package formalizes an **on-the-fly** DW workflow in which spectroscopy signals are assembled directly from trajectory data. The paper specifies the following sequence [2509.03917]:

1. **Sample initial conditions** $(R_g,P_g,e)$ from a phase-space distribution $p_s$  
2. **Compute the doorway function**  
3. **Propagate the trajectory in the ground-state manifold**  
4. **Evaluate the window function for the ground-state contribution**  
5. **Propagate the excited-state trajectory using surface hopping**  
6. **Evaluate the SE and ESA window functions**  
7. **Repeat until Monte Carlo convergence**

For very short pump pulses, the sampling distribution is
$$
p_s(R_g,P_g,e)=|M_{ge}(R_g)|^2\,\rho_g(R_g,P_g),
\tag{35}
$$
whereas for longer pump pulses the pump spectral envelope is incorporated into the sampling:
$$
p_s(R_g,P_g,e)=E_{\mathrm{pu}}(\omega_{\mathrm{pu}}-U_{eg}(R_g))\,|M_{ge}(R_g)|^2\,\rho_g(R_g,P_g).
\tag{36}
$$
The sampled DW expression becomes
$$
S(T,T,Tt)\sim \mathrm{Re}\sum_{k=0,I,II} a_k \left(W_k(R(T),P(T);Tt)\,D^{(s)}(R_g,P_g;T)\right)_{\mathrm{MC}_s},
\tag{37}
$$
with
$$
D^{(s)}(R_g,P_g;T)=p_s(R_g,P_g,e)D(R_g,P_g;T).
\tag{38}
$$
A notable efficiency feature is that if the pump envelope is absorbed into the sampling distribution, the doorway can become constant:
$$
D^{(s)}(R_g,P_g)=1.
\tag{40}
$$
The paper identifies this as computationally advantageous. In practical terms, this means that part of the spectroscopy weighting can be transferred from explicit observable evaluation into the Monte Carlo sampling stage.

## 6. Strong-field extension, computational performance, and application domain

Beyond weak-field DW spectroscopy, the paper introduces **strong-field TA PP** formulas, where linear scaling with field strength no longer applies. Assuming rectangular pulses, the strong-field signal is given as
$$
S_{\mathrm{str}}(T,\omega_{\mathrm{pr}}) \sim \mathrm{Re}\sum_{k=0,I,II} a_k\, W_k^{\mathrm{str}}(\omega_{\mathrm{pr}},R(T),P(T))\, D_k^{\mathrm{str}}(\omega_{\mathrm{pu}},R,P),
\tag{26}
$$
with doorway and window functions expressed through Rabi frequencies such as
$$
\Omega_{eg}(R)=\sqrt{(V_{eg}(R)-\omega_{\mathrm{pu}})^2 + 4X_{\mathrm{pu}}|M_{ge}(R)|^2}.
\tag{28}
$$
The strong-field terms contain factors such as $1-\cos(\Omega T_{\mathrm{pu}})$, reflecting finite-duration coherent driving, and the weak-field limit recovers the standard DW formulas [2509.03917].

The Julia implementation is presented as suitable for both **desktop/laptop use** and **HPC environments**. The paper gives one explicit benchmark: in a pyrazine example, one integral TA PP evaluation from **591 trajectory logs** took about **128 s** on a laptop. Because the package is described as relying only on Julia standard libraries, the implementation is also characterized as having **minimal dependencies** [2509.03917].

The scientific application domain includes **photoinduced molecular relaxation**, **conical-intersection-driven internal conversion**, **vibronic coupling and wavepacket motion**, **chromophores in condensed phases**, and systems with many nuclear degrees of freedom for which exact quantum dynamics is infeasible. **Pyrazine** is used as a prototypical example because it is a classic system for ultrafast excited-state dynamics mediated by conical intersections. The paper states that WaveMixings.jl reproduces established TA PP, dispersed TA PP, TRF, 2D, and 2D-FLEX spectra for pyrazine, indicating continuity with prior in-house implementations [2509.03917].

## 7. Significance, limitations, and prospective extensions

The principal significance of WaveMixings.jl lies in the transition from undocumented internal scripts to an open-source package with tutorials, a wiki, and an API. In the terms used by the paper, this lowers the barrier for other groups to adopt and further develop quasi-classical DW methods [2509.03917]. The package is therefore positioned both as a production tool for routine spectroscopy simulations and as a platform for implementing new observables within the same framework.

Several limitations are explicit in the underlying formalism. The DW approximation, as implemented here, assumes non-overlapping pulses, negligible nuclear motion during each pulse, fixed-nuclei electronic coherence evolution during coherence times, and quasi-classical treatment of population-time dynamics. In addition, laser polarization and orientational averaging are not explicitly treated in the presented integral formulas. These constraints are not incidental details; they define the range of problems for which the generated signals should be interpreted as faithful approximations.

The paper also delineates future extensions, including **population-detected FWM**, **polarization-resolved signals**, **six-wave-mixing**, **anisotropies**, **X-ray TA PP**, and additional post-processing tools. This suggests an intended trajectory in which the package remains centered on the DW framework while expanding the space of supported observables. A plausible implication is that WaveMixings.jl is meant to function as a common software substrate for methodological development in ultrafast chemical physics, rather than only as an implementation of a fixed set of formulas [2509.03917].

Source: https://www.emergentmind.com/topics/wavemixings-jl