API for the jaxqualin.fit module

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.