Metadata-Version: 2.4
Name: pyralysis
Version: 1.1.0
Summary: PYthon Radio Astronomy anaLYSis and Image Synthesis
Author-email: Miguel Cárcamo <miguel.carcamo@usach.cl>
Maintainer-email: Miguel Cárcamo <miguel.carcamo@usach.cl>
License-Expression: GPL-3.0-only
Project-URL: Documentation, https://pyralysis.readthedocs.io
Project-URL: Issues, https://gitlab.com/clirai/pyralysis/-/issues
Project-URL: Repository, https://gitlab.com/clirai/pyralysis
Project-URL: Source, https://gitlab.com/clirai/pyralysis
Keywords: radio,radio-interferometry,interferometry,radioastronomy,imaging,deconvolution,calibration,CASA,ALMA,SKA,visibility,synthesis,python,astronomy,science,data-analysis,signal-processing,high-performance-computing,simulation,image-reconstruction,radio-telescope,big data,big-data,big computing,compressed sensing,gridding,optimization
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy==6.1.0
Requires-Dist: autopep8==2.2.0
Requires-Dist: dafits==2.0.0
Requires-Dist: dask==2024.10.0
Requires-Dist: dask-ms[complete]>=0.2.29
Requires-Dist: distributed==2024.10.0
Requires-Dist: matplotlib==3.10.8
Requires-Dist: more-itertools==10.2.0
Requires-Dist: multimethod==1.11.2
Requires-Dist: numba>=0.59.1
Requires-Dist: numcodecs==0.15.1
Requires-Dist: numpy<3.0.0,>=2.0.0
Requires-Dist: python-casacore==3.7.1
Requires-Dist: radio-beam==0.3.7
Requires-Dist: scipy==1.15.0
Requires-Dist: ska-ost-array-config==4.5.0
Requires-Dist: snakeviz==2.2.0
Requires-Dist: spectral-cube==0.6.5
Requires-Dist: xarray==2024.9
Provides-Extra: all
Requires-Dist: pyfftw; extra == "all"
Requires-Dist: cmcrameri; extra == "all"
Requires-Dist: ipykernel; extra == "all"
Requires-Dist: seaborn; extra == "all"
Requires-Dist: six==1.17.0; extra == "all"
Requires-Dist: pytest==9.0.2; extra == "all"
Requires-Dist: pytest-cov==7.1.0; extra == "all"
Requires-Dist: pytest-xdist==3.8.0; extra == "all"
Provides-Extra: cupy
Requires-Dist: cupy==13.2.0; extra == "cupy"
Provides-Extra: notebook
Requires-Dist: cmcrameri; extra == "notebook"
Requires-Dist: ipykernel; extra == "notebook"
Requires-Dist: seaborn; extra == "notebook"
Provides-Extra: pyfftw
Requires-Dist: pyfftw; extra == "pyfftw"
Provides-Extra: test
Requires-Dist: six==1.17.0; extra == "test"
Requires-Dist: pytest==9.0.2; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: pytest-xdist==3.8.0; extra == "test"
Dynamic: license-file

<div style="text-align: center;">
  <img src="https://gitlab.com/miguelcarcamov/pyralysis/-/wikis/uploads/fd40975ce0601b5c52a3cf8b92f385a5/Pyralisis-25.png" height="400" alt="Pyralysis logo">
</div>

