braintools.input module

`braintools.input` module#

Input Current Generation for Neural Simulations.

This module provides comprehensive tools for generating input currents for neural simulations, supporting both composable object-oriented API and functional API.

Key Features:

Composable API: Object-oriented interface with operator overloading
Functional API: Traditional function-based interface for backward compatibility
Basic Inputs: Constant, step, ramp, section-based currents
Pulse Patterns: Spikes, Gaussian pulses, exponential shapes, bursts
Waveforms: Sinusoidal, square, triangular, sawtooth, chirp
Stochastic Processes: Wiener process, Ornstein-Uhlenbeck process, Poisson
Unit-Aware: Full integration with BrainUnit for physical quantities

Quick Start - Composable API (Recommended):

import brainunit as u
import brainstate
from braintools.input import Ramp, Sinusoidal, Constant

# Set time step
brainstate.environ.set(dt=0.1 * u.ms)

# Create basic inputs
ramp = Ramp(0, 1, 500 * u.ms)
sine = Sinusoidal(0.5, 10 * u.Hz, 500 * u.ms)
baseline = Constant(0.2, 500 * u.ms)

# Combine using operators
combined = baseline + ramp + sine * 0.5

# Apply transformations
clipped = combined.clip(0, 1)
smoothed = clipped.smooth(10 * u.ms)

# Generate the array
current = smoothed()

Quick Start - Functional API:

import brainunit as u
import brainstate
from braintools.input import ramp, sinusoidal, constant

# Set time step
brainstate.environ.set(dt=0.1 * u.ms)

# Generate inputs
ramp_signal = ramp(0, 1, 500 * u.ms)
sine_signal = sinusoidal(0.5, 10 * u.Hz, 500 * u.ms)
baseline_signal = constant(0.2, 500 * u.ms)

# Combine using array operations
combined = baseline_signal + ramp_signal + sine_signal * 0.5

Basic Inputs:

import brainunit as u
import brainstate
from braintools.input import Section, Constant, Step, Ramp

brainstate.environ.set(dt=0.1 * u.ms)

# Section-based input (different phases)
section = Section(
    values=[0, 1, 0.5, 0] * u.nA,
    durations=[100, 200, 200, 100] * u.ms
)

# Constant current
const = Constant(1.5 * u.nA, 500 * u.ms)

# Step function
step = Step(
    values=[0, 1, 0.5],
    times=[0, 100, 400],
    duration=500 * u.ms
)

# Linear ramp
ramp = Ramp(0, 2 * u.nA, 500 * u.ms)

Pulse Patterns:

import brainunit as u
import brainstate
from braintools.input import (
    Spike, GaussianPulse, ExponentialDecay,
    DoubleExponential, Burst
)

brainstate.environ.set(dt=0.1 * u.ms)

# Spike train
spikes = Spike(
    sp_times=[100, 200, 300] * u.ms,
    duration=500 * u.ms,
    sp_lens=2 * u.ms,
    sp_sizes=[1, 1.5, 1.2] * u.nA
)

# Gaussian pulse
pulse = GaussianPulse(
    amplitude=2 * u.nA,
    center=250 * u.ms,
    sigma=50 * u.ms,
    duration=500 * u.ms
)

# Exponential decay (e.g., EPSC)
exp_decay = ExponentialDecay(
    amplitude=1 * u.nA,
    tau=20 * u.ms,
    t_start=100 * u.ms,
    duration=500 * u.ms
)

# Double exponential (realistic synapse)
synapse = DoubleExponential(
    amplitude=1 * u.nA,
    tau_rise=2 * u.ms,
    tau_decay=20 * u.ms,
    t_start=100 * u.ms,
    duration=500 * u.ms
)

# Burst of activity
burst = Burst(
    amplitude=1 * u.nA,
    n_pulses=5,
    pulse_duration=10 * u.ms,
    interval=50 * u.ms,
    t_start=100 * u.ms,
    duration=500 * u.ms
)

