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 increments (white noise), 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)]) # list of (value, duration) pairs
# 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)]) # returns (array, total duration)
# 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: each amplitude holds from its start time to the next one
step = Step(
amplitudes=[0, 1, 0.5] * u.nA,
step_times=[0, 100, 400] * u.ms,
duration=500 * u.ms
)
# Linear ramp
ramp = Ramp(0 * u.nA, 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
)
# Five 20 ms windows of 100 Hz oscillation, 80 ms apart
burst = Burst(
n_bursts=5,
burst_amp=1 * u.nA,
burst_freq=100 * u.Hz,
burst_duration=20 * u.ms,
inter_burst_interval=80 * 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 increments dW ~ N(0, sigma^2 dt): white noise, not the path W(t)
wiener = WienerProcess(
duration=1000 * u.ms,
sigma=0.1 * u.nA,
seed=42
)
# Ornstein-Uhlenbeck process; sigma is its stationary standard deviation
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.
Functional API#
Basic currents#
|
Format an input current with different sections. |
|
Format constant input currents with specified durations. |
|
Generate step function input with multiple levels. |
|
Generate a linearly ramped input current. |
Pulse generators#
|
Format current input like a series of short-time spikes. |
|
Generate Gaussian pulse input. |
|
Generate exponentially decaying input. |
|
Generate double exponential input (alpha function). |
|
Generate burst pattern input. |
Stochastic processes#
|
Generate Wiener-process increments (Gaussian white noise). |
|
Generate Ornstein-Uhlenbeck process input. |
|
Generate Poisson spike train input. |
Waveforms#
|
Generate sinusoidal current input. |
|
Generate square wave current input. |
|
Generate triangular wave current input. |
|
Generate sawtooth wave current input. |
|
Generate chirp (frequency sweep) current input. |
|
Generate sinusoidal current input with additive noise. |
Composable API#
Base classes and utilities#
|
Base class for composable input currents. |
|
Composite input created by combining two inputs with an operator. |
|
A constant value input. |
|
Sequential composition of two inputs. |
|
Time-shifted version of an input. |
|
Clipped version of an input. |
|
Exponentially smoothed version of an input. |
|
Repeated version of an input pattern. |
|
Custom transformation applied to an input. |
Basic currents#
|
Generate input current with different sections. |
|
Generate constant input with specified durations. |
|
Generate step function input with multiple levels. |
|
Generate linearly changing (ramp) input current. |
Pulse generators#
|
Generate spike input at specified times. |
|
Generate Gaussian-shaped pulse input. |
|
Generate exponentially decaying input. |
|
Generate double exponential (alpha function) input. |
|
Generate burst pattern input. |
Stochastic processes#
|
Generate Wiener-process increments (Gaussian white noise). |
|
Generate Ornstein-Uhlenbeck process input. |
|
Generate Poisson spike train input. |
Waveforms#
|
Composable sinusoidal input generator. |
|
Composable square wave input generator. |
|
Composable triangular wave input generator. |
|
Composable sawtooth wave input generator. |
|
Composable chirp (frequency sweep) signal generator. |
|
Composable sinusoidal input with additive noise. |