Overview

Initialize the simulator and fit the ARMA model once.

Parameters:

Return the bounded state needed to keep a running stream going.

Return a picklable snapshot sufficient to resume the stream.

Construct an ARMA simulator from one component definition.

Generate per-detector ARMA noise with continuity across calls.

Yield ARMA chunks lazily while preserving filter state.

Restore a snapshot produced by :meth:export_state.

Parameters:

Raises:

Clear filter state and RNGs.

Return the metadata a stopped stream must persist to resume.

Initialize the simulator and fit the AR model once.

Parameters:

Return the bounded state needed to keep a running stream going.

The state is the recursion memory of every detector; its size is proportional to the order and independent of the generated span.

Return a picklable snapshot sufficient to resume the stream.

Construct an AR-noise simulator from one component definition.

Generate per-detector AR noise with continuity across calls.

Yield AR-noise chunks lazily while preserving recursion state.

Restore a snapshot produced by :meth:export_state.

Parameters:

Raises:

Clear detector state and RNGs.

Return the metadata a stopped stream must persist to resume.

Initialize the additive wrapper.

Generate base noise and add the configured spectral lines.

Yield additive spectral-line chunks lazily.

Reset the additive line state and any resettable base state.

Run the noise simulation with the given configuration.

Parameters:

Returns:

Validate blip-specific parameters.

Return whether this model injects glitches into detector.

Parameters:

Returns:

Return a stable identity for the PSD this model colors against.

None for a model that does no coloring, which therefore imposes no noise floor on the interferometers it claims and cannot contradict another model about one. Read from psd_file where the model has one, so a third-party model gets the same treatment as the built-in ones without restating the attribute name.

Returns:

Generate one waveform together with the parameters that produced it.

What the injector calls, so every event can be recorded rather than merely tallied.

generate_waveform remains the extension point it has always been: a model that overrides it -- including a subclass of a built-in model -- governs what is injected, and its draw is reported with the parameters blank rather than filled in from the superclass's draw, which produced a different waveform. Reversing that precedence would let an override change the strain while the catalogue described the code it replaced.

Generate a Gaussian-windowed white-noise burst.

Pin any external, mutable dependency to an immutable version.

Parametric models are fully specified by their configuration and have nothing external to resolve, so the base implementation is a no-op that returns None. Models backed by a downloaded dataset (e.g. DeepExtractorGlitch) override this to fetch and return the concrete version their run is pinned to. Exposing it on the base lets a caller pin every model in a heterogeneous glitch list uniformly.

Return metadata-friendly model parameters.

Initialize the simulator.

Return a picklable snapshot of the running crossfade stream.

The snapshot persists the bit-generator state and the chunk counter of the stitcher plus the bookkeeping needed to interpolate the PSD schedule on resume. It contains no cached strain: the previous window is regenerated from the bit-generator state.

Construct a colored-noise simulator from one component definition.

Generate per-detector colored noise.

Yield colored-noise chunks lazily while preserving simulator state.

Resume the crossfade stream from an :meth:export_state snapshot.

Parameters:

Raises:

Clear continuity and RNG state.

Initialize the composed simulator.

Generate all component realizations and add them together.

Yield additive component chunks lazily.

Construct one simulator instance from a generic component config.

Initialize the simulator and fit truncated VMA taps once.

Construct a correlated-AR simulator from one component definition.

Generate correlated per-detector noise with stateful continuity.

Yield correlated AR chunks lazily while preserving innovation state.

Clear innovation state and RNG.

Initialize the simulator.

Construct a correlated-noise simulator from one component definition.

Generate correlated per-detector noise.

Yield correlated-noise chunks lazily while preserving simulator state.

Clear continuity and RNG state.

Validate the configuration and preload the PSD table.

Return whether this model injects glitches into detector.

Parameters:

Returns:

Return a stable identity for the PSD this model colors against.

None for a model that does no coloring, which therefore imposes no noise floor on the interferometers it claims and cannot contradict another model about one. Read from psd_file where the model has one, so a third-party model gets the same treatment as the built-in ones without restating the attribute name.

