References

jaxqualin — JAX-accelerated quasinormal mode analysis for gravitational-wave ringdowns.

FitConfig dataclass

Configuration for QNM fitting.

InitialGuessConfig dataclass

Configuration for initial guess generation.

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

ModeSearchAllFreeVaryingN

A class that performs a mode search for a given waveform, varying the number of free modes used in the fit.

Attributes:

Name	Type	Description
h	waveform	The waveform to be fit.
l	int	The harmonic number l of the waveform.
m	int	The harmonic number m of the waveform.
M	float	The mass of the black hole.
a	float	The dimensionless spin of the black hole.
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform.
t0_arr	ndarray	array of starting times for fitting.
N_list	List[int]	A list of integers that specifies the number of free modes to be used in each mode searcher in mode_searchers.
kwargs	Dict[str, Any]	A dictionary of keyword arguments.
flatness_checker_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the IterativeFlatnessChecker class.
mode_searcher_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the ModeSearchAllFreeLM class.
mode_searchers	List[ModeSearchAllFreeLM]	A list of ModeSearchAllFreeLM objects for mode searching with different number of free modes.
found_modes_final	List[mode]	A list of mode objects that contains the final list of modes found by the best mode searcher.
run_string_prefix	str	A string that is used as a prefix for the run name for dumping the pickle file.
load_pickle	bool	A boolean that specifies whether to load the pickle file.
CCE	bool	A boolean that specifies whether the waveform is a CCE waveform. This is not implemented yet.
fixed_fitters	List[QNMFitVaryingStartingTime]	A list of QNMFitVaryingStartingTime objects that contains the final list of fitters used for the flatness checkers in each mode searcher.
flatness_checkers	List[IterativeFlatnessChecker]	A list of IterativeFlatnessChecker objects that contains the list of flatness checkers used for the mode searchers.
best_run_indx	int	An integer that specifies the index of the mode searcher that found the most number of modes.

Methods:

Name	Description
init_searchers	Initializes the mode searchers.
do_mode_searches	Performs the mode searches.

__init__(h, M, a, relevant_lm_list=[], t0_arr=np.linspace(0, 50, num=501), flatness_checker_kwargs={}, mode_searcher_kwargs={}, **kwargs_in)

Initialize the ModeSearchAllFreeVaryingN class.

Parameters:

Name	Type	Description	Default
h	waveform	The waveform to be fit.	required
M	float	The mass of the black hole.	required
a	float	The dimensionless spin of the black hole.	required
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform.	[]
t0_arr	ndarray	array of starting times for fitting.	linspace(0, 50, num=501)
flatness_checker_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the IterativeFlatnessChecker class.	{}
mode_searcher_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the ModeSearchAllFreeLM class.	{}
**kwargs_in	Any	keyword arguments.	{}

do_mode_searches()

Performs the mode searches.

init_searchers()

Initializes the mode searchers.

summarize_final_modes(**kwargs)

Return per-mode final results for the selected best run.

ModeSearchAllFreeVaryingNSXS

A class that performs a mode search for a given SXS waveform, varying the number of free modes used in the fit.

Attributes:

Name	Type	Description
SXS_num	str	The SXS number of the waveform.
l	int	The harmonic number l of the
waveform.	m	The harmonic number m of the waveform.
t0_arr	ndarray	array of starting times for fitting.
N_list	List[int]	A list of integers that specifies the number of free modes to be used in each mode searcher in mode_searchers.
postfix_string	str	A string that is appended to the run name for dumping the pickle file.
CCE	bool	A boolean that specifies whether the waveform is a CCE waveform. This is not implemented yet.
kwargs	Dict[str, Any]	A dictionary of keyword arguments.
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.
relevant_lm_list_override	bool	A boolean that specifies whether to override the relevant_lm_list attribute of the ModeSearchAllFreeVaryingN class.
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform. Used if relevant_lm_list_override is True.
h	waveform	The waveform to be fit.
M	float	The mass of the black hole.
a	float	The dimensionless spin of the black hole.
Lev	int	The resolution level of the SXS simulation.
N_list_string	str	A string that is used as a suffix for the run name for dumping the pickle file.
run_string_fitter	str	A string that is used as a prefix for the run name for dumping the pickle file for the fitters.
run_string	str	A string that is used as a prefix for the run name for dumping the pickle file for the mode searcher.
run_string_full	str	A string that is used as a prefix for the run name for dumping the pickle file for the mode searcher, including the postfix_string.
file_path	str	The path to the pickle file.
load_pickle	bool	A boolean that specifies whether to load the pickle file for the fitters.
mode_searcher_load_pickle	bool	A boolean that specifies whether to load the pickle file for the mode searcher.
set_seed	int	An integer that specifies the seed for the random number generator.
save_mode_searcher	bool	A boolean that specifies whether to save the mode searcher to a pickle file.
mode_searcher_vary_N	ModeSearchAllFreeVaryingN	A ModeSearchAllFreeVaryingN object that performs the mode search.
found_modes_final	List[mode]	A list of mode objects that contains the final list of modes found by the best mode searcher.
download	Optional[bool]	A boolean that specifies whether to download the waveform, for sxs.load.

Methods:

Name	Description
mode_search_varying_N_sxs	Performs the mode searches.
do_mode_search_varying_N	Performs the mode searches and dumps the class instance to a pickle file.
get_waveform	Loads the waveform from the SXS catalog.
pickle_save	Dumps the class instance to a pickle file.
pickle_load	Check whether a pickle file exists and can be loaded.

__init__(SXS_num, l, m, t0_arr=np.linspace(0, 50, num=501), **kwargs_in)

Initialize the ModeSearchAllFreeVaryingNSXS class.

Parameters:

Name	Type	Description	Default
SXS_num	str	The SXS number of the waveform.	required
l	int	The harmonic number l of the waveform.	required
m	int	The harmonic number m of the waveform.	required
t0_arr	ndarray	array of starting times for fitting.	linspace(0, 50, num=501)
**kwargs_in	Any	keyword arguments.	{}

do_mode_search_varying_N()

Performs the mode searches and dumps the class instance to a pickle file.

get_waveform()

Loads the waveform from the SXS catalog.

mode_search_varying_N_sxs()

Performs the mode searches.

pickle_exists()

Check whether a pickle file exists and can be loaded.

pickle_save()

Dump the class instance to a pickle file.

summarize_final_modes(**kwargs)

Return per-mode final results for the selected best run.

QNMFitModel

Bases: QNMFitBase

