🌌 Laniakea

Laniakea is a Ultra-Light Dark Matter Dynamics Pseudo-Spectral solver written in C/C++.

🚀 Motivation

This project is based on the original work by Dr. Faber Edwards et al. (arXiv:1807.04037) and aims to develop a faster and more scalable simulation framework for Ultra-Light Dark Matter (ULDM) models.

Compared to the existing PyUltraLight codebase, my implementation is designed for high-performance computing, enabling large-scale simulations on modern hardware. At the current state, the algorithm is faster than the original implementation and provides mostly identical results. You can plot the results using the provided python scripts.

It works by solving a Schrödinger-Poisson system using a pseudo-spectral method, involving a leap-frog evolution procedure and successive Fourier Transforms over a grid. The wave function of the system evolves according to the following set of equations:

$$i\hbar \frac{\partial \psi}{\partial t}(\vec{x}, t) = \left[-\frac{\hbar^2}{2m} \nabla^2 + m\Phi(\vec{x}, t)\right]\psi(\vec{x}, t)$$ $$\nabla^2 \Phi(\vec{x}, t) = 4\pi mG|\psi(\vec{x}, t)|^2$$

🛠️ Installation

To get started, clone the repository using the command and compile the project using make AFTER you install FFTW and FFmpeg:

  git clone git@github.com:Ciriphys/Laniakea.git
  make

This project uses FFmpeg and FFTW, and currently supports macOS and Linux (tested on Ubuntu). The codebase provides implementation for two different projects: SolitonSim and Laniakea. You'll need to run them both in this order, as SolitonSim provides the soliton data that Laniakea uses to compute the full simulation. All the simulations I've conducted are obtained by running SolitonSim with the following arguments:

  ./run-sltn soliton.dat 900000 9.0

Laniakea uses a native configuration loader to avoid recompilation after each change. You can find some examples in the configs folder. To run Laniakea use the following command:

  ./run-lnk <path-to-config-file>

at this point, a simulation should start and all information should appear on terminal.

⚙️ FFTW Installation Notes

On both systems, you can download and compile FFTW manually from the official website. The library should install automatically in /usr/local/lib unless specified otherwise. If you do make sure to modify the makefile accordingly. Here is a little guide to install FFTW correctly:

./configure --enable-shared --enable-openmp --enable-thread
make && make install

⚙️ FFmpeg Installation Notes

FFmpeg is launched with a pipe on a separate thread on start by default. Here is a guide to install it on different operating systems:

macOS

On macOS, you can obtain FFmpeg via Homebrew:

brew install ffmpeg

Last tested version: macOS Tahoe 26.0.

Linux (Ubuntu)

On Ubuntu, you can obtain FFmpeg via apt:

sudo apt install ffmpeg

Last tested version: Ubuntu 25.10.

📋 Roadmap

Here is a planned roadmap of implemented and upcoming features:

• Pseudo-spectral Schrödinger-Poisson and RKIV methods
• Fully parallelized CPU computation using OpenMP.
• Native video rendering using FFmpeg.
• Native system loader using configuration files.
• Codebase refactoring.
• GPU computation (I do not own a modern GPU right now!).

📜 License

This project is licensed under the GNU General Public License v3.

Portions of this project are based on code released under the BSD 3-Clause License. The original repository can be found here. See LICENSE.BSD for full terms.

🤝 Contributing

By contributing to this project (via pull request or other means), you agree to the terms of the Contributor License Agreement.

Your contributions are welcome!