Noise

Stability: Stable

gwexpy.noise - Noise generation and modeling.

This module provides tools for generating and modeling noise spectra.

Submodules

asd : Functions that return FrequencySeries (ASD) wave : Functions that return time-series waveforms (ndarray)

Examples

>>> from gwexpy.noise.asd import from_pygwinc
>>> from gwexpy.noise.wave import from_asd

>>> asd = from_pygwinc('aLIGO', fmin=4.0, fmax=1024.0, df=0.01)
>>> noise = from_asd(asd, duration=128, sample_rate=2048, t0=0)
gwexpy.noise.from_pygwinc(model: str, frequencies: ndarray | None = None, quantity: Literal['strain', 'darm', 'displacement'] = 'strain', **kwargs: Any) → FrequencySeries[source]

Get detector noise ASD from pyGWINC.

This function returns the Amplitude Spectral Density (ASD) of a gravitational wave detector noise model using pyGWINC.

Parameters:

  • model (str) – The pyGWINC model name (e.g., β€œaLIGO”, β€œAplus”, β€œVoyager”). β€œA+” is automatically converted to β€œAplus”.

  • frequencies (array_like, optional) – Frequency array in Hz. If not provided, a default array is generated using fmin, fmax, and df from kwargs.

  • quantity ({"strain", "darm", "displacement"}, default "strain") –

    Physical quantity of the ASD to return:

    • "strain": Strain ASD [1/sqrt(Hz)]

    • "darm": Differential arm length ASD [m/sqrt(Hz)]

    • "displacement": Deprecated alias for β€œdarm”

  • **kwargs –

    Additional keyword arguments:

    • fminfloat, default 10.0

      Minimum frequency [Hz] for default frequency array.

    • fmaxfloat, default 4000.0

      Maximum frequency [Hz] for default frequency array.

    • dffloat, default 1.0

      Frequency step [Hz] for default frequency array.

Returns:

The ASD as a FrequencySeries with appropriate units.

Return type:

FrequencySeries

Raises:

  • ImportError – If pyGWINC is not installed.

  • ValueError – If quantity is not one of the allowed values. If quantity=”darm” or β€œdisplacement” and arm length cannot be retrieved from the IFO model. If fmin >= fmax.

Notes

Quantity Definitions:

  • Strain ASD: The detector’s sensitivity expressed as equivalent gravitational wave strain per sqrt(Hz).

  • DARM ASD: Differential Arm Length Motion ASD, related to strain by darm = strain * L where L is the arm length.

Arm Length Conversion:

For quantity="darm" (or "displacement"), the strain ASD is multiplied by the arm length L obtained from ifo.Infrastructure.Length.

Frequency Array:

If frequencies is not provided, a uniform frequency array is generated: np.arange(fmin, fmax + df, df).

Examples

>>> from gwexpy.noise.asd import from_pygwinc

Get strain ASD for aLIGO:

>>> asd = from_pygwinc("aLIGO", fmin=10.0, fmax=1000.0, df=1.0)
>>> asd.unit
Unit("1 / Hz(1/2)")

Get DARM ASD:

>>> darm_asd = from_pygwinc("aLIGO", quantity="darm")
>>> darm_asd.unit
Unit("m / Hz(1/2)")
gwexpy.noise.from_obspy(model: str, frequencies: ndarray | None = None, quantity: Literal['displacement', 'velocity', 'acceleration'] = 'acceleration', **kwargs: Any) → FrequencySeries[source]

Get standard noise models from ObsPy.

This function returns the Amplitude Spectral Density (ASD) of seismic or infrasound noise models from ObsPy.

Parameters:

  • model (str) –

    The ObsPy model name. Supported models:

    • "NHNM": New High Noise Model (Peterson 1993)

    • "NLNM": New Low Noise Model (Peterson 1993)

    • "IDCH": IDC Infrasound High Noise Model

    • "IDCL": IDC Infrasound Low Noise Model

  • frequencies (array_like, optional) – Frequency array in Hz for interpolation. If not provided, the original model frequencies are used.

  • quantity ({"displacement", "velocity", "acceleration"}, default "acceleration") –

    Physical quantity of the ASD to return (for seismic models only):

    • "acceleration": Acceleration ASD [m/(sΒ²Β·sqrt(Hz))]

    • "velocity": Velocity ASD [m/(sΒ·sqrt(Hz))]

    • "displacement": Displacement ASD [m/sqrt(Hz)]

    Note

    The "strain" quantity is not supported for seismic noise models. Use from_pygwinc for strain-based detector noise.

  • **kwargs – Additional keyword arguments passed to FrequencySeries constructor.

Returns:

The ASD as a FrequencySeries with appropriate units.

Return type:

FrequencySeries

Raises:

  • ImportError – If ObsPy is not installed.

  • ValueError – If model is not one of the supported models. If quantity is not one of the allowed values. If quantity=”strain” is requested (not supported).

