Skip to content

Latest commit

 

History

History
244 lines (172 loc) · 5.88 KB

README_PYTHON.md

File metadata and controls

244 lines (172 loc) · 5.88 KB

py3dex: Python Implementation of 3DEX

Three-dimensional Fourier-Bessel decomposition for cosmological fields

Version 2.0.0 - Python Translation

Paper License

Overview

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.

Key Features

  • Pure Python: No Fortran/C++ compilation required
  • Modern Dependencies: NumPy, SciPy, healpy, astropy
  • Performance: Numba JIT compilation for critical functions
  • Easy Installation: pip install compatible
  • CLI Tools: Command-line scripts for common operations
  • Well-Tested: Comprehensive pytest suite
  • Documentation: Full API documentation with examples

Installation

Basic Installation

pip install -e .

With Development Tools

pip install -e ".[dev]"

With MPI Support

pip install -e ".[mpi]"

With All Optional Dependencies

pip install -e ".[dev,mpi,performance,docs]"

Quick Start

Python API

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
)

Command-Line Interface

# 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 20

Modules

Core Modules

  • py3dex.utils: Utility functions and helpers
  • py3dex.transforms: Fourier-Bessel transforms and special functions
  • py3dex.stats: Statistical functions and simulations
  • py3dex.cosmotools: Cosmological calculations
  • py3dex.fitstools: FITS file I/O operations
  • py3dex.survey: Survey data handling

CLI Tools

  • py3dex-survey2almn: Standard decomposition
  • py3dex-survey2almn-lm: Low-memory version
  • py3dex-survey2almn-interactive: Interactive mode
  • py3dex-almnfile2rmap: Map reconstruction
  • py3dex-compute-qln: Bessel root computation
  • py3dex-compute-legen-plm: Legendre computation
  • py3dex-compute-qml-pl: QML power spectrum
  • py3dex-genmap: Map generation

Dependencies

Required

  • Python >= 3.8
  • NumPy >= 1.20
  • SciPy >= 1.7
  • healpy >= 1.15
  • astropy >= 5.0
  • numba >= 0.55

Optional

  • mpi4py >= 3.1 (for MPI support)
  • jax >= 0.3 (for GPU acceleration)
  • pytest >= 7.0 (for testing)
  • sphinx >= 4.5 (for documentation)

Documentation

Full documentation is available at https://3dex.readthedocs.io

To build documentation locally:

cd docs
make html

Testing

Run the test suite:

pytest

With coverage:

pytest --cov=py3dex --cov-report=html

Migration from Fortran/C++ Version

The Python version provides equivalent functionality to the original Fortran/C++ implementation with these key differences:

  1. No compilation needed: Pure Python, install with pip
  2. Modern API: Pythonic interfaces, NumPy arrays
  3. Better I/O: Uses astropy.io.fits instead of CFITSIO
  4. Simplified HEALPix: Uses healpy instead of raw HEALPix
  5. Performance: Numba JIT for critical sections

See MIGRATION.md for detailed migration guide.

Performance Notes

  • 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)

Citation

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}
}

License

py3dex is distributed under the CeCILL License (compatible with GNU GPL). See LICENSE.CeCILL for details.

Authors

Original Fortran/C++ Implementation:

Python Translation (2024-2026):

  • Python version translated by Claude Code

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Support

For bugs and feature requests, please open an issue on GitHub: https://github.com/borisleistedt/3DEX/issues

Acknowledgments

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

See Also