ノイズシミュレーション (Noise)

安定性: 安定

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

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

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

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

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

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

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

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

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

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

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

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

Create a boolean mask for line noise exclusion.

True = clean frequency, False = masked frequency.