Notes

Quantity Conversion (Seismic Models):

The NHNM and NLNM models are defined in terms of acceleration. Conversions to velocity and displacement are performed in the frequency domain:

  • velocity = acceleration / (2Ο€f)

  • displacement = acceleration / (2Ο€f)Β²

At f=0, the conversion results in NaN to avoid division by zero.

Unit Table:

Quantity

Unit

acceleration

m / (sΒ² Β· sqrt(Hz))

velocity

m / (s Β· sqrt(Hz))

displacement

m / sqrt(Hz)

Infrasound Models:

For IDCH and IDCL models, the quantity parameter is ignored as these return pressure ASD in units of Pa/sqrt(Hz).

Examples

>>> from gwexpy.noise.asd import from_obspy

Get acceleration ASD for NLNM:

>>> asd = from_obspy("NLNM")
>>> asd.unit
Unit("m / (Hz(1/2) s2)")

Get displacement ASD:

>>> disp_asd = from_obspy("NLNM", quantity="displacement")
>>> disp_asd.unit
Unit("m / Hz(1/2)")

Strain is not supported:

>>> from_obspy("NLNM", quantity="strain")
Traceback (most recent call last):
    ...
ValueError: quantity='strain' is not supported for seismic noise models...
gwexpy.noise.from_asd(asd: FrequencySeries, duration: float, sample_rate: float, t0: float = 0.0, rng: Generator | None = None, seed: int | None = None, **kwargs: Any) → TimeSeries[source]

Generate colored noise TimeSeries from an ASD (Amplitude Spectral Density).

Uses FFT-based colored noise synthesis to produce a time-series with the spectral characteristics defined by the input ASD.

Parameters:

  • asd (FrequencySeries) – The one-sided amplitude spectral density defining the noise spectrum. Values must be finite and non-negative on a strictly increasing, non-negative frequency axis.

  • duration (float) – Duration of the output time-series in seconds.

  • sample_rate (float) – Sample rate of the output time-series in Hz.

  • t0 (float, optional) – Start time of the output TimeSeries.

  • rng (numpy.random.Generator, optional) – Random number generator instance. If None, a new default generator is created.

  • seed (int, optional) – Seed used to initialize the default random generator.

  • **kwargs – Additional arguments passed to TimeSeries constructor (e.g., name, channel, unit). If provided, these override values derived from the ASD.

Returns:

