pyralysis 2.1.0

PYthon Radio Astronomy anaLYSis and Image Synthesis

Pyralysis

PYthon Radio Astronomy anaLYSis and Image Synthesis

Simulate, optimize, and reconstruct — with a Python toolkit built for modern interferometry.

---

Why Pyralysis?

Whether you are prototyping a simulation, studying optimization for imaging, or pipelining large visibility sets, Pyralysis aims to meet you where you work: clear APIs, lazy evaluation where it matters, and documentation you can actually read.

• Interferometric imaging and simulation in one coherent library.
• Dask-friendly workflows for scaling from a laptop to a cluster (including optional SLURM-backed workers).
• Documented user guides, API reference, and runnable examples — try them locally, on Binder, or from a full install (see below).

If you prefer to dive straight in, open the documentation on Read the Docs.

---

Try Pyralysis in your browser (Binder)

Binder builds a short-lived JupyterLab session with Pyralysis checked out from the release branch, so you can run the project without installing anything on your machine. After the environment starts, open the file browser and work through the notebooks under examples/notebooks/ — small simulations, toy datasets, and walkthroughs that mirror the written guides.

Binder is ideal when you want to peek at the API, follow a tutorial cell by cell, or share a reproducible link with a colleague. Sessions run on shared infrastructure with finite RAM and CPU, and the image tracks the release branch (not every commit on development), so treat it as exploration and teaching, not a substitute for HPC or production-scale imaging. For install paths, SLURM-backed Dask, and heavier workflows, use a local or cluster environment (see Install below) and the repository examples page on Read the Docs.

Launch: Open Pyralysis on Binder (same target as the Binder badge above).

---

Install in three steps

Stable releases live on PyPI (pin pyralysis==X.Y.Z when you need a reproducible version). For commits that are not yet released, install from GitLab (see the installation guide).

1. Create a Python environment (Python 3.11–3.12; requires-python is >=3.11,<3.13). Use conda, mamba, micromamba, or plain venv — whatever fits your stack.

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 pulls the latest published release plus common optional pieces (FFT helpers, notebooks, tests). For GPU, prefer micromamba create -f environment_cuda13.yml (conda CUDA + CuPy, then pip install -e .); Pascal: environment_cuda12.yml. Pip-only CuPy wheels: pyralysis[cupy13] or [cupy12] — see the installation guide. For SLURM-backed Dask workers (dask-jobqueue, used when SetupDaskCluster uses dask_cluster_backend="slurm"), add pyralysis[slurm] (see Optional: SLURM).

Simulation and imaging pipelines can attach a local cluster, SLURM, or an existing Dask Client via context configuration — see Pipelines and distributed Dask.

For editable installs, conda environment files, or Docker images:

• Installation guide

Want to explore first without pip? Use Binder above.

GPU imaging (optional)

With a CUDA-capable environment (environment_cuda13.yml / environment_cuda12.yml, or pyralysis[cupy13]), you can keep the same imaging APIs while visibilities live on CuPy-backed Dask collections:

from pyralysis.io import DaskMS

dataset = DaskMS("observation.ms").read(
    array_backend="cupy",
    calculate_psf=True,
)
dataset.calculate_theoretical_noise(per_field=True, per_spw=True)
# Forward model, Mask(dataset=...), ObjectiveFunction, optimizers — same as CPU.

The pipeline follows the measurement set: a CPU image is promoted to GPU during transform() / gradients. Simulation on GPU is not supported yet — simulate on CPU, then with_array_backend(..., "cupy") if needed.

• Guide: Array backends
• Notebook: examples/notebooks/optimization_sandbox_gpu.ipynb (masked χ² + LBFGS on a real MS)

---

Minimal example

Simulate a small dataset and 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)

More simulation patterns (arrays, sky models, injectors, I/O):

• Simulation guide

Reconstruction example

Reconstruct an image from visibilities with an objective 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)

# Objective: 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)

optimizer = LBFGS(objective_function=objective, parameter=image)
reconstructed_image = optimizer.optimize()

Deeper reading:

• Optimization
• Measurement operator

---

Examples in this repository

Location	What you will find
examples/notebooks/	Jupyter notebooks (CPU and GPU optimization sandboxes)
examples/notebooks/optimization_sandbox_gpu.ipynb	CuPy MS read, mask, and masked optimization on HD142527
examples/scripts/*_components.py	Explicit class composition
examples/scripts/*_pipeline.py	Pipeline-style orchestration

Paired scripts include dirtymapper, optimization, and simulation (components vs pipeline variants).

• Repository examples

---

Learn more

Topic	Link
User guide and tutorials	pyralysis.readthedocs.io
NumPy / CuPy array backends (GPU imaging)	array_backend
Binder (JupyterLab, no install)	Launch Binder
Pipelines and distributed Dask	pipelines_distributed
API reference	api/index
Data model and measurement operator	data_model
Versioning policy	versioning

---

Contributing and development

Resource	Link
Contribution guide	CONTRIBUTING.md
Changelog	CHANGELOG.md
New issue	Open an issue
Issue tracker	GitLab issues
Testing and QA	Testing docs
Versioning and releases	Versioning

Pull requests and bug reports are welcome. If you are unsure where to start, open an issue and we can point you to the right part of the codebase.

---

Citation and license

If Pyralysis supports your research, a citation is appreciated:

@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 GNU General Public License v3.0; see the LICENSE file in this repository.

---

Contact

• Documentation: pyralysis.readthedocs.io
• Issues: gitlab.com/clirai/pyralysis/-/issues
• Lead developer: [e-mail]