Metadata-Version: 2.4
Name: fftvis
Version: 1.1.1
Summary: An FFT-based visibility simulator
Author-email: Tyler Cox <tyler.a.cox@berkeley.edu>, Steven Murray <steven.murray@sns.it>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matvis>=1.3.2
Requires-Dist: finufft
Requires-Dist: pyuvdata>=3.1.2
Requires-Dist: psutil
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: ray
Requires-Dist: threadpoolctl
Requires-Dist: numba
Requires-Dist: memray
Provides-Extra: dev
Requires-Dist: mpi4py; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pyradiosky; extra == "dev"
Requires-Dist: pyuvsim[sim]; extra == "dev"
Requires-Dist: hera_sim; extra == "dev"
Dynamic: license-file

# fftvis: A Non-Uniform Fast Fourier Transform-based Visibility Simulator

![Tests](https://github.com/tyler-a-cox/fftvis/actions/workflows/ci.yml/badge.svg)
![codecov](https://codecov.io/gh/tyler-a-cox/fftvis/branch/main/graph/badge.svg)
![Black Formatting](https://img.shields.io/badge/code%20style-black-000000.svg)

`fftvis` is a fast Python package designed for simulating interferometric visibilities using the Non-Uniform Fast Fourier Transform (NUFFT). It provides a convenient and efficient way to generate simulated visibilities.

## Features

- Utilizes the Flatiron Institute NUFFT (finufft) [algorithm](https://arxiv.org/abs/1808.06736) for fast visibility simulations that agree with similar methods ([`matvis`](https://github.com/HERA-team/matvis)) to high precision.
- Designed to be a near drop-in replacement to `matvis` with a ~10-100x improvement in runtime
- Extensible design that allows for easy addition of new backends
- Support for polarized beam patterns and polarized sky models
- Support for per-antenna beams w/ functionality to support representing per-antenna beams with a linear basis. See the example [notebook](./docs/tutorials/beam_decomposition.ipynb) for details.

## Current Limitations
- GPU backend exists only as a stub implementation (coming soon!)
- Diffuse sky models must be pixelized

## Installation

You can install `fftvis` via pip:

```bash
pip install fftvis
```

## Basic Usage

```python
from fftvis import simulate_vis

# Simulate visibilities with the CPU backend (default)
vis = simulate_vis(
    ants=antenna_positions,
    fluxes=source_fluxes,
    ra=source_ra,
    dec=source_dec,
    freqs=frequencies,
    times=observation_times,
    beam=beam_model,
    polarized=True,
    backend="cpu"  # Use "gpu" for GPU acceleration when implemented
)
```

## Architecture

`fftvis` is structured with a modular design:

- **Core**: Contains abstract interfaces and base classes that define the API
- **CPU**: Contains the CPU-specific implementation
- **GPU**: Contains the GPU implementation (currently stubbed for future development)
- **Wrapper**: Provides a high-level API for backward compatibility

This modular design makes the package more maintainable and extensible, allowing for the addition of new backends and optimizations without affecting the user API.

## Contributing
Contributions to `fftvis` are welcome! If you find any issues, have feature requests, or want to contribute improvements, please open an issue or submit a pull request on the GitHub repository: `fftvis` on GitHub

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments
This package relies on the `finufft` implementation provided by [finufft](https://github.com/flatironinstitute/finufft) library. Special thanks to the contributors and maintainers of open-source libraries used in this project.

## Citation

If you use `fftvis` in your research, please cite our paper published in *RAS Techniques and Instruments*:

> **fftvis: a non-uniform Fast Fourier Transform based interferometric visibility simulator**
> Tyler A. Cox, Steven G. Murray, Aaron R. Parsons, Joshua S. Dillon, Kartik Mandar, Zachary E. Martinot, Robert Pascua, Piyanat Kittiwisit, and James E. Aguirre.  
> *RAS Techniques and Instruments*, Volume 4, 2025, rzaf056.  
> DOI: [10.1093/rasti/rzaf056](https://doi.org/10.1093/rasti/rzaf056) | arXiv: [2506.02130](https://arxiv.org/abs/2506.02130)

### BibTeX

```bibtex
@article{2025RASTI...4af056C,
  author        = {Cox, Tyler A. and Murray, Steven G. and Parsons, Aaron R. and Dillon, Joshua S. and Mandar, Kartik and Martinot, Zachary E. and Pascua, Robert and Kittiwisit, Piyanat and Aguirre, James E.},
  title         = "{fftvis: a non-uniform Fast Fourier Transform based interferometric visibility simulator}",
  journal       = {RAS Techniques and Instruments},
  year          = {2025},
  month         = {jan},
  volume        = {4},
  pages         = {rzaf056},
  doi           = {10.1093/rasti/rzaf056},
  archivePrefix = {arXiv},
  eprint        = {2506.02130},
  primaryClass  = {astro-ph.IM},
  adsurl        = {https://ui.adsabs.harvard.edu/abs/2025RASTI...4af056C}
}
