Merge pull request #72 from HERA-Team/refactoring

refactor: rename vis_cpu to matvis

Author: steven-murray

.coveragerc

@@ -1,7 +1,7 @@
 # .coveragerc to control coverage.py
 [run]
 branch = True
-source = vis_cpu
+source = matvis
 omit = */cli.py
 
 [paths]

.github/ISSUE_TEMPLATE/question.md

@@ -1,10 +1,10 @@
 ---
 name: Question
-about: Ask a question about how to use vis_cpu
+about: Ask a question about how to use matvis
 title: "[Question]"
 labels: 'Type: question'
 assignees: steven-murray
 
 ---
 
-<!-- Please ask your question below. Please try to be as specific as you can, and provide information about your installed version of vis_cpu and Python -->
+<!-- Please ask your question below. Please try to be as specific as you can, and provide information about your installed version of matvis and Python -->

.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -1,5 +1,5 @@
 <!--
-Thank you for creating a PR on vis_cpu!
+Thank you for creating a PR on matvis!
 
 Please read through the following and check the boxes to ensure
 your PR meets our coding standards and that it follows the

.github/workflows/run_notebooks.yaml

@@ -31,8 +31,8 @@ jobs:
           pip install .[test] papermill jupyter ipykernel
 
       - name: Install ipykernel
-        run: python -m ipykernel install --user --name viscpu --display-name "viscpu"
+        run: python -m ipykernel install --user --name matvis --display-name "matvis"
 
       - name: Run Notebooks
         run: |
-          papermill -k viscpu docs/tutorials/vis_cpu_tutorial.ipynb tmp.ipynb
+          papermill -k matvis docs/tutorials/matvis_tutorial.ipynb tmp.ipynb

.github/workflows/test_suite.yaml

@@ -43,12 +43,12 @@ jobs:
 
       - name: Run Tests
         run: |
-          python -m pytest --ignore tests/test_plot.py --cov=vis_cpu --cov-config=.coveragerc --cov-report xml:./coverage.xml --durations=25 --log-cli-level=${{ env.LOG_LEVEL}}
+          python -m pytest --ignore tests/test_plot.py --cov=matvis --cov-config=.coveragerc --cov-report xml:./coverage.xml --durations=25 --log-cli-level=${{ env.LOG_LEVEL}}
 
       - name: Run Plotting Tests
         if: matrix.python-version != '3.9' || matrix.os == 'macos-latest'
         run: |
-          python -m pytest tests/test_plot.py --cov=vis_cpu --cov-config=.coveragerc --cov-append --cov-report xml:./coverage.xml --durations=25 --log-cli-level=INFO
+          python -m pytest tests/test_plot.py --cov=matvis --cov-config=.coveragerc --cov-append --cov-report xml:./coverage.xml --durations=25 --log-cli-level=INFO
 
       - name: Upload coverage report
         uses: codecov/codecov-action@v3.1.3
@@ -92,7 +92,7 @@ jobs:
 
       - name: Run Tests
         run: |
-          python -m pytest -k "gpu" --cov=vis_cpu --cov-config=.coveragerc --cov-report xml:./coverage.xml --durations=25 --log-cli-level=INFO
+          python -m pytest -k "gpu" --cov=matvis --cov-config=.coveragerc --cov-report xml:./coverage.xml --durations=25 --log-cli-level=INFO
 
       - name: Upload coverage report
         uses: codecov/codecov-action@v3.1.3

.isort.cfg

@@ -4,7 +4,7 @@ indent='    '
 skip=.tox,.venv,build,dist
 known_standard_library=setuptools,pkg_resources
 known_test=pytest
-known_first_party=vis_cpu
+known_first_party=matvis
 sections=FUTURE,STDLIB,COMPAT,TEST,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
 default_section=THIRDPARTY
 multi_line_output=3

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-exclude: '^docs/conf.py|^src/vis_cpu/data/'
+exclude: '^docs/conf.py|^src/matvis/data/'
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks

