braintools.input.Sinusoidal

class braintools.input.Sinusoidal(amplitude, frequency, duration, t_start=None, t_end=None, bias=False)

Composable sinusoidal input generator.

Creates a sinusoidal waveform with specified amplitude and frequency. This class is composable, allowing mathematical operations with other Input objects to create complex stimulation protocols.

The sinusoidal waveform is defined as:

\[I(t) = A \sin(2\pi f t)\]

where A is amplitude and f is frequency.

Parameters:

• amplitude (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Peak amplitude of the sinusoidal wave.

• frequency (Quantity) – Frequency of oscillation. Must be in Hz units.

• duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Total duration of the signal. Supports time units.

• t_start (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Time when sinusoid starts. Before this, output is 0. Default is 0.

• t_end (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Time when sinusoid ends. After this, output is 0. Default is duration.

• bias (bool) – If True, adds DC offset equal to amplitude (non-negative output). If False, oscillates around 0 (default).

amplitude

Peak amplitude of the sinusoid

Type:

float

frequency

Frequency of oscillation in Hz

Type:

Quantity

t_start

Start time of the sinusoid

Type:

float or Quantity

t_end

End time of the sinusoid

Type:

float or Quantity

bias

Whether DC bias is applied

Type:

bool

Examples

>>> import brainunit as u
>>> import brainstate
>>> brainstate.environ.set(dt=0.1 * u.ms)

Create simple sinusoidal input:

>>> sine = Sinusoidal(1.0, 10 * u.Hz, 1000 * u.ms)
>>> signal = sine()

Create amplitude-modulated signal:

>>> from braintools.input import Ramp
>>> carrier = Sinusoidal(1.0, 100 * u.Hz, 500 * u.ms)
>>> envelope = Ramp(0, 1, 500 * u.ms)
>>> am_signal = carrier * envelope

Create frequency beats by combining sinusoids:

>>> sine1 = Sinusoidal(1.0, 10 * u.Hz, 1000 * u.ms)
>>> sine2 = Sinusoidal(1.0, 11 * u.Hz, 1000 * u.ms)
>>> beats = sine1 + sine2  # 1 Hz beat frequency

Create complex waveform with harmonics:

>>> fundamental = Sinusoidal(1.0, 5 * u.Hz, 2000 * u.ms)
>>> third = Sinusoidal(0.3, 15 * u.Hz, 2000 * u.ms)
>>> fifth = Sinusoidal(0.2, 25 * u.Hz, 2000 * u.ms)
>>> complex_wave = fundamental + third + fifth

Test resonance with windowed sinusoid:

>>> resonance = Sinusoidal(
...     amplitude=2.0,
...     frequency=8 * u.Hz,  # Theta frequency
...     duration=5000 * u.ms,
...     t_start=1000 * u.ms,
...     t_end=4000 * u.ms
... )

Create phase-shifted sinusoids:

>>> sine1 = Sinusoidal(1.0, 10 * u.Hz, 1000 * u.ms)
>>> # Shift by 250ms (90 degrees for 10Hz)
>>> sine2 = sine1.shift(25 * u.ms)
>>> quadrature = sine1 + sine2

Sinusoid with positive bias (rectified):

>>> positive_sine = Sinusoidal(
...     amplitude=5.0,
...     frequency=5 * u.Hz,
...     duration=2000 * u.ms,
...     bias=True  # Oscillates between 0 and 10
... )

Notes

• Phase starts at 0 (sine wave starts at 0)

• Frequency should be less than Nyquist frequency (1/(2*dt))

• With bias=True, output ranges from 0 to 2*amplitude

• Without bias, output ranges from -amplitude to +amplitude

• Can be combined with other Input classes using +, -, *, /

See also

Square

Square wave generator

Chirp

Frequency sweep generator

NoisySinusoidal

Sinusoid with additive noise

sinusoidal

Functional API for sinusoidal input

__init__(amplitude, frequency, duration, t_start=None, t_end=None, bias=False)

Initialize the Input base class.

Parameters:

duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – The total duration of the input.

Methods

__init__(amplitude, frequency, duration[, ...])	Initialize the Input base class.
apply(func)	Apply a custom function to the input.
clip([min_val, max_val])	Clip the input values to a range.
generate()	Generate the sinusoidal input using the functional API.
repeat(n_times)	Repeat the input pattern n times.
scale(factor)	Scale the input by a factor.
shift(time_shift)	Shift the input in time.
smooth(tau)	Apply exponential smoothing to the input.

Attributes

dt	Get the time step from global environment.
n_steps	Get the number of time steps.
shape	Get the shape of the input array.