Returns:

Generate one waveform together with the parameters that produced it.

What the injector calls, so every event can be recorded rather than merely tallied.

generate_waveform remains the extension point it has always been: a model that overrides it -- including a subclass of a built-in model -- governs what is injected, and its draw is reported with the parameters blank rather than filled in from the superclass's draw, which produced a different waveform. Reversing that precedence would let an override change the strain while the catalogue described the code it replaced.

Generate one colored, SNR-calibrated DeepExtractor glitch.

Pin the dataset to a concrete commit SHA, fetching only the samples file.

Reads the commit SHA huggingface_hub stamps into the cache path so the resolved revision is available for reproducibility metadata even when no waveform has been drawn yet — e.g. a batch that fires zero glitch events, where generate_waveform (and therefore _get_dataset) never runs. The samples file is downloaded once and reused by the later full load, so this adds no extra download on the generation path. Returns the resolved SHA, or None when the cache layout does not expose one (e.g. a test stub serving files from a flat directory).

Return metadata-friendly model parameters.

Initialize the simulator with protocol-compatible state.

Return Gaussian white-noise strain arrays.

Yield white-noise strain chunks lazily.

Run the noise simulation with the given configuration.

Validate the configuration and load the SNR table.

Draw one target SNR uniformly from the table, with replacement.

Return the mapping that reconstructs this distribution.

Echoes whichever of the two inputs was configured, so a file-backed table replays as a reference to the file rather than as a copy of its contents inlined into the metadata.

Return the fraction of the supplied table at or above threshold.

Validate configured files and preload the population/PSD tables.

Return whether this model injects glitches into detector.

Parameters:

Returns:

Return a stable identity for the PSD this model colors against.

None for a model that does no coloring, which therefore imposes no noise floor on the interferometers it claims and cannot contradict another model about one. Read from psd_file where the model has one, so a third-party model gets the same treatment as the built-in ones without restating the attribute name.

Returns:

Generate one waveform together with the parameters that produced it.

What the injector calls, so every event can be recorded rather than merely tallied.

generate_waveform remains the extension point it has always been: a model that overrides it -- including a subclass of a built-in model -- governs what is injected, and its draw is reported with the parameters blank rather than filled in from the superclass's draw, which produced a different waveform. Reversing that precedence would let an override change the strain while the catalogue described the code it replaced.

Construct a gengli glitch model from a population file path.

Generate one colored gengli blip waveform.

Pin any external, mutable dependency to an immutable version.

Parametric models are fully specified by their configuration and have nothing external to resolve, so the base implementation is a no-op that returns None. Models backed by a downloaded dataset (e.g. DeepExtractorGlitch) override this to fetch and return the concrete version their run is pinned to. Exposing it on the base lets a caller pin every model in a heterogeneous glitch list uniformly.

Return metadata-friendly model parameters.

Validate the class definition.

Raises:

Rebuild a class from :meth:serialize output.

Parameters:

Returns:

Raises:

Return the mapping that reconstructs this class.

Validate common glitch parameters.

Return whether this model injects glitches into detector.

Parameters:

Returns:

Return a stable identity for the PSD this model colors against.

None for a model that does no coloring, which therefore imposes no noise floor on the interferometers it claims and cannot contradict another model about one. Read from psd_file where the model has one, so a third-party model gets the same treatment as the built-in ones without restating the attribute name.

Returns:

Generate one waveform together with the parameters that produced it.

What the injector calls, so every event can be recorded rather than merely tallied.

generate_waveform remains the extension point it has always been: a model that overrides it -- including a subclass of a built-in model -- governs what is injected, and its draw is reported with the parameters blank rather than filled in from the superclass's draw, which produced a different waveform. Reversing that precedence would let an override change the strain while the catalogue described the code it replaced.

Generate a single glitch waveform.

Pin any external, mutable dependency to an immutable version.

