API for the jaxqualin.selection module

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.