Fit QNM waveform with a parametric frequency model.

When model is None (default), falls back to the Kerr M/a path. For a custom model, pass a :class:QNMModel instance together with model_params_guess and optionally model_params_bounds.

QNMFitVarMa

Bases: QNMFitModel

Backward-compatible convenience wrapper that uses the Kerr M/a model.

This is equivalent to QNMFitModel with model=None (the default Kerr-specific code path). The model, model_params_guess, and model_params_bounds parameters are not accepted here; use :class:QNMFitModel directly for custom models.

QNMFitVaryingStartingTime

A class for fitting the postmerger waveform with a varying starting time.

Attributes:

Name	Type	Description
t0_arr	ndarray	array of starting times for fitting.
h	waveform	waveform object to be fitted.
var_M_a	bool	fit for the mass and spin of the black hole.
Warning	bool	Not tested yet.
real	bool	whether to fit a real-valued waveform.
N_free	int	number of frequency-free QNMs to include in the model. These modes are completely free, i.e. their mode numbers are not fixed like those in qnm_free_list.
qnm_fixed_list	List[mode]	list of fixed-frequency QNMs included in the model.
qnm_free_list	List[mode_free]	list of free-frequency QNMs of fixed mode numbers to include in the model, only used for fitting M and a when var_M_a = True.
N_free	int	number of free QNMs.
run_string_prefix	str	prefix of the run name for dumping the pickle file.
nonconvergence_cut	bool	whether to cut the nonconverged fits.
nonconvergence_indx	List[int]	indices of the nonconverged fits.
initial_num	int	number of initial guesses to use for the first starting time for frequency-free fits.
include_mirror	bool	whether to include the mirror modes, for fitting waveforms with both waveform polarizations.
mirror_ratio_list	List[float]	list of ratios between prograde and mirror mode amplitudes.
iota	float	inclination angle of the source.
psi	float	polarization angle of the source.
save_results	bool	whether to save the results.
params0	ndarray	initial guess for the fit parameters, at least for the earliest t0 fit.
max_nfev	int	maximum number of function evaluations for the fit.
sequential_guess	bool	whether to use the previous fit as the initial guess for the next fit.
load_pickle	bool	whether to load the pickle file if it exists.
fit_save_prefix	str	prefix of the path to save the pickle file.
A_bound	float	maximum value of the amplitude.
fit_kwargs	Dict[str, Any]	keyword arguments for curve fitting.
initial_dict	Dict[str, Any]	key word arguments for make_initial_guess method.
A_guess_relative	bool	whether to multiply the initial guess of the amplitude by the peak strain of the waveform.
set_seed	int	random seed for generating the initial guesses.
weighted	bool	whether to perform a weighted fit.
double_skip	bool	whether to skip the next 2^n t0 fits when a fit does not converge, where n is the number of times the fit did not converge consecutively.
skip_i_init	int	number of t0 fits to skip for the first time a nonconvergent fit occured.
result_full	QNMFitVaryingStartingTimeResult	QNMFitVaryingStartingTimeResult object for storing the fit results.

Methods:

Name	Description
get_mirror_ratio_list	get mirror_ratio_list from iota and psi.
initial_guesses	generate initial guesses for the first t0 fit.
make_nan_result	generate a QNMFitVaryingStartingTimeResult object
with `nan` values. do_fits	perform the fits.

__init__(h, t0_arr, N_free=0, qnm_fixed_list=[], qnm_free_list=[], var_M_a=False, real=False, run_string_prefix='Default', params0=None, max_nfev=DEFAULT_MAX_NFEV, sequential_guess=True, load_pickle=True, fit_save_prefix=FIT_SAVE_PATH, nonconvergence_cut=False, A_bound=np.inf, fit_kwargs={}, initial_num=1, random_initial=False, initial_dict={}, A_guess_relative=True, set_seed=DEFAULT_SEED, weighted=False, double_skip=True, include_mirror=False, iota=None, psi=None, mirror_ignore_phase=True, skip_i_init=1, save_results=True, fit_config=None, model=None, model_params_guess=None, model_params_bounds=None)

Initialize the QNMFitVaryingStartingTime object.

Parameters:

Name	Type	Description	Default
h	waveform	waveform object to be fitted.	required
t0_arr	ndarray	array of starting times for fitting.	required
N_free	int	number of frequency-free QNMs to include in the model. These modes are completely free, i.e. their mode numbers are not fixed like those in qnm_free_list.	0
qnm_fixed_list	List[mode]	list of fixed-frequency QNMs included in the model.	[]
qnm_free_list	List[mode_free]	list of free-frequency QNMs of fixed mode numbers to include in the model, only used for fitting M and a when var_M_a = True.	[]
var_M_a	bool	fit for the mass and spin of the black hole. Warning: Not tested yet.	False
real	bool	whether to fit a real-valued waveform.	False
run_string_prefix	str	prefix of the run name for dumping the pickle file.	'Default'
params0	Optional[ndarray]	initial guess for the fit parameters, at least for the earliest t0 fit.	None
max_nfev	int	maximum number of function evaluations for the fit.	DEFAULT_MAX_NFEV
sequential_guess	bool	whether to use the previous fit as the initial guess for the next fit.	True
load_pickle	bool	whether to load the pickle file if it exists.	True
fit_save_prefix	str	prefix of the path to save the pickle file.	FIT_SAVE_PATH
nonconvergence_cut	bool	whether to cut the nonconverged fits.	False
A_bound	float	maximum value of the amplitude.	inf
fit_kwargs	Dict	keyword arguments for curve fitting.	{}
initial_num	int	number of initial guesses to use for the first starting time for frequency-free fits.	1
random_initial	bool	whether to generate random initial guesses for the first starting time for frequency-free fits.	False
initial_dict	Dict	key word arguments for make_initial_guess method.	{}
A_guess_relative	bool	whether to multiply the initial guess of the amplitude by the peak strain of the waveform.	True
set_seed	int	random seed for generating the initial guesses.	DEFAULT_SEED
weighted	bool	whether to perform a weighted fit.	False
double_skip	bool	whether to skip the next 2^n t0 fits when a fit does not converge, where n is the number of times the fit did not converge consecutively.	True
include_mirror	bool	whether to include the mirror modes, for fitting waveforms with both waveform polarizations.	False
iota	Optional[float]	inclination angle of the source.	None
psi	Optional[float]	polarization angle of the source.	None
mirror_ignore_phase	bool	whether to ignore the phase difference between the prograde and mirror modes.	True
skip_i_init	int	number of t0 fits to skip for the first time a nonconvergent fit occured.	1
save_results	bool	whether to save the results.	True
fit_config	Optional[FitConfig]	optional FitConfig dataclass. If provided, overrides the individual max_nfev, weighted, real, include_mirror, iota, and psi parameters.	None
model		optional QNMModel instance for custom parametric models.	None
model_params_guess		dict of initial guesses for model params.	None
model_params_bounds		dict overriding default model param bounds.	None

