qnm.cached

Caching interface to Kerr QNMs

This is a high-level interface to the package. The global cache qnm.modes_cache (an instance of KerrSeqCache) will return instances of qnm.spinsequence.KerrSpinSeq from memory or disk. If a spin sequence is neither in memory nor on disk then it will be computed and returned.

Use download_data() to fetch a collection of precomputed spin sequences from the web.

Functions

build_package_default_cache(ksc)	Compute the standard list of modes that this package promises to have in its cache.
download_data([overwrite])	Fetch and decompress tarball of precomputed spin sequences from the web.
get_cachedir()	Return the location of the cache directory.
get_home()	Return the user’s home directory.
load_cached_mode(s, l, m, n)	Read a KerrSpinSeq from disk.
mode_pickle_path(s, l, m, n)	Construct the path to a pickle file for the mode (s, l, m, n)
write_mode(spin_seq[, pickle_path])	Write an instance of KerrSpinSeq to disk.

Classes

KerrSeqCache([init_schw, …])

High-level caching interface for getting precomputed spin sequences.

class qnm.cached.KerrSeqCache(init_schw=False, compute_if_not_found=True, compute_pars=None)

High-level caching interface for getting precomputed spin sequences.

An instance of KerrSeqCache will return instances of qnm.spinsequence.KerrSpinSeq from memory or disk. If a spin sequence is neither in memory nor on disk then it will be computed and returned.

Use download_data() to fetch a collection of precomputed spin sequences from the web.

Parameters:

init_schw: bool, optional [default: False]

Value of init flag to pass to qnm.schwarzschild.tabulated.QNMDict. You should set this to True the first time in a session that you create a QNMDict (most likely via this class).

compute_if_not_found: bool, optional [default: True]

If a mode sequence is not found on disk, this flag controls whether to try to compute the sequence from scratch.

compute_pars: dict, optional [default: None]

A dict of parameters to pass to qnm.spinsequence.KerrSpinSeq if computing a mode sequence from scratch.

Examples

>>> import qnm
>>> # qnm.download_data() # Only need to do this once
>>> grav_220 = qnm.modes_cache(s=-2,l=2,m=2,n=0)
>>> omega, A, C = grav_220(a=0.68)
>>> print(omega)
(0.5239751042900845-0.08151262363119986j)

Methods

__call__(s, l, m, n[, compute_if_not_found, …])	Load a qnm.spinsequence.KerrSpinSeq from the cache or from disk if available.
write_all()	Write all of the modes in the cache to disk.

__call__(s, l, m, n, compute_if_not_found=None, compute_pars=None)

Load a qnm.spinsequence.KerrSpinSeq from the cache or from disk if available.

If the mode sequence is not available on disk, optionally compute it from scratch.

Parameters:

s: int

Spin-weight of field of interest.

l: int

Multipole number of mode. l >= angular.l_min(s, m)

m: int

Azimuthal number of mode.

n: int

Overtone number of mode.

compute_if_not_found: bool, optional [default: self.compute_if_not_found]

Whether or not to compute from scratch the spin sequence if it is not available on disk.

compute_pars: dict, optional [default: self.compute_pars]

Dict of parameters to pass to KerrSpinSeq if a mode sequence needs to be computed from scratch.

Returns:

KerrSpinSeq

The mode, if it is in the cache, on disk, or has been computed from scratch. If the mode is not available and compute_if_not_found is false, return None.

write_all()

Write all of the modes in the cache to disk.

TODO: Take an overwrite argument which will force overwrite or not.

qnm.cached.build_package_default_cache(ksc)

Compute the standard list of modes that this package promises to have in its cache.

This method is intended to be used for building the modes from scratch in a predictable way. If modes are available on disk then there will be no computation, simply loading all the default modes.

Parameters:

ksc: KerrSeqCache

The cache that will hold the modes we are about to compute.

Returns:

KerrSeqCache

The updated cache.

qnm.cached.download_data(overwrite=False)

Fetch and decompress tarball of precomputed spin sequences from the web.

Parameters:

overwrite: bool, optional [default: False]

If there is already a tarball on disk, this flag controls whether or not it is overwritten.

qnm.cached.get_cachedir()

Return the location of the cache directory. This follows a pattern similar to matplotlib’s treatment of config/cache dirs.

The directory is chosen as follows: 1. If the QNMCACHEDIR environment variable is supplied, choose that. 2a. On Linux, follow the XDG specification and look first in

$XDG_CACHE_HOME, if defined, or $HOME/.cache.

2b. On other platforms, choose $HOME/.qnm. 3. If the chosen directory exists and is writable, use that as the

configuration directory.

4. A writable directory could not be found; return None.

Returns:

pathlib.Path object or None

qnm.cached.get_home()

Return the user’s home directory. If the user’s home directory cannot be found, return None.

qnm.cached.load_cached_mode(s, l, m, n)

Read a KerrSpinSeq from disk.

Path is determined by mode_pickle_path(s, l, m, n)().

Parameters:

s: int

Spin-weight of field of interest.

l: int

Multipole number of mode. l >= angular.l_min(s, m)

m: int

Azimuthal number of mode.

n: int

Overtone number of mode.

Returns:

KerrSpinSeq

The mode, if it exists. Otherwise None.

qnm.cached.mode_pickle_path(s, l, m, n)

Construct the path to a pickle file for the mode (s, l, m, n)

Parameters:

s: int

Spin-weight of field of interest.

l: int

Multipole number of mode. l >= angular.l_min(s, m)

m: int

Azimuthal number of mode.

n: int

Overtone number of mode.

Returns:

pathlib.Path object or None

<cachedir>/data/s<s>_l<l>_m<m>_n<n>.pickle

qnm.cached.write_mode(spin_seq, pickle_path=None)

Write an instance of KerrSpinSeq to disk.

Parameters:

spin_seq: KerrSpinSeq

The mode to write to disk.

pickle_path: string or pathlib.Path, optional [default: None]

Path to file to write. If None, get the path from mode_pickle_path().

Raises:

TODO