Current Version: 1.0.4
+Current Version: 1.0.5
diff --git a/docs/html/user/main.html b/docs/html/user/main.html index 2a4ae87..2bea1fb 100644 --- a/docs/html/user/main.html +++ b/docs/html/user/main.html @@ -47,7 +47,26 @@ +Bases: object
Generate waveforms put through response functions
+This class generates waveforms put through the LISA response function. In the +future, ground-based analysis may be added. Therefore, it currently +returns the TDI variables according the response keyword arguments given.
+If you use this class, please cite arXiv:2005.01827 +and arXiv:2111.01064, as well as the papers +listed for the waveform and response given just below.
+Right now, it is hard coded to produce the waveform with
+PhenomHMAmpPhase. This can also be used
+to produce PhenomD. See the docs for that waveform. The papers describing PhenomHM/PhenomD
+waveforms are here: arXiv:1708.00404,
+arXiv:1508.07250, and
+arXiv:1508.07253.
The response function is the fast frequency domain response function
+from arXiv:1806.10734 and
+arXiv:2003.00357. It is implemented in
+LISATDIResponse <bbhx.response.fastfdresponse.LISATDIResponse.
This class is GPU accelerated.
+amp_phase_kwargs (dict, optional) – Keyword arguments for the
+initialization of the ampltidue-phase waveform class: PhenomHMAmpPhase.
response_kwargs (dict, optional) – Keyword arguments for the initialization
+of the response class: LISATDIResponse <bbhx.response.fastfdresponse.LISATDIResponse.
interp_kwargs (dict, optional) – Keyword arguments for the initialization
+of the interpolation class: TemplateInterpFD.
use_gpu (bool, optional) – If True, use a GPU. (Default: False)
Waveform generation class.
+obj
+Length of the final output data.
+int
+Interpolation class.
+obj
+Length of initial evaluations of waveform and response.
+int
+Total number of binaries analyzed.
+int
+Number of parameters to interpolate (9).
+int
+Number of harmonic modes.
+int
+Array with buffer information with shape:
+(self.num_interp_params, self.num_bin_all, self.num_modes, self.length).
+The order of the parameters is amplitude, phase, t-f, transferL1re, transferL1im,
+transferL2re, transferL2im, transferL3re, transferL3im.
xp.ndarray
+Response generation class.
+obj
+A GPU is being used if use_gpu==True.
bool
+Direct summation waveform generation class.
+obj
+Either numpy or cupy.
obj
+Citations for this class
+Generate the binary black hole frequency-domain TDI waveforms
+m1 (double scalar or np.ndarray) – Mass 1 in Solar Masses \((m1 > m2)\).
m2 (double or np.ndarray) – Mass 2 in Solar Masses \((m1 > m2)\).
chi1z (double or np.ndarray) – Dimensionless spin 1 (for Mass 1) in Solar Masses.
chi2z (double or np.ndarray) – Dimensionless spin 2 (for Mass 1) in Solar Masses.
distance (double or np.ndarray) – Luminosity distance in m.
phi_ref (double or np.ndarray) – Phase at f_ref.
f_ref (double or np.ndarray) – Reference frequency at which phi_ref and t_ref are set.
+If f_ref == 0, it will be set internally by the PhenomHM code
+to \(f_\text{max} = \text{max}(f^2A_{22}(f))\).
inc (double or np.ndarray) – Inclination of the binary in radians \((\iota\in[0.0, \pi])\).
lam (double or np.ndarray) – Ecliptic longitude \((\lambda\in[0.0, 2\pi])\).
beta (double or np.ndarray) – Ecliptic latitude \((\beta\in[-\pi/2, \pi/2])\).
psi (double or np.ndarray) – Polarization angle in radians \((\psi\in[0.0, \pi])\).
t_ref (double or np.ndarray) – Reference time in seconds. It is set at f_ref.
t_obs_start (double, optional) – Start time of observation in years
+in the LISA constellation reference frame. If shift_t_limits==True,
+this is with reference to \(t=0\). If shift_t_limits==False this is
+with reference to t_ref and works backwards. So, in this case,
+t_obs_start gives how much time back from merger to start the waveform.
+(Default: 1.0)
t_obs_end (double, optional) – End time of observation in years in the
+LISA constellation reference frame. If
+shift_t_limits==True, this is with reference to \(t=0\).
+If shift_t_limits==False this is with reference to t_ref
+and works backwards. So, in this case, t_obs_end gives how much time
+back from merger to start the waveform. If the value is zero, it takes
+everything after the merger as well. (Default: 0.0)
freqs (np.ndarray, optional) – Frequencies at which to evaluate the final waveform.
+If length is also given, the interpolants interpolate to these
+frequencies. If length is not given, the waveform amplitude, phase,
+and response will be directly evaluated at these frequencies. In this case,
+a 2D np.ndarray can also be provided. (Default: None)
length (int, optional) – Number of frequencies to use in sparse array for +interpolation.
modes (list, optional) – Harmonic modes to use. If not given, they will
+default to those available in the waveform model. For PhenomHM:
+[(2,2), (3,3), (4,4), (2,1), (3,2), (4,3)]. For PhenomD: [(2,2)].
+(Default: None)
shift_t_limits (bool, optional) – If False, t_obs_start and t_obs_end
+are relative to t_ref counting backwards in time. If True,
+those quantities are relative to \(t=0\). (Default: False)
direct (bool, optional) – If True, directly compute the waveform without
+interpolation. (Default: False)
compress (bool, optional) – If True, combine harmonics into single channel
+waveforms. (Default: True)
squeeze (bool, optional) – If True, remove any axes of length 1 from the
+final return information. (Default: False)
fill (bool, optional) – If True, fill data streams according to the combine
+keyword argument. If ``False, returns information for the fast likelihood functions.
combine (bool, optional) – If True, combine all waveforms into the same output
+data stream. (Default: False)
(3, self.length, self.num_bin_all).Final waveform for each binary. If direct==True and compress==True.
+# TODO: switch dimensions?
(3, self.num_modes, self.length, self.num_bin_all).Final waveform for each binary. If direct==True and compress==False.
(3, self.data_length).Final waveform of all binaries in the same data stream.
+If fill==True and combine==True.
(self.num_bin_all, 3, self.data_length).Final waveform of all binaries in the same data stream.
+If fill==True and combine==False.
First entry is template_channels property from TemplateInterpFD.
+Second entry is start_inds attribute from self.interp_response.
+Third entry is lengths attribute from self.interp_response.
xp.ndarray
+ValueError – length and freqs not given. Modes are given but not in a list.
LISATDIResponseLISATDIResponse.allowable_modesLISATDIResponse.ells_defaultLISATDIResponse.mms_defaultLISATDIResponse.includes_ampsLISATDIResponse.order_fresnel_stencilLISATDIResponse.response_genLISATDIResponse.TDItagLISATDIResponse.use_gpuLISATDIResponse.xpLISATDIResponse.citationLISATDIResponse.transferL1LISATDIResponse.transferL2LISATDIResponse.transferL3LISATDIResponse.phaseLISATDIResponse.tfLISATDIResponse.__call__()Bases: object
Evaluate the fast frequency domain response function
+The response function is the fast frequency domain response function +from arXiv:1806.10734 and +arXiv:2003.00357. Please cite +these papers if this class is used. This response assumes a fixed, +non-breathing armlength for the LISA constellation.
+This class has GPU capability.
+TDItag (str, optional) – TDI channels to generate. Options are "XYZ" and
+"AET". If "XYZ" is not given, it will default to "AET".
+(Default: "AET")
order_fresnel_stencil (int, optional) – Order of the Fresnel stencil in the
+response. Currently, anything above 0 is not implemented. This is left
+in for future compatibility. (Default: 0)
use_gpu (bool, optional) – If True, use a GPU. (Default: False)
Allowed list of mode tuple pairs (l,m) for
+the chosen waveform model.
list
+Default values for the l index of the harmonic.
np.ndarray
+Default values for the m index of the harmonic.
np.ndarray
+If True, the out_buffer contains the first
+entry for amplitudes.
bool
+Order of the Fresnel stencil in the +response. Currently, anything above 0 is not implemented. This is left +in for future compatibility.
+int
+Respones generator in C/C++.
+obj
+TDI channels to generate. Either "XYZ" or "AET".
str
+A GPU is being used if use_gpu==True.
bool
+Either numpy or cupy.
obj
+Return citations for this class
+(num_bin_all, num_modes, length)
TransferL1 term in response. Shape
+(num_bin_all, num_modes, length)
TransferL2 term in response. Shape
+(num_bin_all, num_modes, length)
TransferL3 term in response. Shape
+(num_bin_all, num_modes, length)
Get updated phase info. Shape
+(num_bin_all, num_modes, length)
Get tf info. Shape
+Evaluate respones function
+freqs (1D or 2D xp.ndarray) – Frequency at which the response is evaluated.
+2D shape is (num_bin_all, length). If given as a 1D array,
+it should be of length num_bin_all * length.
inc (scalar or 1D xp.ndarray) – Inclination of BBH system in radians.
lam (scalar or 1D xp.ndarray) – Ecliptic longitude in SSB frame in radians.
beta (scalar or 1D xp.ndarray) – Ecliptic latitude in SSB frame in radians.
psi (scalar or 1D xp.ndarray) – Polarization angle of the system in radians.
phi_ref (scalar or 1D xp.ndarray) – Reference phase. Note:
+The response function rotates the source by phi_ref. For this reason,
+the main waveform functions (e.g. bbhx.waveform.BBHWaveformFD)
+provide phi_ref = 0.0 into the source-frame scaled waveform generators
+(e.g. bbhx.waveforms.phenomhm.PhenomHMAmpPhase). This allows
+the reference phase to be applied here in the response.
length (int) – The length of the individual frequency arrays. This is required +because of the options for putting in 1D arrays into this function. +The length tells the chunk size in a 1D array.
modes (list, optional) – Harmonic modes to use. If not given, they will
+default to those available in the waveform model PhenomHM:
+[(2,2), (3,3), (4,4), (2,1), (3,2), (4,3)]. (Default: None)
phase (xp.ndarray, optional) – Waveform phase. This is adjusted by the phaseRdelay
+quantity in the code. If more than 1D, the shape should be
+(num_bin_all, num_modes, length). If 1D, its total length
+should be equivalent to num_bin_all * num_modes * length.
+If out_buffer is not provided, phase and tf are required.
tf (xp.ndarray, optional) – Waveform time-frequency correspondence. This tells the
+response where the LISA constellation is at each frequency.
+If more than 1D, the shape should be
+(num_bin_all, num_modes, length). If 1D, its total length
+should be equivalent to num_bin_all * num_modes * length.
+If out_buffer is not provided, phase and tf are required.
out_buffer (xp.ndarray, optional) – 1D array initialized to contain all computations
+from the inital waveform and response function. If providing out_buffer,
+the response fills it directly. To make this happen easily in GPU/CPU
+agnostic manner, out_buffer needs to be a 1D array with length
+equivalent to nparams * num_bin_all * num_modes * length.
+nparams can be 8 if the buffer does not include the amplitudes
+(which are not needed at all for the response computation) or 9
+if it includes the amplitudes. (Default: None)
adjust_phase (bool, optional) – If True adjust the phase array in-place
+inside the response code. Note: This only applies when
+inputing phase and tf. (Default: True)
ValueError – Incorrect dimensions for the arrays.
+TemplateInterpFDTemplateInterpFD.data_lengthTemplateInterpFD.lengthTemplateInterpFD.num_bin_allTemplateInterpFD.num_channelsTemplateInterpFD.num_modesTemplateInterpFD.template_carrierTemplateInterpFD.template_genTemplateInterpFD.use_gpuTemplateInterpFD.xpTemplateInterpFD.template_channelsTemplateInterpFD.citationTemplateInterpFD.__call__()CubicSplineInterpolant
+mT_q()modpi()Bases: object
Interpolate frequency domain template.
+This class wraps CubicSplineInterpolant so
+that it fits into this specific waveform production method.
This class has GPU capabilities.
+use_gpu (bool, optional) – If True, use GPU.
Length of data. This class interpolates to this length.
+int
+Length of original frequency array.
+int
+Number of binaries.
+int
+Number of channels in data.
+int
+Number of harmonics.
+int
+Carrier for output templates.
+Templates can be accessed through the template_channels property.
complex128 xp.ndarray
+C/CUDA wrapped function for computing interpolated +waveforms.
+obj
+If True, using GPU.
+bool
+Either numpy or cupy.
+obj
+Get template channels from self.template_carrier.
citations for this class
+Generate frequency domain template via interpolation.
+This class takes all waveform and response information as sparse arrays +and then interpolates to the proper frequency array.
+This class acts in a unique why by passing arrays of pointers from python +into C++/CUDA.
+data_freqs (double xp.ndarray) – Frequencies to interpolate to.
interp_container (obj) – container attribute from the interpolant
+class: CubicSplineInterpolant.
t_start (double xp.ndarray) – Array of start times (sec) for each binary.
t_end (double xp.ndarray) – Array of end times (sec) for each binary.
length (int) – Length of original frequency array.
num_modes (int) – Number of harmonics.
num_channels (int) – Number of channels in data.
shape of each array: (self.num_channels, self.data_length)
list
+Bases: object
GPU-accelerated Multiple Cubic Splines
+This class produces multiple cubic splines. The cubic splines are produced +with “not-a-knot” boundary conditions.
+This class has GPU capability.
+x (xp.ndarray) – f values as input for the spline. Can be 1D flattend array
+of total length
+(num_bin_all * length) or 2D array with shape: (num_bin_all, length).
y_all (xp.ndarray) – y values for the spline. This can be a 1D flattened
+array with length
+(num_interp_params * num_bin_all * num_modes * length)
+or 4D arrays of shape: (num_interp_params, num_bin_all, num_modes, length).
num_interp_params (int, optional) – If x and y_all are flattened,
+the user must provide the number of interpolation parameters.
+(Default: None)
num_bin_all (int, optional) – If x and y_all are flattened,
+the user must provide the number of total binaries.
+(Default: None)
num_modes (int, optional) – If x and y_all are flattened,
+the user must provide the number of modes.
+(Default: None)
length (int, optional) – If x and y_all are flattened,
+the user must provide the length of the frequency array for each binary.
+(Default: None)
use_gpu (bool, optional) – If True, prepare arrays for a GPU. Default is +False.
ValueError – If input arguments are not correct.
+Get shaped x array.
+Get shaped y array.
+Get shaped c1 array.
+Get shaped c2 array.
+Get shaped c3 array.
+Container for easy transit of interpolation information.
+PhenomHMAmpPhasePhenomHMAmpPhase.allowable_modesPhenomHMAmpPhase.ells_defaultPhenomHMAmpPhase.mms_defaultPhenomHMAmpPhase.mf_maxPhenomHMAmpPhase.mf_minPhenomHMAmpPhase.phenomhm_ringdown_freqsPhenomHMAmpPhase.phenomd_ringdown_freqsPhenomHMAmpPhase.run_phenomdPhenomHMAmpPhase.use_gpuPhenomHMAmpPhase.waveform_genPhenomHMAmpPhase.xpPhenomHMAmpPhase.y_rdPhenomHMAmpPhase.c1_rdPhenomHMAmpPhase.c2_rdPhenomHMAmpPhase.c3_rdPhenomHMAmpPhase.y_dmPhenomHMAmpPhase.c1_dmPhenomHMAmpPhase.c2_dmPhenomHMAmpPhase.c3_dmPhenomHMAmpPhase.waveform_carrierPhenomHMAmpPhase.citationPhenomHMAmpPhase.ampPhenomHMAmpPhase.phasePhenomHMAmpPhase.tfPhenomHMAmpPhase.freqs_shapedPhenomHMAmpPhase.freqsPhenomHMAmpPhase.__call__()Bases: object
Produce PhenomHM in the amplitude and phase representation
+This class implements PhenomD and PhenomHM in a GPU-accelerated form. +If you use this class, please cite +arXiv:2005.01827, +arXiv:2111.01064 +arXiv:1708.00404, +arXiv:1508.07250, and +`arXiv:1508.07253 <https://arxiv.org/abs/1508.07253>_.
+use_gpu (bool, optional) – If True, run on the GPU.
run_phenomd (bool, optional) – If True, run the PhenomD
+waveform rather than PhenomHM. Really this is the same
+as choosing modes=[(2,2)] in the PhenomHM waveform.
mf_min (double, optional) – Dimensionless minimum frequency to use when performing
+interpolation. (Default: 1e-4)
mf_max (double, optional) – Dimensionless maximum frequency to use when performing
+interpolation. (Default: 6e-1)
initial_t_val (double, optional) – Time at the start of the
+time window. This shifts the phase accordingly but does
+not shift the tf correspondence so that the response
+is still accurately reflected. (Default: 0.0)
Allowed list of mode tuple pairs (l,m) for
+the chosen waveform model.
list
+Default values for the l index of the harmonic.
np.ndarray
+Default values for the m index of the harmonic.
np.ndarray
+Dimensionless maximum frequency to use when performing +interpolation.
+double
+Dimensionless minimum frequency to use when performing +interpolation.
+double
+Ringdown frequency determination in PhenomHM.
+obj
+Ringdown frequency determination in PhenomD.
+obj
+If True, run the PhenomD
+waveform rather than PhenomHM. Really this is the same
+as choosing modes=[(2,2)] in the PhenomHM waveform.
bool
+If True, run on the GPU.
bool
+Amplitude, phase, tf determination.
+obj
+numpy or cupy
+obj
+Y-values for PhenomD ringdown frequncy for Cubic Spline.
+xp.ndarray
+Cubic Spline c1 values for PhenomD ringdown frequency.
+xp.ndarray
+Cubic Spline c2 values for PhenomD ringdown frequency.
+xp.ndarray
+Cubic Spline c3 values for PhenomD ringdown frequency.
+xp.ndarray
+Y-values for PhenomD damping frequncy for Cubic Spline.
+xp.ndarray
+Cubic Spline c1 values for PhenomD damping frequency.
+xp.ndarray
+Cubic Spline c2 values for PhenomD damping frequency.
+xp.ndarray
+Cubic Spline c3 values for PhenomD damping frequency.
+xp.ndarray
+Carrier for amplitude, phase, and tf information.
+xp.ndarray
+Return citations for this class
+Get the amplitude array with shape (num_bin_all, num_modes, length)
Get the phase array with shape (num_bin_all, num_modes, length)
Get the tf array with shape (num_bin_all, num_modes, length)
Get the freqs array with shape (num_bin_all, length)
Get the flat freqs array
+Generate PhenomHM/D waveforms
+Generate PhenomHM/PhenomD waveforms based on user given quantitites +in the Amplitude-Phase representation.
+m1 (double scalar or np.ndarray) – Mass 1 in Solar Masses \((m1 > m2)\).
m2 (double or np.ndarray) – Mass 2 in Solar Masses \((m1 > m2)\).
chi1z (double or np.ndarray) – Dimensionless spin 1 (for Mass 1) in Solar Masses.
chi2z (double or np.ndarray) – Dimensionless spin 2 (for Mass 1) in Solar Masses.
distance (double or np.ndarray) – Luminosity distance in m.
phi_ref (double or np.ndarray) – Phase at f_ref.
f_ref (double or np.ndarray) – Reference frequency at which phi_ref and t_ref are set.
+If f_ref == 0, it will be set internally by the PhenomHM code
+to \(f_\text{max} = \text{max}(f^2A_{22}(f))\).
t_ref (double or np.ndarray) – Reference time in seconds. It is set at f_ref.
length (int) – Length of the frequency array over which the waveform is created.
freqs (1D or 2D xp.ndarray, optional) – If None, the class will generate the
+frequency array over which the waveform is evaluated. If 1D xp.ndarray,
+this array will be copied for all binaries evaluated. If 2D,
+it must have shape (num_bin_all, length). (Default: None)
out_buffer (xp.ndarray, optional) – If None, a buffer array will be created.
+If provided, it should be flattened from shape
+(nparams, length, num_modes, num_bin_all). nparams can
+be 3 if just evaluating PhenomHM/D. If using the same buffer for
+the response it must be 9. (Default: None)
modes (list, optional) – Harmonic modes to use. If not given, they will
+default to those available in the waveform model. For PhenomHM:
+[(2,2), (3,3), (4,4), (2,1), (3,2), (4,3)]. For PhenomD: [(2,2)].
+(Default: None)