Tutorial 1: Quickstart with braintools.cogtask#

braintools.cogtask is a modular framework for building cognitive-task data for neural-network training and computational neuroscience simulations. This quickstart uses a fixed-length perceptual decision-making task and covers the current API for:

  1. Importing cogtask and choosing a time step.

  2. Sampling one reproducible trial from a pre-built task.

  3. Sampling JIT/vmap-friendly batches for training loops.

  4. Reading X, Y, metadata, masks, and class counts.

  5. Changing the sampling time step without relying on stale JIT shapes.

1. Setup#

Task durations are specified in real time, such as 1500 * u.ms, and are resolved to integer timesteps through a dt. You can set an ambient default with brainstate.environ.set(dt=...). For code that uses the JIT-compiled batch_sample method, prefer passing dt= to the task constructor so the static timestep count is tied to the task object itself.

import numpy as np
import brainstate
import brainunit as u

from braintools import cogtask

DT = 1.0 * u.ms
brainstate.environ.set(dt=DT)

2. Create a pre-built task#

Pre-built tasks are exported from braintools.cogtask. Their constructors accept paradigm-specific parameters, such as stimulus duration and number of choices, plus common Task options such as seed=, dt=, output_mode=, and num_classes=.

Here we use categorical output mode, the default. The target Y is a 1-D array of integer class labels over time.

def make_pdm(dt=DT, seed=0):
    return cogtask.PerceptualDecisionMaking(
        t_stimulus=1500 * u.ms,
        num_choices=2,
        seed=seed,
        dt=dt,
    )


task = make_pdm()
task
Task(name=PerceptualDecisionMaking, inputs=9, outputs=3, output_mode=categorical)

3. Sample one trial#

sample_trial(index) returns (X, Y, info):

  • X: input tensor with shape (T, num_inputs).

  • Y: target tensor with shape (T,) in categorical mode, or (T, num_outputs) in vector mode.

  • info: Python-side metadata with phase_history, trial_state, dt, index, and mask.

For this fixed-length task, info['mask'] is None. Variable-length tasks use a boolean mask; Tutorial 3 covers that path in detail.

X, Y, info = task.sample_trial(0)

print('X.shape =', X.shape)
print('Y.shape =', Y.shape)
print('num_inputs =', task.num_inputs)
print('num_outputs =', task.num_outputs)
print('num_classes =', task.num_classes)
print('info keys =', sorted(info))
print("info['mask'] =", info['mask'])
X.shape = (1700, 9)
Y.shape = (1700,)
num_inputs = 9
num_outputs = 3
num_classes = 3
info keys = ['dt', 'index', 'mask', 'phase_history', 'trial_state']
info['mask'] = None

num_outputs is the width of the output FeatureSet. In categorical mode, model heads should usually use task.num_classes, because Y stores class ids rather than dense output vectors.

phase_history is useful for debugging task timing. Each entry is (name, start, end) in timesteps. Compound composition nodes (Sequence, Parallel, Repeat, …) are recorded too, after their children, with their own full span – here the top-level Sequence covers the whole trial.

for name, start, end in info['phase_history']:
    print(f'{name:<12s}  [{start:4d} : {end:4d})')
fixation      [   0 :  100)
stimulus      [ 100 : 1600)
response      [1600 : 1700)
Sequence      [   0 : 1700)
state = info['trial_state']
print('trial_index =', int(state['trial_index']))
print('ground_truth =', int(state['ground_truth']))
print('coherence =', f"{float(state['coherence']):.1f}")
print('stimulus_direction =', f"{float(state['stimulus_direction']):.3f}")
trial_index = 0
ground_truth = 0
coherence = 25.6
stimulus_direction = 0.000

4. Sample batches for training#

batch_sample(B) is the JIT/vmap-compiled entry point. It returns time-first arrays by default, matching common RNN conventions.

Call

Returned shapes

task.sample_trial(i)

X: (T, num_inputs), Y: (T,) or (T, num_outputs)

