Skip to content

Latest commit

 

History

History
266 lines (198 loc) · 5.43 KB

MIGRATION.md

File metadata and controls

266 lines (198 loc) · 5.43 KB

Migration Guide: Fortran/C++ to Python

This guide helps users migrate from the original Fortran/C++ 3DEX to py3dex.

Installation Changes

Before (Fortran/C++)

export CFITSIO=/path/to/cfitsio
export HEALPIX=/path/to/healpix
export LAPACK=/path/to/lapack
export BLAS=/path/to/blas
./configure
make

After (Python)

pip install py3dex

API Changes

Fortran → Python Module Mapping

Fortran Module Python Module
f3dex_utils py3dex.utils
f3dex_transforms py3dex.transforms
f3dex_stats py3dex.stats
f3dex_cosmotools py3dex.cosmotools
f3dex_fitstools py3dex.fitstools
survey.cpp py3dex.survey

Function Name Changes

Most function names are preserved, with these conventions:

  • Fortran UPPERCASE → Python lowercase
  • Underscores preserved
  • Array indexing: Fortran 1-based → Python 0-based

Examples:

! Fortran
CALL gen_kln(kln, nnmax, nlmax, rmax)
CALL gen_cln(cln, kln, nnmax, nlmax, rmax)
CALL BJL(l, x, jl)
# Python
kln = transforms.gen_kln(nnmax, nlmax, rmax)
cln = transforms.gen_cln(kln, nnmax, nlmax, rmax)
jl = transforms.bjl(l, x)

Array Indexing

! Fortran: 1-based indexing
REAL(DP), DIMENSION(1:nnmax, 0:nlmax, 0:nmmax) :: almn
almn(1, 0, 0) = value
# Python: 0-based indexing
almn = np.zeros((nnmax, nlmax+1, nmmax+1), dtype=complex)
almn[0, 0, 0] = value

FITS I/O

! Fortran
CALL write_almn(filename, almn, header, nnmax, nlmax, nmmax)
# Python
fitstools.write_almn(filename, almn, header)

CLI Command Changes

Fortran/C++ Python
bin/survey2almn py3dex-survey2almn
bin/survey2almn_lm py3dex-survey2almn-lm
bin/survey2almn_interactive py3dex-survey2almn-interactive
bin/almnfile2rmap py3dex-almnfile2rmap
bin/compute_qln py3dex-compute-qln

Arguments remain the same:

# Fortran
bin/survey2almn survey.txt almn.fits cln.fits 20 20 256 2000.0

# Python
py3dex-survey2almn survey.txt almn.fits cln.fits 20 20 256 2000.0

Data Format Compatibility

FITS Files

Python version produces compatible FITS files:

  • almn files: Binary tables with real/imaginary extensions
  • cln files: Binary tables with kln optional extension
  • Maps: HEALPix format via healpy

Files can be read by both versions.

ASCII Survey Files

Format unchanged:

# phi theta r (mass)
1.234 0.567 456.78
2.345 1.678 567.89
...

Performance Considerations

Parallelization

Fortran/C++ Python
OpenMP (!$OMP) multiprocessing / Numba parallel
MPI (mpirun) mpi4py

Memory Usage

  • Python version may use more memory for large datasets
  • Use survey2almn_lm for nside > 1024

Speed

  • First run slower due to Numba JIT compilation
  • Subsequent runs comparable to Fortran
  • Use JAX backend for GPU acceleration (experimental)

Code Examples

Example 1: Basic Decomposition

Fortran:

PROGRAM survey2almn
  USE f3dex_transforms
  USE f3dex_fitstools

  INTEGER :: nnmax=20, nlmax=20, nside=256
  REAL(DP) :: rmax=2000.0
  REAL(DP), ALLOCATABLE :: survey(:,:), kln(:,:), cln(:,:)
  COMPLEX(DP), ALLOCATABLE :: almn(:,:,:)

  CALL read_survey('survey.txt', survey)
  CALL gen_kln(kln, nnmax, nlmax, rmax)
  CALL gen_cln(cln, kln, nnmax, nlmax, rmax)
  CALL survey2almn_opt(nside, nnmax, nlmax, nlmax, survey, nbpts, almn, kln)
  CALL write_almn('almn.fits', almn, nnmax, nlmax, nlmax)
END PROGRAM

Python:

import numpy as np
from py3dex import transforms, fitstools

nnmax, nlmax, nside, rmax = 20, 20, 256, 2000.0

survey = np.loadtxt('survey.txt')
kln = transforms.gen_kln(nnmax, nlmax, rmax)
cln = transforms.gen_cln(kln, nnmax, nlmax, rmax)
almn = transforms.survey2almn_simple(
    survey, len(survey), nside, nnmax, nlmax, nlmax, kln
)
fitstools.write_almn('almn.fits', almn)

Example 2: Survey with Cosmology

C++:

survey surv;
surv.fromSurveyFile("params.txt", true);
surv.applySelectionFunction(selFunc);

Python:

from py3dex.survey import Survey

surv = Survey()
surv.from_parameter_file("params.txt", load_data=True)
surv.apply_selection_function(sel_func)

Known Differences

1. Precision

  • Fortran: Uses REAL(DP) (typically float64)
  • Python: Uses NumPy float64 by default
  • Results should match to machine precision

2. HEALPix Integration

  • Fortran: Direct HEALPix library calls
  • Python: Uses healpy wrapper
  • Some advanced HEALPix features may differ

3. Error Handling

  • Fortran: Uses STOP and error codes
  • Python: Uses exceptions (try/except)

4. Missing Features

Currently not implemented in Python:

  • Some optimized assembly routines
  • Direct MPI decomposition (use mpi4py wrapper)
  • Specific compiler optimizations

Troubleshooting

Import Errors

# If you get import errors
import sys
sys.path.insert(0, '/path/to/3DEX/src')
import py3dex

Performance Issues

# Ensure Numba is installed
pip install numba

# For first-run compilation
import py3dex.transforms
# Warm up JIT
_ = py3dex.transforms.bjl(0, 1.0)

Memory Issues

# Use low-memory version
py3dex-survey2almn-lm survey.txt almn.fits cln.fits 20 20 1024 2000.0

Support

For migration issues, please:

  1. Check this guide
  2. See README_PYTHON.md
  3. Open an issue on GitHub

Contributing

Improvements to this migration guide are welcome!