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.
• Composable, flexible, and extensible — not the same thing (see below): plug pieces together, choose what fits your science, and add your own classes without forking the core.
• Dask-friendly — large arrays and visibilities are handled as lazy, chunked work: Pyralysis builds a task graph instead of loading everything into RAM at once, then Dask runs those chunks in parallel on your laptop, a local cluster, or optional SLURM workers. You keep writing normal Python; scaling is mostly configuration, not a rewrite. Details: Pipelines and distributed Dask.
• 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.

Flexible, composable, and extensible

These words get mixed up; in Pyralysis they mean different jobs:

The same ideas show up in scripts, notebooks, and pipelines.

Show, don’t hide: adding or swapping a regularizer is a list change, not a fork of the optimizer:

from pyralysis.optimization import ObjectiveFunction
from pyralysis.optimization.terms import ChiSquared, L1Norm, TSV

# Start simple…
terms = [
    ChiSquared(model_visibility=model_visibility, penalization_factor=1.0),
    L1Norm(penalization_factor=0.01),
]
# …or swap / extend without touching L-BFGS / FISTA wiring:
terms = [
    ChiSquared(model_visibility=model_visibility, penalization_factor=1.0),
    TSV(penalization_factor=0.001),  # replace L1, or append both
]
objective = ObjectiveFunction(terms=terms, parameter=image)

Two ways to structure a workflow (same science, different abstraction — flexibility of how you orchestrate):

• Components — you wire Dataset, operator, ObjectiveFunction, optimizer by hand (examples/scripts/*_components.py).
• Pipelines — step + context orchestration (examples/scripts/*_pipeline.py).

Motivation and architecture (OOP, why not a monolith): Why Pyralysis?. Hands-on walkthroughs: Quickstart · Examples · Binder.

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; recommended for large images and datasets)

CUDA / CuPy is optional for small CPU workflows. For large measurement sets or large images, GPU imaging is recommended when a CUDA-capable environment is available.

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(terms=terms, parameter=image, persist_gradient=True)

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

Deeper reading:

• Optimization
• Measurement operator

Examples in this repository

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

• Repository examples

Learn more

Contributing and development

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: miguel.carcamo@usach.cl