Metadata-Version: 2.4
Name: pyralysis
Version: 1.2.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: slurm
Requires-Dist: dask-jobqueue<0.9,>=0.8.2; python_version < "3.10" and extra == "slurm"
Requires-Dist: dask-jobqueue>=0.9.0; python_version >= "3.10" and extra == "slurm"
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 Status](https://readthedocs.org/projects/pyralysis/badge/)](https://pyralysis.readthedocs.io/)
  [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gl/clirai%2Fpyralysis/release?urlpath=lab%2Ftree%2Fexamples%2Fnotebooks)
  [![PyPI Wheel](https://img.shields.io/pypi/wheel/pyralysis)](https://pypi.org/project/pyralysis/#files)

  [![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/)
  [![ReadMe](https://img.shields.io/badge/ReadMe-018EF5?logo=readme&logoColor=fff)](https://gitlab.com/clirai/pyralysis/-/blob/development/README.md)
  [![Read the Docs](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=fff)](https://pyralysis.readthedocs.io/)

  [![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=fff)](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)
  [![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/)

### Try in your browser (Binder)

You can open the **[Binder](https://mybinder.org)** environment from the badge above to run the **sandbox notebooks** in JupyterLab without installing Pyralysis locally. That is a convenient way to try **small simulations**, **toy datasets**, and **step-by-step examples** under `examples/notebooks/`. The live session uses the **`release`** branch and is meant for exploration, not large production runs. For details, see the [repository examples](https://pyralysis.readthedocs.io/examples.html) page on Read the Docs.

---

## 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 **SLURM**-backed Dask workers (`dask-jobqueue`, used by pipeline steps such as `SetupDaskCluster` with `dask_cluster_backend="slurm"`), install `pyralysis[slurm]` as well (see the [installation](https://pyralysis.readthedocs.io/installation.html#optional-slurm) page).
Simulation and imaging **pipelines** can attach a local cluster, SLURM, or an existing `Client` via context `config`; details are in [Pipelines and distributed Dask](https://pyralysis.readthedocs.io/pipelines_distributed.html).

For editable installs, conda env files, or Docker images, see:

- [Installation guide](https://pyralysis.readthedocs.io/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/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/optimization.html)
- [Measurement operator](https://pyralysis.readthedocs.io/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/examples.html)

---

## Learn more

- **User guide and tutorials**: [https://pyralysis.readthedocs.io/](https://pyralysis.readthedocs.io/)
- **Pipelines and distributed Dask** (local / SLURM / existing client): [pipelines_distributed](https://pyralysis.readthedocs.io/pipelines_distributed.html)
- **API reference**: [https://pyralysis.readthedocs.io/api/index.html](https://pyralysis.readthedocs.io/api/index.html)
- **Data model and measurement operator**: [https://pyralysis.readthedocs.io/data_model.html](https://pyralysis.readthedocs.io/data_model.html)
- **Versioning policy**: [https://pyralysis.readthedocs.io/versioning.html](https://pyralysis.readthedocs.io/versioning.html)

---

## Contributing and development

- **Contribution guide**: [CONTRIBUTING.md](CONTRIBUTING.md)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
- **Issue templates**: [New issue form](https://gitlab.com/clirai/pyralysis/-/issues/new)
- **Versioning and releases (SemVer, tags, setuptools-scm)**: [Versioning](https://pyralysis.readthedocs.io/versioning.html)
- **Running tests and quality**: [Testing & QA](https://pyralysis.readthedocs.io/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)
