jqnm 0.1.0__tar.gz

jqnm-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2024 Cedric Ewen
+Copyright (c) 2019 Leo C. Stein (original qnm package)
+
+This package is derived from the qnm package (https://github.com/duetosymmetry/qnm)
+by Leo C. Stein, which is also MIT licensed.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jqnm-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include requirements.txt
+include pyproject.toml
+recursive-include jqnm/schwarzschild/data *
+recursive-include jqnm *.py

jqnm-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: jqnm
+Version: 0.1.0
+Summary: JAX-accelerated package for computing Kerr quasinormal mode frequencies with automatic differentiation support
+Author-email: Cedric Ewen <chessdric@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ewencedr/jqnm
+Project-URL: Repository, https://github.com/ewencedr/jqnm
+Project-URL: Issues, https://github.com/ewencedr/jqnm/issues
+Project-URL: Original Package, https://github.com/duetosymmetry/qnm
+Keywords: black holes,quasinormal modes,physics,scientific computing,numerical methods,jax,gpu,differentiable,gravitational waves
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: jax>=0.4.28
+Requires-Dist: optimistix>=0.0.6
+Requires-Dist: equinox>=0.11.0
+Requires-Dist: tqdm
+Provides-Extra: cuda12
+Requires-Dist: jax[cuda12]; extra == "cuda12"
+Provides-Extra: cuda11
+Requires-Dist: jax[cuda11]; extra == "cuda11"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: qnm; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: qnm; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# jqnm - JAX-Accelerated Kerr Quasinormal Modes
+
+[![PyPI version](https://badge.fury.io/py/jqnm.svg)](https://badge.fury.io/py/jqnm)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`jqnm` is a JAX-accelerated Python package for computing Kerr black hole
+quasinormal mode frequencies, angular separation constants, and
+spherical-spheroidal mixing coefficients.
+
+This package is a **JAX-based rewrite** of the excellent [qnm](https://github.com/duetosymmetry/qnm) 
+package by [Leo C. Stein](https://duetosymmetry.com), providing:
+
+- **GPU acceleration** via JAX
+- **Automatic differentiation** - compute gradients of QNM frequencies with respect to spin
+- **JIT compilation** for faster repeated computations
+- **Automatic caching** - modes computed once and cached at `~/.jqnm/`
+- Full compatibility with the original `qnm` package interface
+
+## Installation
+
+### PyPI
+
+```shell
+pip install jqnm
+```
+
+### From source
+
+```shell
+git clone https://github.com/ewencedr/jqnm.git
+cd jqnm
+pip install .
+```
+
+### GPU Support
+
+For GPU acceleration, install JAX with CUDA support:
+
+```shell
+# For CUDA 12
+pip install jqnm[cuda12]
+
+# For CUDA 11  
+pip install jqnm[cuda11]
+```
+
+## Dependencies
+
+- numpy
+- scipy
+- [JAX](https://github.com/google/jax) (>=0.4.28)
+- [optimistix](https://github.com/patrick-kidger/optimistix) - differentiable root finding
+- [equinox](https://github.com/patrick-kidger/equinox)
+- tqdm (for download progress)
+
+## Quick Start
+
+```python
+import jqnm
+
+# Get the (2,2,0) gravitational mode
+# On first use, modes are computed and cached automatically
+grav_220 = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+
+# Compute QNM frequency at spin a=0.68
+omega, A, C = grav_220(a=0.68)
+print(omega)
+# (0.5239751042900859-0.08151262363117728j)
+```
+
+Modes are automatically computed on first use and cached to `~/.jqnm/data/` for subsequent runs.
+
+> **Note:** `import jqnm` enables 64-bit precision in JAX
+> (`jax.config.update("jax_enable_x64", True)`), because the continued-fraction
+> root finding needs double precision. The setting is global, so it applies to
+> all JAX code in the same process.
+
+## Automatic Differentiation
+
+One of the key features of `jqnm` is the ability to compute gradients:
+
+```python
+import jax
+import jax.numpy as jnp
+import jqnm
+
+# Get a mode
+mode = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+
+# Define a function that returns the real part of omega
+def get_omega_real(a):
+    omega, A, C = mode(a=a)
+    return jnp.real(omega)
+
+# Compute the derivative with respect to spin
+d_omega_da = jax.grad(get_omega_real)
+print(d_omega_da(0.5))
+```
+
+## Usage
+
+The highest-level interface is via `jqnm.modes_cache`, which loads cached 
+*spin sequences* from disk or computes them on first use. A spin sequence is 
+a mode labeled by (s,l,m,n), with the spin `a` ranging from a=0 to some maximum 
+(e.g., 0.9995).
+
+```python
+import jqnm
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Get multiple overtones
+s, l, m = (-2, 2, 2)
+mode_list = [(s, l, m, n) for n in np.arange(0, 7)]
+modes = {ind: jqnm.modes_cache(*ind) for ind in mode_list}
+
+# Plot omega trajectories
+plt.figure(figsize=(10, 4))
+plt.subplot(1, 2, 1)
+for mode, seq in modes.items():
+    plt.plot(np.real(seq.omega), np.imag(seq.omega))
+plt.xlabel('Re(ω)')
+plt.ylabel('Im(ω)')
+plt.title('QNM Frequencies')
+
+plt.subplot(1, 2, 2)
+for mode, seq in modes.items():
+    plt.plot(np.real(seq.A), np.imag(seq.A))
+plt.xlabel('Re(A)')
+plt.ylabel('Im(A)')
+plt.title('Separation Constants')
+plt.tight_layout()
+plt.show()
+```
+
+## Spherical-Spheroidal Decomposition
+
+The angular dependence of QNMs are spin-weighted *spheroidal* harmonics. 
+The package returns coefficients C for expressing spheroidals in terms of 
+sphericals:
+
+```python
+import jqnm
+
+grav_220 = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+omega, A, C = grav_220(a=0.68)
+
+# Get the corresponding l values
+ells = jqnm.angular.ells(s=-2, m=2, l_max=grav_220.l_max)
+print(f"ell values: {ells}")
+print(f"C coefficients: {C}")
+```
+
+## Credits and Acknowledgments
+
+This package is a JAX-based rewrite of the [qnm](https://github.com/duetosymmetry/qnm) 
+package created by [Leo C. Stein](https://duetosymmetry.com). The original package 
+and its scientific foundations are described in:
+
+> Stein, Leo C. (2019). *qnm: A Python package for calculating Kerr quasinormal 
+> modes, separation constants, and spherical-spheroidal mixing coefficients.* 
+> Journal of Open Source Software, 4(42), 1683. 
+> [doi:10.21105/joss.01683](https://doi.org/10.21105/joss.01683)
+> [arXiv:1908.10377](https://arxiv.org/abs/1908.10377)
+
+If you use this package in academic work, please cite the original `qnm` paper above.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+This package is derived from [qnm](https://github.com/duetosymmetry/qnm) 
+(Copyright © 2019 Leo C. Stein), which is also MIT licensed.

jqnm-0.1.0/README.md

@@ -0,0 +1,173 @@
+# jqnm - JAX-Accelerated Kerr Quasinormal Modes
+
+[![PyPI version](https://badge.fury.io/py/jqnm.svg)](https://badge.fury.io/py/jqnm)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`jqnm` is a JAX-accelerated Python package for computing Kerr black hole
+quasinormal mode frequencies, angular separation constants, and
+spherical-spheroidal mixing coefficients.
+
+This package is a **JAX-based rewrite** of the excellent [qnm](https://github.com/duetosymmetry/qnm) 
+package by [Leo C. Stein](https://duetosymmetry.com), providing:
+
+- **GPU acceleration** via JAX
+- **Automatic differentiation** - compute gradients of QNM frequencies with respect to spin
+- **JIT compilation** for faster repeated computations
+- **Automatic caching** - modes computed once and cached at `~/.jqnm/`
+- Full compatibility with the original `qnm` package interface
+
+## Installation
+
+### PyPI
+
+```shell
+pip install jqnm
+```
+
+### From source
+
+```shell
+git clone https://github.com/ewencedr/jqnm.git
+cd jqnm
+pip install .
+```
+
+### GPU Support
+
+For GPU acceleration, install JAX with CUDA support:
+
+```shell
+# For CUDA 12
+pip install jqnm[cuda12]
+
+# For CUDA 11  
+pip install jqnm[cuda11]
+```
+
+## Dependencies
+
+- numpy
+- scipy
+- [JAX](https://github.com/google/jax) (>=0.4.28)
+- [optimistix](https://github.com/patrick-kidger/optimistix) - differentiable root finding
+- [equinox](https://github.com/patrick-kidger/equinox)
+- tqdm (for download progress)
+
+## Quick Start
+
+```python
+import jqnm
+
+# Get the (2,2,0) gravitational mode
+# On first use, modes are computed and cached automatically
+grav_220 = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+
+# Compute QNM frequency at spin a=0.68
+omega, A, C = grav_220(a=0.68)
+print(omega)
+# (0.5239751042900859-0.08151262363117728j)
+```
+
+Modes are automatically computed on first use and cached to `~/.jqnm/data/` for subsequent runs.
+
+> **Note:** `import jqnm` enables 64-bit precision in JAX
+> (`jax.config.update("jax_enable_x64", True)`), because the continued-fraction
+> root finding needs double precision. The setting is global, so it applies to
+> all JAX code in the same process.
+
+## Automatic Differentiation
+
+One of the key features of `jqnm` is the ability to compute gradients:
+
+```python
+import jax
+import jax.numpy as jnp
+import jqnm
+
+# Get a mode
+mode = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+
+# Define a function that returns the real part of omega
+def get_omega_real(a):
+    omega, A, C = mode(a=a)
+    return jnp.real(omega)
+
+# Compute the derivative with respect to spin
+d_omega_da = jax.grad(get_omega_real)
+print(d_omega_da(0.5))
+```
+
+## Usage
+
+The highest-level interface is via `jqnm.modes_cache`, which loads cached 
+*spin sequences* from disk or computes them on first use. A spin sequence is 
+a mode labeled by (s,l,m,n), with the spin `a` ranging from a=0 to some maximum 
+(e.g., 0.9995).
+
+```python
+import jqnm
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Get multiple overtones
+s, l, m = (-2, 2, 2)
+mode_list = [(s, l, m, n) for n in np.arange(0, 7)]
+modes = {ind: jqnm.modes_cache(*ind) for ind in mode_list}
+
+# Plot omega trajectories
+plt.figure(figsize=(10, 4))
+plt.subplot(1, 2, 1)
+for mode, seq in modes.items():
+    plt.plot(np.real(seq.omega), np.imag(seq.omega))
+plt.xlabel('Re(ω)')
+plt.ylabel('Im(ω)')
+plt.title('QNM Frequencies')
+
+plt.subplot(1, 2, 2)
+for mode, seq in modes.items():
+    plt.plot(np.real(seq.A), np.imag(seq.A))
+plt.xlabel('Re(A)')
+plt.ylabel('Im(A)')
+plt.title('Separation Constants')
+plt.tight_layout()
+plt.show()
+```
+
+## Spherical-Spheroidal Decomposition
+
+The angular dependence of QNMs are spin-weighted *spheroidal* harmonics. 
+The package returns coefficients C for expressing spheroidals in terms of 
+sphericals:
+
+```python
+import jqnm
+
+grav_220 = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+omega, A, C = grav_220(a=0.68)
+
+# Get the corresponding l values
+ells = jqnm.angular.ells(s=-2, m=2, l_max=grav_220.l_max)
+print(f"ell values: {ells}")
+print(f"C coefficients: {C}")
+```
+
+## Credits and Acknowledgments
+
+This package is a JAX-based rewrite of the [qnm](https://github.com/duetosymmetry/qnm) 
+package created by [Leo C. Stein](https://duetosymmetry.com). The original package 
+and its scientific foundations are described in:
+
+> Stein, Leo C. (2019). *qnm: A Python package for calculating Kerr quasinormal 
+> modes, separation constants, and spherical-spheroidal mixing coefficients.* 
+> Journal of Open Source Software, 4(42), 1683. 
+> [doi:10.21105/joss.01683](https://doi.org/10.21105/joss.01683)
+> [arXiv:1908.10377](https://arxiv.org/abs/1908.10377)
+
+If you use this package in academic work, please cite the original `qnm` paper above.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+This package is derived from [qnm](https://github.com/duetosymmetry/qnm) 
+(Copyright © 2019 Leo C. Stein), which is also MIT licensed.

jqnm-0.1.0/jqnm/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2024 Cedric Ewen
+Copyright (c) 2019 Leo C. Stein (original qnm package)
+
+This package is derived from the qnm package (https://github.com/duetosymmetry/qnm)
+by Leo C. Stein, which is also MIT licensed.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jqnm-0.1.0/jqnm/__init__.py

@@ -0,0 +1,113 @@
+"""jqnm - JAX-accelerated Kerr quasinormal modes.
+
+A JAX-based rewrite of the qnm package for computing Kerr black hole
+quasinormal mode frequencies, angular separation constants, and
+spherical-spheroidal mixing coefficients.
+
+This package provides GPU acceleration and automatic differentiation
+capabilities via JAX.
+
+The highest-level interface is via :class:`jqnm.cached.KerrSeqCache`,
+which will fetch instances of :class:`jqnm.spinsequence.KerrSpinSeq`.
+
+Examples
+--------
+
+>>> import jqnm
+>>> # Modes are computed and cached automatically on first use
+>>> grav_220 = jqnm.modes_cache(s=-2, l=2, m=2, n=0)
+>>> omega, A, C = grav_220(a=0.68)
+>>> print(omega)
+(0.5239751042900845-0.08151262363119986j)
+
+**Members**
+
+.. autosummary::
+
+   jqnm.download_data
+   jqnm.modes_cache
+
+.. autofunction:: download_data
+
+"""
+
+from __future__ import print_function, division, absolute_import
+
+# Enable 64-bit precision in JAX
+import jax
+jax.config.update("jax_enable_x64", True)
+
+from ._version import __version__
+
+__copyright__ = "Copyright (C) 2024 Cedric Ewen"
+__email__ = "chessdric@gmail.com"
+__status__ = "beta"
+__author__ = "Cedric Ewen"
+__license__ = """
+MIT License
+
+Copyright (c) 2024 Cedric Ewen
+Copyright (c) 2019 Leo C. Stein (original qnm package)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+"""
+
+__credits__ = """
+This package is a JAX-based rewrite of the qnm package by Leo C. Stein.
+Original package: https://github.com/duetosymmetry/qnm
+
+If you use this package in academic work, please cite:
+  Stein, Leo C. (2019). "qnm: A Python package for calculating Kerr 
+  quasinormal modes, separation constants, and spherical-spheroidal 
+  mixing coefficients." J. Open Source Softw., 4(42), 1683.
+  doi:10.21105/joss.01683, arXiv:1908.10377
+"""
+
+from . import radial
+from . import angular
+from . import contfrac
+from . import nearby
+
+from . import spinsequence
+
+from . import cached
+from .cached import download_data
+
+############################################################
+## Package initialization
+
+# Singleton for cache
+modes_cache = cached.KerrSeqCache(init_schw=True)
+"""Interface to the cache of QNMs.  This is a singleton instance of
+:class:`jqnm.cached.KerrSeqCache`.  It can be called like a function
+`jqnm.modes_cache(s,l,m,n)` to get a specific mode, the result being an
+instance of :class:`jqnm.spinsequence.KerrSpinSeq`."""
+
+# Ensure common versions of jitted functions are compiled
+def _ensure_jitted():
+    finder = nearby.NearbyRootFinder(a=0.3, s=-2, m=2, A_closest_to=3.6+0.1j,
+                                     l_max=20, omega_guess=0.4-0.09j,
+                                     tol=1e-10, n_inv=0, Nr_max=4000)
+    finder.do_solve()
+    finder.set_params(Nr_max=float("inf"))
+    finder.do_solve()
+    
+    return
+
+_ensure_jitted()

jqnm-0.1.0/jqnm/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"