Calibration Marginalization API Reference

This module provides tools for performing calibration marginalization in RIFT, allowing for the estimation of parameters while accounting for uncertainty in the calibration.

RIFT.calmarg.generate_realizations.build_realizations_from_nodes(amp_rand_array, phase_rand_array, T_segment, dT, fmin, fmax, log_freq_spline_locations)

Build the complex two-sided per-realization calibration factor array from spline-node values. Factored out of create_realizations() so the SAME spline construction is reused both for prior draws and for proposal-seeded draws (seed_realizations_from_breadcrumb).

amp_rand_array, phase_rand_array : (n_spline_points, n_realizations). Returns dat_out (npts_seg, n_realizations) complex, unity outside [fmin,fmax].

Phase sign: the RIFT packing labels bins with the negative of the LAL frequency, so dat_out at label f is conj(alpha(f)) for the standard-convention response alpha = amp*exp(i*phase). Apply it to the data UNCONJUGATED: <h|C d> = <alpha h|d>. See DESIGN_calmarg_in_loop.md, “Phase-sign trap”.

RIFT.calmarg.generate_realizations.create_realizations(fname, T_segment, dT, fmin, fmax, n_spline_points, n_realizations, correction_type='template')

RIFT.calmarg.generate_realizations.draw_prior_realizations_with_nodes(env_dir, dets, T_segment, dT, fmin, fmax, n_spline_points, n_realizations, fmin_ifo=None, rng=None, correction_types=None)

Draw PRIOR calibration realizations AND keep the spline-node draws.

Same prior as create_realizations(), but it returns the node vectors (which create_realizations discards) so a pilot can fit a proposal over them. Used by the ILE –calibration-dump-responsibilities path.

env_dir : directory of per-detector envelope files <ifo>.txt. dets : detector order; the returned node vector is concatenated per det as

[det0_amp, det0_phase, det1_amp, det1_phase, …] (breadcrumb layout).

Returns dict with:

realizations : {ifo: (npts_seg, n_realizations) complex} nodes : (n_realizations, 2*n_spline_points*len(dets)) prior draws prior_mean : (dim,) diagonal-Gaussian prior mean over the full node vector prior_sigma : (dim,) prior sigma node_log_f : (n_spline_points,) log10 spline node frequencies (det 0) n_nodes_amp : n_spline_points dets : list

RIFT.calmarg.generate_realizations.node_prior(fname, fmin, fmax, n_spline_points, correction_type='template')

Return the calibration PRIOR over spline nodes for one detector, as the diagonal Gaussian implied by the envelope file.

The per-detector node vector is laid out as

[amp_0 .. amp_{N-1}, phase_0 .. phase_{N-1}] (N = n_spline_points)

with amp node i ~ N(median_amp_i, sigma_amp_i) and phase node i ~ N(median_phase_i, sigma_phase_i), independent (this is exactly the prior that create_realizations() draws from).

Returns dict(mean, sigma, node_log_f, n_nodes_amp) – mean/sigma length 2N.

correction_type defaults to “template”. LVK H1/L1/K1 envelopes are “data”; resolve per detector with calibration.correction_type_for_ifo, as ILE does.

RIFT.calmarg.generate_realizations.nodes_to_spline_coefficients_matrix(n_points)

RIFT.calmarg.generate_realizations.prior_cal_breadcrumb_dict(env_dir, dets, fmin, fmax, n_spline_points, fmin_ifo=None, correction_types=None)

Build the ‘cal’ breadcrumb dict for the broad PRIOR, with proposal == prior.

Suitable as an iteration-0 placeholder breadcrumb: seeding from it (seed_realizations_from_breadcrumb) draws cal realizations from the prior with ZERO importance weights (log prior - log proposal = 0), i.e. it is equivalent to the cold prior draws – but, unlike a 0-byte placeholder, it LOADS cleanly (so an older ILE binary that does not guard against an empty placeholder will not crash on it).

