pyralysis 1.2.0

PYthon Radio Astronomy anaLYSis and Image Synthesis

---

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

Try in your browser (Binder)

You can open the Binder 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 page on Read the Docs.

---

Install in three steps

Stable releases are published on PyPI (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).

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

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

• Installation guide

---

Minimal example

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

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

Reconstruction example

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

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
• Measurement operator

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

---

Learn more

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

---

Contributing and development

• Contribution guide: CONTRIBUTING.md
• Changelog: CHANGELOG.md
• Issue templates: New issue form
• Versioning and releases (SemVer, tags, setuptools-scm): Versioning
• Running tests and quality: Testing & QA
• Issue tracker: https://gitlab.com/clirai/pyralysis/-/issues

---

Citation and license

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

@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/
• Issues: https://gitlab.com/clirai/pyralysis/-/issues
• Lead developer: [e-mail]