<div style="text-align: center;">

  [![codecov](https://codecov.io/gl/clirai/pyralysis/branch/development/graph/badge.svg?token=MVFAA1YKC7)](https://codecov.io/gl/clirai/pyralysis)
  [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
  [![Documentation](https://img.shields.io/badge/docs-ReadTheDocs-blue)](https://pyralysis.readthedocs.io)
  [![GitLab Contributors](https://img.shields.io/gitlab/contributors/clirai/pyralysis)](https://gitlab.com/clirai/pyralysis/-/project_members)

  [![Python Version](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|3.12-blue)](https://www.python.org/)
  [![PyPI Version](https://img.shields.io/pypi/v/pyralysis)](https://pypi.org/project/pyralysis)
  [![PyPI Downloads](https://img.shields.io/pypi/dm/pyralysis)](https://pypi.org/project/pyralysis/)

  [![Docker Image Version](https://img.shields.io/badge/docker-latest-blue)](https://gitlab.com/clirai/pyralysis/container_registry)
  [![License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
  [![Documentation Status](https://readthedocs.org/projects/pyralysis/badge/?version=latest)](https://pyralysis.readthedocs.io/en/latest/?badge=latest)

  [![Pipeline Status](https://gitlab.com/clirai/pyralysis/badges/development/pipeline.svg)](https://gitlab.com/clirai/pyralysis/-/pipelines?ref=development)

</div>

---

## Pyralysis

**Pyralysis** is an open-source Python library for radio astronomy imaging, simulation, and optimization.
It is designed to be easy to install, learn, and use for modern radio interferometry workflows.

For full documentation, tutorials, and API reference, see the **Pyralysis documentation** on ReadTheDocs:

- [Pyralysis documentation](https://pyralysis.readthedocs.io)

---

## Install in three steps

Stable releases are published on **[PyPI](https://pypi.org/project/pyralysis/)** (pin `pyralysis==X.Y.Z` when you need a fixed version).
For commits not yet released, install from GitLab (see the installation guide).

- **1. Create a Python environment** (Python 3.9–3.12 recommended).
  Use whatever you prefer: `conda`, `mamba`, `micromamba`, or plain `venv`.

- **2. Install from PyPI using the SKA extra index** (needed so pip can resolve some dependencies).

```bash
pip install --extra-index-url https://artefact.skao.int/repository/pypi-internal/simple pyralysis[all]
```

This installs the **latest published** PyPI release plus common optional dependencies (FFT, notebooks, tests). For **CuPy / GPU**, use `pyralysis[all,cupy]` or `pyralysis[cupy]` only.
For editable installs, conda env files, or Docker images, see:

- [Installation guide](https://pyralysis.readthedocs.io/en/latest/installation.html)

---

## Minimal example

Start by simulating a small dataset and then add thermal noise:

```python
from pyralysis.io.antenna_config_io import AntennaConfigurationIo
from pyralysis.simulation import Simulator
from pyralysis.models.sky import PointSource
from pyralysis.injectors import ThermalNoiseInjector

# Load array configuration
interferometer = AntennaConfigurationIo(input_name="path/to/array.cfg").read()
interferometer.configure_observation(
    min_frequency_hz=1e9, max_frequency_hz=1.1e9, frequency_step_hz=1e7,
    right_ascension="12:00:00", declination="45:00:00",
    integration_time=10, observation_time="1h"
)

# Define a source and simulate
source = PointSource(
    reference_intensity=1.0,
    sky_position="12:00:00 45:00:00",
    reference_frequency=1e9,
)
sim = Simulator(interferometer=interferometer, sources=source)
dataset = sim.simulate(create_dataset=True)

# Add thermal noise
thermal = ThermalNoiseInjector(system_temperature=50, integration_time=10, channel_bandwidth=1e6)
noisy_dataset = thermal.apply(dataset)
```

For more simulation examples (arrays, sky models, injectors, and data access), see:

- [Simulation guide](https://pyralysis.readthedocs.io/en/latest/simulation.html)

### Reconstruction example

Next, reconstruct an image from the (noisy) visibilities using an objective function and L‑BFGS:

```python
from pyralysis.reconstruction import Image
from pyralysis.optimization import ObjectiveFunction
from pyralysis.optimization.terms import ChiSquared, L1Norm
from pyralysis.optimization.optimizer import LBFGS
from pyralysis.measurement import ModelVisibility

# Create initial image (e.g. empty sky model)
image = Image.empty(imsize=(512, 512), cellsize=0.001)  # adjust to your case

# Build model visibility from dataset and image
model_visibility = ModelVisibility(dataset=noisy_dataset, image=image)

# Define objective function: data fidelity + simple L1 regularization
terms = [
    ChiSquared(model_visibility=model_visibility, penalization_factor=1.0),
    L1Norm(penalization_factor=0.01),
]
objective = ObjectiveFunction(term_list=terms, image=image, persist_gradient=True)

# Run L-BFGS reconstruction
optimizer = LBFGS(objective_function=objective, parameter=image)
reconstructed_image = optimizer.optimize()
```

For detailed reconstruction workflows (measurement operator, regularizers, optimizers), see:

- [Optimization](https://pyralysis.readthedocs.io/en/latest/optimization.html)
- [Measurement operator](https://pyralysis.readthedocs.io/en/latest/measurement_operator.html)

## Examples in this repository

- Jupyter notebooks are in `examples/notebooks/`.
- CLI scripts are in `examples/scripts/`, split by style:
  - `*_components.py` for explicit class composition.
  - `*_pipeline.py` for pipeline-based orchestration.
- Current paired scripts:
  - `dirtymapper_components.py` / `dirtymapper_pipeline.py`
  - `optimization_components.py` / `optimization_pipeline.py`
  - `simulation_components.py` / `simulation_pipeline.py`

See the documentation page for quick usage patterns:

- [Repository examples](https://pyralysis.readthedocs.io/en/latest/examples.html)

---

## Learn more

- **User guide and tutorials**: [https://pyralysis.readthedocs.io/en/latest/](https://pyralysis.readthedocs.io/en/latest/)
- **API reference**: [https://pyralysis.readthedocs.io/en/latest/api/index.html](https://pyralysis.readthedocs.io/en/latest/api/index.html)
- **Data model and measurement operator**: [https://pyralysis.readthedocs.io/en/latest/data_model.html](https://pyralysis.readthedocs.io/en/latest/data_model.html)
- **Versioning policy**: [https://pyralysis.readthedocs.io/en/latest/versioning.html](https://pyralysis.readthedocs.io/en/latest/versioning.html)

---

## Contributing and development

- **Versioning and releases (SemVer, tags, setuptools-scm)**: [Versioning](https://pyralysis.readthedocs.io/en/latest/versioning.html)
- **Running tests and quality**: [Testing & QA](https://pyralysis.readthedocs.io/en/latest/testing.html)
- **Issue tracker**: [https://gitlab.com/clirai/pyralysis/-/issues](https://gitlab.com/clirai/pyralysis/-/issues)

---

## Citation and license

If you use Pyralysis in your research, please consider citing:

```bibtex
@software{carcamo2021pyralysis,
  author = {Miguel Cárcamo},
  title = {Pyralysis: A Python framework for radio interferometric imaging and simulation},
  year = {2021},
  url = {https://gitlab.com/clirai/pyralysis},
  note = {https://pyralysis.readthedocs.io}
}
```

Pyralysis is distributed under the terms of the GNU General Public License version 3 (GPLv3).
See `LICENSE` for details.

---

### Contact

- **Documentation**: [https://pyralysis.readthedocs.io](https://pyralysis.readthedocs.io)
- **Issues**: [https://gitlab.com/clirai/pyralysis/-/issues](https://gitlab.com/clirai/pyralysis/-/issues)
- **Lead developer**: [miguel.carcamo@usach.cl](mailto:miguel.carcamo@usach.cl)
