rd-spiral: An open-source Python library for investigating 2D reaction-diffusion dynamics through pseudo-spectral methods

rd-spiral implements a mathematically rigorous framework for simulating spiral wave dynamics in reaction-diffusion systems. The library bridges theoretical formulations with practical implementation, providing transparent algorithms suitable for both educational exploration and research-quality investigations of pattern formation phenomena.

• Pseudo-spectral spatial discretization with exponential convergence for smooth solutions
• Adaptive time integration (Dormand-Prince RK5(4)) handling stiffness ratios exceeding 6:1
• Comprehensive statistical analysis framework for quantifying dynamical regimes
• Information-theoretic measures for pattern complexity characterization
• Robust output preservation with checkpoint mechanisms for extended simulations

The library implements the dimensionless reaction-diffusion system:

$$\frac{\partial u}{\partial t} = D_1\nabla^2 u + u - u^3 - uv^2 + \beta(u^2v + v^3)$$

$$\frac{\partial v}{\partial t} = D_2\nabla^2 v + v - u^2v - v^3 - \beta(u^3 + uv^2)$$

where $D_1$, $D_2$ are diffusion coefficients and $\beta$ is the coupling parameter controlling non-equilibrium dynamics.

• Python ≥ 3.8
• NumPy ≥ 1.20.0
• SciPy ≥ 1.7.0
• pandas ≥ 1.3.0
• xarray ≥ 0.19.0
• netCDF4 ≥ 1.5.7

pip install git+https://github.com/sandyherho/rd_spiral.git

git clone https://github.com/sandyherho/rd_spiral.git
cd rd_spiral
pip install -e .

# Execute pre-configured simulations
rd-spiral configs/stable_spiral.txt      # Stable rotating spiral
rd-spiral configs/turbulent_spiral.txt   # Spatiotemporal chaos
rd-spiral configs/pattern_decay.txt      # Diffusion-dominated decay

from rd_spiral import ReactionDiffusionSolver, parse_config

# Load configuration
config = parse_config('configs/stable_spiral.txt')

# Initialize and run solver
solver = ReactionDiffusionSolver(config)
solver.run()

The library includes three validated parameter configurations demonstrating distinct dynamical behaviors:

rd_outputs/
├── stable_spiral/
│   ├── solution.nc          # Full spatiotemporal data (NetCDF4)
│   ├── stats.csv           # Time series statistics
│   ├── config.txt          # Simulation parameters
│   └── initial_conditions.npz
└── turbulent_spiral/
    ├── solution.nc
    ├── stats.csv
    ├── checkpoints/        # Intermediate states for long runs
    └── simulation_status.txt

This implementation has been validated for investigating:

• Spiral wave stability and bifurcations in excitable media
• Defect-mediated turbulence in pattern-forming systems
• Information-theoretic characterization of spatiotemporal chaos
• Non-Gaussian statistics in deterministic dynamical systems

If you use rd-spiral in your research, please cite:

@article{herho2025rdspiral,
  author = {Herho, S. H. S. and Anwar, I. P. and Suwarman, R.},
  title = {{rd-spiral: An open-source Python library for learning 
           2D reaction-diffusion dynamics through pseudo-spectral methods}},
  journal = {[xxxx]},
  year = {202x},
  volume = {XX},
  pages = {XX--XX},
  doi = {10.XXXX/XXXXXXX}
}

We welcome contributions that maintain the library's emphasis on pedagogical clarity and mathematical rigor. Please ensure all code follows PEP 8 standards and includes comprehensive documentation.

This project is licensed under the MIT License - see the LICENSE file for details.

This work was supported by the Dean's Distinguished Fellowship from CNAS at UC Riverside (2023) and ITB Research, Community Service and Innovation Program (PPMI-ITB) in 2025.