Merge pull request #167 from astro-informatics/release/v1.0.0

PreRelease/v1.0.0

.coveragerc

@@ -1,17 +1,4 @@
-[paths]
-source =
-    ../s2fft
-    */site-packages/s2fft
-
-[run]
-branch = true
-parallel = true
-source =
-    s2fft
-
 [report]
-show_missing = true
-precision = 2
 omit = 
     *test_*
     *__init__*

.github/workflows/docs.yml

@@ -4,9 +4,7 @@ on:
   push:
     branches:
     - main
-    # Add following in for testing
-    # - feature/deploy_docs
-
+
 jobs:
   build:
 

.github/workflows/tests.yml

@@ -34,5 +34,5 @@ jobs:
     
     - name: Run tests
       run: |
-        pytest --cov-report term --cov=s2wav --cov-config=.coveragerc 
+        pytest --cov-report term --cov=s2fft --cov-config=.coveragerc 
         codecov --token 298dc7ee-bb9f-4221-b31f-3576cc6cb702

.pip_readme.rst

@@ -1,58 +1,90 @@
-.. image:: https://img.shields.io/badge/GitHub-PyTemplate-brightgreen.svg?style=flat
-    :target: https://github.com/astro-informatics/s2fft
 .. image:: https://github.com/astro-informatics/s2fft/actions/workflows/tests.yml/badge.svg?branch=main
     :target: https://github.com/astro-informatics/s2fft/actions/workflows/tests.yml
-.. image:: https://readthedocs.org/projects/ansicolortags/badge/?version=latest
-    :target: https://astro-informatics.github.io/s2fft
+.. image:: https://img.shields.io/badge/GitHub-PyTemplate-brightgreen.svg?style=flat
+    :target: https://github.com/astro-informatics/s2fft
 .. image:: https://codecov.io/gh/astro-informatics/s2fft/branch/main/graph/badge.svg?token=7QYAFAAWLE
     :target: https://codecov.io/gh/astro-informatics/s2fft
 .. image:: https://img.shields.io/badge/License-MIT-yellow.svg
     :target: https://opensource.org/licenses/MIT
 .. image:: http://img.shields.io/badge/arXiv-xxxx.xxxxx-orange.svg?style=flat
     :target: https://arxiv.org/abs/xxxx.xxxxx
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+    :target: https://colab.research.google.com/drive/1YmJ2ljsF8HBvhPmD4hrYPlyAKc4WPUgq?usp=sharing
 
-S2FFT: JAX accelerated spin-spherical harmonic transforms
+Differentiable and accelerated spherical transforms with JAX
 =================================================================================================================
 
-Add some basic discussion about ``S2FFT`` here.
+`S2FFT` is a JAX package for computing Fourier transforms on the sphere
+and rotation group. It leverages autodiff to provide differentiable
+transforms, which are also deployable on hardware accelerators
+(e.g. GPUs and TPUs).
 
-Installation
-============
+More specifically, `S2FFT` provides support for spin spherical harmonic
+and Wigner transforms (for both real and complex signals), with support
+for adjoint transformations where needed, and comes with different
+optimisations (precompute or not) that one may select depending on
+available resources and desired angular resolution $L$.
 
-Add some basic installation instructions here.
-
 Documentation
 =============
