Skip to content

docs: new readme #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kramerqk merged 1 commit into from
Mar 4, 2026
Merged

docs: new readme #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 71 additions & 140 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,50 @@
<!-- Currently entirely Copilot-generated -->

<img src="web/favicon.ico" width="50">

# RTEST: Real Time Electronic Structure Theory

![Ruff Code Check](https://github.com/kramerqk/tdhf_proto/actions/workflows/ruff.yml/badge.svg)
![Pytest](https://github.com/kramerqk/tdhf_proto/actions/workflows/pytest.yml/badge.svg)
# RTEST: Real-Time Electronic Structure Theory

![Ruff Code Check](https://github.com/kramerqk/rtest/actions/workflows/ruff.yml/badge.svg)
![Pytest](https://github.com/kramerqk/rtest/actions/workflows/pytest.yml/badge.svg)

## Overview
RTEST is a Python package for real-time electronic structure theory simulations, implementing Time-Dependent Hartree-Fock (TDHF) and Time-Dependent Density Functional Theory (TDDFT) methods.
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.

<div align="left">
<img width="70%" src="for_presentation/density_animation.gif" alt="Animation of the density difference over time">
</div>

Import and use RTEST in your Python scripts for programmatic control over simulations. Alternatively, you can also use RTEST as a CLI tool with YAML configuration files (see [CLI Usage](#alternative-using-as-a-cli-tool) below).

## Requirements
- **Linux or macOS** (PySCF is not supported on native Windows - use WSL on Windows)
- Python 3.10 or higher
- PySCF 2.11.0
- NumPy, SciPy, Matplotlib
- Additional dependencies listed in `pyproject.toml`

**Windows Users:** PySCF only runs on Linux/macOS. Windows users must use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install) to run this software.
> [!IMPORTANT]
> PySCF is not natively supported on Windows. Linux or macOS is required. Alternatively, WSL or a traditional virtual machine can be used.

## Installation
- Python 3.10
- additional dependencies are listed in pyproject.toml


## Programmatic use

### Installation

Install directly from GitHub:
```bash
Expand All @@ -30,29 +53,28 @@ python3 -m venv venv
source venv/bin/activate # On Linux/macOS/WSL

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

**Note:** The `--prefer-binary` flag is recommended for PySCF, which is a dependency of the project.

### Updating

To update to the latest version:
```bash
pip install --upgrade --force-reinstall --no-deps git+https://github.com/kramerqk/TDHF_Proto.git
pip install --upgrade --force-reinstall --no-deps git+https://github.com/kramerqk/rtest.git
```

To check your current version:
```bash
pip show rtest
```

## Usage
### Quick start
> [!TIP]
> More code examples can be found here in the wiki.

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

```python
from typing import List
from rtest import tdhf, SimulationConfig, SimulationResults, setup_logging

# Enable logging
Expand All @@ -66,107 +88,21 @@ config = SimulationConfig.create(
timeframe=150.0
)

# Disable cubefile saving
# Disable cube file saving
config.save = False

# Run the simulation
results: List[SimulationResults] = tdhf(config, method="tdhf")
# Run simulation
results = tdhf(config, method="tdhf")

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

# Access specific data from the results via the DataHandler
# 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}")
```

### Advanced Configuration

```python
from rtest import tdhf, SimulationConfig
from rtest.methods.shared.pulse import Pulse
from rtest.methods.shared.calculable import Calculable

# Custom configuration with pulses and observables
config = SimulationConfig(
molecule="H2O",
basis="6-31g**",
dt=0.01,
timeframe=150.0,
# define specific laser pulses yourself
pulses=[
Pulse.GAUSSIAN_DEFAULTS(axis="x")[0],
Pulse.GAUSSIAN_DEFAULTS(axis="y")[0],
],
# define what to calculate for returned results
calculables=[
Calculable.INDUCED_DIPOLE_DEFAULT(axis="x"),
Calculable.INDUCED_DIPOLE_DEFAULT(axis="y"),
],
# calculate an approximated absorption spectrum
# (off-diagonal of polarizability-tensor assumed = 0)
approximate_absorption_spectrum=True,
# save density-diff to ground state as .cube-file every 25 steps
save=True,
frames_interval=25
)

results = tdhf(config)

# Access the results
print(results[0].data_handler.get_data("induced_dipole_x"))
print(results[0].data_handler.get_data("induced_dipole_y"))
```

### Enabling Logging

You easily enable logging by calling `setup_logging`:

<!-- **Option 1: Use the built-in helper (recommended for quick setup)** -->
```python
from rtest import setup_logging

# Enable logging
setup_logging("INFO")

# Now run the simulation
from rtest import tdhf, SimulationConfig
...
```

<!-- **Option 2: Configure logging yourself (for advanced users)**
```python
import logging

# Basic configuration
logging.basicConfig(level=logging.INFO)

# Or configure just the tdhf logger
logging.getLogger("tdhf").setLevel(logging.INFO)
logging.getLogger("tdhf").addHandler(logging.StreamHandler())
``` -->

**Available log levels:**
- `"WARNING"` - Only show warnings and errors
- `"INFO"` - Show progress and important events (recommended)
- `"VERBOSE"` - Show more detailed information
- `"DEBUG"` - Show all debugging information

## Project Structure
- `src/rtest/analysis/` - Post-simulation analysis
- `src/rtest/config/` - Globals, config-handling of both CLI [`.yaml`] and library-usage
- `src/rtest/cubefile/` - Cube file generation for molecular visualization
- `src/rtest/definitions` - Molecule coordinate definitions (`"H2"`, `"H2O"`, etc.)
- `src/rtest/helpers` - Misc. helpers
- `src/rtest/logging` - Logging utility
- `src/rtest/methods/` - Core simulation methods (TDHF [hf, dft], ~~TDDFT~~, ~~TDHFCIS~~)
- `src/rtest/modules/` - Propagators, misc.
- `src/rtest/plotting/` - Visualization utilities
- `src/rtest/results` - Results plotting and saving

---

## Alternative: Using as a CLI Tool
## 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.

Expand All @@ -176,16 +112,12 @@ Clone the repository and install in editable mode:

```bash
# Clone the repository
git clone https://github.com/kramerqk/TDHF_Proto.git
# Or with SSH: git clone git@github.com:kramerqk/TDHF_Proto.git
cd TDHF_Proto

# On Ubuntu/Debian (including WSL), install venv if not already available:
# sudo apt install python3-venv
git clone https://github.com/kramerqk/rtest.git
cd rtest

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

# Install in editable mode
pip install --prefer-binary -e .
Expand All @@ -196,9 +128,9 @@ Alternatively, install dependencies using requirements.txt:
pip install -r requirements.txt
```

On WSL, you may need `pip install PyQt6` for matplotlib to display the generated plots in an interactive window. The corresponding .png-file will be saved regardless.

### CLI Usage
### Quick Start
> [!TIP]
> See the project wiki for all available parameters.

1. Copy the template configuration file:
```bash
Expand All @@ -209,31 +141,30 @@ cp input.template.yaml input.yaml

3. Run a simulation:
```bash
python main.py
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 visualization
- Simulation data (.npy)
- Generated plots and figures
- Cube files for visualisation

5. **Visualize results** (if cubefile-generation was enabled in `input.yaml`):
5. **Visualise results** (if cube file generation was enabled in `input.yaml`):
```bash
python3 -m http.server
```
Then open http://localhost:8000 in your browser to view the 3D molecular visualization (automatically loads the latest run with cube files)

### CLI Configuration

The CLI simulation is configured via `input.yaml`. Key options include:
- **Simulation method**: Hartree-Fock (`hf`) or density functional theory (`dft`)
- **System definition**: Define your molecular system
- **Propagation parameters**: Set timesteps, integration methods, etc.
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.

See `input.template.yaml` for detailed configuration options and explanations.

---
## 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
[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] Polygonising a scalar field (Marching Cubes). (1994, May). https://paulbourke.net/geometry/polygonise/
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

Binary file added for_presentation/density_animation.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.