do_fits()

Perform the fits.

get_mirror_ratio_list()

Get the ratios between the prograde and mirror modes from iota and psi.

Returns:

Type	Description
List[float]	list of ratios between prograde and mirror mode amplitudes.

initial_guesses()

Generate initial guesses for the first t0 fit.

Returns:

Name	Type	Description
best_guess_index	int	index of the best initial guess.
qnm_fit_list	List[QNMFit]	list of QNMFit objects for the initial guesses.
guess_list	List[ndarray]	list of initial guess parameters used.

make_nan_result()

Generate a QNMFitVaryingStartingTimeResult object with nan values.

QNMFitVaryingStartingTimeResult

fixed_mode_flatness_plot_overlays(**kwargs)

Return (bold_dict, t_flat_start_dict) for flatness overlays.

summarize_fixed_mode_flatness(**kwargs)

Return per-mode flatness summary for fixed-frequency modes.

This wraps jaxqualin.selection.summarize_fixed_mode_flatness.

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.

waveform

A class representing a waveform containing a ringdown phase to be fitted.

Attributes:

Name	Type	Description
fulltime	ndarray	The full time array of the waveform.
fullh	ndarray	The full complex waveform.
peaktime	float	The time of peak strain jnp.abs(h) of the waveform.
peakindx	int	The array index of the time of peak strain of the waveform.
t_peak	int	The time of peak strain of the waveform. This can be defined by the user and overrides peaktime.
time	ndarray	The time array of the waveform after the peak, starting at t_peak and time shifted such that t_peak = 0.
hr	ndarray	The real part of the waveform after the peak.
hi	ndarray	The imaginary part of the waveform after the peak.
h	ndarray	The complex waveform after the peak.
l	int	The spherical harmonic mode number l of the waveform.
m	int	The spherical harmonic mode number m of the waveform.

Methods:

Name	Description
update_peaktime	Sets t_peak to override the peak time.
argabsmax	Returns the array index of the time of peak strain of the waveform.
postmerger	Returns the time, real part, and imaginary part of the waveform after the peak.
set_lm	Sets the spherical harmonic mode numbers l and m of the waveform.

__init__(fulltime, fullh, t_peak=None, t_start=0.0, t_end=np.inf, l=None, m=None, remove_num=DEFAULT_REMOVE_NUM)

Initialize a waveform.

Parameters:

Name	Type	Description	Default
fulltime	ndarray	The full time array of the waveform.	required
fullh	ndarray	The full complex waveform.	required
t_peak	Optional[float]	The time of peak strain of the waveform. This can be defined by the user and overrides peaktime.	None
t_start	float	The time after the peak to start the waveform.	0.0
t_end	float	The time after the peak to end the waveform.	inf
l	int	The spherical harmonic mode number l of the waveform.	None
m	int	The spherical harmonic mode number m of the waveform.	None
remove_num	int	The number of points to remove from the beginning of the waveform to avoid numerical artifacts.	DEFAULT_REMOVE_NUM

argabsmax(remove_num=DEFAULT_REMOVE_NUM)

Returns the array index of the time of peak strain of the waveform.

Parameters:

Name	Type	Description	Default
remove_num	int	The number of points to remove from the beginning of the waveform to avoid numerical artifacts.	DEFAULT_REMOVE_NUM

Returns:

Type	Description
int	The array index of the time of peak strain of the waveform.

postmerger(t_start, t_end=np.inf)

Returns the time, real part, and imaginary part of the waveform after the peak.

Parameters:

Name	Type	Description	Default
t_start	float	The time after the peak to start the waveform. t_end: The time after the peak to end the waveform.	required

Returns:

Type	Description
ndarray	The time, real part, and imaginary part of the waveform after the
ndarray	peak.

set_lm(l, m)

Sets the spherical harmonic mode numbers l and m of the waveform.

Parameters:

Name	Type	Description	Default
l	int	The spherical harmonic mode number l of the waveform.	required
m	int	The spherical harmonic mode number m of the waveform.	required

update_peaktime(t_peak)

Override the peak time of the waveform.

Parameters:

Name	Type	Description	Default
t_peak	float	The user-defined peak time of the waveform.	required

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.

make_hyper_fit_functions(filepath=_default_hyperfit_data_path, PN=True)

Make a dictionary of hyperfit functions from a hyperfit data file.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath of the hyperfit data file.	_default_hyperfit_data_path
PN	bool	Whether to use Post Newtonian variables (eta, chi_p, chi_m) or the natural parameterization of the BBH simulations (q, chi_1, chi_2).	True

Returns:

Type	Description
Dict[str, Dict[str, Callable[[float, float, float], float]]]	A dictionary of hyperfit functions. The keys are the mode names, and the values are dictionaries with keys A and phi for the amplitude and phase hyperfit functions, respectively.

make_interpolators(filepath=_default_interpolate_data_path, PN=True)

Make a dictionary of interpolators from a data file containing the extracted amplitude and phases of different modes from BBH simulations.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath of the data file.	_default_interpolate_data_path
PN	bool	Whether to use Post Newtonian variables (eta, chi_p, chi_m) or the natural parameterization of the BBH simulations (q, chi_1, chi_2).	True

Returns:

Type	Description
Dict[str, Dict[str, LinearNDInterpolator]]	A dictionary of interpolators. The keys are the mode names, and the values are dictionaries with keys A, dA, phi, and dphi for the amplitude, amplitude fluctuation, phase, and phase fluctuation interpolators, respectively.

data

download_file(filepath, url, overwrite='update')

Downloads a file from a url to a filepath

Parameters:

Name	Type	Description	Default
filepath	str	The filepath to save the downloaded file to	required
url	str	The url to download the file from	required
overwrite	str	Whether to overwrite the file if it already exists. Can be one of 'force', 'update', or 'never'.	'update'

last_modified_time(url)

Returns the last modified time of a url

Parameters:

Name	Type	Description	Default
url	str	The url to check the last modified time of	required

Returns:

Type	Description
struct_time	The last modified time of the url as a time.struct_time object

