Welcome to Pyralysis’s documentation

PYthon Radio Astronomy anaLYSis and Image Synthesis

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

Tip

First visit? Follow Installation, skim Context: Why Pyralysis? if you want the big picture, then try Quickstart Guide or the hands-on Repository Examples. Prefer not to install yet? Use Binder (launch in JupyterLab) — same environment as the Binder badge above; good for tutorials, not large production runs.

Note

Imaging vs reconstruction. Radio astronomers usually say imaging (or image synthesis / image formation). Pyralysis also says reconstruction and image optimization for the same task family — forming an image from visibilities. See Glossary.

See also

Elsewhere on the web PyPI releases · Source & issues (GitLab) · Repository README

Pyralysis is an open-source Python library for radio astronomy imaging, simulation, and optimization.

Note

These pages are built with Sphinx and sphinx-book-theme. Use the left sidebar to browse and the search box in the header (on wide screens). Code blocks support one-click copy (hover the copy icon).

Choose your path

Install & environment

Pip with the SKA extra index, optional extras (CuPy, SLURM), conda, and Docker pointers.

Installation

Quickstart

Load data, simulate, and run a minimal imaging-style workflow with copy-paste examples.

Quickstart Guide

Examples & Binder

Components vs pipelines, notebooks, and Binder — the hands-on view of flexibility.

Repository Examples

Why Pyralysis?

Motivation, modularity, and architecture. For a quick flexible / composable / extensible map, see the GitLab README.

Context: Why Pyralysis?

FAQ

Answers to common setup and usage questions.

Frequently Asked Questions (FAQ)

API reference

Auto-generated module and class reference for the public Python API.

autoapi/index

Pyralysis provides:

• Advanced simulation: radio interferometry with custom arrays and sky models

• High performance: Dask-based parallel processing for scalable computation

• Flexible optimization: modular objective functions and regularization

• SKA-ready tooling: subarray simulation and phased-array style configurations

• Dynamic workflows: array updates with baseline recalculation where applicable

• Scientific Python stack: NumPy, Dask, Xarray, Astropy, and related ecosystems

• Research-grade quality: tests, coverage, and documented APIs

Architecture figures (stack + UML) live on Context: Why Pyralysis? (Detailed software stack. TikZ source: docs/source/diagrams/tikz/architecture.tex. Rebuild with make -C docs/source/diagrams/tikz all., Subsystem overview. Top-level packages under src/pyralysis and the main dependency edges (dataset at the centre; estimators beside transformers; runtime / cli as supporting surfaces). See fig16_subsystem_overview.dot., and the key-diagram table there). Optimizer hierarchy: Optimizer hierarchy — see optimizers..

📖 Full documentation is in the sections below.

Contents:

Introduction

• Context: Why Pyralysis?
  • Motivation
  • Software architecture
  • Key project goals
  • Making the software accessible
  • Challenges in existing imaging software
  • Beyond CLEAN: mathematical optimization
  • Scaling for large data and large computers
  • Outlook
  • References
• The Radio Interferometry Inverse Problem
  • What you’ll learn
  • What is a Visibility?
  • Gridding: From Irregular Data to a Regular Fourier Grid
  • Deconvolution: Cleaning the Dirty Image
  • Approaches to Solving the Inverse Problem
  • Further Reading
  • References
• Signs and Conventions
  • Image Pixel Size Convention (cellsize)
  • Direction Cosines Convention (l, m, n)
  • UV Cell Size and Axis Mapping
  • Nyquist Limits (Useful Rules of Thumb)
  • FFT/IDFT Sign Convention
  • Phase-Shift Convention (Grid and Visibilities)
  • IDFT for Visibility to Image
  • Hermitian Symmetry Convention
  • Sky-Model Source Placement Factor

Getting Started

• Installation
  • Try without installing (Binder)
  • Prerequisites
  • Installation Methods
  • Optional Dependencies
  • Troubleshooting
  • Common issues
• Quickstart Guide
  • Let’s get started!
  • Three steps to get a dataset
  • Loading Measurement Sets
  • Why use dask-ms?
  • Performing Gridding
  • Configuring Gridding Parameters
  • Using Convolution Kernels in the Measurement Operator and Degridding
  • What is Non-Parametric Simulation?
  • Next steps