Layout matches seed_realizations_from_breadcrumb: the full node vector is concatenated per detector in dets order as [det0_amp_0..,det0_phase_0..,det1_amp..,…]; dim = 2N*len(dets).

RIFT.calmarg.generate_realizations.retrieve_envelope_from_file(fname, frequency_array=None, correction_type='template', **kwargs)

Read template-response amplitude/phase means and widths from an LVK envelope.

data envelopes describe eta*d; template envelopes describe alpha*h. Convert envelope summaries before drawing Gaussian template-response nodes, following Bilby’s CalibrationPriorDict.from_envelope_file. This is a Gaussian approximation in template-node space, not inversion of individual random draws. Low-level callers supplying template envelopes retain the historical default.

RIFT.calmarg.generate_realizations.seed_realizations_from_breadcrumb(bc, T_segment, dT, fmin, fmax, n_spline_points, n_realizations, fmin_ifo=None, rng=None, prior=None)

Draw n_realizations calibration factors per detector from a LEARNED Gaussian proposal (a breadcrumb), and return the Phase-0 importance weights.

This is the production seed path (Option C): instead of drawing cal nodes from the broad prior, draw them from the consolidated pilot proposal (concentrated on the high-likelihood cal region), and carry log_w = log prior - log proposal so the marginalization stays unbiased.

bcbreadcrumb dict (breadcrumbs.load(…)) OR its [“cal”] sub-dict. The proposal

is a joint Gaussian over the FULL multi-detector node vector, concatenated over bc[“dets”] in order: [det0_amp, det0_phase, det1_amp, det1_phase, …].

fmin : scalar template fmin (used for all dets) OR ignored per-det if fmin_ifo given. fmin_ifo : optional {ifo: fmin} for per-detector low-frequency cutoffs. rng : numpy Generator (default: a fresh default_rng()).

Returns (dat_out_dict, cal_log_weights, nodes):

dat_out_dict : {ifo: (npts_seg, n_realizations) complex} cal_log_weights: (n_realizations,) = log prior - log proposal (shared across dets,

since it is ONE joint draw per realization).

nodes(n_realizations, dim) the proposal-drawn node vectors (so a pilot

can refit a proposal from a seeded run).

Source functions to match how RIFT generates waveforms

RIFT.calmarg.rift_source.RIFT_lal_binary_black_hole(frequency_array, mass_1, mass_2, luminosity_distance, spin_1x, spin_1y, spin_1z, spin_2x, spin_2y, spin_2z, iota, phase, *, lambda_1=0.0, lambda_2=0.0, **kwargs)

RIFT.calmarg.rift_source.RIFT_lal_binary_black_hole_orig(frequency_array, mass_1, mass_2, luminosity_distance, spin_1x, spin_1y, spin_1z, spin_2x, spin_2y, spin_2z, lambda_1, lambda_2, iota, phase, **kwargs)

RIFT.calmarg.rift_source.RIFT_lal_eccentric_binary_black_hole(frequency_array, mass_1, mass_2, luminosity_distance, spin_1x, spin_1y, spin_1z, spin_2x, spin_2y, spin_2z, iota, phase, eccentricity, mean_per_ano, *, lambda_1=0.0, lambda_2=0.0, **kwargs)

RIFT.calmarg.rift_source.RIFT_lal_eccentric_tidal_binary(frequency_array, mass_1, mass_2, luminosity_distance, spin_1x, spin_1y, spin_1z, spin_2x, spin_2y, spin_2z, iota, phase, eccentricity, mean_per_ano, lambda_1, lambda_2, **kwargs)

Expose eccentricity, mean anomaly and both component tides to Bilby.

RIFT.calmarg.rift_source.RIFT_lal_tidal_binary(frequency_array, mass_1, mass_2, luminosity_distance, spin_1x, spin_1y, spin_1z, spin_2x, spin_2y, spin_2z, iota, phase, lambda_1, lambda_2, **kwargs)

Expose both component tides to Bilby’s positional-parameter discovery.