ezmsg.simbiophys.oscillator#

Oscillator/sinusoidal signal generators.

Functions

advance_drifting_sine(n_samples, dt, ang_freq, amp, phase_state, freq_off_state, step_std, bound_hz, rng)[source]#

Generate a sinusoid whose frequency slowly wanders, via phase accumulation.

The instantaneous frequency is base + offset where offset does a bounded random walk (clamped to +/- bound_hz). Phase is integrated sample-by-sample so the waveform stays continuous even as the frequency changes and across chunk boundaries.

Parameters:

n_samples (int) – Number of output samples for this chunk.
dt (float) – Sample period (seconds).
ang_freq (ndarray) – Base angular frequency 2*pi*f, shape (1, k).
amp (ndarray) – Amplitude, shape (1, k).
phase_state (ndarray) – Carried phase from the previous chunk, shape (1, k).
freq_off_state (ndarray) – Carried frequency offset (Hz), shape (1, k).
step_std (float) – Per-sample random-walk std (see freq_drift_step_std()); 0 disables drift (fixed frequency).
bound_hz (float) – Frequency offset is clamped to +/- bound_hz.
rng (Generator) – Random generator for the walk.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

(data, new_phase_state, new_freq_off_state) where data has shape (n_samples, k) and the two states have shape (1, k).

freq_drift_step_std(drift_rate_per_sec, dt)[source]#

Per-sample random-walk std that yields a given drift rate.

A frequency doing a zero-mean random walk with per-sample increment std s drifts with RMS s * sqrt(T/dt) over an interval T. Choosing s = drift_rate_per_sec * sqrt(dt) makes the RMS drift over 1 s equal to drift_rate_per_sec (Hz/s), independent of sample rate or chunking.

Return type:

float

Parameters:

drift_rate_per_sec (float)
dt (float)

Classes

class SinGenerator(*args, settings=None, **kwargs)[source]#

Bases: BaseClockDrivenUnit[SinGeneratorSettings, SinProducer]

Generates sinusoidal waveforms synchronized to clock ticks.

Receives timing from INPUT_CLOCK (LinearAxis from Clock) and outputs sinusoidal AxisArray on OUTPUT_SIGNAL.

Parameters:: settings (Settings | None)

SETTINGS#: alias of SinGeneratorSettings

class SinGeneratorSettings(fs, n_time=None, n_ch=1, freq=1.0, amp=1.0, phase=0.0, freq_drift_rate=0.0, freq_drift_bound=1.5, freq_drift_seed=None)[source]#

Bases: ClockDrivenSettings

Settings for SinGenerator.

Parameters:

fs (float)
n_time (int | None)
n_ch (int)
freq (float | ArrayLike)
amp (float | ArrayLike)
phase (float | ArrayLike)
freq_drift_rate (float)
freq_drift_bound (float)
freq_drift_seed (int | None)

n_ch: int = 1#: Number of channels to output.

freq: float | ArrayLike = 1.0#: The frequency of the sinusoid, in Hz. Scalar or per-channel array.

amp: float | ArrayLike = 1.0#: The amplitude of the sinusoid. Scalar or per-channel array.

phase: float | ArrayLike = 0.0#: The initial phase of the sinusoid, in radians. Scalar or per-channel array.

freq_drift_rate: float = 0.0#: Frequency drift rate in Hz per second (RMS wander over 1 s). When > 0 the frequency does a slow bounded random walk to emulate e.g. recording-clock drift. 0 (default) keeps the frequency fixed.

freq_drift_bound: float = 1.5#: The drifting frequency is clamped to +/- freq_drift_bound Hz around the base freq.

freq_drift_seed: int | None = None#: Random seed for the frequency-drift walk. If None, uses system entropy.

__init__(fs, n_time=None, n_ch=1, freq=1.0, amp=1.0, phase=0.0, freq_drift_rate=0.0, freq_drift_bound=1.5, freq_drift_seed=None)#

Parameters:

fs (float)
n_time (int | None)
n_ch (int)
freq (float | ArrayLike)
amp (float | ArrayLike)
phase (float | ArrayLike)
freq_drift_rate (float)
freq_drift_bound (float)
freq_drift_seed (int | None)

Return type:

None

class SinGeneratorState[source]#

Bases: ClockDrivenState

State for SinGenerator.

template: AxisArray | None = None#

ang_freq: ndarray | None = None#

amp: ndarray | None = None#

phase: ndarray | None = None#

drift_rng: Generator | None = None#

drift_phase: ndarray | None = None#

drift_freq_off: ndarray | None = None#

drift_step_std: float = 0.0#

class SinProducer(*args, **kwargs)[source]#

Bases: BaseClockDrivenProducer[SinGeneratorSettings, SinGeneratorState]

Generates sinusoidal waveforms synchronized to clock ticks.

Each clock tick produces a block of sinusoidal data based on the sample rate (fs) and chunk size (n_time) settings.

class SpiralGenerator(*args, settings=None, **kwargs)[source]#

Bases: BaseClockDrivenUnit[SpiralGeneratorSettings, SpiralProducer]

Generates 2D spiral motion synchronized to clock ticks.

Receives timing from INPUT_CLOCK (LinearAxis from Clock) and outputs 2D position AxisArray (x, y) on OUTPUT_SIGNAL.

The spiral pattern has both radius and angle varying over time: - Radius oscillates sinusoidally (breathing in/out) - Angle increases linearly (rotation)

Parameters:: settings (Settings | None)

SETTINGS#: alias of SpiralGeneratorSettings

class SpiralGeneratorSettings(fs, n_time=None, r_mean=150.0, r_amp=50.0, radial_freq=0.1, radial_phase=0.0, angular_freq=0.25, angular_phase=0.0)[source]#

Bases: ClockDrivenSettings

Settings for SpiralGenerator.

Generates 2D position (x, y) following a spiral pattern where both the radius and angle change over time.

The parametric equations are:: r(t) = r_mean + r_amp * sin(2*π*radial_freq*t + radial_phase) θ(t) = 2*π*angular_freq*t + angular_phase x(t) = r(t) * cos(θ(t)) y(t) = r(t) * sin(θ(t))

Parameters:

fs (float)
n_time (int | None)
r_mean (float)
r_amp (float)
radial_freq (float)
radial_phase (float)
angular_freq (float)
angular_phase (float)

r_mean: float = 150.0#: Mean radius of the spiral.

r_amp: float = 50.0#: Amplitude of the radial oscillation.

radial_freq: float = 0.1#: Frequency of the radial oscillation in Hz.

radial_phase: float = 0.0#: Initial phase of the radial oscillation in radians.

angular_freq: float = 0.25#: Frequency of the angular rotation in Hz.

angular_phase: float = 0.0#: Initial angular phase in radians.

__init__(fs, n_time=None, r_mean=150.0, r_amp=50.0, radial_freq=0.1, radial_phase=0.0, angular_freq=0.25, angular_phase=0.0)#

Parameters:

fs (float)
n_time (int | None)
r_mean (float)
r_amp (float)
radial_freq (float)
radial_phase (float)
angular_freq (float)
angular_phase (float)

Return type:

None

class SpiralGeneratorState[source]#

Bases: ClockDrivenState

State for SpiralGenerator.

template: AxisArray | None = None#

class SpiralProducer(*args, **kwargs)[source]#

Bases: BaseClockDrivenProducer[SpiralGeneratorSettings, SpiralGeneratorState]

Generates spiral motion synchronized to clock ticks.

Each clock tick produces a block of 2D position data (x, y) following a spiral pattern where both radius and angle change over time.