Skip to content

Ripplegw

Functions:

Name Description
get_waveform_metadata

Return a copy of the descriptive metadata for a registered waveform.
list_waveforms

List registered waveform names, optionally filtered by metadata.
register

Class decorator that adds a Waveform subclass to the registry.
waveform

Construct a registered waveform by name.

Attributes:

Name Type Description
WAVEFORM_REGISTRY dict[str, type[Waveform]]

Global name -> Waveform subclass registry, populated at import by

WAVEFORM_REGISTRY: dict[str, type[Waveform]] = {} module-attribute ¤

Global name -> Waveform subclass registry, populated at import by register.

AmplitudePhaseWaveform ¤

Bases: FrequencyDomainWaveform

A frequency-domain model that reports amplitude and phase separately.

amplitude(f, params) * exp(1j * phase(f, params)) reproduces the pre-polarization strain h0 this model builds internally — see strain. __call__ then applies the inclination-dependent plus/cross prefactors on top of h0, so amplitude/phase never need to know about polarization.

Methods:

Name Description
__call__

Evaluate the waveform.
amplitude

Amplitude of h0, as a function of frequency. Includes distance scaling.
phase

Phase of h0, as a function of frequency (the exponent in exp(1j * phase)).
strain

Pre-polarization strain: amplitude(f, params) * exp(1j * phase(f, params)).

Attributes:

Name Type Description
parameter_names tuple[str, ...]

Parameter names required by this model, in the order __call__ expects them.

parameter_names: tuple[str, ...] abstractmethod property ¤

Parameter names required by this model, in the order __call__ expects them.

__call__(axis: Float[Array, ' n'], /, params: Mapping[str, FloatLike]) -> StrainDict abstractmethod ¤

Evaluate the waveform.

Parameters:

Name Type Description Default
axis Float[Array, ' n']

Evaluation grid (a frequency or time array).

 required
params Mapping[str, FloatLike]

Source parameters, keyed by name.

 required

Returns:

Type Description
StrainDict

A dict keyed by polarization/component, e.g. {"p": ..., "c": ...}.

amplitude(frequency: Float[Array, ' n_freq'], params: Mapping[str, FloatLike]) -> Float[Array, ' n_freq'] abstractmethod ¤

Amplitude of h0, as a function of frequency. Includes distance scaling.

phase(frequency: Float[Array, ' n_freq'], params: Mapping[str, FloatLike]) -> Float[Array, ' n_freq'] abstractmethod ¤

Phase of h0, as a function of frequency (the exponent in exp(1j * phase)).

strain(frequency: Float[Array, ' n_freq'], params: Mapping[str, FloatLike]) -> Complex[Array, ' n_freq'] ¤

Pre-polarization strain: amplitude(f, params) * exp(1j * phase(f, params)).

Computed as amp * cos(phase) + 1j * (amp * sin(phase)), not via jnp.exp(1j * phase) -- XLA's complex-exponential lowering costs roughly 2x the transcendental ops of the equivalent explicit cos/sin split (measured), and this identity is exact for real phase.

DistanceScaledWaveform ¤

Bases: Waveform

Mixin for waveforms whose params includes a distance d_L.

at_unit_distance(axis, params) == __call__(axis, {**params, "d_L": 1.0}) exactly, by construction. __call__(axis, params) == at_unit_distance(axis, params) / params["d_L"] holds only to floating-point precision, since this re-evaluates the model rather than factoring distance out of a cached result.

Methods:

Name Description
__call__

Evaluate the waveform.
at_unit_distance

Evaluate at d_L = 1 Mpc; any d_L already in params is ignored.

Attributes:

Name Type Description
parameter_names tuple[str, ...]

Parameter names required by this model, in the order __call__ expects them.

parameter_names: tuple[str, ...] abstractmethod property ¤

Parameter names required by this model, in the order __call__ expects them.

__call__(axis: Float[Array, ' n'], /, params: Mapping[str, FloatLike]) -> StrainDict abstractmethod ¤

Evaluate the waveform.

Parameters:

Name Type Description Default
axis Float[Array, ' n']

Evaluation grid (a frequency or time array).

 required
params Mapping[str, FloatLike]

Source parameters, keyed by name.

 required

Returns:

Type Description
StrainDict

A dict keyed by polarization/component, e.g. {"p": ..., "c": ...}.

at_unit_distance(axis: Float[Array, ' n'], params: Mapping[str, FloatLike]) -> StrainDict ¤

Evaluate at d_L = 1 Mpc; any d_L already in params is ignored.

FrequencyDomainWaveform ¤

Bases: Waveform

A Waveform whose axis is a frequency array.

Methods:

Name Description
__call__

Evaluate the waveform.

Attributes:

Name Type Description
parameter_names tuple[str, ...]

