WaveMixings.jl: DW Spectroscopy Toolkit

• WaveMixings.jl is a Julia package that implements the quasi-classical doorway-window approximation to simulate transient nonlinear spectroscopic signals.
• It processes trajectory data on-the-fly, converting electronic energies, transition dipole moments, and state populations into observable spectra like TA PP and 2D signals.
• Leveraging Julia’s multiple dispatch and BLAS-backed linear algebra, the package replaces undocumented scripts with a reproducible and extensible workflow for nonadiabatic dynamics.

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 (Vasquez et al., 4 Sep 2025).

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” (Vasquez et al., 4 Sep 2025). 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 (Vasquez et al., 4 Sep 2025).

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 (Vasquez et al., 4 Sep 2025).

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

$D(T)$0

where $D(T)$1 is the ground-state manifold, $D(T)$2 the bright excited-state manifold, and $D(T)$3 a higher-lying probe-accessible manifold. The corresponding dipole operators are block-partitioned so that $D(T)$4 and $D(T)$5 describe upward and downward transitions between the manifolds $D(T)$6, $D(T)$7, and $D(T)$8.

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 (Vasquez et al., 4 Sep 2025). 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 (Vasquez et al., 4 Sep 2025).

For integral transient absorption pump-probe, the signal is obtained by setting the second coherence delay to zero:

$D(T)$9

The doorway function is

$W_k(Tt)$0

where $W_k(Tt)$1 is the pump spectrum, $W_k(Tt)$2 is the transition frequency, $W_k(Tt)$3 is the transition dipole moment, and $W_k(Tt)$4 is the ground-state vibrational Wigner distribution. The integral window functions are

$W_k(Tt)$5

$W_k(Tt)$6

$W_k(Tt)$7

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

$W_k(Tt)$8

For dispersed TA PP, detection-frequency resolution is retained:

$W_k(Tt)$9

The window functions include a dephasing rate $\zeta(T)$0, which controls the line shape in the frequency domain and yields Lorentzian-like factors of the form

$\zeta(T)$1

This introduces finite linewidths and frequency dispersion in the transmitted probe (Vasquez et al., 4 Sep 2025).

For 2D spectra, the DW signal is Fourier transformed with respect to both coherence-time variables:

$\zeta(T)$2

The package includes both non-rephasing and rephasing phase-matching directions, with $\zeta(T)$3 for non-rephasing and $\zeta(T)$4 for rephasing. The doorway is

$\zeta(T)$5

The window functions are

$\zeta(T)$6

$\zeta(T)$7

$\zeta(T)$8

Both doorway and window are therefore complex-valued, and $\zeta(T)$9 broadens spectral features.

The paper also implements 2D-FLEX, a fluorescence-detected 2D technique with

$k=0,I,II$0

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 (Vasquez et al., 4 Sep 2025).

4. Software architecture and internal organization

WaveMixings.jl is described as a multi-module Julia package with four major functional areas (Vasquez et al., 4 Sep 2025).

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 (Vasquez et al., 4 Sep 2025):

1. Sample initial conditions $k=0,I,II$1 from a phase-space distribution $k=0,I,II$2
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

$k=0,I,II$3

whereas for longer pump pulses the pump spectral envelope is incorporated into the sampling:

$k=0,I,II$4

The sampled DW expression becomes

$k=0,I,II$5

with

$k=0,I,II$6

A notable efficiency feature is that if the pump envelope is absorbed into the sampling distribution, the doorway can become constant:

$k=0,I,II$7

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

$k=0,I,II$8

with doorway and window functions expressed through Rabi frequencies such as

$k=0,I,II$9

The strong-field terms contain factors such as $a_0=a_I=1, \qquad a_{II}=-1,$0, reflecting finite-duration coherent driving, and the weak-field limit recovers the standard DW formulas (Vasquez et al., 4 Sep 2025).

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 (Vasquez et al., 4 Sep 2025).

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 (Vasquez et al., 4 Sep 2025).

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 (Vasquez et al., 4 Sep 2025). 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 (Vasquez et al., 4 Sep 2025).