Waveforms:

import brainunit as u
import brainstate
from braintools.input import (
    Sinusoidal, Square, Triangular,
    Sawtooth, Chirp, NoisySinusoidal
)

brainstate.environ.set(dt=0.1 * u.ms)

# Sinusoidal
sine = Sinusoidal(
    amplitude=1 * u.nA,
    frequency=10 * u.Hz,
    duration=1000 * u.ms
)

# Square wave
square = Square(
    amplitude=1 * u.nA,
    frequency=5 * u.Hz,
    duration=1000 * u.ms,
    duty_cycle=0.5
)

# Triangular wave
triangle = Triangular(
    amplitude=1 * u.nA,
    frequency=5 * u.Hz,
    duration=1000 * u.ms
)

# Sawtooth wave
sawtooth = Sawtooth(
    amplitude=1 * u.nA,
    frequency=5 * u.Hz,
    duration=1000 * u.ms
)

# Chirp (frequency sweep)
chirp = Chirp(
    amplitude=1 * u.nA,
    f_start=1 * u.Hz,
    f_end=50 * u.Hz,
    duration=1000 * u.ms
)

# Noisy sinusoidal
noisy_sine = NoisySinusoidal(
    amplitude=1 * u.nA,
    frequency=10 * u.Hz,
    duration=1000 * u.ms,
    noise_amplitude=0.1 * u.nA
)

Stochastic Processes:

import brainunit as u
import brainstate
from braintools.input import WienerProcess, OUProcess, Poisson

brainstate.environ.set(dt=0.1 * u.ms)

# Wiener process (Brownian motion)
wiener = WienerProcess(
    duration=1000 * u.ms,
    sigma=0.1 * u.nA,
    seed=42
)

# Ornstein-Uhlenbeck process
ou = OUProcess(
    duration=1000 * u.ms,
    mean=0.5 * u.nA,
    sigma=0.2 * u.nA,
    tau=20 * u.ms,
    seed=42
)

# Poisson spike train
poisson = Poisson(
    duration=1000 * u.ms,
    rate=20 * u.Hz,
    amplitude=1 * u.nA,
    seed=42
)

Composability:

import brainunit as u
import brainstate
from braintools.input import Constant, Sinusoidal, WienerProcess

brainstate.environ.set(dt=0.1 * u.ms)

# Build complex stimulation protocols
baseline = Constant(0.5 * u.nA, 1000 * u.ms)
modulation = Sinusoidal(0.3 * u.nA, 5 * u.Hz, 1000 * u.ms)
noise = WienerProcess(1000 * u.ms, sigma=0.05 * u.nA)

# Combine with operators
signal = baseline + modulation + noise

# Apply transformations
clipped = signal.clip(0 * u.nA, 1.5 * u.nA)
smoothed = clipped.smooth(5 * u.ms)
delayed = smoothed.shift(50 * u.ms)

# Sequential concatenation
protocol = baseline & modulation & baseline

# Generate
current = protocol()

The input toolkit offers both functional helpers and composable classes for constructing stimulation protocols. The tables below group the public API by category. Legacy names ending with Input/_input remain available as deprecated aliases and emit DeprecationWarning when used.

Functional API#

Basic currents#

`section`(values, durations[, return_length])	Format an input current with different sections.
`constant`(I_and_duration)	Format constant input currents with specified durations.
`step`(amplitudes, step_times[, duration])	Generate step function input with multiple levels.
`ramp`(c_start, c_end, duration[, t_start, t_end])	Generate a linearly ramped input current.

Pulse generators#

`spike`(sp_times, sp_lens, sp_sizes, duration)	Format current input like a series of short-time spikes.
`gaussian_pulse`(amplitude, center, sigma, ...)	Generate Gaussian pulse input.
`exponential_decay`(amplitude, tau, duration)	Generate exponentially decaying input.
`double_exponential`(amplitude, tau_rise, ...)	Generate double exponential input (alpha function).
`burst`(burst_amp, burst_freq, burst_duration, ...)	Generate burst pattern input.

