TARANTULA

Xray induced dynamics for the experimental frontier

A dual functional C++ code for:

1. TDSE_XFEL: Numerical solution of the time-dependent Schrödinger equation (TDSE) to simulate electronic population transfer dynamics in the presence of ultrafast, intense x-rays pulses for an arbitary number of states and decay channels and includes:

   • Rotating-wave approximation (RWA)
   • Gaussian pulse envelopes with:
     • focal-volume averaging
     • bandwidth averaging
     • AC-Stark shifts
   • Photon energy and pulse intensity scans
   • Decay channel populations dynamics with user provided:
     • Auger-Meitney decay widths
     • photoionization cross-sections
   • 1 or 2 pulse mode configurations with either:
     • orientational averaging
     • perpendicular polariztion

2. SPAWN_DECAY: Model wave packet evolution over multiple potential energy surfaces (PES) in multi-step Auger-Meitner decay cascades, via novel trajectory basis function decay spawning alorithm:

   • Current implementation prototypes decay spawning algorithm by modelling wave packet evolution across pre-defined PES from ab initio molecular dynamics (AIMD) simulations
   • Algorithm propagates trajectory basis functions (TBFs) acroos multiple potential energy surfaces using:
     • Partial Auger rates for each channel that determine the population transer rate
     • User-defined spawning recurrance paramter to resolves the dispersion of the nuclear wavepacket
   • Spawning algorithm uses phase-matching and bond-length mapping for cascade dynamics

This code was used for these publications, here the full set theoretical and computational details can be found:

TDSE_XFEL

1. Site-specific generation of excited state wavepackets with high-intensity attosecond x rays

   • A. E. A. Fouda and P. J. Ho J. Chem. Phys. (2021) 154, 224111
   • https://doi.org/10.1063/5.0050891

2. Resonant Double-Core Excitations with Ultrafast, Intense Pulses

   • A. E. A. Fouda, D. Koulentianos, L. Young, G. Doumy and P. J. Ho Mol. Phys. (2022) e2133749
   • https://doi.org/10.1080/00268976.2022.2133749

SPAWN_DECAY

1. Quantum molecular charge-transfer model for multistep Auger–Meitner decay cascade dynamics
   • A. E. A. Fouda, S. H. Southworth and P. J. Ho J. Chem. Theory Comput. (2024) 20, 20, 8782-8794
   • https://doi.org/10.1021/acs.jctc.4c00778

If this code and/or research is useful/related to your work please give em a cite!

The docs are a work in progress, please reach out to me if you have questions about this code

1. Code Architecture
2. Dependencies
3. Build Instructions
4. Running Simulations
5. Input File Reference
6. Output Files
7. Examples

TARANTULA/
├── src/
│   ├── main.cpp               # Entry point: dispatches to TDSE_XFEL or SPAWN_DECAY
│   ├── xfel_tdse.cpp          # XFEL_TDSE() — full TDSE setup, time loop, and output
│   ├── pulse_interaction.cpp  # TDSEUTILITY class — focal-volume avg, bandwidth avg, EOM driver
│   ├── rk4.cpp                # EOMDRIVER class — RK4 integrator, REQ (TDSE), REQ_SPAWN, decay
│   ├── spawn_decay.cpp        # SPAWN_DECAY() — spawning algorithm on AIMD data
│   └── read_and_write.cpp     # I/O: read_matrix, file2vector, FILEWRITER class
├── include/
│   ├── xfel_tdse.h            # Declaration of XFEL_TDSE()
│   ├── spawn_decay.h          # Declaration of SPAWN_DECAY()
│   ├── pulse_interaction.h    # TDSEUTILITY class declaration
│   ├── rk4.hpp                # EOMDRIVER class declaration
│   ├── read_and_write.h       # I/O function/class declarations + templates
│   └── vectypedef.hpp         # Type aliases (complexd, vec1x, vec2x, etc.)
├── bin/
│   └── tarantula              # Compiled binary
├── obj/                       # Object files
├── examples/
│   ├── n2o_tdse/              # N2O XFEL TDSE example (publication test case)
│   │   ├── inputs/            # Input data files
│   │   ├── matrix_elements/   # Hamiltonian matrix elements
│   │   ├── outputs/           # Simulation outputs
│   │   └── reference/         # Reference outputs for regression testing
│   └── ibr_spawn/             # IBr Auger-Meitner spawning example (publication test case)
│       ├── inputs/            # Input data files + AIMD trajectories
│       ├── outputs/           # Simulation outputs
│       └── reference/         # Reference outputs for regression testing
└── Makefile                   # Build system

