{"id":24738387,"url":"https://github.com/astro-informatics/s2wav","last_synced_at":"2025-07-24T03:04:17.270Z","repository":{"id":64961641,"uuid":"488969594","full_name":"astro-informatics/s2wav","owner":"astro-informatics","description":"Differentiable and accelerated wavelet transform on the sphere with JAX","archived":false,"fork":false,"pushed_at":"2024-04-11T16:10:59.000Z","size":12164,"stargazers_count":12,"open_issues_count":16,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-12T23:47:12.068Z","etag":null,"topics":["dictionary","differentiable-programming","jax","sphere","spherical-harmonics","wavelet-transform"],"latest_commit_sha":null,"homepage":"https://astro-informatics.github.io/s2wav/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astro-informatics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-05-05T12:47:21.000Z","updated_at":"2024-04-15T11:48:07.377Z","dependencies_parsed_at":"2024-04-15T11:47:56.403Z","dependency_job_id":null,"html_url":"https://github.com/astro-informatics/s2wav","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-informatics%2Fs2wav","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-informatics%2Fs2wav/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-informatics%2Fs2wav/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-informatics%2Fs2wav/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astro-informatics","download_url":"https://codeload.github.com/astro-informatics/s2wav/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235934909,"owners_count":19068759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dictionary","differentiable-programming","jax","sphere","spherical-harmonics","wavelet-transform"],"created_at":"2025-01-27T22:36:20.647Z","updated_at":"2025-01-27T22:37:26.418Z","avatar_url":"https://github.com/astro-informatics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![image](https://github.com/astro-informatics/s2wav/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/astro-informatics/s2wav/actions/workflows/tests.yml)\n[![image](https://codecov.io/gh/astro-informatics/s2wav/branch/main/graph/badge.svg?token=ZES6J4K3KZ)](https://codecov.io/gh/astro-informatics/s2wav)\n[![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![image](https://badge.fury.io/py/s2wav.svg)](https://badge.fury.io/py/s2wav)\n[![image](http://img.shields.io/badge/arXiv-2402.01282-orange.svg?style=flat)](https://arxiv.org/abs/2402.01282) \u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-) \u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e \n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)]([https://colab.research.google.com/drive/15E64EAQ7TIp2a3cCoXtnNgf7Ud9MYjVq?usp=sharing](https://colab.research.google.com/github/astro-informatics/s2wav/blob/main/notebooks/jax_transform.ipynb))\n\n\u003cimg align=\"left\" height=\"85\" width=\"98\" src=\"./docs/assets/sax_logo.png\"\u003e\n\n# Differentiable and accelerated wavelet transform on the sphere\n\n`S2WAV` is a python package for computing wavelet transforms on the sphere\nand rotation group, both in JAX and PyTorch. It leverages autodiff to provide differentiable\ntransforms, which are also deployable on modern hardware accelerators\n(e.g. GPUs and TPUs), and can be mapped across multiple accelerators.\n\nMore specifically, `S2WAV` provides support for scale-discretised\nwavelet transforms on the sphere and rotation group (for both real and\ncomplex signals), with support for adjoints where needed, and comes with\na variety of different optimisations (e.g. precompute or not,\nmulti-resolution algorithms) that one may select depending on available\nresources and desired angular resolution $L$. `S2WAV` is a sister package of \n[`S2FFT`](https://github.com/astro-informatics/s2fft), both of which are part of the `SAX` \nproject, which aims to provide comprehensive support for differentiable transforms on the \nsphere and rotation group.\n\n\u003e [!TIP]\n\u003e As of version 1.0.0 `S2WAV` also provides partial frontend support for PyTorch. In future \n\u003e this will be expanded to full support. Also note that this release also provides JAX support \n\u003e for existing C spherical harmonic libraries, specifically `SSHT`. This works be wrapping \n\u003e python bindings with custom JAX frontends. Note that currently this C to JAX interoperability \n\u003e is limited to CPU.\n\n## Wavelet Transform :zap: \n`S2WAV` is an updated implementation of the scale-discretised wavelet transform on the \nsphere, which builds upon the papers of [Leistedt et al 2013](https://arxiv.org/abs/1211.1680) \nand [McEwen et al 2017](https://arxiv.org/abs/1509.06749). This wavelet transform is designed to \nhave excellent localisation and uncorrelation properties, and has been successfully adopted for \nvarious applications e.g. scattering transforms on the sphere [McEwen et al 2022](https://arxiv.org/pdf/2102.02828.pdf). \nThe wavelet dictionary is constructed by tiling the harmonic line with infinitely differentiable \nCauchy-Schwartz functions, which can straightforwardly be performed in an efficient multiresolution \nmanner, as in the Euclidean case. This is what the directional wavelet filters look like in pixel space.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/assets/figures/spherical_wavelets.png\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n## Installation :computer:\n\nThe Python dependencies for the `S2WAV` package are listed in the file\n`requirements/requirements-core.txt` and will be automatically installed\ninto the active python environment by [pip](https://pypi.org) when running\n\n``` bash\npip install s2wav     \n```\nThis will install the core functionality which includes JAX support (including PyTorch support).\n\nAlternatively, the `S2WAV` package may be installed directly from GitHub by cloning this \nrepository and then running\n\n``` bash\npip install .\n```\n\nfrom the root directory.\n\nUnit tests can then be executed to ensure the installation was successful by first \ninstalling the test requirements and then running pytest\n\n``` bash\npip install -r requirements/requirements-tests.txt\npytest tests/  \n```\n\nDocumentation for the released version is available [here](https://astro-informatics.github.io/s2wav/).\nTo build the documentation locally run \n\n``` bash\npip install -r requirements/requirements-docs.txt\ncd docs \nmake html\nopen _build/html/index.html\n```\n\n## Usage :rocket:\n\nTo import and use `S2WAV` is as simple follows:\n\n``` python\n# Compute wavelet coefficients\nf_wav, f_scal = s2wav.analysis(f, L, N)\n\n# Map back to signal on the sphere \nf = s2wav.synthesis(f_wav, f_scal, L, N)\n```\n\u003e [!NOTE]  \n\u003e However we strongly recommend that the multiresolution argument is set to true, as this \n\u003e will accelerate the transform by a factor of the total number of wavelet scales, which \n\u003e can be around an order of magnitude.\n\n## C JAX Frontends for SSHT :bulb:\n\n`S2WAV` also provides JAX support for SSHT, which is a highly optimised C library which \nimplements the underlying spherical harmonic transforms. This works by wrapping python \nbindings with custom JAX frontends. Note that this C to JAX interoperability is currently \nlimited to CPU.\n\nFor example, one may call these alternate backends for the spherical wavelet transform by:\n\n``` python\n# Compute wavelet coefficients using SSHT C library backend\nf_wav, f_scal = s2wav.analysis(f, L, N, use_c_backend=True)\n\n# Map back to signal on the sphere using SSHT C library backend\nf = s2wav.synthesis(f_wav, f_scal, L, N, use_c_backend=True)\n```\nThese JAX frontends supports out of the box reverse mode automatic differentiation, \nand under the hood is simply linking to the C packages you are familiar with. In this \nway S2fft enhances existing packages with gradient functionality for modern scientific \ncomputing or machine learning applications!\n\nFor further details on usage see the associated [notebooks](https://astro-informatics.github.io/s2wav/tutorials/index.html).\n\n## Contributors ✨\nWe strongly encourage contributions from any interested developers; a\nsimple example would be adding support for new wavelet filters e.g. spherical needlets \n[Chan et al 2016](https://arxiv.org/abs/1511.05578) or spherical ridgelets \n[McEwen \u0026 Price 2020](https://arxiv.org/pdf/1510.01595.pdf)! Thanks goes to these wonderful people ([emoji\nkey](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://cosmomatt.github.io\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/32554533?v=4?s=100\" width=\"100px;\" alt=\"Matt Price\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMatt Price\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/astro-informatics/s2wav/commits?author=CosmoMatt\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/astro-informatics/s2wav/pulls?q=is%3Apr+reviewed-by%3ACosmoMatt\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"https://github.com/astro-informatics/s2wav/commits?author=CosmoMatt\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#design-CosmoMatt\" title=\"Design\"\u003e🎨\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://www.jasonmcewen.org\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/3181701?v=4?s=100\" width=\"100px;\" alt=\"Jason McEwen \"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJason McEwen \u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/astro-informatics/s2wav/pulls?q=is%3Apr+reviewed-by%3Ajasonmcewen\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"#design-jasonmcewen\" title=\"Design\"\u003e🎨\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://alicjaap.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/114654380?v=4?s=100\" width=\"100px;\" alt=\"Alicja Polanska\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAlicja Polanska\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/astro-informatics/s2wav/commits?author=alicjapolanska\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/astro-informatics/s2wav/pulls?q=is%3Apr+reviewed-by%3Aalicjapolanska\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/JessWhitney\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/115358717?v=4?s=100\" width=\"100px;\" alt=\"Jessica Whitney\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJessica Whitney\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/astro-informatics/s2wav/commits?author=JessWhitney\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/astro-informatics/s2wav/pulls?q=is%3Apr+reviewed-by%3AJessWhitney\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## Attribution\n\nA BibTeX entry for `S2WAV` is:\n\n``` \n@article{price:s2wav, \n   author = {Matthew A. Price and Alicja Polanska and Jessica Whitney and Jason D. McEwen},\n    title = {\"Differentiable and accelerated directional wavelet transform on the sphere and ball\"},\n   eprint = {arXiv:2402.01282},\n     year = {2024}\n}\n```\n\nwe also request that you cite the following paper \n\n``` \n@article{price:s2fft, \n   author      = \"Matthew A. Price and Jason D. McEwen\",\n   title       = \"Differentiable and accelerated spherical harmonic and Wigner transforms\",\n   journal     = \"Journal of Computational Physics, submitted\",\n   year        = \"2023\",\n   eprint      = \"arXiv:2311.14670\"        \n}\n```\n\nin which the core underlying algorithms for the spherical harmonic and Wigner transforms \nare developed.\n\n## License :memo:\n\nCopyright 2024 Matthew Price, Jessica Whtiney, Alicja Polanska, Jason\nMcEwen and contributors.\n\n`S2WAV` is free software made available under the MIT License. For\ndetails see the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastro-informatics%2Fs2wav","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastro-informatics%2Fs2wav","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastro-informatics%2Fs2wav/lists"}