periodfind 0.0.6

GPU-accelerated period finding utilities

PeriodFind

A collection of CUDA-accelerated periodicity detection algorithms, with both C++ and Python APIs. Includes a Rust-based CPU backend for environments without GPU hardware.

Algorithms

Algorithm	Unified API	GPU (CUDA)	CPU (Rust)
Conditional Entropy	periodfind.ConditionalEntropy	periodfind.gpu.ConditionalEntropy	periodfind.cpu.ConditionalEntropy
Analysis of Variance	periodfind.AOV	periodfind.gpu.AOV	periodfind.cpu.AOV
Lomb-Scargle	periodfind.LombScargle	periodfind.gpu.LombScargle	periodfind.cpu.LombScargle

Device API

Periodfind provides a PyTorch-style device abstraction so you can write device-agnostic code. When no device is set, it auto-detects GPU availability (tries to import the CUDA extensions and runs nvidia-smi).

import periodfind

# Set the global default device
periodfind.set_device('cpu')   # or 'gpu'
print(periodfind.get_device()) # 'cpu'

# Factory functions dispatch to the right backend
ce  = periodfind.ConditionalEntropy(n_phase=10, n_mag=10)
aov = periodfind.AOV(n_phase=15)
ls  = periodfind.LombScargle()

# Per-call override (ignores the global default)
ce_gpu = periodfind.ConditionalEntropy(n_phase=10, n_mag=10, device='gpu')

You can still import backends directly:

from periodfind.gpu import ConditionalEntropy  # CUDA backend
from periodfind.cpu import ConditionalEntropy  # Rust CPU backend

Installing

GPU backend (CUDA)

Requires CUDA installed with nvcc on your PATH (or set $CUDA_HOME).

pip install cython numpy
pip install -e .

CPU backend (Rust)

Requires a Rust toolchain and maturin:

pip install maturin
cd rust && maturin develop --release

This builds the periodfind.cpu module using Rayon for multithreaded parallelism. No GPU needed.

Python API

Ensure that Cython and numpy are both installed. Then, simply run:

python setup.py install

And periodfind should be installed!

C++ API

First, ensure that CMake is installed, and that it is at least version 3.8. Next, create a build directory for CMake to use, and cd into it:

mkdir cmakebuild
cd cmakebuild

Now, run CMake, and build the library:

cmake ..
make

Finally, install the package by running make install (may require super-user priveleges), which will install the library in /usr/local/lib/ and the headers in /usr/local/include/periodfind/ by default (on Linux, location will be different on other operating systems).

Testing

Run the full test suite with pytest:

pytest tests/ -v

Tests are organized into three categories:

• Unit tests (test_periodfind.py): Statistics, Periodogram, and utility tests (no GPU or Rust needed)
• CPU standalone tests (test_cpu_standalone.py): Tests for the Rust CPU backend
• GPU integration tests (test_periodfind.py): CUDA algorithm tests (auto-skipped if no GPU is available)

To run only CPU tests (no GPU required):

pytest tests/test_periodfind.py tests/test_cpu_standalone.py -v

CI

GitHub Actions runs CPU tests automatically on every push and PR. See .github/workflows/tests.yml. GPU tests run on self-hosted runners when available.

Compatibility

This package has been tested only on Linux hosts running CUDA 10.2 and CUDA 11. Other operating systems and versions of CUDA may work, but it is not guaranteed.

Acknowledgements

Funding for this project was provided by the Larson Scholar Fellowship as part of the SURF program.

License

This package is licensed under the BSD 3-clause license. The copyright holder is the California Institute of Technology (Caltech).

setup.py and MANIFEST.in are based off of an example project at https://github.com/rmcgibbo/npcuda-example/, licensed under the BSD 2-clause license.