• Using Pyralysis
  • What this guide covers
  • Basic Workflow
  • Loading Measurement Sets
  • Simulating a Synthetic Dataset
  • Simulating Non-Parametric Sources
  • Gridding Visibilities
  • Performing Image Reconstruction
  • Phase Center Shifting
  • Saving Reconstructed Images
  • Next Steps
  • See also
• Repository Examples
  • Try notebooks online (Binder)
  • Current notebook highlights
  • Current script pairs
  • When to use which style
  • Related docs

Core Capabilities

• Simulation Framework
  • What you can do with simulation
  • Main Components
  • Creating a dataset
  • Thermal noise and temperature models
  • Chunk Handling for Large-Scale Simulations
  • Configuring the Interferometer
  • Defining Sky Models
  • Noise Injection
  • Example Workflow
  • Subarrays and Antenna Filtering
  • See also
• Visibility data weights
  • Thermal noise injection
  • Analytic estimator
  • Empirical estimator
  • Recommended simulation order
• Protoplanetary disk models
  • Geometry: inclination and position angle
  • Model images (sky brightness)
  • UV-plane visibilities (Fourier theory)
  • Building individual disk components
  • Composing multi-component disks
  • Simulating visibilities
  • See also
• Faraday Rotation and Depolarization
  • The Faraday rotation effect
  • Faraday thin vs Faraday thick
  • Thin component
  • Thick component
  • Composing components
  • Use in simulation
  • See also
• Data Model: Dataset and SubMS
  • Overview
  • The Dataset class
  • The SubMS class and why we have a list
  • Accessing visibilities
  • Where SubMS is used
  • Further reading
• Flaggers: RFI detection and dataset integration
  • Overview
  • Architecture
  • SumThreshold algorithm mapped to code
  • Threshold strategies
  • Dataset-level usage
  • NumPy and Dask behavior
  • Future extension
• Gridding Techniques in Pyralysis
  • Why gridding matters
  • Basic Gridding with Gridder
  • The Grid Value Object
  • Weighting Schemes
  • Convolutional Kernels
  • Interpolation Methods for Visibility Extraction
  • Dask reduction strategies (CPU / distributed)
  • GPU scatter path (CuPy)
  • Gridding with Dirty Mapping
  • Saving and plotting outputs
  • Phase Center Shifting
  • Conclusion
  • See also
• Wide-field imaging and the \(w\)-term
  • The problem
  • Classical approaches
  • How Pyralysis models the \(w\)-term
  • Using the UV grid after DirtyMapper
  • Composing the UV interpolator and the \(w\) window
  • When to use coplanar vs w-stacking
  • How many \(w\)-planes
  • Simulation
  • Reconstruction pipelines and CLI
  • Related APIs
• Measurement Operator
  • Overview
  • Intensity model
  • Mathematical context
  • Visibility estimation methods
  • Primary beam
  • Usage
  • Related
• Array Configuration & Subarrays
  • Overview
  • Array Configuration Files
  • Loading Array Configurations
  • Creating Subarrays
  • Observer Pattern for Dynamic Updates
  • Advanced Subarray Operations
  • Performance Considerations
  • Use Cases

Advanced Optimization

• Optimization in Pyralysis
  • Introduction
  • Architecture
  • Building your optimization problem
  • Data fidelity and normalization
  • Smooth regularizers
  • Masking and degrees of freedom
  • End-to-end workflow
  • Choosing components
  • See also
• Optimizers
  • Introduction
  • Overview
  • Stopping criteria
  • Common setup
  • Conjugate gradient methods
  • LBFGS (limited-memory BFGS)
  • LBFGSB (bound-constrained L-BFGS-B)
  • Saving intermediate results
  • Implementation notes
  • Progress vs diagnostics
  • See also
• Line Searchers
  • Introduction
  • Mathematical foundation
  • Step size geometry: too short, too long, and why seeders help
  • Architecture: seeders + searchers
  • Available line searchers
  • Selection guide
  • Implementation examples
  • See also
• Step Size Seeders
  • Introduction
  • Role in the optimization stack
  • Barzilai–Borwein family
  • Interpolation seeders
  • Additional scalar seeders
  • Dask and array backends
  • Shared parameters
  • Selection guide
  • Implementation example
  • References
  • See also