make_hyper_fit_functions(filepath=_default_hyperfit_data_path, PN=True)

Make a dictionary of hyperfit functions from a hyperfit data file.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath of the hyperfit data file.	_default_hyperfit_data_path
PN	bool	Whether to use Post Newtonian variables (eta, chi_p, chi_m) or the natural parameterization of the BBH simulations (q, chi_1, chi_2).	True

Returns:

Type	Description
Dict[str, Dict[str, Callable[[float, float, float], float]]]	A dictionary of hyperfit functions. The keys are the mode names, and the values are dictionaries with keys A and phi for the amplitude and phase hyperfit functions, respectively.

make_interpolators(filepath=_default_interpolate_data_path, PN=True)

Make a dictionary of interpolators from a data file containing the extracted amplitude and phases of different modes from BBH simulations.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath of the data file.	_default_interpolate_data_path
PN	bool	Whether to use Post Newtonian variables (eta, chi_p, chi_m) or the natural parameterization of the BBH simulations (q, chi_1, chi_2).	True

Returns:

Type	Description
Dict[str, Dict[str, LinearNDInterpolator]]	A dictionary of interpolators. The keys are the mode names, and the values are dictionaries with keys A, dA, phi, and dphi for the amplitude, amplitude fluctuation, phase, and phase fluctuation interpolators, respectively.

fit

FitConfig dataclass

Configuration for QNM fitting.

InitialGuessConfig dataclass

Configuration for initial guess generation.

QNMFitBase

Base class for QNM fitting with shared initialization and utilities.

QNMFitModel

Bases: QNMFitBase

Fit QNM waveform with a parametric frequency model.

When model is None (default), falls back to the Kerr M/a path. For a custom model, pass a :class:QNMModel instance together with model_params_guess and optionally model_params_bounds.

QNMFitVarMa

Bases: QNMFitModel

Backward-compatible convenience wrapper that uses the Kerr M/a model.

This is equivalent to QNMFitModel with model=None (the default Kerr-specific code path). The model, model_params_guess, and model_params_bounds parameters are not accepted here; use :class:QNMFitModel directly for custom models.

QNMFitVaryingStartingTime

A class for fitting the postmerger waveform with a varying starting time.

Attributes:

Name	Type	Description
t0_arr	ndarray	array of starting times for fitting.
h	waveform	waveform object to be fitted.
var_M_a	bool	fit for the mass and spin of the black hole.
Warning	bool	Not tested yet.
real	bool	whether to fit a real-valued waveform.
N_free	int	number of frequency-free QNMs to include in the model. These modes are completely free, i.e. their mode numbers are not fixed like those in qnm_free_list.
qnm_fixed_list	List[mode]	list of fixed-frequency QNMs included in the model.
qnm_free_list	List[mode_free]	list of free-frequency QNMs of fixed mode numbers to include in the model, only used for fitting M and a when var_M_a = True.
N_free	int	number of free QNMs.
run_string_prefix	str	prefix of the run name for dumping the pickle file.
nonconvergence_cut	bool	whether to cut the nonconverged fits.
nonconvergence_indx	List[int]	indices of the nonconverged fits.
initial_num	int	number of initial guesses to use for the first starting time for frequency-free fits.
include_mirror	bool	whether to include the mirror modes, for fitting waveforms with both waveform polarizations.
mirror_ratio_list	List[float]	list of ratios between prograde and mirror mode amplitudes.
iota	float	inclination angle of the source.
psi	float	polarization angle of the source.
save_results	bool	whether to save the results.
params0	ndarray	initial guess for the fit parameters, at least for the earliest t0 fit.
max_nfev	int	maximum number of function evaluations for the fit.
sequential_guess	bool	whether to use the previous fit as the initial guess for the next fit.
load_pickle	bool	whether to load the pickle file if it exists.
fit_save_prefix	str	prefix of the path to save the pickle file.
A_bound	float	maximum value of the amplitude.
fit_kwargs	Dict[str, Any]	keyword arguments for curve fitting.
initial_dict	Dict[str, Any]	key word arguments for make_initial_guess method.
A_guess_relative	bool	whether to multiply the initial guess of the amplitude by the peak strain of the waveform.
set_seed	int	random seed for generating the initial guesses.
weighted	bool	whether to perform a weighted fit.
double_skip	bool	whether to skip the next 2^n t0 fits when a fit does not converge, where n is the number of times the fit did not converge consecutively.
skip_i_init	int	number of t0 fits to skip for the first time a nonconvergent fit occured.
result_full	QNMFitVaryingStartingTimeResult	QNMFitVaryingStartingTimeResult object for storing the fit results.

Methods:

Name	Description
get_mirror_ratio_list	get mirror_ratio_list from iota and psi.
initial_guesses	generate initial guesses for the first t0 fit.
make_nan_result	generate a QNMFitVaryingStartingTimeResult object
with `nan` values. do_fits	perform the fits.

__init__(h, t0_arr, N_free=0, qnm_fixed_list=[], qnm_free_list=[], var_M_a=False, real=False, run_string_prefix='Default', params0=None, max_nfev=DEFAULT_MAX_NFEV, sequential_guess=True, load_pickle=True, fit_save_prefix=FIT_SAVE_PATH, nonconvergence_cut=False, A_bound=np.inf, fit_kwargs={}, initial_num=1, random_initial=False, initial_dict={}, A_guess_relative=True, set_seed=DEFAULT_SEED, weighted=False, double_skip=True, include_mirror=False, iota=None, psi=None, mirror_ignore_phase=True, skip_i_init=1, save_results=True, fit_config=None, model=None, model_params_guess=None, model_params_bounds=None)

Initialize the QNMFitVaryingStartingTime object.

Parameters:

