Three-dimensional Fourier-Bessel decomposition for cosmological fields
Version 2.0.0 - Python Translation
py3dex is a pure Python implementation of the 3DEX library for fast Fourier-Bessel decomposition of 3D cosmological fields. It provides tools for analyzing galaxy surveys and reconstructing 3D density fields from observational data.
- Pure Python: No Fortran/C++ compilation required
- Modern Dependencies: NumPy, SciPy, healpy, astropy
- Performance: Numba JIT compilation for critical functions
- Easy Installation:
pip installcompatible - CLI Tools: Command-line scripts for common operations
- Well-Tested: Comprehensive pytest suite
- Documentation: Full API documentation with examples
pip install -e .pip install -e ".[dev]"pip install -e ".[mpi]"pip install -e ".[dev,mpi,performance,docs]"import numpy as np
from py3dex import transforms, fitstools
# Load survey data (phi, theta, r)
survey = np.loadtxt("mysurvey.txt")
nbpts = len(survey)
# Set parameters
nnmax, nlmax, nside, rmax = 20, 20, 256, 2000.0
# Generate Fourier-Bessel coefficients
kln = transforms.gen_kln(nnmax, nlmax, rmax)
cln = transforms.gen_cln(kln, nnmax, nlmax, rmax)
# Perform decomposition
almn = transforms.survey2almn_simple(
survey, nbpts, nside, nnmax, nlmax, nlmax, kln
)
# Save results
fitstools.write_almn("almn.fits", almn)
fitstools.write_cln("cln.fits", cln, kln)
# Reconstruct map at radius
map_recon = transforms.almn2rmap(
almn, radius=400.0, nside=nside, nnmax=nnmax,
nlmax=nlmax, nmmax=nlmax, kln=kln, cln=cln
)# Fourier-Bessel decomposition
py3dex-survey2almn survey.txt almn.fits cln.fits 20 20 256 2000.0
# Reconstruct map at radius
py3dex-almnfile2rmap almn.fits map.fits 400.0 256 10 10 2000.0
# Interactive mode with parameter file
py3dex-survey2almn-interactive parameters.txt
# Compute Bessel roots table
py3dex-compute-qln qln_table.fits 20 20py3dex.utils: Utility functions and helperspy3dex.transforms: Fourier-Bessel transforms and special functionspy3dex.stats: Statistical functions and simulationspy3dex.cosmotools: Cosmological calculationspy3dex.fitstools: FITS file I/O operationspy3dex.survey: Survey data handling
py3dex-survey2almn: Standard decompositionpy3dex-survey2almn-lm: Low-memory versionpy3dex-survey2almn-interactive: Interactive modepy3dex-almnfile2rmap: Map reconstructionpy3dex-compute-qln: Bessel root computationpy3dex-compute-legen-plm: Legendre computationpy3dex-compute-qml-pl: QML power spectrumpy3dex-genmap: Map generation
- Python >= 3.8
- NumPy >= 1.20
- SciPy >= 1.7
- healpy >= 1.15
- astropy >= 5.0
- numba >= 0.55
- mpi4py >= 3.1 (for MPI support)
- jax >= 0.3 (for GPU acceleration)
- pytest >= 7.0 (for testing)
- sphinx >= 4.5 (for documentation)
Full documentation is available at https://3dex.readthedocs.io
To build documentation locally:
cd docs
make htmlRun the test suite:
pytestWith coverage:
pytest --cov=py3dex --cov-report=htmlThe Python version provides equivalent functionality to the original Fortran/C++ implementation with these key differences:
- No compilation needed: Pure Python, install with pip
- Modern API: Pythonic interfaces, NumPy arrays
- Better I/O: Uses astropy.io.fits instead of CFITSIO
- Simplified HEALPix: Uses healpy instead of raw HEALPix
- Performance: Numba JIT for critical sections
See MIGRATION.md for detailed migration guide.
- Uses Numba JIT compilation for Bessel functions (first run slower)
- OpenMP parallelization replaced by multiprocessing
- For large datasets (nside > 1024), use low-memory version
- GPU acceleration available with JAX (experimental)
If you use py3dex in your research, please cite the original paper:
@article{leistedt2012,
title={3DEX: a code for fast spherical Fourier-Bessel decomposition of 3D surveys},
author={Leistedt, Boris and Rassat, Anais and R{\'e}fr{\'e}gier, Alexandre and Starck, Jean-Luc},
journal={Astronomy \& Astrophysics},
volume={540},
pages={A60},
year={2012},
doi={10.1051/0004-6361/201118463},
eprint={1111.3591},
archivePrefix={arXiv}
}py3dex is distributed under the CeCILL License (compatible with GNU GPL).
See LICENSE.CeCILL for details.
Original Fortran/C++ Implementation:
- Boris Leistedt (boris.leistedt@gmail.com)
- François Lanusse (francois.lanusse@gmail.com)
Python Translation (2024-2026):
- Python version translated by Claude Code
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
For bugs and feature requests, please open an issue on GitHub: https://github.com/borisleistedt/3DEX/issues
This work builds on the original 3DEX package and uses:
- HEALPix via healpy
- FITS I/O via astropy
- Special functions from SciPy
- Performance optimizations via Numba
- Original paper: arXiv:1111.3591
- HEALPix: http://healpix.sourceforge.net
- healpy: https://healpy.readthedocs.io