Parametric models are fully specified by their configuration and have nothing external to resolve, so the base implementation is a no-op that returns None. Models backed by a downloaded dataset (e.g. DeepExtractorGlitch) override this to fetch and return the concrete version their run is pinned to. Exposing it on the base lets a caller pin every model in a heterogeneous glitch list uniformly.

Return metadata-friendly model parameters.

Construct a glitch-only component from one component definition.

Validate the population definition.

Raises:

Wrap a base simulator so it also injects this population.

Parameters:

Returns:

Return the exact bytes the digest is taken over.

Sorted keys, no insignificant whitespace, ASCII only and no NaN: a mapping that two processes can be relied on to render identically. Exposed rather than hidden so a campaign that disagrees about a digest can diff what was hashed instead of guessing.

Returns:

Rebuild a population from :meth:serialize output.

Parameters:

Returns:

Raises:

Return the population's sha256:... digest.

What a campaign manifest pins. Every registered quantity, every prose field and the schema version go into it, so a population that has been edited cannot present itself as the one a finished run used.

Returns:

Decompose the expected injected count per class and interferometer.

Parameters:

Returns:

Raises:

Return one class's glitch model by name.

Parameters:

Returns:

Raises:

Return the population's glitch models in registration order.

Generate this population's glitch strain on its own, with no noise under it.

This is the object paired arms share. A comparison whose arms differ in their signal content, their geometry, their detection threshold or their ranking statistic must not differ in their glitches, and the way to guarantee that is for every arm to add the same array rather than to re-run a generator and trust it to agree. The returned stamp carries the population digest and the seed, so an arm can record which realization it added -- and the digest is the field to pin, for the reason :class:GlitchRealization gives.

The realization is reproducible for a fixed (package version, population, seed) and does not depend on the base noise, on the other interferometers in the run, or on whether it was generated in one call or streamed -- see the module's tests, which assert each of those separately.

Parameters:

Returns:

Raises:

Return the mapping that reconstructs this population.

Validate that gps_end is after gps_start.

Initialize the fetcher.

Parameters:

Probe GWOSC for per-detector strain-data availability.

Unlike :attr:clean_segments, which only reflects vetoes (GW events and data-quality flags), this checks whether the strain data itself has been published and is downloadable for the full configured GPS interval. A detector can have a fully "clean" interval yet have no published strain — e.g. the data has not been released yet for the observing run — in which case a fetch would fail. Use this for a pre-flight check before fetching.

Parameters:

Returns:

Fetch clean noise segments.

Clean segments are computed by excluding GW events and data-quality issues according to the filter configuration.

Parameters:

Returns:

Raises:

Fetch raw strain data without filtering.

Parameters:

Returns:

Raises:

Initialize the real-noise simulator.

Parameters:

Probe GWOSC for per-detector strain-data availability.

Convenience passthrough to :meth:GwoscNoiseFetcher.check_availability. Use this as a pre-flight check: a detector may have a fully clean interval (no vetoes) yet have no published strain data, in which case :meth:generate would fail with a clear error.

Parameters:

Returns:

Fetch clean noise and return the longest contiguous segment per detector.

Real GWOSC noise is fragmented by the excision of GW events and data-quality vetoes, so the clean data generally consists of several non-contiguous spans. To honour the NoiseSimulator contract — a single, gap-free array per detector — this returns the longest contiguous clean segment for each detector.

Concatenating the fragments instead (the historical behaviour) splices non-adjacent samples together, creating discontinuities that show up as sharp transients after whitening. Use :meth:generate_segments to obtain every clean segment separately when the full clean data is required.

Parameters:

Returns:

Raises:

Fetch clean noise and return per-detector lists of contiguous segments.

Unlike :meth:generate, this preserves the gap structure of the real data: each clean segment — the spans left after excluding GW events and data-quality vetoes — is returned as its own array, in GPS-time order. Adjacent segments are not contiguous in time, so callers must treat each segment independently; concatenating them would splice non-adjacent samples together and introduce discontinuities at the joins (which manifest as sharp transients after whitening).

Parameters:

Returns:

Raises:

Yield clean-noise chunks lazily.