Name	Type	Description	Default
h	waveform	waveform object to be fitted.	required
t0_arr	ndarray	array of starting times for fitting.	required
N_free	int	number of frequency-free QNMs to include in the model. These modes are completely free, i.e. their mode numbers are not fixed like those in qnm_free_list.	0
qnm_fixed_list	List[mode]	list of fixed-frequency QNMs included in the model.	[]
qnm_free_list	List[mode_free]	list of free-frequency QNMs of fixed mode numbers to include in the model, only used for fitting M and a when var_M_a = True.	[]
var_M_a	bool	fit for the mass and spin of the black hole. Warning: Not tested yet.	False
real	bool	whether to fit a real-valued waveform.	False
run_string_prefix	str	prefix of the run name for dumping the pickle file.	'Default'
params0	Optional[ndarray]	initial guess for the fit parameters, at least for the earliest t0 fit.	None
max_nfev	int	maximum number of function evaluations for the fit.	DEFAULT_MAX_NFEV
sequential_guess	bool	whether to use the previous fit as the initial guess for the next fit.	True
load_pickle	bool	whether to load the pickle file if it exists.	True
fit_save_prefix	str	prefix of the path to save the pickle file.	FIT_SAVE_PATH
nonconvergence_cut	bool	whether to cut the nonconverged fits.	False
A_bound	float	maximum value of the amplitude.	inf
fit_kwargs	Dict	keyword arguments for curve fitting.	{}
initial_num	int	number of initial guesses to use for the first starting time for frequency-free fits.	1
random_initial	bool	whether to generate random initial guesses for the first starting time for frequency-free fits.	False
initial_dict	Dict	key word arguments for make_initial_guess method.	{}
A_guess_relative	bool	whether to multiply the initial guess of the amplitude by the peak strain of the waveform.	True
set_seed	int	random seed for generating the initial guesses.	DEFAULT_SEED
weighted	bool	whether to perform a weighted fit.	False
double_skip	bool	whether to skip the next 2^n t0 fits when a fit does not converge, where n is the number of times the fit did not converge consecutively.	True
include_mirror	bool	whether to include the mirror modes, for fitting waveforms with both waveform polarizations.	False
iota	Optional[float]	inclination angle of the source.	None
psi	Optional[float]	polarization angle of the source.	None
mirror_ignore_phase	bool	whether to ignore the phase difference between the prograde and mirror modes.	True
skip_i_init	int	number of t0 fits to skip for the first time a nonconvergent fit occured.	1
save_results	bool	whether to save the results.	True
fit_config	Optional[FitConfig]	optional FitConfig dataclass. If provided, overrides the individual max_nfev, weighted, real, include_mirror, iota, and psi parameters.	None
model		optional QNMModel instance for custom parametric models.	None
model_params_guess		dict of initial guesses for model params.	None
model_params_bounds		dict overriding default model param bounds.	None

do_fits()

Perform the fits.

get_mirror_ratio_list()

Get the ratios between the prograde and mirror modes from iota and psi.

Returns:

Type	Description
List[float]	list of ratios between prograde and mirror mode amplitudes.

initial_guesses()

Generate initial guesses for the first t0 fit.

Returns:

Name	Type	Description
best_guess_index	int	index of the best initial guess.
qnm_fit_list	List[QNMFit]	list of QNMFit objects for the initial guesses.
guess_list	List[ndarray]	list of initial guess parameters used.

make_nan_result()

Generate a QNMFitVaryingStartingTimeResult object with nan values.

QNMFitVaryingStartingTimeResult

fixed_mode_flatness_plot_overlays(**kwargs)

Return (bold_dict, t_flat_start_dict) for flatness overlays.

summarize_fixed_mode_flatness(**kwargs)

Return per-mode flatness summary for fixed-frequency modes.

This wraps jaxqualin.selection.summarize_fixed_mode_flatness.

qnm_fit_func_var_model(t, qnm_fixed_list, qnm_free_list, fix_mode_params_list, free_mode_params_list, model_params, part=None)

Like qnm_fit_func_varMa but with an arbitrary parameter dict.

qnm_fit_func_wrapper_complex_var_model(t, qnm_fixed_list, qnm_free_list, model, *args)

Complex-interweaved wrapper for a generic QNMModel.

qnm_fit_func_wrapper_var_model(t, qnm_fixed_list, qnm_free_list, model, *args, part=None)

Wrapper that unpacks optimisation vector for a generic QNMModel.

plot

plot_amplitudes(results_full, fixed_modes=None, ax=None, alpha=1.0, ls='-', use_label=True, legend=True, color_dict={}, lw=2.0, bold_dict={}, lw_bold=4.0, alpha_bold=1.0, t_flat_start_dict={}, flat_start_s=20, flat_start_marker='o', plot_mirror_pred=False, iota=None, psi=0.0, af=None, A_fac=1.0)

Plot the amplitudes of the QNM modes as a function of starting time of the fit.

Parameters:

Name	Type	Description	Default
results_full	Union[QNMFitVaryingStartingTimeResult, QNMFitVaryingStartingTimeResultModel, QNMFitVaryingStartingTimeResultVarMa]	The results object of the fit.	required
fixed_modes	Optional[Union[QNMFitVaryingStartingTimeResult, QNMFitVaryingStartingTimeResultModel, QNMFitVaryingStartingTimeResultVarMa]]	The list of fixed modes to plot.	None
ax	Axes	The matplotlib axes to plot on. If None, a new figure and axes will be created.	None
alpha	float	The alpha value of the lines.	1.0
ls	str	The line style of the lines.	'-'
use_label	bool	Whether to use the mode name as the legend label.	True
legend	bool	Whether to include the legend.	True
color_dict	Dict[str, str]	A dictionary of the colors of the mode names.	{}
lw	float	The line width of the lines.	2.0
bold_dict	Dict[str, Tuple[int, int]]	A dictionary of mode names to tuples of indices indicating the starting and ending index of the region where the amplitude is flat. The line between the indices will be plotted with a larger line width.	{}
lw_bold	float	The line width of the lines between the corresponding indices in bold_dict.	4.0
alpha_bold	float	The alpha value of the lines corresponding to the indices in bold_dict.	1.0
t_flat_start_dict	Dict[str, float]	A dictionary of mode names to the optimal starting times. A scatter point will be plotted at the starting time of the fit for the corresponding mode.	{}
flat_start_s	float	The size of the scatter points corresponding to the indices in t_flat_start_dict.	20
flat_start_marker	str	The marker of the scatter points corresponding to the indices in t_flat_start_dict.	'o'
plot_mirror_pred	bool	Whether to plot the predicted amplitude of the mirror modes.	False
iota	Optional[float]	The inclination angle of the source.	None
psi	float	polarization angle of the source.	0.0
af	Optional[float]	The remnant spin of the black hole.	None
A_fac	float	The factor by which to multiply the amplitudes.	1.0

plot_mode_searcher_results(mode_searcher_vary_N, axs=None)

Plot the results of the best mode searcher in a ModeSearchAllFreeVaryingN object, including the frequency evolution of the free fit, and the amplitudes and phases of the final modes.

Parameters:

