RTEST: Real-Time Electronic Structure Theory

Overview

RTEST is a Python package for simulating the electronic response of molecules to lasers by means of real-time electronic structure theory. In contrast to linear-response models, Time-Dependent Hartree-Fock (TDHF) and Time-Dependent Density Functional Theory (TDDFT) methods numerically propagate the density using the von Neumann equation and therefore include higher-order density responses. The ground state calculations are performed using PySCF.

Two interfaces are provided: a programmatic interface suited for pipeline development and in-depth analysis, as well as a command-line interface that reads from an input configuration file.

Note

RTEST is not intended to be a fully sophisticated quantum chemistry program. It is rather a prototyping project aimed at gaining insights into each aspect that makes up a real-time electron dynamics simulation.

Features

Modularisation

Real-time simulations are typically composed of multiple components such as the propagator, the molecule and environment as well as the desired output. As RTEST is highly modularised, many components can be exchanged to benchmark each part that makes up the simulation. This includes - among other things - the choice of:

• simulation method (Hartree-Fock and Density Functional Theory),
• propagator (fixed and adaptive timestep Runge-Kutta, Magnus expansion),
• laser (intensity, type, orientation),
• output (absorption spectrum, induced dipole, density difference).

Visualisation

An interactive animation of the density difference is accessible through the browser.

Requirements

Important

PySCF is not natively supported on Windows. Linux or macOS is required. Alternatively, WSL or a traditional virtual machine can be used.

• Python 3.10
• additional dependencies are listed in pyproject.toml

Programmatic use

Installation

Install directly from GitHub:

# Create and activate virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Linux/macOS/WSL

# install
pip install --prefer-binary git+https://github.com/kramerqk/rtest.git

Updating

To update to the latest version:

pip install --upgrade --force-reinstall --no-deps git+https://github.com/kramerqk/rtest.git

To check your current version:

pip show rtest

Quick start

Tip

More code examples can be found here in the wiki.

The following code runs a simple simulation on diatomic hydrogen and extracts the induced dipole along the x-axis:

from rtest import tdhf, SimulationConfig, SimulationResults, setup_logging

# Enable logging
setup_logging("INFO")

# Create a configuration using .create() (calculables, pulses, etc. set automatically)
config = SimulationConfig.create(
    molecule="H 0 0 0; H 0 0 0.74",  # H2 molecule
    basis="sto-3g",
    dt=0.01,
    timeframe=150.0
)

# Disable cube file saving
config.save = False 

# Run simulation
results = tdhf(config, method="tdhf")

# Access results
print(f"Simulation results: {results}")

# Extract data via the DataHandler
induced_dipole_x = results[0].data_handler.get_data('induced_dipole_x')
print(f"induced_dipole_x data: {induced_dipole_x}")

Declarative (CLI) use

If you prefer to run simulations via YAML configuration files rather than programmatically, RTEST can also be used as a CLI tool.

Installation for CLI Usage

Clone the repository and install in editable mode:

# Clone the repository
git clone https://github.com/kramerqk/rtest.git
cd rtest

# Create and activate virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install in editable mode
pip install --prefer-binary -e .

Alternatively, install dependencies using requirements.txt:

pip install -r requirements.txt

Quick Start

Tip

See the project wiki for all available parameters.

1. Copy the template configuration file:

cp input.template.yaml input.yaml

2. Edit input.yaml to configure your simulation (see comments in the file for options)

3. Run a simulation:

python3 main.py

4. Output files will be saved in out/<run_id>/ where <run_id> is a timestamp-based identifier (e.g., out/20260129_143052/). Output may include (see input.yaml):

• Simulation data (.npy)
• Generated plots and figures
• Cube files for visualisation

5. Visualise results (if cube file generation was enabled in input.yaml):

python3 -m http.server

Then open http://localhost:8000 in your browser to view the 3D molecular visualisation. The page automatically loads the most recent run with cube files.

What's next

• include more quantum chemistry methods such as TDCIS, TDCC
• make use of Cython extensions for time-intensive calculations
• add a unified web interface and API
• give estimates of numerical error (both discretisation and floating-point arithmetic)

References

The following sources are referenced in the code:

• [Lorensen1987] Lorensen, W. E., & Cline, H. E. (1987). Marching cubes: A high resolution 3D surface construction algorithm. ACM SIGGRAPH Computer Graphics, 21(4), 163–169. https://doi.org/10.1145/37402.37422
• [Bourke1994] Bourke, P. (1994). Polygonising a scalar field. Paulbourke.net. https://paulbourke.net/geometry/polygonise/
• [Sundnes2024] Sundnes, J. (2024). Solving Ordinary Differential Equations in Python. In Simula SpringerBriefs on Computing. Springer Nature Switzerland. https://doi.org/10.1007/978-3-031-46768-4