Fetches the longest contiguous clean segment once (see :meth:generate) and yields it in chunks of chunk_duration seconds. Chunking the longest contiguous span keeps every chunk free of the discontinuities that splicing fragments would introduce.

Parameters:

Yields:

Initialize the segment filter.

Parameters:

Compute clean (analysis-ready) segments for each detector.

Clean segments are the requested GPS range minus the union of: - GW event vetosegments (if any GW filter is active) - DQ vetosegments (if the data-quality filter is active) - Hardware injection segments (if enabled)

Parameters:

Returns:

Query data-quality flags for detector and build vetosegments.

Uses gwosc.timeline.get_segments() to fetch pre-computed DQ veto segments for each flag in dq_flags.

Parameters:

Returns:

Query GWTC events in the GPS range and build vetosegments.

For HIGH_CONFIDENCE_GW, only events with FAR <= far_threshold are included. For ALL_GW_SIGNALS, all events in the range are included.

Parameters:

Returns:

Query hardware injection events and build vetosegments.

Parameters:

Returns:

Initialize the additive glitch wrapper.

Generate base noise and inject the configured glitches.

Yield glitch-injected chunks lazily.

Reset the additive wrapper and any resettable base state.

Rewinds the epoch to the one the wrapper was constructed with, which _initialize_process does not: this is the caller saying "start over", where a seed passed to generate is the caller saying "this segment, whose epoch I have just told you, begins a new realization". The two need different answers, and conflating them is what put every streamed segment on the wrong epoch.

Initialize the dummy backend.

Parameters:

Raises:

Return this backend's exact, closed-form one-sided cross-spectral density.

Every channel is temporally white, so the returned matrix is frequency-independent: 2 * Sigma / sampling_frequency at every frequency, where Sigma is the per-sample covariance matrix drawn from at construction. This is an exact analytic value, not a statistical estimate off a realization.

Generate one simultaneous, correlated strain+witness realization.

Yield simultaneous strain+witness chunks lazily, preserving RNG state.

Return the joint one-sided cross-spectral density over all channels.

Generate one simultaneous strain+witness realization.

Yield simultaneous strain+witness chunks lazily.

Continuity contract: consecutive chunks from this iterator must equal the same realization a caller would obtain from one seeded :meth:generate_joint call spanning the combined duration -- the same contract NoiseSimulator.generate_stream makes for strain-only output.

Validate the configured distribution parameters.

Draw one amplitude sample.

Initialize the simulator and fit the matrix spectral factor once.

The cross-spectral matrix may be given either as files (psd_files plus csd_files, absent off-diagonal pairs mean zero coherence) or as an in-memory target_matrices array on target_frequencies, which lets an analytic pair bypass the tabulated-curve interpolation.

Parameters:

Return the bounded state needed to keep a running stream going.

The state is the recursion history plus the pending output; its size is proportional to the order and independent of the generated span.

Return a picklable snapshot sufficient to resume the stream.

Construct a multichannel simulator from one component definition.

Generate per-detector multichannel noise with continuity across calls.

Yield multichannel chunks lazily while preserving recursion history.

Restore a snapshot produced by :meth:export_state.

Parameters:

Raises:

Clear the recursion history, pending output and generator.

Return the metadata a stopped stream must persist to resume.

Validate the configured coherence parameters.

Raises:

Draw one interferometer's amplitude ratio for a shared waveform.

Parameters:

Returns:

Return the mapping that reconstructs this coherence specification.

Accept string, flat mapping, or explicit {simulator, options} input.

Validate the normalized component entry.

Generate per-detector strain arrays.

Yield per-detector strain chunks lazily.

Initialize the simulator and design the colouring filter once.

The target may be given either as a file (psd_file) or directly as a one-sided array (target_psd), so an analytic target can bypass the tabulated-curve interpolation entirely. When target_frequencies is omitted for an array target it defaults to the one-sided grid matching its length at the configured sampling frequency.

Parameters:

Return the bounded state needed to keep a running stream going.