Name	Type	Description	Default
mode_searcher_vary_N	ModeSearchAllFreeVaryingN	The ModeSearchAllFreeVaryingN object to plot the results of.	required
axs	Optional[Axes]	The axes to plot on. If None, a new figure and axes is created.	None

plot_omega_free(results_full, ax=None, plot_indxs=[], t0_min=None, t0_max=None, indicate_start=False, color=None, line_alpha=0.3, scatter_alpha=0.5, scatter_size=1.0, color_indicate=False, color_indicate_list=[])

Plot the complex QNM frequencies as a function of starting time of the fit.

Parameters:

Name	Type	Description	Default
results_full	Union[QNMFitVaryingStartingTimeResult, QNMFitVaryingStartingTimeResultModel, QNMFitVaryingStartingTimeResultVarMa]	The results object of the fit.	required
ax	Axes	The matplotlib axes to plot on. If None, a new figure and axes will be created.	None
plot_indxs	List[int]	The indices of the modes to plot. If empty, all modes will be plotted.	[]
t0_min	Optional[float]	The minimum starting time to plot.	None
t0_max	Optional[float]	The maximum starting time to plot.	None
indicate_start	bool	Whether to indicate the starting point of the fit with a marker.	False
color	Optional[str]	The color of the scatter points and line.	None
line_alpha	float	The alpha value of the line.	0.3
scatter_alpha	float	The alpha value of the scatter points.	0.5
scatter_size	float	The size of the scatter points.	1.0
color_indicate	bool	Whether to color the scatter points and line according to color_indicate_list.	False
color_indicate_list	List[int]	Which default color to use for each mode, if color_indicate is True.	[]

plot_phases(results_full, fixed_modes=None, ax=None, alpha=1.0, ls='-', use_label=True, shift_phase=True, legend=True, color_dict={}, lw=2.0, bold_dict={}, lw_bold=4.0, alpha_bold=1.0, t_flat_start_dict={}, flat_start_s=20, flat_start_marker='o', plot_mirror_pred=False, iota=None, psi=0.0, af=None)

Plot the phases of the QNM modes as a function of starting time of the fit.

Parameters:

Name	Type	Description	Default
results_full	Union[QNMFitVaryingStartingTimeResult, QNMFitVaryingStartingTimeResultModel, QNMFitVaryingStartingTimeResultVarMa]	The results object of the fit.	required
fixed_modes	Optional[Union[QNMFitVaryingStartingTimeResult, QNMFitVaryingStartingTimeResultModel, QNMFitVaryingStartingTimeResultVarMa]]	The list of fixed modes to plot.	None
ax	Axes	The matplotlib axes to plot on. If None, a new figure and axes will be created.	None
alpha	float	The alpha value of the lines.	1.0
ls	str	The line style of the lines.	'-'
use_label	bool	Whether to use the mode name as the legend label.	True
shift_phase	bool	Whether to shift the phase by pi if the amplitude is negative.	True
legend	bool	Whether to include the legend.	True
color_dict	Dict[str, str]	A dictionary of the colors of the mode names.	{}
lw	float	The line width of the lines.	2.0
bold_dict	Dict[str, Tuple[int, int]]	A dictionary of mode names to tuples of indices indicating the starting and ending index of the region where the amplitude is flat. The line between the indices will be plotted with a larger line width.	{}
lw_bold	float	The line width of the lines corresponding to the indices in bold_dict.	4.0
alpha_bold	float	The alpha value of the lines corresponding to the indices in bold_dict.	1.0
t_flat_start_dict	Dict[str, float]	A dictionary of mode names to the optimal starting times. A scatter point will be plotted at the starting time of the fit for the corresponding mode.	{}
flat_start_s	int	The size of the scatter points corresponding to the indices in t_flat_start_dict.	20
flat_start_marker	str	The marker of the scatter points corresponding to the indices in t_flat_start_dict.	'o'
plot_mirror_pred	bool	Whether to plot the predicted phase of the mirror modes.	False
iota	Optional[float]	The inclination angle of the source.	None
psi	float	polarization angle of the source.	0.0
af	Optional[float]	The remnant spin of the black hole.	None

plot_predicted_qnms(ax, predicted_qnm_list, alpha_r=0.05, alpha_i=0.05, plot_ellipse=True, ellipse_edgecolor='gray', ellipse_facecolor='lightgray', ellipse_alpha=0.5, fix_indx=[], label_offset=(0, 0.0), change_lim=True, facecolor='none', edgecolor='gray', cut_at_0=False, pred_alpha=1.0, present_modes=[], edgecolor_present='k', expand_points=(1.1, 1.7), xminmin=-2, xmaxmax=2, yminmin=0.05, ymaxmax=-0.7, positive_y_alpha=0.5)

Plot the expected QNM frequencies on the complex plane.

Parameters:

Name	Type	Description	Default
ax	Axes	The matplotlib axes to plot on.	required
predicted_qnm_list	List[mode]	The list of expected QNM modes to plot in the complex plane.	required
alpha_r	float	The half width of the ellipse in the real direction.	0.05
alpha_i	float	The half width of the ellipse in the imaginary direction.	0.05
plot_ellipse	bool	Whether to plot the ellipse.	True
ellipse_edgecolor	str	The color of the ellipse edge.	'gray'
ellipse_facecolor	str	The color of the ellipse face.	'lightgray'
ellipse_alpha	float	The alpha value of the ellipse.	0.5
fix_indx	List[int]	The indices of the modes included in the fit with fixed frequencies. These modes will appear as solid black circles.	[]
label_offset	Tuple[float, float]	The offset of the mode labels from the mode position.	(0, 0.0)
change_lim	bool	Whether to change the axes limits of the ax passed.	True
facecolor	str	The face color of the scatter points.	'none'
edgecolor	str	The edge color of the scatter points.	'gray'
cut_at_0	bool	Whether to cut the axes at omegai = 0.	False
pred_alpha	float	The alpha value of the scatter points and labels.	1.0
present_modes	List[str]	The list of modes that are deemed present in the waveform.	[]
edgecolor_present	str	The edge color of the scatter points and labels of the modes that are deemed present in the waveform.	'k'
expand_points	Tuple[float, float]	The expansion factor passed to adjustText.adjust_text.	(1.1, 1.7)
xminmin	float	The minimum value of the x-axis after adjusting.	-2
xmaxmax	float	The maximum value of the x-axis after adjusting.	2
yminmin	float	The minimum value of the y-axis after adjusting.	0.05
ymaxmax	float	The maximum value of the y-axis after adjusting.	-0.7