macOS (Homebrew):

brew install armadillo

Ubuntu/Debian:

sudo apt-get install libarmadillo-dev

From source:

wget https://sourceforge.net/projects/arma/files/armadillo-12.8.0.tar.xz
tar xf armadillo-12.8.0.tar.xz
cd armadillo-12.8.0
cmake . -DCMAKE_INSTALL_PREFIX=$HOME/armadillo-install
make install

1. A C++11 compiler — the default Makefile uses the Intel C++ compiler (icpc). If you don't have Intel compilers, switch to g++ or clang++ (see below).
2. Armadillo — installed somewhere accessible (see Dependencies).
3. OpenMP — used for parallelisation (comes with icpc and g++; on macOS with clang++ you need libomp).

Before building, edit the Makefile to set two things:

The default is icpc (Intel C++ classic). To change it, uncomment/set CXX:

# Intel (default in the shipped Makefile):
CXX = icpc

# GNU:
CXX = g++

# Intel oneAPI (newer):
CXX = icpx

# macOS Xcode clang (requires libomp for OpenMP):
CXX = clang++

Intel compiler setup: If using Intel compilers on a cluster, source the Intel environment first, e.g.:

source /path/to/intel/oneapi/setvars.sh

Set the CFLAGS line to point to your Armadillo installation:

# Custom install path (default in shipped Makefile):
CFLAGS = $(OPTS) /path/to/armadillo-install/include -fopenmp

# System-installed Armadillo (Homebrew / apt — no path needed):
CFLAGS = $(OPTS) -fopenmp

Note: If Armadillo is installed via Homebrew (brew install armadillo) or a system package manager, the include path is already in the compiler's default search path, so you can simply use CFLAGS = $(OPTS) -fopenmp.

If using clang++ on macOS, you need Homebrew's libomp for OpenMP:

brew install libomp

Then update the Makefile:

CXX = clang++
CFLAGS = $(OPTS) -I$(shell brew --prefix libomp)/include -fopenmp
LDFLAGS = -L$(shell brew --prefix libomp)/lib -lomp

cd /path/to/TARANTULA
make clean
make

The compiled binary is placed at bin/tarantula.

The shipped Makefile compiles the following source files:

read_and_write.cpp  pulse_interaction.cpp  main.cpp  rk4.cpp  xfel_tdse.cpp  spawn_decay.cpp

Key variables:

Tip: For production runs, change -O0 to -O2 in OPTS for optimised builds.

TARANTULA reads all input from the current working directory. You must cd into a directory that contains an inputs/ folder (and for TDSE_XFEL, a matrix_elements/ folder).

cd examples/n2o_tdse
../../bin/tarantula

Output files are written to outputs/ in the current working directory.

The main configuration file uses a keyword-value format (one per line, whitespace-delimited). Lines beginning with # are comments.

Output files are written to outputs/. Columns are whitespace-delimited.

Column format: time pop_0 pop_1 ... pop_(N-1) [decay_channels...] norm

Reproduces the double core-hole XANES N2O wave packet simulation from:

A. E. A. Fouda, D. Koulentianos, L. Young, G. Doumy and P. J. Ho, Mol. Phys. (2022) e2133749

Simulation details:: 9 electronic states, Gaussian pulse (1.5 fs FWHM, 1.2 eV bandwidth), bandwidth averaging (100 points), perpendicular orientational averaging, Auger + photoionisation decay.

cd examples/n2o_tdse
../../bin/tarantula
# Output written to outputs/0_perp_avg.txt, outputs/0_x.txt, outputs/0_y.txt

Reproduces IBr multi-step decay cascade dynamics from:

A. E. A. Fouda, S. H. Southworth and P. J. Ho, J. Chem. Theory Comput. (2024) 20, 20, 8782-8794

Simulation details: 5 electronic states, 2 decay steps, 2 channels per step, TBF spawning every 5000 time steps, using AIMD trajectory data for potential energies and bond lengths.

cd examples/ibr_spawn
../../bin/tarantula
# Output: outputs/population_0.txt through population_4.txt, plus bond length/energy/charge/spin data

Python plotting scripts are provided in the example directory:

• plotting_population_all.py — overview of all state populations
• plotting_spawn.py — individual spawned TBF populations
• plotting_spawn_weight_avg.py — weight-averaged molecular properties