The state is the filter memory of every detector plus the pending output and block bookkeeping. It contains no generated strain and its size is independent of the generated span.

Return a picklable snapshot sufficient to resume the stream.

Construct an overlap-save FIR simulator from one component definition.

Generate per-detector coloured noise with continuity across calls.

Yield coloured-noise chunks lazily while preserving filter memory.

Restore a snapshot produced by :meth:export_state.

Parameters:

Raises:

Clear the filter memory, pending samples and random-number generators.

Return the metadata a stopped stream must persist to resume.

This is the per-detector bit-generator state plus the settings needed to rebuild the filter, and is reported separately from the continuation state.

Store the simulator factory and executor preferences.

Generate per-detector strain arrays in parallel.

Yield parallel-generated chunks lazily.

Clear cached worker simulators, resetting continuity across workers.

Validate the configured power-law parameters.

Draw one target SNR by inverting the survival function.

rng.random() returns a uniform on [0, 1), so the inverted survival minimum * (1 - u) ** (-1 / alpha) covers [minimum, inf) and never divides by zero. Truncation rescales the same inversion onto [minimum, maximum].

The untruncated branch is guarded rather than trusted. __post_init__ already refuses a configuration whose draws can leave the float range, so nothing built through it reaches the guard; what the guard covers is a value that got past that check anyway -- an instance mutated after construction, or a configuration sitting on the boundary where the bound is computed in logarithms and can be a rounding hair out. An unusable target has to stop here either way, because past this point it is a scale factor on a waveform and a number in a truth catalogue, where infinity is indistinguishable from a very loud glitch.

Return the mapping that reconstructs this distribution.

Return the fraction of draws at or above threshold.

The selection factor of a recording or detection cut applied to this class: how much of the configured population a search at that threshold would ever see. Read off the distribution in closed form rather than estimated from a realization, so an expected-count decomposition is exact rather than Monte-Carlo.

Parameters:

Returns:

Draw one target SNR.

Return the mapping that reconstructs this distribution.

Return the fraction of draws at or above threshold.

Validate scattered-light parameters.

Return whether this model injects glitches into detector.

Parameters:

Returns:

Return a stable identity for the PSD this model colors against.

None for a model that does no coloring, which therefore imposes no noise floor on the interferometers it claims and cannot contradict another model about one. Read from psd_file where the model has one, so a third-party model gets the same treatment as the built-in ones without restating the attribute name.

Returns:

Generate one waveform together with the parameters that produced it.

What the injector calls, so every event can be recorded rather than merely tallied.

generate_waveform remains the extension point it has always been: a model that overrides it -- including a subclass of a built-in model -- governs what is injected, and its draw is reported with the parameters blank rather than filled in from the superclass's draw, which produced a different waveform. Reversing that precedence would let an override change the strain while the catalogue described the code it replaced.

Generate a chirping scattered-light glitch.

Pin any external, mutable dependency to an immutable version.

Parametric models are fully specified by their configuration and have nothing external to resolve, so the base implementation is a no-op that returns None. Models backed by a downloaded dataset (e.g. DeepExtractorGlitch) override this to fetch and return the concrete version their run is pinned to. Exposing it on the base lets a caller pin every model in a heterogeneous glitch list uniformly.

Return metadata-friendly model parameters.

Initialize the Schumann simulator.

Construct a Schumann-noise simulator from one component definition.

Generate correlated Schumann strain noise.

Yield Schumann-noise chunks lazily while preserving simulator state.

Clear continuity and RNG state.

Return the isotropic Schumann magnetic PSD on a frequency grid.

Return the isotropic Schumann coherence approximation.

Validate the resonance parameter vectors.

Validate scalar line parameters.

Initialize the line generator.

Construct a spectral-line simulator from one component definition.

Generate line-only strain for all requested detectors.

Yield spectral-line chunks lazily.

Clear continuity state and phase initialization.

Initialize the white-noise component state.

Construct one white-noise component from generic config.

Return Gaussian white-noise strain arrays.

Yield white-noise strain chunks lazily.