postprocess

qnmode

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.

selection

ModeSearchAllFreeVaryingN

A class that performs a mode search for a given waveform, varying the number of free modes used in the fit.

Attributes:

Name	Type	Description
h	waveform	The waveform to be fit.
l	int	The harmonic number l of the waveform.
m	int	The harmonic number m of the waveform.
M	float	The mass of the black hole.
a	float	The dimensionless spin of the black hole.
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform.
t0_arr	ndarray	array of starting times for fitting.
N_list	List[int]	A list of integers that specifies the number of free modes to be used in each mode searcher in mode_searchers.
kwargs	Dict[str, Any]	A dictionary of keyword arguments.
flatness_checker_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the IterativeFlatnessChecker class.
mode_searcher_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the ModeSearchAllFreeLM class.
mode_searchers	List[ModeSearchAllFreeLM]	A list of ModeSearchAllFreeLM objects for mode searching with different number of free modes.
found_modes_final	List[mode]	A list of mode objects that contains the final list of modes found by the best mode searcher.
run_string_prefix	str	A string that is used as a prefix for the run name for dumping the pickle file.
load_pickle	bool	A boolean that specifies whether to load the pickle file.
CCE	bool	A boolean that specifies whether the waveform is a CCE waveform. This is not implemented yet.
fixed_fitters	List[QNMFitVaryingStartingTime]	A list of QNMFitVaryingStartingTime objects that contains the final list of fitters used for the flatness checkers in each mode searcher.
flatness_checkers	List[IterativeFlatnessChecker]	A list of IterativeFlatnessChecker objects that contains the list of flatness checkers used for the mode searchers.
best_run_indx	int	An integer that specifies the index of the mode searcher that found the most number of modes.

Methods:

Name	Description
init_searchers	Initializes the mode searchers.
do_mode_searches	Performs the mode searches.

__init__(h, M, a, relevant_lm_list=[], t0_arr=np.linspace(0, 50, num=501), flatness_checker_kwargs={}, mode_searcher_kwargs={}, **kwargs_in)

Initialize the ModeSearchAllFreeVaryingN class.

Parameters:

Name	Type	Description	Default
h	waveform	The waveform to be fit.	required
M	float	The mass of the black hole.	required
a	float	The dimensionless spin of the black hole.	required
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform.	[]
t0_arr	ndarray	array of starting times for fitting.	linspace(0, 50, num=501)
flatness_checker_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the IterativeFlatnessChecker class.	{}
mode_searcher_kwargs	Dict[str, Any]	A dictionary of keyword arguments for the ModeSearchAllFreeLM class.	{}
**kwargs_in	Any	keyword arguments.	{}

do_mode_searches()

Performs the mode searches.

init_searchers()

Initializes the mode searchers.

summarize_final_modes(**kwargs)

Return per-mode final results for the selected best run.

ModeSearchAllFreeVaryingNSXS

A class that performs a mode search for a given SXS waveform, varying the number of free modes used in the fit.

Attributes:

Name	Type	Description
SXS_num	str	The SXS number of the waveform.
l	int	The harmonic number l of the
waveform.	m	The harmonic number m of the waveform.
t0_arr	ndarray	array of starting times for fitting.
N_list	List[int]	A list of integers that specifies the number of free modes to be used in each mode searcher in mode_searchers.
postfix_string	str	A string that is appended to the run name for dumping the pickle file.
CCE	bool	A boolean that specifies whether the waveform is a CCE waveform. This is not implemented yet.
kwargs	Dict[str, Any]	A dictionary of keyword arguments.
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.
relevant_lm_list_override	bool	A boolean that specifies whether to override the relevant_lm_list attribute of the ModeSearchAllFreeVaryingN class.
relevant_lm_list	List[Tuple[int, int]]	A list of tuples of the form (l, m) that specifies which recoil modes are relevant for the waveform. Used if relevant_lm_list_override is True.
h	waveform	The waveform to be fit.
M	float	The mass of the black hole.
a	float	The dimensionless spin of the black hole.
Lev	int	The resolution level of the SXS simulation.
N_list_string	str	A string that is used as a suffix for the run name for dumping the pickle file.
run_string_fitter	str	A string that is used as a prefix for the run name for dumping the pickle file for the fitters.
run_string	str	A string that is used as a prefix for the run name for dumping the pickle file for the mode searcher.
run_string_full	str	A string that is used as a prefix for the run name for dumping the pickle file for the mode searcher, including the postfix_string.
file_path	str	The path to the pickle file.
load_pickle	bool	A boolean that specifies whether to load the pickle file for the fitters.
mode_searcher_load_pickle	bool	A boolean that specifies whether to load the pickle file for the mode searcher.
set_seed	int	An integer that specifies the seed for the random number generator.
save_mode_searcher	bool	A boolean that specifies whether to save the mode searcher to a pickle file.
mode_searcher_vary_N	ModeSearchAllFreeVaryingN	A ModeSearchAllFreeVaryingN object that performs the mode search.
found_modes_final	List[mode]	A list of mode objects that contains the final list of modes found by the best mode searcher.
download	Optional[bool]	A boolean that specifies whether to download the waveform, for sxs.load.

Methods:

Name	Description
mode_search_varying_N_sxs	Performs the mode searches.
do_mode_search_varying_N	Performs the mode searches and dumps the class instance to a pickle file.
get_waveform	Loads the waveform from the SXS catalog.
pickle_save	Dumps the class instance to a pickle file.
pickle_load	Check whether a pickle file exists and can be loaded.

__init__(SXS_num, l, m, t0_arr=np.linspace(0, 50, num=501), **kwargs_in)

Initialize the ModeSearchAllFreeVaryingNSXS class.

Parameters:

Name	Type	Description	Default
SXS_num	str	The SXS number of the waveform.	required
l	int	The harmonic number l of the waveform.	required
m	int	The harmonic number m of the waveform.	required
t0_arr	ndarray	array of starting times for fitting.	linspace(0, 50, num=501)
**kwargs_in	Any	keyword arguments.	{}

do_mode_search_varying_N()

Performs the mode searches and dumps the class instance to a pickle file.

get_waveform()

Loads the waveform from the SXS catalog.

mode_search_varying_N_sxs()

Performs the mode searches.

pickle_exists()

Check whether a pickle file exists and can be loaded.

pickle_save()

Dump the class instance to a pickle file.

summarize_final_modes(**kwargs)

Return per-mode final results for the selected best run.

fixed_mode_flatness_to_plot_overlays(flatness_summary)

