Interfaces

phenomxpy can be used directly (see Installation) or through higher-level interface layers documented below.

See Using waveform interfaces for runnable notebook examples.

gwtemplate plugin

The supported external interface is phenomxpy.plugins.gwtemplate_plugin. It provides generator classes compatible with gwtemplate: PyIMRPhenomT, PyIMRPhenomTHM, PyIMRPhenomTP, PyIMRPhenomTPHM, and PyIMRPhenomTFamily.

Use this path for LISA / DDPC workflows and for GeneratePolarizations(..., interface="gwtemplate") in phenomxpy.common.

Generator classes for the gwtemplate waveform interface.

This is the supported external interface for phenomxpy.

class phenomxpy.plugins.gwtemplate_plugin.MassTime(value: object, total_mass: float)[source]

Bases: object

Time samples in mass units, with seconds available via total_mass.

property seconds: Same times in seconds (no astropy wrapper).

to(unit)[source]

total_mass: float

property unit

value: object

class phenomxpy.plugins.gwtemplate_plugin.PyIMRPhenomT(*args: Any, **kwargs: Any)[source]

Bases: CompactBinaryCoalescenceGenerator

Generator classes for the gwtemplate waveform interface.

property duration

Duration of the currently initialized waveform model.

The approximate end of the waveform is 500M after the peak of the 22 amplitude.

If the model is initialized with a deltaT, the duration includes the last sample.

If the model is initialized without deltaT, the duration still reports 500M after merger, although it can be evaluated beyond that time.

Returns:: Duration of the currently initialized waveform model. .seconds attribute returns the duration in seconds. .value attribute returns the duration in mass units.
Return type:: MassTime

property epoch

Start time of the currently initialized waveform model.

The epoch is the time of the peak of the 22 amplitude.

Returns:: Start time of the currently initialized waveform model. .seconds attribute returns the start time in seconds. .value attribute returns the start time in mass units.
Return type:: MassTime

generate_frequency_domain_polarizations()[source]

generate_time_domain_polarizations(**kwargs)[source]

initialize_model(**parameters)[source]

Initialize the waveform model with the given parameters.

Parameters:

times (xp.ndarray) – Time array in seconds. Only used here to check for consistent input parameters.
**parameters (dict) – Parameters for the waveform model.

Returns:

True if the model is initialized successfully.

Return type:

bool

property metadata

uniform_time_array(deltaT)[source]

Uniform time array of the currently initialized waveform model in seconds.

The time array is generated on demand, not stored.

Parameters:: deltaT (astropy Quantity) – Time spacing in astropy units.
Returns:: Uniform time array. .seconds attribute returns the time array in seconds. .value attribute returns the time array in mass units.
Return type:: MassTime