-
-Link to the full documentation (when deployed).
-
-Contributors
-============
-Author names & Contributors
+Read the full documentation [here](https://astro-informatics.github.io/s2fft/#).
 
 Attribution
 ===========
-A BibTeX entry for <project-name> is:
+Should this code be used in any way, we kindly request that the following article is
+referenced. A BibTeX entry for this reference may look like:
+
+.. code-block:: 
+
+    @article{price:s2fft, 
+        author      = "Matthew A. Price and Jason D. McEwen and Contributors",
+        title       = "Differentiable and accelerated spherical harmonic and Wigner transforms",
+        journal     = "Journal of Computational Physics",
+        year        = "2023",
+        eprint      = "arXiv:0000.00000"        
+    }
+
+You might also like to consider citing our related papers on which this
+code builds:
+
+.. code-block::
+
+    @article{mcewen:fssht,
+        author      = "Jason D. McEwen and Yves Wiaux",
+        title       = "A novel sampling theorem on the sphere",
+        journal     = "IEEE Trans. Sig. Proc.",
+        year        = "2011",
+        volume      = "59",
+        number      = "12",
+        pages       = "5876--5887",        
+        eprint      = "arXiv:1110.6298",
+        doi         = "10.1109/TSP.2011.2166394"
+    }
+
 
 .. code-block:: 
 
-     @article{S2FFT, 
-        author = {Author~List},
-         title = {"A totally amazing name"},
-       journal = {ArXiv},
-        eprint = {arXiv:0000.00000},
-          year = {what year is it?!}
-     }
+    @article{mcewen:so3,
+        author      = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
+        title       = "A novel sampling theorem on the rotation group",
+        journal     = "IEEE Sig. Proc. Let.",
+        year        = "2015",
+        volume      = "22",
+        number      = "12",
+        pages       = "2425--2429",
+        eprint      = "arXiv:1508.03101",
+        doi         = "10.1109/LSP.2015.2490676"    
+    }
 
 License
 =======
 
-``S2FFT`` is released under the MIT license (see 
-`LICENSE.txt <https://github.com/astro-informatics/s2fft/blob/main/LICENCE.txt>`_).
-
-.. code-block::
+We provide this code under an MIT open-source licence with the hope that
+it will be of use to a wider community.
 
-     S2FFT
-     Copyright (C) 2022 Author names & contributors
+Copyright 2023 Matthew Price, Jason McEwen and contributors.
 
-     This program is released under the MIT license (see `LICENSE.txt`).
+`S2FFT` is free software made available under the MIT License. For
+details see the LICENSE file.

MANIFEST.in

@@ -7,9 +7,7 @@ include .pip_readme.rst
 include README.rst
 include pytest.ini
 include LICENCE.txt
-include LICENCE_EXT.txt
 include s2fft/default-logging-config.yaml
-include tox.ini
 
 exclude .coveragerc
 exclude *.log

README.md

@@ -1,18 +1,18 @@
 [![image](https://github.com/astro-informatics/s2fft/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/astro-informatics/s2fft/actions/workflows/tests.yml)
-[![image](https://readthedocs.org/projects/ansicolortags/badge/?version=latest)](https://astro-informatics.github.io/s2fft)
 [![image](https://codecov.io/gh/astro-informatics/s2fft/branch/main/graph/badge.svg?token=7QYAFAAWLE)](https://codecov.io/gh/astro-informatics/s2fft)
 [![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![image](http://img.shields.io/badge/arXiv-xxxx.xxxxx-orange.svg?style=flat)](https://arxiv.org/abs/xxxx.xxxxx)<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-) <!-- ALL-CONTRIBUTORS-BADGE:END --> 
 [![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1YmJ2ljsF8HBvhPmD4hrYPlyAKc4WPUgq?usp=sharing)
 
 <img align="left" height="85" width="98" src="./docs/assets/sax_logo.png">
 
 # Differentiable and accelerated spherical transforms with JAX
 
 `S2FFT` is a JAX package for computing Fourier transforms on the sphere
 and rotation group. It leverages autodiff to provide differentiable
-transforms, which are also deployable on modern hardware accelerators
+transforms, which are also deployable on hardware accelerators
 (e.g. GPUs and TPUs).
 
 More specifically, `S2FFT` provides support for spin spherical harmonic
@@ -30,7 +30,20 @@ algorithms are based on new Wigner-d recursions that are stable to high
 angular resolution $L$. The diagram below illustrates the recursions
 (for further details see Price & McEwen, in prep.).
 
-![image](./docs/assets/figures/schematic.png)
+![image](./docs/assets/figures/Wigner_recursion_legend_darkmode.png)
+With this recursion to hand, the spherical harmonic coefficients of an 
+isolatitudinally sampled map may be computed as a two step process. First, 
+a 1D Fourier transform over longitude, for each latitudinal ring. Second, 
+a projection onto the real polar-d functions. One may precompute and store 
+all real polar-d functions for extreme acceleration, however this comes 
+with an equally extreme memory overhead, which is infeasible at L ~ 1024. 
+Alternatively, the real polar-d functions may calculated recursively, 
+computing only a portion of the projection at a time, hence incurring 
+negligible memory overhead at the cost of slightly slower execution. The 
+diagram below illustrates the separable spherical harmonic transform 
+(for further details see Price & McEwen, in prep.).
+
+![image](./docs/assets/figures/sax_schematic_legend_darkmode.png)
 
 ## Sampling :earth_africa:
 
@@ -70,8 +83,7 @@ from the root directory of the repository. Unit tests can then be
 executed to ensure the installation was successful by running
 
 ``` bash
-pytest tests/         # for pytest
-tox -e py38           # for tox 
+pytest tests/  
 ```
 
 In the very near future one will be able to install `S2FFT` directly
@@ -166,10 +178,11 @@ referenced. A BibTeX entry for this reference may look like:
 
 ``` 
 @article{price:s2fft, 
-   AUTHOR      = "Matthew A. Price and Jason D. McEwen and Contributors",
-   TITLE       = "TBA",
-   YEAR        = "2023",
-   EPRINT      = "arXiv:0000.00000"        
+   author      = "Matthew A. Price and Jason D. McEwen and Contributors",
+   title       = "Differentiable and accelerated spherical harmonic and Wigner transforms",
+   journal     = "Journal of Computational Physics",
+   year        = "2023",
+   eprint      = "arXiv:0000.00000"        
 }
 ```
 
@@ -178,29 +191,29 @@ code builds:
 
 ``` 
 @article{mcewen:fssht,
-    AUTHOR      = "Jason D. McEwen and Yves Wiaux",
-    TITLE       = "A novel sampling theorem on the sphere",
-    JOURNAL     = "IEEE Trans. Sig. Proc.",
-    YEAR        = "2011",
-    VOLUME      = "59",
-    NUMBER      = "12",
-    PAGES       = "5876--5887",        
-    EPRINT      = "arXiv:1110.6298",
-    DOI         = "10.1109/TSP.2011.2166394"
+    author      = "Jason D. McEwen and Yves Wiaux",
+    title       = "A novel sampling theorem on the sphere",
+    journal     = "IEEE Trans. Sig. Proc.",
+    year        = "2011",
+    volume      = "59",
+    number      = "12",
+    pages       = "5876--5887",        
+    eprint      = "arXiv:1110.6298",
+    doi         = "10.1109/TSP.2011.2166394"
 }
 ```
 
 ``` 
 @article{mcewen:so3,
-    AUTHOR      = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
-    TITLE       = "A novel sampling theorem on the rotation group",
-    JOURNAL     = "IEEE Sig. Proc. Let.",
-    YEAR        = "2015",
-    VOLUME      = "22",
-    NUMBER      = "12",
-    PAGES       = "2425--2429",
-    EPRINT      = "arXiv:1508.03101",
-    DOI         = "10.1109/LSP.2015.2490676"    
+    author      = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
+    title       = "A novel sampling theorem on the rotation group",
+    journal     = "IEEE Sig. Proc. Let.",
+    year        = "2015",
+    volume      = "22",
+    number      = "12",
+    pages       = "2425--2429",
+    eprint      = "arXiv:1508.03101",
+    doi         = "10.1109/LSP.2015.2490676"    
 }
 ```
 

docs/conf.py

@@ -100,12 +100,12 @@
     "header_links_before_dropdown": 5,
     "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
     "icon_links": [
-        # {
-        #     "name": "ArXiv",
-        #     "url": "https://arxiv.org/abs/xxxx.xxxxx",
-        #     "icon": "_static/arxiv-logomark-small.png",
-        #     "type": "local",
-        # },
+        {
+            "name": "ArXiv",
+            "url": "https://arxiv.org/abs/xxxx.xxxxx",
+            "icon": "_static/arxiv-logomark-small.png",
+            "type": "local",
+        },
         # {
         #     "name": "YouTube",
         #     "url": "https://www.youtube.com/channel/UCrCOQsyQOJhOUaIYzmbkKQQ",

docs/index.rst

@@ -18,7 +18,20 @@ distributed, and so map very well onto the architecture of hardware accelerators
 GPUs and TPUs).  In particular, these algorithms are based on new Wigner-d recursions
 that are stable to high angular resolution :math:`L`.  The diagram below illustrates the recursions (for further details see Price & McEwen 2023).
 
-.. image:: ./assets/figures/schematic.png
+.. image:: ./assets/figures/Wigner_recursion_github_docs.png
+
+With this recursion to hand, the spherical harmonic coefficients of an 
+isolatitudinally sampled map may be computed as a two step process. First, 
+a 1D Fourier transform over longitude, for each latitudinal ring. Second, 
+a projection onto the real polar-d functions. One may precompute and store 
+all real polar-d functions for extreme acceleration, however this comes 
+with an equally extreme memory overhead, which is infeasible at L ~ 1024. 
+Alternatively, the real polar-d functions may calculated recursively, 
+computing only a portion of the projection at a time, hence incurring 
+negligible memory overhead at the cost of slightly slower execution. The 
+diagram below illustrates the separable spherical harmonic transform.
+
+.. image:: ./assets/figures/sax_schematic_github_docs.png
 
 Sampling |:earth_africa:|
 -----------------------------------
@@ -68,41 +81,42 @@ article is referenced. A BibTeX entry for this reference may look like:
 
 .. code-block:: 
 
-     @article{price:s2fft, 
-        AUTHOR      = "Matthew A. Price and Jason D. McEwen",
-        TITLE       = "TBA",
-        YEAR        = "2023",
-        EPRINT      = "arXiv:0000.00000"        
-     }
+    @article{price:s2fft, 
+        author      = "Matthew A. Price and Jason D. McEwen and Contributors",
+        title       = "Differentiable and accelerated spherical harmonic and Wigner transforms",
+        journal     = "Journal of Computational Physics",
+        year        = "2023",
+        eprint      = "arXiv:0000.00000"        
+    }
 
 You might also like to consider citing our related papers on which this code builds:
 
 .. code-block:: 
 
     @article{mcewen:fssht,
-        AUTHOR      = "Jason D. McEwen and Yves Wiaux",
-        TITLE       = "A novel sampling theorem on the sphere",
-        JOURNAL     = "IEEE Trans. Sig. Proc.",
-        YEAR        = "2011",
-        VOLUME      = "59",
-        NUMBER      = "12",
-        PAGES       = "5876--5887",        
-        EPRINT      = "arXiv:1110.6298",
-        DOI         = "10.1109/TSP.2011.2166394"
+        author      = "Jason D. McEwen and Yves Wiaux",
+        title       = "A novel sampling theorem on the sphere",
+        journal     = "IEEE Trans. Sig. Proc.",
+        year        = "2011",
+        volume      = "59",
+        number      = "12",
+        pages       = "5876--5887",        
+        eprint      = "arXiv:1110.6298",
+        doi         = "10.1109/TSP.2011.2166394"
     }
 
 .. code-block::
    
     @article{mcewen:so3,
-        AUTHOR      = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
-        TITLE       = "A novel sampling theorem on the rotation group",
-        JOURNAL     = "IEEE Sig. Proc. Let.",
-        YEAR        = "2015",
-        VOLUME      = "22",
-        NUMBER      = "12",
-        PAGES       = "2425--2429",
-        EPRINT      = "arXiv:1508.03101",
-        DOI         = "10.1109/LSP.2015.2490676"    
+        author      = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
+        title       = "A novel sampling theorem on the rotation group",
+        journal     = "IEEE Sig. Proc. Let.",
+        year        = "2015",
+        volume      = "22",
+        number      = "12",
+        pages       = "2425--2429",
+        eprint      = "arXiv:1508.03101",
+        doi         = "10.1109/LSP.2015.2490676"     
     }
 
 License |:memo:|