Convert summarize_fixed_mode_flatness output to plot overlay dicts.

summarize_fixed_mode_flatness(result_full, delta_t=None, flatness_length=None, quantile_range=DEFAULT_P_STABLE, med_min=DEFAULT_A_TOL, weight_1=DEFAULT_BETA_A, weight_2=DEFAULT_BETA_PHI, fluc_tol=DEFAULT_EPSILON_STABLE, wrap_phase=True)

Compute per-mode flatness summary for a fixed-frequency fit result.

Parameters:

Name	Type	Description	Default
result_full		QNMFitVaryingStartingTimeResult-like object with t0_arr, A_fix_dict, and phi_fix_dict.	required
delta_t		Flatness window width in time units. Ignored if flatness_length is provided.	None
flatness_length		Optional explicit window length in index units.	None
quantile_range		Quantile range used for fluctuation estimate.	DEFAULT_P_STABLE
med_min		Floor for amplitude/phase normalization medians.	DEFAULT_A_TOL
weight_1		Amplitude fluctuation weight.	DEFAULT_BETA_A
weight_2		Phase fluctuation weight.	DEFAULT_BETA_PHI
fluc_tol		Threshold for earliest acceptable flatness window.	DEFAULT_EPSILON_STABLE
wrap_phase		If True, compute phase quantiles using circular wrapping.	True

Returns:

Type	Description
	Dict keyed by mode string. Each value includes: - flattest window start/end index and times - flattest fluctuation - median amplitude/phase within flattest window - earliest acceptable flat-window start index/time

summarize_mode_searcher_final_modes(mode_searcher_vary_N, quantile_low=0.05, quantile_high=0.95, wrap_phase=True)

Summarize final-mode flatness outputs from a mode-search result.

Uses the selected best run in ModeSearchAllFreeVaryingN and returns a per-mode dictionary containing mode presence, flattest window times, median amplitude/phase, asymmetric uncertainty ranges (upper/lower quantiles), and earliest flatness start time.

utils

all_close_to(array, val)

Check whether all elements of an array are close to a given value.

get_m(m)

Return 0 if m is the sentinel value, otherwise return m.

get_retrofac(retro)

Return -1 if retro is True, otherwise 1.

interweave(a, b)

Interweave two arrays into a single array with alternating elements.

load_pickle_file(path)

Load and return a Python object from a pickle file.

max_consecutive_trues(arrin, tol=1)

Return the start and end indices of the longest mostly-true window.

sign0(x)

Return the sign of x, treating zero as positive (+1).

sorti(li, i)

Sort a list of lists by the i-th element in descending order.

waveforms

waveform

A class representing a waveform containing a ringdown phase to be fitted.

Attributes:

Name	Type	Description
fulltime	ndarray	The full time array of the waveform.
fullh	ndarray	The full complex waveform.
peaktime	float	The time of peak strain jnp.abs(h) of the waveform.
peakindx	int	The array index of the time of peak strain of the waveform.
t_peak	int	The time of peak strain of the waveform. This can be defined by the user and overrides peaktime.
time	ndarray	The time array of the waveform after the peak, starting at t_peak and time shifted such that t_peak = 0.
hr	ndarray	The real part of the waveform after the peak.
hi	ndarray	The imaginary part of the waveform after the peak.
h	ndarray	The complex waveform after the peak.
l	int	The spherical harmonic mode number l of the waveform.
m	int	The spherical harmonic mode number m of the waveform.

Methods:

Name	Description
update_peaktime	Sets t_peak to override the peak time.
argabsmax	Returns the array index of the time of peak strain of the waveform.
postmerger	Returns the time, real part, and imaginary part of the waveform after the peak.
set_lm	Sets the spherical harmonic mode numbers l and m of the waveform.

__init__(fulltime, fullh, t_peak=None, t_start=0.0, t_end=np.inf, l=None, m=None, remove_num=DEFAULT_REMOVE_NUM)

Initialize a waveform.

Parameters:

Name	Type	Description	Default
fulltime	ndarray	The full time array of the waveform.	required
fullh	ndarray	The full complex waveform.	required
t_peak	Optional[float]	The time of peak strain of the waveform. This can be defined by the user and overrides peaktime.	None
t_start	float	The time after the peak to start the waveform.	0.0
t_end	float	The time after the peak to end the waveform.	inf
l	int	The spherical harmonic mode number l of the waveform.	None
m	int	The spherical harmonic mode number m of the waveform.	None
remove_num	int	The number of points to remove from the beginning of the waveform to avoid numerical artifacts.	DEFAULT_REMOVE_NUM

argabsmax(remove_num=DEFAULT_REMOVE_NUM)

Returns the array index of the time of peak strain of the waveform.

Parameters:

Name	Type	Description	Default
remove_num	int	The number of points to remove from the beginning of the waveform to avoid numerical artifacts.	DEFAULT_REMOVE_NUM

Returns:

Type	Description
int	The array index of the time of peak strain of the waveform.

postmerger(t_start, t_end=np.inf)

Returns the time, real part, and imaginary part of the waveform after the peak.

Parameters:

Name	Type	Description	Default
t_start	float	The time after the peak to start the waveform. t_end: The time after the peak to end the waveform.	required

Returns:

Type	Description
ndarray	The time, real part, and imaginary part of the waveform after the
ndarray	peak.

set_lm(l, m)

Sets the spherical harmonic mode numbers l and m of the waveform.

Parameters:

Name	Type	Description	Default
l	int	The spherical harmonic mode number l of the waveform.	required
m	int	The spherical harmonic mode number m of the waveform.	required

update_peaktime(t_peak)

Override the peak time of the waveform.

Parameters:

Name	Type	Description	Default
t_peak	float	The user-defined peak time of the waveform.	required

get_SXS_waveform_summed(SXS_num, iota, psi, l_max=4, res=0, N_ext=2)

Obtain the waveform of a SXS simulation summed over all modes up to l_max.

Parameters:

Name	Type	Description	Default
SXS_num	str	The SXS simulation number.	required
iota	float	The inclination angle of the binary.	required
psi	float	The phase to use.	required
l_max	int	The maximum l mode to include in the waveform.	4
res	int	The level of the simulation, relative to the highest resolution level (res = 0 means highest resolution). Must be zero or negative.	0
N_ext	int	The extrapolation order of the simulation.	2

Returns:

Name	Type	Description
h	waveform	The waveform.
Mf	float	The final mass of the binary.
af	float	The final spin of the binary.