AUTHORS.rst

@@ -6,3 +6,4 @@ Contributors
 * Hugh Garsden
 * Phil Bull
 * Steven Murray <steven.g.murray@asu.edu>
+* Piyanat Kittiwisit <piyanat.kittiwisit@gmail.com>

README.rst

@@ -1,44 +1,65 @@
 =======
-vis_cpu
+matvis
 =======
-.. image:: https://github.com/hera-team/vis_cpu/workflows/Tests/badge.svg
-    :target: https://github.com/hera-team/vis_cpu
+.. image:: https://github.com/hera-team/ matvis/workflows/Tests/badge.svg
+    :target: https://github.com/hera-team/ matvis
 .. image:: https://badge.fury.io/py/vis-cpu.svg
     :target: https://badge.fury.io/py/vis-cpu
-.. image:: https://codecov.io/gh/hera-team/vis_cpu/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/hera-team/vis_cpu
+.. image:: https://codecov.io/gh/hera-team/ matvis/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/hera-team/ matvis
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 
 
-Fast visibility simulator capable of running on CPU and GPU.
+Fast matrix-based visibility simulator capable of running on CPU and GPU.
 
 
 Description
 ===========
 
-``vis_cpu`` is a Python/numpy-based simulator for interferometer visibilities.
-It models the sky as an ensemble of point sources, each with their own frequency
-spectrum. Diffuse emission can be modelled by treating (e.g.) each pixel of a Healpix
-map as a separate source. The code is capable of modelling polarized visibilities
-and primary beams, but currently only a Stokes I sky model.
+``matvis`` is a fast Python matrix-based interferometric visibility simulator with both
+CPU and GPU implementations.
 
-``vis_cpu`` includes a separate ``pycuda``-based implementation called ``vis_gpu``.
-This is intended to keep feature parity with the ``vis_cpu`` code to the greatest
-extent possible.
+It is applicable to wide field-of-view instruments such as the Hydrogen Epoch of
+Reionization Array (HERA) and the Square Kilometre Array (SKA), as it does not make
+any approximations of the visibility integral (such as the flat-sky approximation).
+The only approximation made is that the sky is a collection of point sources, which
+is valid for sky models that intrinsically consist of point-sources, but is an
+approximation for diffuse sky models.
+
+An example wrapper for the main ``matvis`` simulator function is provided in this
+package (``matvis.simulate_vis()``).
+
+Features
+--------
+
+* Matrix-based algorithm is fast and scales well to large numbers of antennas.
+* Supports both CPU and GPU implementations as drop-in replacements for each other.
+* Supports both dense and sparse sky models.
+* Includes a wrapper for simulating multiple frequencies and setting up the simulation.
+* No approximations of the visibility integral (such as the flat-sky approximation).
+* Arbitrary primary beams per-antenna using the ``pyuvdata.UVBeam`` class.
+
+Limitations
+-----------
+
+* Currently no support for polarized sky models.
+* Currently no way of taking advantage of baseline redundancy to speed up simulations.
+* Diffuse sky models must be pixelised, which may not be the best basis-function for
+  some sky models.
 
-An example wrapper for the main ``vis_cpu`` simulator function is provided in this
-package (``vis_cpu.wrapper.simulate_vis()``).
 
 Installation
 ============
-Merely do ``pip install vis_cpu``. If you want to use the GPU functions, install
-with ``pip install vis_cpu[gpu]``.
+``pip install matvis``.
+
+If you want to use the GPU functions, install
+with ``pip install matvis[gpu]``.
 
 Developers
 ==========
 Run ``pre-commit install`` before working on this code.
 
 Read the Docs
 =============
-https://vis-cpu.readthedocs.io/en/latest/
+https://matvis.readthedocs.io/en/latest/

ci/notebook-env.yml

@@ -1,4 +1,4 @@
-name: viscpu
+name: matvis
 channels:
   - conda-forge
   - defaults