Parameter names required by this model, in the order __call__ expects them.

parameter_names: tuple[str, ...] abstractmethod property ¤

Parameter names required by this model, in the order __call__ expects them.

__call__(axis: Float[Array, ' n'], /, params: Mapping[str, FloatLike]) -> StrainDict abstractmethod ¤

Evaluate the waveform.

Parameters:

Name Type Description Default
axis Float[Array, ' n']

Evaluation grid (a frequency or time array).

 required
params Mapping[str, FloatLike]

Source parameters, keyed by name.

 required

Returns:

Type Description
StrainDict

A dict keyed by polarization/component, e.g. {"p": ..., "c": ...}.

TimeDomainWaveform ¤

Bases: Waveform

A Waveform whose axis is a time array.

Methods:

Name Description
__call__

Evaluate the waveform.

Attributes:

Name Type Description
parameter_names tuple[str, ...]

Parameter names required by this model, in the order __call__ expects them.

parameter_names: tuple[str, ...] abstractmethod property ¤

Parameter names required by this model, in the order __call__ expects them.

__call__(axis: Float[Array, ' n'], /, params: Mapping[str, FloatLike]) -> StrainDict abstractmethod ¤

Evaluate the waveform.

Parameters:

Name Type Description Default
axis Float[Array, ' n']

Evaluation grid (a frequency or time array).

 required
params Mapping[str, FloatLike]

Source parameters, keyed by name.

 required

Returns:

Type Description
StrainDict

A dict keyed by polarization/component, e.g. {"p": ..., "c": ...}.

Waveform ¤

Bases: ABC

Base class for all waveform models.

A model is configured once at construction (reference frequency, and so on) and then called as wf(axis, params): axis is the evaluation grid, params maps parameter names to values, and the result is a dict keyed by polarization, e.g. {"p": ..., "c": ...}.

Subclass FrequencyDomainWaveform or TimeDomainWaveform rather than this class directly, and decorate the model with @register so users can reach it via ripplegw.waveform("YourModel").

Attributes:

Name Type Description
waveform_metadata dict[str, Any]

Descriptive metadata set by @register (e.g. is_tidal); read by ripplegw.list_waveforms and ripplegw.get_waveform_metadata.

Methods:

Name Description
__call__

Evaluate the waveform.

parameter_names: tuple[str, ...] abstractmethod property ¤

Parameter names required by this model, in the order __call__ expects them.

__call__(axis: Float[Array, ' n'], /, params: Mapping[str, FloatLike]) -> StrainDict abstractmethod ¤

Evaluate the waveform.

Parameters:

Name Type Description Default
axis Float[Array, ' n']

Evaluation grid (a frequency or time array).

 required
params Mapping[str, FloatLike]

Source parameters, keyed by name.

 required

Returns:

Type Description
StrainDict

A dict keyed by polarization/component, e.g. {"p": ..., "c": ...}.

get_waveform_metadata(name: str) -> dict[str, Any] ¤

Return a copy of the descriptive metadata for a registered waveform.

Parameters:

Name Type Description Default
name str

A registered model name.

 required

Returns:

Type Description
dict[str, Any]

The model's metadata, e.g. {"domain": "FD", ...}.

Raises:

Type Description
ValueError

If name is not registered.

list_waveforms(**filters) -> list[str] ¤

List registered waveform names, optionally filtered by metadata.

Parameters:

Name Type Description Default
**filters

Constraints on waveform_metadata, e.g. domain="FD" or is_precessing=True. A model matches only if its metadata defines every requested key with the requested value. Unknown/typo'd keys simply match nothing; use get_waveform_metadata to inspect available keys.

 {}

Returns:

Type Description
list[str]

Sorted matching names.

register(name: Optional[str] = None, *, override: bool = False, **metadata) ¤

Class decorator that adds a Waveform subclass to the registry.

Keyword arguments are stored on the class as waveform_metadata; that is what list_waveforms filters on.

Parameters:

Name Type Description Default
name Optional[str]

Registry key users pass to waveform(). Defaults to the class name.

 None
override bool

Allow replacing a name that is already registered.

 False
**metadata

Descriptive tags, e.g. is_tidal=True.

 {}

Returns:

Type Description

The decorator, which returns the class unchanged.

Raises:

Type Description
ValueError

If name is already registered and override is False.
TypeError

If the decorated class is not a Waveform subclass.

waveform(name: str, /, **config) -> Waveform ¤

Construct a registered waveform by name.

Parameters:

Name Type Description Default
name str

A registered model name (see list_waveforms).

 required
**config

Constructor configuration forwarded to the model (e.g. f_ref=20.0 for CBC models).

 {}

Returns:

Type Description
Waveform

A configured instance, callable as wf(axis, params).

Raises:

Type Description
ValueError

If name is not registered.