The generated noise time-series as a gwexpy TimeSeries.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.asd import from_pygwinc
>>> from gwexpy.noise.wave import from_asd
>>> asd = from_pygwinc('aLIGO', fmin=4.0, fmax=1024.0, df=0.01)
>>> noise = from_asd(asd, duration=128, sample_rate=2048, t0=0)
gwexpy.noise.pink_noise(amplitude: float | Quantity, f_ref: float | Quantity = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate Pink noise ASD (~ f^-0.5).

The power spectral density (PSD) follows f^-1, meaning the amplitude spectral density (ASD) follows f^-0.5.

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude at the reference frequency.

  • f_ref (float or astropy.units.Quantity, optional) – The reference frequency in Hz (default is 1.0).

  • **kwargs (Any) – Additional keyword arguments passed to power_law.

Returns:

The generated pink noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import pink_noise
>>> from astropy import units as u
>>> asd = pink_noise(10.0, f_ref=10.0, df=1.0, fmin=1, fmax=100)
>>> # 10 Hz is at index 9 (if fmin=1, f_0=1, index 9 is f=10)
>>> bool(abs(asd[9].value - 10.0) < 1e-10)
True
gwexpy.noise.power_law(exponent: float, amplitude: float | Quantity = 1.0, f_ref: float | Quantity = 1.0, frequencies: ndarray | None = None, **kwargs: Any) → FrequencySeries[source]

Generate an ASD FrequencySeries following a power law.

ASD(f) = amplitude * (f / f_ref) ** (-exponent).

gwexpy.noise.red_noise(amplitude: float | Quantity, f_ref: float | Quantity = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate Red (Brownian) noise ASD (~ f^-1).

The power spectral density (PSD) follows f^-2, meaning the amplitude spectral density (ASD) follows f^-1.

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude at the reference frequency.

  • f_ref (float or astropy.units.Quantity, optional) – The reference frequency in Hz (default is 1.0).

  • **kwargs (Any) – Additional keyword arguments passed to power_law.

Returns:

The generated red noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import red_noise
>>> # Generate red noise with 1e-10 unit/rtHz at 1 Hz
>>> asd = red_noise(1e-10, f_ref=1.0, df=0.1, fmin=0.1, fmax=10)
>>> bool(abs(asd.value[9] - 1e-10) < 1e-18)  # At index 9, f=1.0Hz
True
gwexpy.noise.white_noise(amplitude: float | Quantity, **kwargs: Any) → FrequencySeries[source]

Generate White noise ASD (~ f^0).

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude. If a float is provided, it is assumed to be in the same units as the target spectrum (e.g., [m/rtHz] or [V/rtHz]). If a Quantity is provided, its units are preserved in the output.

  • **kwargs (Any) – Additional keyword arguments passed to power_law. Typically includes df, fmin, fmax, or frequencies.

Returns:

The generated white noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import white_noise
>>> asd = white_noise(1e-18, df=1.0, fmin=0, fmax=100)
>>> asd.unit
Unit(dimensionless)
gwexpy.noise.transient_gaussian_noise(duration: float | Quantity, sample_rate: float | Quantity, A1: float, psd: Any | None = None, rng: Any | None = None, seed: int | None = None, **kwargs: Any) → TimeSeries[source]

Generate Model I non-Gaussian noise: Superposition of transient Gaussian noise.

x(t) = n0(t) + A1 * B(t) * n1(t).

Parameters:

  • duration (float, u.Quantity) – Duration of the noise in seconds.

  • sample_rate (float, u.Quantity) – Sample rate in Hz.

  • A1 (float) – Amplitude scaling factor for the transient part.

  • psd (FrequencySeries, optional) – One-sided PSD used to color both Gaussian components. If None, white noise is used.

  • rng (numpy.random.Generator, optional) – Random number generator. If None and seed is not provided, the legacy global NumPy RNG is used for the white-noise path.

  • seed (int, optional) – Seed used to initialize a default random generator.

  • **kwargs – Additional arguments for TimeSeries.

Return type:

TimeSeries

gwexpy.noise.scatter_light_noise(duration: float | Quantity, sample_rate: float | Quantity, A2: float, f_sc: float = 0.2, G: float = 3e-22, lambda_val: float = 1.064e-06, x0: float = 1.0, f_amp: float = 0.1, **kwargs: Any) → TimeSeries[source]

Generate Model II non-Gaussian noise: Scattered light noise.

x(t) = n0(t) + G * sin(4pi/lambda * (x0 + delta_x_sc(t))) delta_x_sc = A2 * (1 + 0.25 * sin(2pi * f_amp * t)) * cos(2pi * f_sc * t).

Parameters:

  • duration (float, u.Quantity) – Duration of the noise in seconds.

  • sample_rate (float, u.Quantity) – Sample rate in Hz.

  • A2 (float) – Amplitude of the scattering motion.

  • f_sc (float, default=0.2) – Frequency of the scattering motion in Hz.

  • G (float, default=3e-22) – Overall amplitude scaling.

  • lambda_val (float, default=1064e-9) – Wavelength in meters.

  • x0 (float, default=1.0) – Static offset in meters.

  • f_amp (float, default=0.1) – Frequency of the amplitude modulation in Hz.

  • **kwargs – Additional arguments for TimeSeries.

Return type:

TimeSeries

gwexpy.noise.inject_noise(clean_ts: TimeSeries, noise_ts: TimeSeries) → TimeSeries[source]

Inject noise_ts into clean_ts and return the noisy TimeSeries.

The function returns the pointwise sum of the clean time series and the noise time series. Both series must be aligned in time and have compatible sample rates. This convenience wrapper preserves metadata where possible.

Parameters:

  • clean_ts (TimeSeries) – Clean (signal-only) time series that will receive the noise. The series may have name, unit, and time span attributes.

  • noise_ts (TimeSeries) – Noise time series to add to clean_ts. Should be aligned with clean_ts (same sample rate and overlapping span). If sample rates differ, users should resample externally prior to calling this function.

Returns:

New TimeSeries equal to clean_ts + noise_ts. Metadata from clean_ts are preserved where possible; unit will follow arithmetic rules (e.g., addition requires compatible units).

Return type:

TimeSeries

Raises:

ValueError – If the time alignment or sample rates are incompatible (unless the underlying TimeSeries implementation handles resampling).

Examples

>>> from gwexpy import TimeSeries
>>> import numpy as np
>>> t = np.linspace(0, 1, 100)
>>> clean_ts = TimeSeries(np.sin(2 * np.pi * 10 * t), t0=0, sample_rate=100)
>>> noise_ts = TimeSeries(np.random.randn(100) * 0.1, t0=0, sample_rate=100)
>>> noisy = inject_noise(clean_ts, noise_ts)
>>> isinstance(noisy, TimeSeries)
True
gwexpy.noise.apply_line_mask(spectrogram: Spectrogram, detector: str = 'KAGRA', custom_lines: list[tuple[float, float]] | None = None, fill_value: float = nan) → Spectrogram[source]

Apply a line mask to a spectrogram.

Masked frequencies are replaced with fill_value.

gwexpy.noise.create_line_mask(frequencies: ndarray, detector: str = 'KAGRA', custom_lines: list[tuple[float, float]] | None = None) → ndarray[source]

Create a boolean mask for line noise exclusion.

True = clean frequency, False = masked frequency.

ASD

gwexpy.noise.asd - Functions that generate ASD (Amplitude Spectral Density).

This module provides convenient access to ASD-generating functions. All functions in this module return FrequencySeries objects with appropriate units based on the requested physical quantity.

ASD Functions

from_pygwincGenerate ASD from pyGWINC detector noise models

Supported quantities: β€œstrain” [1/sqrt(Hz)], β€œdarm” [m/sqrt(Hz)], β€œdisplacement” (alias of β€œdarm”)

from_obspyGenerate ASD from ObsPy seismic/infrasound noise models

Supported quantities: β€œdisplacement” [m/sqrt(Hz)], β€œvelocity” [m/(sΒ·sqrt(Hz))], β€œacceleration” [m/(sΒ²Β·sqrt(Hz))] Note: β€œstrain” is NOT supported for seismic models.

power_law, white_noise, pink_noise, red_noise : Colored noise ASD generators schumann_resonance, geomagnetic_background : Geomagnetic noise models lorentzian_line, gaussian_line, voigt_line : Spectral line shapes

Examples

>>> from gwexpy.noise.asd import from_pygwinc, from_obspy

# Get strain ASD from pyGWINC >>> strain_asd = from_pygwinc(β€œaLIGO”, quantity=”strain”)

# Get DARM (differential arm length) ASD >>> darm_asd = from_pygwinc(β€œaLIGO”, quantity=”darm”)

# Get displacement ASD from ObsPy NLNM >>> disp_asd = from_obspy(β€œNLNM”, quantity=”displacement”)

gwexpy.noise.asd.from_pygwinc(model: str, frequencies: ndarray | None = None, quantity: Literal['strain', 'darm', 'displacement'] = 'strain', **kwargs: Any) → FrequencySeries[source]

Get detector noise ASD from pyGWINC.

This function returns the Amplitude Spectral Density (ASD) of a gravitational wave detector noise model using pyGWINC.

Parameters:

  • model (str) – The pyGWINC model name (e.g., β€œaLIGO”, β€œAplus”, β€œVoyager”). β€œA+” is automatically converted to β€œAplus”.

  • frequencies (array_like, optional) – Frequency array in Hz. If not provided, a default array is generated using fmin, fmax, and df from kwargs.

  • quantity ({"strain", "darm", "displacement"}, default "strain") –

    Physical quantity of the ASD to return:

    • "strain": Strain ASD [1/sqrt(Hz)]

    • "darm": Differential arm length ASD [m/sqrt(Hz)]

    • "displacement": Deprecated alias for β€œdarm”

  • **kwargs –

    Additional keyword arguments:

    • fminfloat, default 10.0

      Minimum frequency [Hz] for default frequency array.

    • fmaxfloat, default 4000.0

      Maximum frequency [Hz] for default frequency array.

    • dffloat, default 1.0

      Frequency step [Hz] for default frequency array.

Returns:

The ASD as a FrequencySeries with appropriate units.

Return type:

FrequencySeries

Raises:

  • ImportError – If pyGWINC is not installed.

  • ValueError – If quantity is not one of the allowed values. If quantity=”darm” or β€œdisplacement” and arm length cannot be retrieved from the IFO model. If fmin >= fmax.

Notes

Quantity Definitions:

  • Strain ASD: The detector’s sensitivity expressed as equivalent gravitational wave strain per sqrt(Hz).

  • DARM ASD: Differential Arm Length Motion ASD, related to strain by darm = strain * L where L is the arm length.

Arm Length Conversion:

For quantity="darm" (or "displacement"), the strain ASD is multiplied by the arm length L obtained from ifo.Infrastructure.Length.

Frequency Array:

If frequencies is not provided, a uniform frequency array is generated: np.arange(fmin, fmax + df, df).

Examples

>>> from gwexpy.noise.asd import from_pygwinc

Get strain ASD for aLIGO:

>>> asd = from_pygwinc("aLIGO", fmin=10.0, fmax=1000.0, df=1.0)
>>> asd.unit
Unit("1 / Hz(1/2)")

Get DARM ASD:

>>> darm_asd = from_pygwinc("aLIGO", quantity="darm")
>>> darm_asd.unit
Unit("m / Hz(1/2)")
gwexpy.noise.asd.from_obspy(model: str, frequencies: ndarray | None = None, quantity: Literal['displacement', 'velocity', 'acceleration'] = 'acceleration', **kwargs: Any) → FrequencySeries[source]

Get standard noise models from ObsPy.

This function returns the Amplitude Spectral Density (ASD) of seismic or infrasound noise models from ObsPy.

Parameters:

  • model (str) –

    The ObsPy model name. Supported models:

    • "NHNM": New High Noise Model (Peterson 1993)

    • "NLNM": New Low Noise Model (Peterson 1993)

    • "IDCH": IDC Infrasound High Noise Model

    • "IDCL": IDC Infrasound Low Noise Model

  • frequencies (array_like, optional) – Frequency array in Hz for interpolation. If not provided, the original model frequencies are used.

  • quantity ({"displacement", "velocity", "acceleration"}, default "acceleration") –

    Physical quantity of the ASD to return (for seismic models only):

    • "acceleration": Acceleration ASD [m/(sΒ²Β·sqrt(Hz))]

    • "velocity": Velocity ASD [m/(sΒ·sqrt(Hz))]

    • "displacement": Displacement ASD [m/sqrt(Hz)]

    Note

    The "strain" quantity is not supported for seismic noise models. Use from_pygwinc for strain-based detector noise.

  • **kwargs – Additional keyword arguments passed to FrequencySeries constructor.

Returns:

The ASD as a FrequencySeries with appropriate units.

Return type:

FrequencySeries

Raises:

  • ImportError – If ObsPy is not installed.

  • ValueError – If model is not one of the supported models. If quantity is not one of the allowed values. If quantity=”strain” is requested (not supported).

Notes

Quantity Conversion (Seismic Models):

The NHNM and NLNM models are defined in terms of acceleration. Conversions to velocity and displacement are performed in the frequency domain:

  • velocity = acceleration / (2Ο€f)

  • displacement = acceleration / (2Ο€f)Β²

At f=0, the conversion results in NaN to avoid division by zero.

Unit Table:

Quantity

Unit

acceleration

m / (sΒ² Β· sqrt(Hz))

velocity

m / (s Β· sqrt(Hz))

displacement

m / sqrt(Hz)

Infrasound Models:

For IDCH and IDCL models, the quantity parameter is ignored as these return pressure ASD in units of Pa/sqrt(Hz).

Examples

>>> from gwexpy.noise.asd import from_obspy

Get acceleration ASD for NLNM:

>>> asd = from_obspy("NLNM")
>>> asd.unit
Unit("m / (Hz(1/2) s2)")

Get displacement ASD:

>>> disp_asd = from_obspy("NLNM", quantity="displacement")
>>> disp_asd.unit
Unit("m / Hz(1/2)")

Strain is not supported:

>>> from_obspy("NLNM", quantity="strain")
Traceback (most recent call last):
    ...
ValueError: quantity='strain' is not supported for seismic noise models...
gwexpy.noise.asd.power_law(exponent: float, amplitude: float | Quantity = 1.0, f_ref: float | Quantity = 1.0, frequencies: ndarray | None = None, **kwargs: Any) → FrequencySeries[source]

Generate an ASD FrequencySeries following a power law.

ASD(f) = amplitude * (f / f_ref) ** (-exponent).

gwexpy.noise.asd.white_noise(amplitude: float | Quantity, **kwargs: Any) → FrequencySeries[source]

Generate White noise ASD (~ f^0).

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude. If a float is provided, it is assumed to be in the same units as the target spectrum (e.g., [m/rtHz] or [V/rtHz]). If a Quantity is provided, its units are preserved in the output.

  • **kwargs (Any) – Additional keyword arguments passed to power_law. Typically includes df, fmin, fmax, or frequencies.

Returns:

The generated white noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import white_noise
>>> asd = white_noise(1e-18, df=1.0, fmin=0, fmax=100)
>>> asd.unit
Unit(dimensionless)
gwexpy.noise.asd.pink_noise(amplitude: float | Quantity, f_ref: float | Quantity = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate Pink noise ASD (~ f^-0.5).

The power spectral density (PSD) follows f^-1, meaning the amplitude spectral density (ASD) follows f^-0.5.

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude at the reference frequency.

  • f_ref (float or astropy.units.Quantity, optional) – The reference frequency in Hz (default is 1.0).

  • **kwargs (Any) – Additional keyword arguments passed to power_law.

Returns:

The generated pink noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import pink_noise
>>> from astropy import units as u
>>> asd = pink_noise(10.0, f_ref=10.0, df=1.0, fmin=1, fmax=100)
>>> # 10 Hz is at index 9 (if fmin=1, f_0=1, index 9 is f=10)
>>> bool(abs(asd[9].value - 10.0) < 1e-10)
True
gwexpy.noise.asd.red_noise(amplitude: float | Quantity, f_ref: float | Quantity = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate Red (Brownian) noise ASD (~ f^-1).

The power spectral density (PSD) follows f^-2, meaning the amplitude spectral density (ASD) follows f^-1.

Parameters:

  • amplitude (float or astropy.units.Quantity) – The noise amplitude at the reference frequency.

  • f_ref (float or astropy.units.Quantity, optional) – The reference frequency in Hz (default is 1.0).

  • **kwargs (Any) – Additional keyword arguments passed to power_law.

Returns:

The generated red noise ASD.

Return type:

FrequencySeries

Examples

>>> from gwexpy.noise import red_noise
>>> # Generate red noise with 1e-10 unit/rtHz at 1 Hz
>>> asd = red_noise(1e-10, f_ref=1.0, df=0.1, fmin=0.1, fmax=10)
>>> bool(abs(asd.value[9] - 1e-10) < 1e-18)  # At index 9, f=1.0Hz
True
gwexpy.noise.asd.schumann_resonance(frequencies: ndarray | None = None, modes: list[tuple[float, float, float]] | None = None, amplitude_scale: float = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate Schumann Resonance ASD by combining Lorentzians in PSD space.

Parameters:

  • frequencies (array-like, optional) – Target frequency array.

  • modes (list of tuples, optional) – (f0, Q, amplitude_asd in pT/rtHz). If None, uses defaults from observation.

  • amplitude_scale (float) – Scaling factor for amplitude.

  • **kwargs – Additional arguments for FrequencySeries.

gwexpy.noise.asd.geomagnetic_background(frequencies: ndarray, amplitude_1hz: float = 1e-11, exponent: float = 1.0, **kwargs: Any) → FrequencySeries[source]

Generate 1/f^alpha magnetic background noise.

Wrapper for colored.power_law.

Parameters:

  • frequencies (ndarray) – Target frequency array in Hz.

  • amplitude_1hz (float) – Amplitude at 1Hz, typically in pT/rtHz (default 10e-12 = 10pT). Note: The user provided example says 10e-12 (10pT), assumed unit of result. However, if user passes unit=’pT…’, amplitude should be consistent.

  • exponent (float) – Power-law exponent applied to the background spectrum.

  • **kwargs – Additional keyword arguments passed to power_law.

gwexpy.noise.asd.lorentzian_line(f0: float, amplitude: float | Quantity, Q: float | None = None, gamma: float | None = None, frequencies: ndarray | None = None, **kwargs: Any) → FrequencySeries[source]

Generate a Lorentzian peak (ASD form, Peak Normalization).

Formula: ASD(f) = A * gamma / sqrt( (f-f0)^2 + gamma^2 )

This implementation uses Peak Normalization where the profile peaks exactly at amplitude when f = f0. This differs from the physics convention of Area Normalization (where the integral is A).

This form is suitable for modeling spectral lines in ASD (Amplitude Spectral Density) where the peak height is known.

Parameters:

  • f0 (float) – Center frequency.

  • amplitude (float or Quantity) – Peak ASD value.

  • Q (float, optional) – Quality factor. gamma = f0 / (2*Q). Either Q or gamma must be provided.

  • gamma (float, optional) – HWHM (Half Width at Half Maximum).

  • frequencies (array-like, optional) – Target frequency array.

  • **kwargs – Additional metadata passed to FrequencySeries.

gwexpy.noise.asd.gaussian_line(f0: float, amplitude: float | Quantity, sigma: float, frequencies: ndarray | None = None, **kwargs: Any) → FrequencySeries[source]

Generate a Gaussian peak (ASD).

Formula: ASD(f) = A * exp( - (f-f0)^2 / (2*sigma^2) )

gwexpy.noise.asd.voigt_line(f0: float, amplitude: float | Quantity, sigma: float, gamma: float, frequencies: ndarray | None = None, **kwargs: Any) → FrequencySeries[source]

Generate a Voigt peak (ASD) using Faddeeva function.

Normalized to have peak value = β€˜amplitude’.

Waveform

Notes

from_asd returns a TimeSeries (not a NumPy array). The output inherits name and channel from the input ASD and uses unit * sqrt(Hz) as the time-domain unit. Use the t0 argument to set the start time.

gwexpy.noise.wave - Generate time-series waveforms.

This module provides functions for generating common time-series waveforms including noise, periodic signals, and transient signals.

All functions return gwexpy.TimeSeries objects.

Submodule Structure

  • gwexpy.noise.asd: Functions that return ASD (FrequencySeries)

  • gwexpy.noise.wave: Functions that return time-series waveforms (TimeSeries)

Examples

>>> from gwexpy.noise.wave import sine, gaussian, chirp
>>> sine_wave = sine(duration=1.0, sample_rate=1024, frequency=10.0)
>>> noise = gaussian(duration=1.0, sample_rate=1024, std=0.1)
>>> sweep = chirp(duration=1.0, sample_rate=1024, f0=10, f1=100)
gwexpy.noise.wave.from_asd(asd: FrequencySeries, duration: float, sample_rate: float, t0: float = 0.0, rng: Generator | None = None, seed: int | None = None, **kwargs: Any) → TimeSeries[source]

Generate colored noise TimeSeries from an ASD (Amplitude Spectral Density).

Uses FFT-based colored noise synthesis to produce a time-series with the spectral characteristics defined by the input ASD.

Parameters:

  • asd (FrequencySeries) – The one-sided amplitude spectral density defining the noise spectrum. Values must be finite and non-negative on a strictly increasing, non-negative frequency axis.

  • duration (float) – Duration of the output time-series in seconds.

  • sample_rate (float) – Sample rate of the output time-series in Hz.

  • t0 (float, optional) – Start time of the output TimeSeries.

  • rng (numpy.random.Generator, optional) – Random number generator instance. If None, a new default generator is created.

  • seed (int, optional) – Seed used to initialize the default random generator.

  • **kwargs – Additional arguments passed to TimeSeries constructor (e.g., name, channel, unit). If provided, these override values derived from the ASD.

Returns:

The generated noise time-series as a gwexpy TimeSeries.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.asd import from_pygwinc
>>> from gwexpy.noise.wave import from_asd
>>> asd = from_pygwinc('aLIGO', fmin=4.0, fmax=1024.0, df=0.01)
>>> noise = from_asd(asd, duration=128, sample_rate=2048, t0=0)
gwexpy.noise.wave.gaussian(duration: float, sample_rate: float, std: float = 1.0, mean: float = 0.0, t0: float = 0.0, rng: Generator | None = None, seed: int | None = None, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate Gaussian (normal) white noise.

Parameters:

  • duration (float) – Duration of the output in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • std (float, optional) – Standard deviation of the noise. Default is 1.0.

  • mean (float, optional) – Mean of the noise. Default is 0.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • rng (numpy.random.Generator, optional) – Random number generator. If None, creates a new one.

  • seed (int, optional) – Seed used to initialize the default random generator.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Gaussian noise time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import gaussian
>>> noise = gaussian(duration=1.0, sample_rate=1024, std=0.1)
gwexpy.noise.wave.uniform(duration: float, sample_rate: float, low: float = -1.0, high: float = 1.0, t0: float = 0.0, rng: Generator | None = None, seed: int | None = None, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate uniform white noise.

Parameters:

  • duration (float) – Duration of the output in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • low (float, optional) – Lower bound of the uniform distribution. Default is -1.0.

  • high (float, optional) – Upper bound of the uniform distribution. Default is 1.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • rng (numpy.random.Generator, optional) – Random number generator.

  • seed (int, optional) – Seed used to initialize the default random generator.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Uniform noise time-series.

Return type:

TimeSeries

gwexpy.noise.wave.colored(duration: float, sample_rate: float, exponent: float, amplitude: float = 1.0, f_ref: float = 1.0, t0: float = 0.0, rng: Generator | None = None, seed: int | None = None, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate colored (power-law) noise.

The noise follows a power-law spectrum: ASD(f) ~ f^(-exponent).

Parameters:

  • duration (float) – Duration of the output in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • exponent (float) – Power-law exponent in ASD. Common values: - 0: white noise - 0.5: pink noise (1/f^0.5) - 1: red/Brownian noise (1/f)

  • amplitude (float, optional) – Amplitude at the reference frequency. Default is 1.0.

  • f_ref (float, optional) – Reference frequency in Hz. Default is 1.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • rng (numpy.random.Generator, optional) – Random number generator.

  • seed (int, optional) – Seed used to initialize the default random generator.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Colored noise time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import colored
>>> pink = colored(duration=1.0, sample_rate=1024, exponent=0.5)
gwexpy.noise.wave.white_noise(duration: float, sample_rate: float, amplitude: float = 1.0, **kwargs: Any) → TimeSeries[source]

Generate white noise (flat spectrum).

Shortcut for colored(exponent=0).

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • amplitude (float, optional) – Noise amplitude. Default is 1.0.

  • **kwargs – Additional arguments passed to colored().

Returns:

White noise time-series.

Return type:

TimeSeries

gwexpy.noise.wave.pink_noise(duration: float, sample_rate: float, amplitude: float = 1.0, **kwargs: Any) → TimeSeries[source]

Generate pink noise (1/f^0.5 spectrum).

Shortcut for colored(exponent=0.5).

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • amplitude (float, optional) – Noise amplitude at reference frequency. Default is 1.0.

  • **kwargs – Additional arguments passed to colored().

Returns:

Pink noise time-series.

Return type:

TimeSeries

gwexpy.noise.wave.red_noise(duration: float, sample_rate: float, amplitude: float = 1.0, **kwargs: Any) → TimeSeries[source]

Generate red/Brownian noise (1/f spectrum).

Shortcut for colored(exponent=1.0).

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • amplitude (float, optional) – Noise amplitude at reference frequency. Default is 1.0.

  • **kwargs – Additional arguments passed to colored().

Returns:

Red noise time-series.

Return type:

TimeSeries

gwexpy.noise.wave.sine(duration: float, sample_rate: float, frequency: float, amplitude: float = 1.0, phase: float = 0.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a sine wave.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • frequency (float) – Frequency in Hz.

  • amplitude (float, optional) – Amplitude. Default is 1.0.

  • phase (float, optional) – Initial phase in radians. Default is 0.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Sine wave time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import sine
>>> wave = sine(duration=1.0, sample_rate=1024, frequency=10.0)
gwexpy.noise.wave.square(duration: float, sample_rate: float, frequency: float, amplitude: float = 1.0, phase: float = 0.0, duty: float = 0.5, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a square wave.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • frequency (float) – Frequency in Hz.

  • amplitude (float, optional) – Amplitude. Default is 1.0.

  • phase (float, optional) – Initial phase in radians. Default is 0.0.

  • duty (float, optional) – Duty cycle (0 to 1). Default is 0.5.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Square wave time-series.

Return type:

TimeSeries

gwexpy.noise.wave.sawtooth(duration: float, sample_rate: float, frequency: float, amplitude: float = 1.0, phase: float = 0.0, width: float = 1.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a sawtooth wave.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • frequency (float) – Frequency in Hz.

  • amplitude (float, optional) – Amplitude. Default is 1.0.

  • phase (float, optional) – Initial phase in radians. Default is 0.0.

  • width (float, optional) – Width parameter (0 to 1). 1 gives rising sawtooth, 0 gives falling. Default is 1.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Sawtooth wave time-series.

Return type:

TimeSeries

gwexpy.noise.wave.triangle(duration: float, sample_rate: float, frequency: float, amplitude: float = 1.0, phase: float = 0.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a triangle wave.

This is a sawtooth with width=0.5.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • frequency (float) – Frequency in Hz.

  • amplitude (float, optional) – Amplitude. Default is 1.0.

  • phase (float, optional) – Initial phase in radians. Default is 0.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Triangle wave time-series.

Return type:

TimeSeries

gwexpy.noise.wave.chirp(duration: float, sample_rate: float, f0: float, f1: float, t1: float | None = None, method: str = 'linear', amplitude: float = 1.0, phase: float = 0.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a swept-frequency cosine (chirp) signal.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • f0 (float) – Initial frequency in Hz.

  • f1 (float) – Final frequency in Hz (at time t1).

  • t1 (float, optional) – Time at which f1 is reached. Default is duration.

  • method (str, optional) – Frequency sweep method: β€˜linear’, β€˜quadratic’, β€˜logarithmic’, β€˜hyperbolic’. Default is β€˜linear’.

  • amplitude (float, optional) – Amplitude. Default is 1.0.

  • phase (float, optional) – Initial phase in radians. Default is 0.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Chirp signal time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import chirp
>>> sweep = chirp(duration=1.0, sample_rate=1024, f0=10, f1=100)
gwexpy.noise.wave.step(duration: float, sample_rate: float, t_step: float = 0.0, amplitude: float = 1.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate a step (Heaviside) function.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • t_step (float, optional) – Time of the step (relative to t0). Default is 0.0.

  • amplitude (float, optional) – Amplitude of the step. Default is 1.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Step function time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import step
>>> s = step(duration=1.0, sample_rate=1024, t_step=0.5)
gwexpy.noise.wave.impulse(duration: float, sample_rate: float, t_impulse: float = 0.0, amplitude: float = 1.0, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate an impulse (delta-like) signal.

The impulse is placed at the sample closest to t_impulse.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • t_impulse (float, optional) – Time of the impulse (relative to t0). Default is 0.0.

  • amplitude (float, optional) – Amplitude of the impulse. Default is 1.0.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Impulse signal time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import impulse
>>> i = impulse(duration=1.0, sample_rate=1024, t_impulse=0.5)
gwexpy.noise.wave.exponential(duration: float, sample_rate: float, tau: float, amplitude: float = 1.0, t_start: float = 0.0, decay: bool = True, t0: float = 0.0, unit: Any = None, name: str | None = None, channel: str | None = None) → TimeSeries[source]

Generate an exponential signal.

Parameters:

  • duration (float) – Duration in seconds.

  • sample_rate (float) – Sample rate in Hz.

  • tau (float) – Time constant in seconds.

  • amplitude (float, optional) – Initial amplitude. Default is 1.0.

  • t_start (float, optional) – Start time of the exponential (relative to t0). Default is 0.0.

  • decay (bool, optional) – If True, decay (exp(-t/tau)). If False, growth (exp(+t/tau)). Default is True.

  • t0 (float, optional) – Start time. Default is 0.0.

  • unit (astropy.units.Unit, optional) – Unit of the output.

  • name (str, optional) – Name for the TimeSeries.

  • channel (str, optional) – Channel name.

Returns:

Exponential signal time-series.

Return type:

TimeSeries

Examples

>>> from gwexpy.noise.wave import exponential
>>> decay_signal = exponential(duration=1.0, sample_rate=1024, tau=0.2)