task.batch_sample(B)

X: (T, B, num_inputs), Y: (T, B) or (T, B, num_outputs)

task.batch_sample(B, time_first=False)

X: (B, T, num_inputs), Y: (B, T) or (B, T, num_outputs)

task.batch_sample(B, return_mask=True)

adds mask with the same time/batch layout as Y

task.batch_sample(B, return_meta=True)

adds batched metadata from get_trial_meta

return_mask=True also works for fixed-length tasks; the returned mask is all True. That makes it convenient to write one training loop for fixed- and variable-length tasks.

Xb, Yb, mask = task.batch_sample(32, return_mask=True)

print('Xb.shape =', Xb.shape)
print('Yb.shape =', Yb.shape)
print('mask.shape =', mask.shape)
print('all mask entries valid?', bool(np.asarray(mask).all()))
Xb.shape = (1700, 32, 9)
Yb.shape = (1700, 32)
mask.shape = (1700, 32)
all mask entries valid? True

Reproducible batches#

When Task is constructed with seed=N, each trial uses jax.random.fold_in(PRNGKey(N), index) as its per-trial random key. Two calls with the same start_index produce identical batches; advancing start_index gives a fresh, non-overlapping slice of trials.

X1, Y1 = task.batch_sample(8, start_index=0)
X2, Y2 = task.batch_sample(8, start_index=0)
X3, Y3 = task.batch_sample(8, start_index=8)

same_start = (
    np.array_equal(np.asarray(X1), np.asarray(X2))
    and np.array_equal(np.asarray(Y1), np.asarray(Y2))
)
next_start_differs = not np.array_equal(np.asarray(X1), np.asarray(X3))

print('same start_index identical?', same_start)
print('next start_index differs?', next_start_differs)
same start_index identical? True
next start_index differs? True

Streaming batches through training#

A typical training loop increments start_index by batch_size at every step. Passing return_mask=True from the start keeps the loop compatible with both fixed- and variable-length tasks.

batch_size = 16
num_steps = 4

for step in range(num_steps):
    Xb, Yb, mask = task.batch_sample(
        batch_size,
        start_index=step * batch_size,
        return_mask=True,
    )
    # train_step(model, Xb, Yb, mask)
    print(
        f'step {step:>2d}  X={Xb.shape}  Y={Yb.shape}  mask={mask.shape}'
    )
step  0  X=(1700, 16, 9)  Y=(1700, 16)  mask=(1700, 16)
step  1  X=(1700, 16, 9)  Y=(1700, 16)  mask=(1700, 16)
step  2  X=(1700, 16, 9)  Y=(1700, 16)  mask=(1700, 16)
step  3  X=(1700, 16, 9)  Y=(1700, 16)  mask=(1700, 16)

5. Change dt safely#

The real-time phase durations stay fixed when dt changes; only the number of timesteps changes. Because batch_sample is JIT-compiled and returns static shapes, create a task with the desired dt instead of wrapping repeated batch calls on the same task in different ambient brainstate.environ.context(dt=...) blocks.

fine_task = make_pdm(dt=0.5 * u.ms)
coarse_task = make_pdm(dt=2.0 * u.ms)

X_fine, _ = fine_task.batch_sample(4)
X_coarse, _ = coarse_task.batch_sample(4)

print('dt=0.5 ms  ->  T =', X_fine.shape[0])
print('dt=2.0 ms  ->  T =', X_coarse.shape[0])
dt=0.5 ms  ->  T = 3400
dt=2.0 ms  ->  T = 850

6. Where to next#

  • Tutorial 2 - Building custom tasks: phase composition, features, encoders, label helpers, and class-based Task subclasses.

  • Tutorial 3 - Variable-length trial sequences: VariableDuration, conditional control flow, packed buffers, masks, and masked losses.

  • API reference: see braintools.cogtask in the API Reference section for the full list of pre-built tasks, encoders, phases, and utilities.