Stochastic processes#

`wiener_process`(duration[, sigma, n, ...])	Generate Wiener process (Brownian motion) input.
`ou_process`(mean, sigma, tau, duration[, n, ...])	Generate Ornstein-Uhlenbeck process input.
`poisson`(rate, duration[, amplitude, n, ...])	Generate Poisson spike train input.

Waveforms#

`sinusoidal`(amplitude, frequency, duration[, ...])	Generate sinusoidal current input.
`square`(amplitude, frequency, duration[, ...])	Generate square wave current input.
`triangular`(amplitude, frequency, duration[, ...])	Generate triangular wave current input.
`sawtooth`(amplitude, frequency, duration[, ...])	Generate sawtooth wave current input.
`chirp`(amplitude, f_start, f_end, duration[, ...])	Generate chirp (frequency sweep) current input.
`noisy_sinusoidal`(amplitude, frequency, ...)	Generate sinusoidal current input with additive noise.

Composable API#

Base classes and utilities#

`Input`(duration)	Base class for composable input currents.
`Composite`(input1, input2, operator)	Composite input created by combining two inputs with an operator.
`ConstantValue`(value, duration)	A constant value input.
`Sequential`(*inputs)	Sequential composition of two inputs.
`TimeShifted`(input_obj, time_shift)	Time-shifted version of an input.
`Clipped`(input_obj[, min_val, max_val])	Clipped version of an input.
`Smoothed`(input_obj, tau)	Exponentially smoothed version of an input.
`Repeated`(input_obj, n_times)	Repeated version of an input pattern.
`Transformed`(input_obj, func)	Custom transformation applied to an input.

Basic currents#

`Section`(values, durations)	Generate input current with different sections.
`Constant`(I_and_duration)	Generate constant input with specified durations.
`Step`(amplitudes, step_times[, duration])	Generate step function input with multiple levels.
`Ramp`(c_start, c_end, duration[, t_start, t_end])	Generate linearly changing (ramp) input current.

Pulse generators#

`Spike`(sp_times, duration[, sp_lens, sp_sizes])	Generate spike input at specified times.
`GaussianPulse`(amplitude, center, sigma, duration)	Generate Gaussian-shaped pulse input.
`ExponentialDecay`(amplitude, tau, duration[, ...])	Generate exponentially decaying input.
`DoubleExponential`(amplitude, tau_rise, ...)	Generate double exponential (alpha function) input.
`Burst`(n_bursts, burst_amp, burst_freq, ...)	Generate burst pattern input.

Stochastic processes#

`WienerProcess`(duration[, n, t_start, t_end, ...])	Generate Wiener process (Brownian motion) input.
`OUProcess`(mean, sigma, tau, duration[, n, ...])	Generate Ornstein-Uhlenbeck process input.
`Poisson`(rate, duration[, n, t_start, t_end, ...])	Generate Poisson spike train input.

Waveforms#

`Sinusoidal`(amplitude, frequency, duration[, ...])	Composable sinusoidal input generator.
`Square`(amplitude, frequency, duration[, ...])	Composable square wave input generator.
`Triangular`(amplitude, frequency, duration[, ...])	Composable triangular wave input generator.
`Sawtooth`(amplitude, frequency, duration[, ...])	Composable sawtooth wave input generator.
`Chirp`(amplitude, f_start, f_end, duration[, ...])	Composable chirp (frequency sweep) signal generator.
`NoisySinusoidal`(amplitude, frequency, ...[, ...])	Composable sinusoidal input with additive noise.

braintools.input module

Contents

braintools.input module#

Functional API#

Basic currents#

Pulse generators#

Stochastic processes#

Waveforms#

Composable API#

Base classes and utilities#

Basic currents#

Pulse generators#

Stochastic processes#

Waveforms#

`braintools.input` module#