• Compressed Sensing & Proximal Methods
  • Introduction
  • Mathematical Foundation of Compressed Sensing
  • From Theory to Optimization
  • Theoretical Guarantees
  • Proximal Operators: The Key to Practical Implementation
  • Proximal Optimization Algorithms
  • FISTA (Fast Iterative Shrinkage-Thresholding Algorithm)
  • SDMM (Simultaneous Direction Method of Multipliers)
  • Regularizers with Proximal Operators
  • Complete Example: Sparse Reconstruction
  • Conclusion
  • References
  • See Also
• Regularization Methods
  • Overview
  • Available Regularizers
  • Regularizer Compatibility with Optimizers
  • Key Features
  • TSV Regularizer Details
  • Using Regularizers in Objective Functions
  • Advanced Usage with Masks
  • Multi-channel Support
  • Performance Optimization
  • Best Practices
  • See Also
• Objective Function Framework
  • Overview
  • Architecture
  • Key Benefits
  • Data Fidelity Terms
  • Normalization Modes
  • Building Complex Objective Functions
  • Performance Features
  • Multi-channel Support
  • Using the Objective Function
  • Advanced Features
  • Best Practices

Data Management

• Parameter Management
  • Overview
  • Key Features
  • Projections
  • Creating Parameters
  • Array Backend Support
  • Chunking Configuration
  • Mathematical Operations
  • Memory Management
  • Spatial Properties
  • Data Access Properties
  • Utility Methods
  • Advanced Features
  • Performance Optimization
  • Best Practices
• Image Processing
  • Overview
  • Key Features
  • Creating Images
  • Image I/O Operations
  • Automatic Header Parsing
  • Coordinate System Properties
  • Spatial Properties
  • FITS Header Management
  • Unit Conversions
  • Noise Estimation
  • Advanced Image Features
  • Performance Optimizations
  • Best Practices
  • Troubleshooting
• I/O Operations & Data Formats
  • Overview
  • Available I/O Formats
  • FITS (Flexible Image Transport System)
  • Zarr Arrays
  • Zarr dataset (pyralysis Dataset)
  • Measurement Sets (MS)
  • Visibility sanitization (NaN / Inf)
  • Host boundary contract (FITS, Zarr, MS)
  • Performance Optimization
  • Format Selection Guide
  • Best Practices
  • Troubleshooting
• Measurement Set I/O
  • Architecture
  • Reading
  • Writing
• Array backends
  • Supported backends
  • Choosing a workflow
  • Quick start (CPU)
  • Quick start (GPU)
  • Selecting a CUDA device
  • End-to-end GPU imaging
  • What gets converted
  • Writing results
  • GPU memory lifecycle
  • Other GPU caveats
  • What works on GPU today
  • Verify your environment
  • Public API
• Performance & Scalability
  • Overview
  • Dask Integration
  • Chunking Strategies
  • Gridding performance (DirtyMapper / weighting)
  • Memory Management
  • Performance Optimization
  • Optimizer-Specific Performance Features
  • Scalability Features
  • Benchmarking Performance
  • Best Practices
  • Troubleshooting Performance Issues
• Pipelines and distributed Dask
  • Default step order
  • Context fields
  • Configuration (context.config)
  • Examples
  • API entry points

Development & Support

• Testing & Quality Assurance
  • Overview
  • Testing Coverage
  • Running Tests
  • Test Structure
  • Writing Tests
  • Testing Regularizers
  • Testing Objective Functions
  • Testing Parameter Classes
  • Testing Image Processing
  • Performance Testing
  • Continuous Integration
  • Best Practices
• Versioning and Release Policy
  • How the version is assigned
  • Commit messages (optional)
  • For users and reproducibility
  • For contributors
  • Release workflow
  • References
• References
• Frequently Asked Questions (FAQ)
  • General Questions
  • Installation and Setup
  • Using Pyralysis
  • Optimization and Line Search
  • Data storage, weighting, and I/O
  • Didn’t find your answer?
• Glossary
• License

---

Quickstart Guide | Frequently Asked Questions (FAQ)