API for the jaxqualin.qnmode module

KerrModel

Bases: QNMModel

Kerr black-hole QNM frequency model.

Computes QNM frequencies as a function of mass M and dimensionless spin a using the qnm package, exactly replicating the logic in :meth:mode_free.fix_mode.

Parameters:

Name	Type	Description	Default
s	int	Spin weight (default -2).	-2
retro_def_orbit	bool	Retrograde convention (default True).	True

QNMModel

Base class for parametric QNM frequency models.

Subclasses must override :meth:compute_omega and set :attr:param_names.

Attributes:

Name	Type	Description
param_names	List[str]	Ordered list of parameter names (e.g. ["M", "a"]).

n_params property

Number of model parameters.

compute_omega(lmnx, **params)

Return the complex QNM frequency for lmnx given params.

Must be overridden by subclasses.

param_bounds()

Return {name: (lower, upper)} for each model parameter.

The default is (-inf, inf) for every parameter.

custom_mode

A mode with a user-specified complex frequency.

Unlike mode / mode_free, this class does not load Kerr spin sequences. It implements the same duck-typed interface so it can be used anywhere a mode_free is expected (e.g. in qnm_fixed_list).

Attributes:

Name	Type	Description
omega		The complex QNM frequency.
omegar		The real part of the QNM frequency.
omegai		The imaginary part of the QNM frequency.
lmnx		Always None (no quantum numbers).

Parameters:

Name	Type	Description	Default
omega	complex	Complex QNM frequency.	required
label	Optional[str]	Optional human-readable label. If None, an auto-generated label of the form mode_<index> is used when the mode is created via :func:custom_mode_list.	None

fix_mode(*args, **kwargs)

No-op: the frequency is already fixed.

mode

Bases: mode_free

A class representing a frequency-fixed mode of a black hole.

Attributes:

Name	Type	Description
M	float	The mass of the black hole.
a	float	The spin parameter of the black hole.
retro_def_orbit	bool	Whether define retrograde modes with respect to the orbital frame (True) or remnant black hole frame (False). See the methods paper for details.

mode_free

A class representing a mode of a black hole.

Attributes:

Name	Type	Description
lmnx	Union[List[List[int]], str]	A list of lists of integers representing the mode numbers, or a string equal to constant. Each list of integers represents a constituent linear mode, and the list of lists represents a nonlinear mode if len(lmnx) > 1. For example, [[2, 2, 0], [3, 3, 0]] represents the 2,2,0x3,3,0 quadratic mode.
spinseq_list	List[KerrSpinSeq]	A list of qnm.spinsequence.KerrSpinSeq objects of the qnm package that maps the spin parameter a of the black hole into the QNM frequencies.
spinseq_list_neg_a	List[KerrSpinSeq]	Same as spinseq_list but for the retrograde branch of the QNM solution.
omegar	float	The real part of the QNM , if fixed. jax.Array of a single jnp.float64.
omegai	float	The imaginary part of the QNM frequency, if fixed. jax.Array of a single jnp.float64.
omega	complex	The complex QNM frequency, if fixed. jax.Array of a single jnp.complex128.
M	float	The mass of the black hole, if fixed.
a	float	The spin parameter of the black hole, if fixed.

Methods:

Name	Description
__init__	Initializes a mode_free object.
fix_mode	Fixes the complex frequency of the mode.

__init__(lmnx, s=-2)

Initializes a mode_free object.

Parameters:

Name	Type	Description	Default
lmnx	Union[List[List[int]], str]	A list of lists of integers representing the mode numbers, or a string equal to constant. Each list of integers represents a constituent linear mode, and the list of lists represents a nonlinear mode if len(lmnx) > 1. For example, [[2, 2, 0], [3, 3, 0]] represents the 2,2,0x3,3,0 quadratic mode.	required
s	int	The spin weight of the mode. Defaults to -2.	-2

fix_mode(M, a, retro_def_orbit=True)

Fixes the complex frequency of the mode.

Parameters:

Name	Type	Description	Default
M	float	The mass of the black hole.	required
a	float	The spin parameter of the black hole.	required
retro_def_orbit	bool	Whether to define retrograde modes with respect to the orbital frame (True) or remnant black hole frame (False). See the methods paper for details. Defaults to True.	True

is_overtone()

Determines whether the mode is an overtone.

Returns:

Type	Description
bool	Whether the mode is an overtone.

string()

Returns a string representation of the mode numbers.

Returns:

Type	Description
str	A string representation of the mode numbers.

sum_lm()

Returns the sum of the mode quantum numbers of constituent linear modes.

Returns:

Type	Description
Tuple[int, int]	The sum of the mode quantum numbers of constituent linear modes.

tex_string()

Returns a TeX string representation of the mode numbers.

Returns:

Type	Description
str	A TeX string representation of the mode numbers.

model_mode

Bases: model_mode_free

A :class:model_mode_free that fixes its frequency at init time.

Parameters:

Name	Type	Description	Default
lmnx	Union[List[List[int]], str]	Mode quantum numbers.	required
model	QNMModel	The :class:QNMModel that computes frequencies.	required
label	Optional[str]	Optional human-readable label.	None
s	int	Spin weight (unused, kept for API parity).	-2
**params		Model parameters forwarded to :meth:fix_mode.	{}

model_mode_free

A mode whose frequency is determined by a :class:QNMModel.

Attributes:

Name	Type	Description
lmnx		Mode quantum numbers (or "constant").
model		The :class:QNMModel that computes frequencies.

fix_mode(**params)

Compute and store the frequency from the model parameters.

custom_mode_list(omegas, labels=None)

Create a list of :class:custom_mode objects.

Parameters:

Name	Type	Description	Default
omegas	List[complex]	Complex frequencies.	required
labels	Optional[List[Optional[str]]]	Optional per-mode labels. None entries (or the whole argument) result in auto-generated labels mode_0, mode_1, etc.	None

Returns:

Type	Description
List[custom_mode]	A list of :class:custom_mode instances with _auto_index set.