Merge pull request #72 from HERA-Team/refactoring

refactor: rename vis_cpu to matvis

.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

codecov.yml

@@ -1,4 +1,4 @@
 fixes:
-  - "/home/runner/work/vis_cpu/::"
+  - "/home/runner/work/matvis/::"
 codecov:
  token: f1912835-f0e2-4153-891b-f68eb359207f

docs/Makefile

@@ -78,17 +78,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/vis_cpu.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/matvis.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/vis_cpu.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/matvis.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/vis_cpu"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/vis_cpu"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/matvis"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/matvis"
 	@echo "# devhelp"
 
 epub:

docs/api.rst

@@ -9,7 +9,7 @@ High-Level Wrapper
    :template: custom-module.rst
    :toctree: _autosummary
 
-   vis_cpu.wrapper
+   matvis.wrapper
 
 
 Simulator implementations
@@ -18,14 +18,14 @@ Simulator implementations
    :template: custom-module.rst
    :toctree: _autosummary
 
-   vis_cpu.cpu
-   vis_cpu.gpu
+   matvis.cpu
+   matvis.gpu
 
 Other Utilities
 ---------------
 .. autosummary::
    :template: custom-module.rst
    :toctree: _autosummary
 
-   vis_cpu.plot
-   vis_cpu.conversions
+   matvis.plot
+   matvis.conversions

docs/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# vis_cpu documentation build configuration file, created by
+# matvis documentation build configuration file, created by
 # sphinx-quickstart on Mon Dec  2 10:40:08 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -65,7 +65,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'vis_cpu'
+project = u'matvis'
 copyright = u'%s, Steven Murray' % (time.localtime()[0])
 
 # The version info for the project you're documenting, acts as replacement for
@@ -83,9 +83,9 @@
 
 
 # The short X.Y version.
-version = _version('vis_cpu')
+version = _version('matvis')
 # The full version, including alpha/beta/rc tags.
-release = _version('vis_cpu')
+release = _version('matvis')
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -200,7 +200,7 @@
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'vis_cpudoc'
+htmlhelp_basename = 'matvisdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -219,7 +219,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'vis_cpu.tex', u'vis_cpu Documentation',
+  ('index', 'matvis.tex', u'matvis Documentation',
    u'Steven Murray', 'manual'),
 ]
 
@@ -249,7 +249,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'vis_cpu', u'vis_cpu Documentation',
+    ('index', 'matvis', u'matvis Documentation',
      [u'Steven Murray'], 1)
 ]
 
@@ -263,8 +263,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'vis_cpu', u'vis_cpu Documentation',
-   u'Steven Murray', 'vis_cpu', 'One line description of project.',
+  ('index', 'matvis', u'matvis Documentation',
+   u'Steven Murray', 'matvis', 'One line description of project.',
    'Miscellaneous'),
 ]
 

docs/tutorials.rst

@@ -1,9 +1,9 @@
 Tutorials and FAQs
 ==================
 
-The following introductory tutorial will help you get started with ``vis_cpu``:
+The following introductory tutorial will help you get started with ``matvis``:
 
 .. toctree::
    :maxdepth: 2
 
-   tutorials/vis_cpu_tutorial
+   tutorials/matvis_tutorial