.. Pyralysis documentation master file, created by
   sphinx-quickstart on Wed May 18 14:51:48 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. image:: https://gitlab.com/miguelcarcamov/pyralysis/-/wikis/uploads/fd40975ce0601b5c52a3cf8b92f385a5/Pyralisis-25.png
   :width: 600px
   :height: 600px
   :scale: 100 %
   :alt: Pyralysis logo
   :align: center

.. raw:: html
   :file: _includes/project_badges.html

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 :doc:`installation`, skim :doc:`context` if you want the big picture, then try :doc:`quickstart` or the hands-on :doc:`examples`.
   Prefer not to install yet? Use **Binder** (`launch in JupyterLab <https://mybinder.org/v2/gl/clirai%2Fpyralysis/release?urlpath=lab%2Ftree%2Fexamples%2Fnotebooks>`_) — 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
   :doc:`glossary`.

.. seealso::
   **Elsewhere on the web**
   `PyPI releases <https://pypi.org/project/pyralysis/>`__ ·
   `Source & issues (GitLab) <https://gitlab.com/clirai/pyralysis>`__ ·
   `Repository README <https://gitlab.com/clirai/pyralysis/-/blob/development/README.md>`__

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

.. note::
   These pages are built with `Sphinx <https://www.sphinx-doc.org/>`_ and `sphinx-book-theme <https://sphinx-book-theme.readthedocs.io/>`_.
   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
----------------

.. grid:: 1 1 2 3
   :gutter: 2

   .. grid-item-card:: Install & environment
      :link-type: doc
      :link: installation

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

   .. grid-item-card:: Quickstart
      :link-type: doc
      :link: quickstart

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

   .. grid-item-card:: Examples & Binder
      :link-type: doc
      :link: examples

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

   .. grid-item-card:: Why Pyralysis?
      :link-type: doc
      :link: context

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

   .. grid-item-card:: FAQ
      :link-type: doc
      :link: faq

      Answers to common setup and usage questions.

   .. grid-item-card:: API reference
      :link-type: doc
      :link: autoapi/index

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

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

📖 **Full documentation** is in the sections below.

Contents:
---------

.. toctree::
   :maxdepth: 2
   :caption: Introduction

   context
   inverse_problem
   signs_and_conventions

.. toctree::
   :maxdepth: 2
   :caption: Getting Started

   installation
   quickstart
   usage
   examples

.. toctree::
   :maxdepth: 2
   :caption: Core Capabilities

   simulation
   visibility_weights
   disk_models
   faraday
   data_model
   flaggers
   gridding
   measurement_operator
   array_configuration

.. toctree::
   :maxdepth: 2
   :caption: Advanced Optimization

   optimization
   optimizers
   linesearchers
   step_size_seeders
   compressed_sensing
   regularization
   objective_functions

.. toctree::
   :maxdepth: 2
   :caption: Data Management

   parameter_management
   image_processing
   io_operations
   array_backend
   performance
   pipelines_distributed

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   autoapi/index

.. toctree::
   :maxdepth: 2
   :caption: Development & Support

   testing
   versioning
   references
   faq
   glossary
   license

----

:doc:`quickstart` | :doc:`faq`