diff --git a/README.md b/README.md index af7fc96..4f542a1 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,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. + +
+ Animation of the density difference over time +
-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 @@ -30,16 +53,14 @@ 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: @@ -47,12 +68,13 @@ To check your current version: 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 @@ -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`: - - -```python -from rtest import setup_logging - -# Enable logging -setup_logging("INFO") - -# Now run the simulation -from rtest import tdhf, SimulationConfig -... -``` - - - -**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. @@ -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 . @@ -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 @@ -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//` where `` 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 + diff --git a/for_presentation/density_animation.gif b/for_presentation/density_animation.gif new file mode 100644 index 0000000..4c20bbd Binary files /dev/null and b/for_presentation/density_animation.gif differ