class phenomxpy.plugins.gwtemplate_plugin.PyIMRPhenomTHM(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTHM model.

class phenomxpy.plugins.gwtemplate_plugin.PyIMRPhenomTP(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTP model.

class phenomxpy.plugins.gwtemplate_plugin.PyIMRPhenomTPHM(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTPHM model.

gwsignal plugin (requires modified LALSuite)

phenomxpy.plugins.gwsignal_plugin defines the same generator API for lalsimulation.gwsignal, but upstream LALSuite does not yet register external Python generators. Using phenomxpy through gwsignal therefore requires a modified LALSuite build with plugin support enabled.

Until that is available in a standard release, prefer the gwtemplate plugin above.

The API is documented here for reference and for use with modified LALSuite.

Generator classes for a future gwsignal plugin interface.

Upstream LALSuite does not yet register external Python generators; a modified LALSuite build is required to use this module through lalsimulation.gwsignal.

class phenomxpy.plugins.gwsignal_plugin.PyIMRPhenomT(*args: Any, **kwargs: Any)[source]

Bases: CompactBinaryCoalescenceGenerator

Generator class for a future gwsignal plugin interface.

This is the parent class from which all the other IMRPhenomT* models subclass.

Example usage:

from lalsimulation import gwsignal as gws

gen = PyIMRPhenomT()
hp, hc = gws.core.waveform.GenerateTDWaveform(params, gen)

property duration

Duration of the currently initialized waveform model in seconds.

The approximate end of the waveform is 500M after the peak of the 22 amplitude.

If the model is initialized with a deltaT, the duration includes the last sample.

If the model is initialized without deltaT, the duration still reports 500M after merger but it can be evaluated beyond that time.

property epoch

Start time of the currently initialized waveform model in seconds.

The epoch is the time of the peak of the 22 amplitude.

generate_fd_waveform(**parameters)[source]

generate_td_waveform(**parameters)[source]

initialize_model(times=None, **parameters)[source]

Initialize the waveform model with the given parameters.

Parameters:

times (xp.ndarray) – Time array in seconds. Only used here to check for consistent input parameters.
**parameters (dict) – Parameters for the waveform model.

Returns:

True if the model is initialized successfully.

Return type:

bool

property metadata

uniform_time_array(delta_t_sec)[source]

Uniform time array of the currently initialized waveform model in seconds.

The time array is generated on demand, not stored.

Parameters:: delta_t_sec (float) – Time spacing in seconds.
Returns:: Uniform time array in seconds.
Return type:: numpy.ndarray

class phenomxpy.plugins.gwsignal_plugin.PyIMRPhenomTHM(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTHM model.

class phenomxpy.plugins.gwsignal_plugin.PyIMRPhenomTP(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTP model.

class phenomxpy.plugins.gwsignal_plugin.PyIMRPhenomTPHM(*args: Any, **kwargs: Any)[source]

Bases: PyIMRPhenomT

gwsignal generator wrapper for the IMRPhenomTPHM model.

Common interface utilities

phenomxpy.common is not a plugin module. It provides shared helpers used by the plugins and by other callers:

GeneratePolarizations() — unified entry point for interface="c", "gwsignal", "gwtemplate", or "phenomxpy"
convert_params_from_astropy() — parameter conversion from gwsignal-style dicts
bilby_frequency_phenomxpy() and bilby_time_phenomxpy() — Bilby waveform hooks

Utility functions to interface with external softwares

phenomxpy.common.GeneratePolarizations(parameters={}, approximant='IMRPhenomT', domain='TD', return_generator=False, chunk_options={})[source]

Wrapper function to generate hp, hc in time or frequency domain from different interfaces:

LALSuite C interface: use swiglal python wrappers

LALSuite gwsignal interface: the lalsuite python interface. Can call phenomxpy, FIXME pyseobnr

phenomxpy: use phenomxpy directly.

Parameters:

parameters (astropy dict) – Waveform parameters with astropy units and extra options
approximant (str) – Approximant name
domain ({"TD", "FD"}) – Polarizations in time or frequency domain. Will perform an FFT if using a time domain approximant.
return_generator (bool) – Return the class object for the python generator.

Returns:

Tuple with 2 gwpy Time(Frequency)Series. – hp, hc: polarizations in time or frequency domain.
Optionally also return the python generator object.

phenomxpy.common.bilby_frequency_phenomxpy(frequency_array, mass_1, mass_2, luminosity_distance, a_1, a_2, tilt_1, tilt_2, phi_12, phi_jl, theta_jn, phase, eccentricity=0.0, mean_anomaly=0.0, **kwargs)[source]

frequency_domain_model for bilby waveform generator. Same interface as bilby.gw.source.lal_binary_black_hole.

Parameters:

frequency_array (array_like) – The frequencies at which we want to calculate the strain
mass_1 (float) – The mass of the heavier object in solar masses
mass_2 (float) – The mass of the lighter object in solar masses
luminosity_distance (float) – The luminosity distance in megaparsec
a_1 (float) – Dimensionless primary spin magnitude
tilt_1 (float) – Primary tilt angle
phi_12 (float) – Azimuthal angle between the two component spins
a_2 (float) – Dimensionless secondary spin magnitude
tilt_2 (float) – Secondary tilt angle
phi_jl (float) – Azimuthal angle between the total binary angular momentum and the orbital angular momentum
theta_jn (float) – Angle between the total binary angular momentum and the line of sight
phase (float) – The phase at reference frequency or peak amplitude (depends on waveform)
kwargs (dict) – Include parameters like reference_frequency, minimum_frequency and waveform_approximant and any extra option accepted by phenomxpy.

Returns:

{“plus”: hplus, “cross”: hcross} the two polarizations in Fourier domain in an equispaced frequency grid.

Return type:

dictionary

phenomxpy.common.bilby_time_phenomxpy(parameters, **waveform_kwargs)[source]

time_domain_model for bilby waveform generator.

Parameters:

parameters (dict) – Bilby parameter dictionary (masses, spins, inclination, etc.).
waveform_kwargs (dict) – Extra waveform options passed to the bilby waveform generator, including waveform_approximant and any phenomxpy-specific options.

Returns:

(hp, hc, times, cparams) where hp and hc are the time-domain polarizations, times is the time array, and cparams is the conditioning-parameter dictionary from the underlying approximant.

Return type:

tuple

phenomxpy.common.convert_params_from_astropy(input_params)[source]

Convert gwsignal (astropy dictionary) to phenomxpy.

Parameters are transformed to the units in the default_dict of gwsignal.

Units are removed.

Parameters:: input_params (gwsiganl dictionary) – parameters with astropy units.
Returns:: Parameters in phenomxpy format without units.
Return type:: dict

phenomxpy.common.strip_units(waveform_dict)[source]: Remove units from astropy dictionary.