From d2ee31f542cc98c93620f0f843c165874179eebe Mon Sep 17 00:00:00 2001 From: Anno Knierim Date: Mon, 18 Nov 2024 09:29:21 +0100 Subject: [PATCH 1/5] Update README, switch to restructured text --- README.md | 40 ------------------------- README.rst | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 40 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 8cf4d52..0000000 --- a/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# pyvisgen [![Actions Status](https://github.com/radionets-project/pyvisgen/workflows/CI/badge.svg)](https://github.com/radionets-project/pyvisgen/actions) - -Python implementation of the VISGEN tool developed at [Haystack Observatory](https://www.haystack.mit.edu/astronomy/). It uses the Radio Interferometer Measurement Equation (RIME) to simulate the measurement process of a radio interferometer. A gridder is also implemented to process the resulting visibilities and convert them to images suitable as input for the neural networks developed in the [radionets repository](https://github.com/radionets-project/radionets). - -## Installation -You can install the necessary packages in a conda environment of your choice by executing -``` -$ pip install -e . -``` - -## Usage -There are 3 possible modes at the moment: `simulate` (default), `slurm`, and `gridding`. `simulate` and `slurm` both utilize the RIME formalism for creating visibilities data. With the option `gridding`, these visibilities get gridded and prepared as input images for training a neural network from the radionets framework. The necessary options and variables are set with a `toml` file. An exemplary file can be found in `config/data_set.toml`. -``` -$ pyvisgen_create_dataset --mode=simulate some_file.toml -``` -In the examples directory, you can find introductory jupyter notebooks which can be used as an entry point. - -## Input images -As input images for the RIME formalism, we use GAN-generated radio galaxies created by [Rustige et. al.](https://doi.org/10.1093/rasti/rzad016) and [Kummer et. al.](https://doi.org/10.18420/inf2022_38). -Below, you can see four example images consisting of FRI and FRII sources. - -![sources](https://github.com/radionets-project/pyvisgen/assets/23259659/285e36f6-74e7-45f1-9976-896a38217880) - -Any image can be used as input for the formalism, as long as they are stored in the h5 format, generated with [`h5py`](https://www.h5py.org/). - -## RIME -Currently, we use the following expression for the simulation process: -$$\mathbf{V}_{\mathrm{pq}}(l, m) = \sum\_{l, m} \mathbf{E}\_{\mathrm{p}}(l, m) \mathbf{K}\_{\mathrm{p}}(l, m) \mathbf{B}(l, m) \mathbf{K}^{H}\_{\mathrm{q}}(l, m) \mathbf{E}^{H}\_{\mathrm{q}}(l, m) $$ -Here, $\mathbf{B}(l, m)$ corresponds to the source distribution, $\mathbf{K}(l, m) = \exp(-2\pi\cdot i\cdot (ul + vm))$ represents the phase delay and $\mathbf{E}(l, m) = \mathrm{jinc}\left(\frac{2\pi}{\lambda}d\cdot \theta\_{lm}\right)$ the telescope properties, with $\mathrm{jinc(x)}=\frac{J_1(x}{x}$ and $J_1(x)$ as the first Bessel function. -An exemplary result can be found below. - -![visibilities](https://github.com/radionets-project/pyvisgen/assets/23259659/858a5d4b-893a-4216-8d33-41d33981354c) - -## Visualization of Jones matrices -In this section, you can see visualizations of the matrices $\mathbf{E}(l, m)$ and $\mathbf{K}(l, m)$. -### Visualization of the E matrix -![visualize_E](https://github.com/radionets-project/pyvisgen/assets/23259659/194a321b-77cd-423b-9d01-c18c0741d6c5) - -### Visualization of the K matrix -![visualize_K](https://github.com/radionets-project/pyvisgen/assets/23259659/501f487a-498b-4143-b54a-eb0e2f28e417) diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..09f6ae3 --- /dev/null +++ b/README.rst @@ -0,0 +1,87 @@ +========================= +pyvisgen |ci| |codecov| +========================= + +.. |ci| image:: https://github.com/radionets-project/pyvisgen/workflows/CI/badge.svg?branch=main + :target: https://github.com/radionets-project/pyvisgen/actions/workflows/ci.yml?branch=main + :alt: Test Status + +.. |codecov| image:: https://codecov.io/github/radionets-project/pyvisgen/badge.svg + :target: https://codecov.io/github/radionets-project/pyvisgen + :alt: Code coverage + + +Python implementation of the VISGEN tool developed at `Haystack Observatory `_. +It uses the Radio Interferometer Measurement Equation (RIME) to simulate the measurement process of a radio interferometer. +A gridder is also implemented to process the resulting visibilities and convert them to images suitable as input for +the neural networks developed in the `radionets repository `_. + +Installation +============ + +You can install the necessary packages in a conda environment of your choice by executing + +.. code:: + + $ pip install -e . + + +Usage +===== + +There are 3 possible modes at the moment: ``simulate`` (default), ``slurm``, and ``gridding``. ``simulate`` and ``slurm`` both +utilize the RIME formalism for creating visibilities data. With the option ``gridding``, these visibilities get gridded and prepared +as input images for training a neural network from the radionets framework. The necessary options and variables are set with a ``toml`` +file. An exemplary file can be found in ``config/data_set.toml``. + +..code:: + + $ pyvisgen_create_dataset --mode=simulate some_file.toml + + +In the examples directory, you can find introductory jupyter notebooks which can be used as an entry point. + +Input images +============ + +As input images for the RIME formalism, we use GAN-generated radio galaxies created by `Rustige et. al. `_ +and `Kummer et. al. `_. Below, you can see four example images consisting of FRI and FRII sources. + +.. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/285e36f6-74e7-45f1-9976-896a38217880 + :alt: sources + +Any image can be used as input for the formalism, as long as they are stored in the h5 format, generated with |h5py|_. + +.. |h5py| replace:: ``h5py`` +.. _h5py: https://www.h5py.org/ + +RIME +==== + +Currently, we use the following expression for the simulation process: + +.. math:: + + \mathbf{V}_{\mathrm{pq}}(l, m) = \sum\_{l, m} \mathbf{E}\_{\mathrm{p}}(l, m) \mathbf{K}\_{\mathrm{p}}(l, m) \mathbf{B}(l, m) \mathbf{K}^{H}\_{\mathrm{q}}(l, m) \mathbf{E}^{H}\_{\mathrm{q}}(l, m) + +Here, :math:`\mathbf{B}(l, m)` corresponds to the source distribution, :math:`\mathbf{K}(l, m) = \exp(-2\pi\cdot i\cdot (ul + vm))` represents +the phase delay, and :math:`\mathbf{E}(l, m) = \mathrm{jinc}\left(\frac{2\pi}{\lambda}d\cdot \theta\_{lm}\right)` the telescope properties, +with :math:`\mathrm{jinc(x)}=\frac{J_1(x}{x}` and :math:`J_1(x)` as the first Bessel function. An exemplary result can be found below. + +.. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/858a5d4b-893a-4216-8d33-41d33981354c + :alt: visibilities + +Visualization of Jones matrices +=============================== + +In this section, you can see visualizations of the matrices :math:`\mathbf{E}(l, m)` and :math:`\mathbf{K}(l, m)`. + +Visualization of the E matrix +----------------------------- +.. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/194a321b-77cd-423b-9d01-c18c0741d6c5 + :alt: visualize_E + +Visualization of the K matrix +----------------------------- +.. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/501f487a-498b-4143-b54a-eb0e2f28e417 + :alt: visualize_K From c5d31ef7db971624fa330c645e937183a6cb32fb Mon Sep 17 00:00:00 2001 From: Anno Knierim Date: Wed, 20 Nov 2024 08:44:55 +0100 Subject: [PATCH 2/5] Fix broken equation and inline math Backslashes in LaTeX expressions have to be escaped, i.e. `\\`, due to the way GitHub renders `.rst` files --- README.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 09f6ae3..dc1320a 100644 --- a/README.rst +++ b/README.rst @@ -60,13 +60,11 @@ RIME Currently, we use the following expression for the simulation process: -.. math:: +$$\\mathbf{V}_{\\mathrm{pq}}(l, m) = \\sum_{l, m} \\mathbf{E}_{\\mathrm{p}}(l, m) \\mathbf{K}_{\\mathrm{p}}(l, m) \\mathbf{B}(l, m) \\mathbf{K}^{H}_{\\mathrm{q}}(l, m) \\mathbf{E}^{H}_{\\mathrm{q}}(l, m)$$ - \mathbf{V}_{\mathrm{pq}}(l, m) = \sum\_{l, m} \mathbf{E}\_{\mathrm{p}}(l, m) \mathbf{K}\_{\mathrm{p}}(l, m) \mathbf{B}(l, m) \mathbf{K}^{H}\_{\mathrm{q}}(l, m) \mathbf{E}^{H}\_{\mathrm{q}}(l, m) - -Here, :math:`\mathbf{B}(l, m)` corresponds to the source distribution, :math:`\mathbf{K}(l, m) = \exp(-2\pi\cdot i\cdot (ul + vm))` represents -the phase delay, and :math:`\mathbf{E}(l, m) = \mathrm{jinc}\left(\frac{2\pi}{\lambda}d\cdot \theta\_{lm}\right)` the telescope properties, -with :math:`\mathrm{jinc(x)}=\frac{J_1(x}{x}` and :math:`J_1(x)` as the first Bessel function. An exemplary result can be found below. +Here, $\\mathbf{B}(l, m)$ corresponds to the source distribution, $\\mathbf{K}(l, m) = \\exp(-2\\pi\\cdot i\\cdot (ul + vm))$ represents +the phase delay, and $\\mathbf{E}(l, m) = \\mathrm{jinc}\\left(\\frac{2\\pi}{\\lambda}d\\cdot \\theta_{lm}\\right)$ the telescope properties, +with $\\mathrm{jinc(x)} = \\frac{J_1(x)}{x}$ and $J_1(x)$ as the first Bessel function. An exemplary result can be found below. .. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/858a5d4b-893a-4216-8d33-41d33981354c :alt: visibilities @@ -74,14 +72,14 @@ with :math:`\mathrm{jinc(x)}=\frac{J_1(x}{x}` and :math:`J_1(x)` as the first Be Visualization of Jones matrices =============================== -In this section, you can see visualizations of the matrices :math:`\mathbf{E}(l, m)` and :math:`\mathbf{K}(l, m)`. +In this section, you can see visualizations of the matrices $\\mathbf{E}(l, m)$ and $\\mathbf{K}(l, m)$. -Visualization of the E matrix +Visualization of the $\\mathbf{E}$ matrix ----------------------------- .. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/194a321b-77cd-423b-9d01-c18c0741d6c5 :alt: visualize_E -Visualization of the K matrix +Visualization of the $\\mathbf{K}$ matrix ----------------------------- .. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/501f487a-498b-4143-b54a-eb0e2f28e417 :alt: visualize_K From 69645b729329e19f9d1ec7ff769b01ab99953d5e Mon Sep 17 00:00:00 2001 From: Anno Knierim Date: Wed, 20 Nov 2024 08:51:28 +0100 Subject: [PATCH 3/5] Fix h3 heading --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index dc1320a..5620b90 100644 --- a/README.rst +++ b/README.rst @@ -75,11 +75,11 @@ Visualization of Jones matrices In this section, you can see visualizations of the matrices $\\mathbf{E}(l, m)$ and $\\mathbf{K}(l, m)$. Visualization of the $\\mathbf{E}$ matrix ------------------------------ +----------------------------------------- .. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/194a321b-77cd-423b-9d01-c18c0741d6c5 :alt: visualize_E Visualization of the $\\mathbf{K}$ matrix ------------------------------ +----------------------------------------- .. image:: https://github.com/radionets-project/pyvisgen/assets/23259659/501f487a-498b-4143-b54a-eb0e2f28e417 :alt: visualize_K From 0ecb35f54cc7bedfbbee50fb48c02eb4eaf4d130 Mon Sep 17 00:00:00 2001 From: Anno Knierim Date: Wed, 20 Nov 2024 08:53:15 +0100 Subject: [PATCH 4/5] Fix code directive --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 09f6ae3..d27b353 100644 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ utilize the RIME formalism for creating visibilities data. With the option ``gri as input images for training a neural network from the radionets framework. The necessary options and variables are set with a ``toml`` file. An exemplary file can be found in ``config/data_set.toml``. -..code:: +.. code:: $ pyvisgen_create_dataset --mode=simulate some_file.toml From e7314bc5af97f2009f9547d1c88b84cfc2de39c0 Mon Sep 17 00:00:00 2001 From: Anno Knierim Date: Wed, 20 Nov 2024 08:54:59 +0100 Subject: [PATCH 5/5] Add changelog --- docs/changes/45.maintenance.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/changes/45.maintenance.rst diff --git a/docs/changes/45.maintenance.rst b/docs/changes/45.maintenance.rst new file mode 100644 index 0000000..8e06829 --- /dev/null +++ b/docs/changes/45.maintenance.rst @@ -0,0 +1,2 @@ +- Switch README to reStructuredText +- Add Codecov badge