If#

class braintools.cogtask.If(condition, then, else_=None, name='If')[source]#

Conditional phase selection based on a boolean condition.

Evaluates the condition at runtime and executes either the then phase or the else_ phase (if provided).

Note

Under batch_sample (jit/vmap) the branch is selected with jax.lax.cond, so both branches are traced. The output buffers (X/Y/mask) are correct, but Python-side ctx state written inside a branch (and phase_history) reflects whichever branch traced last, not the one actually taken. Do not read branch-written ctx[...] values in get_trial_meta or downstream phases when batching; gate such state on the same condition at the top level instead.

Parameters:
  • condition (Callable[[Context], bool]) – Function that takes context and returns True/False.

  • then (Phase) – Phase to execute if condition is True.

  • else_ (Phase | None) – Phase to execute if condition is False.

  • name (str) – Name for this conditional phase.

Examples

>>> import brainunit as u
>>> import numpy as np
>>> from braintools.cogtask import Feature, Fixation, If, Response, Task
>>> # Go / no-go: the response label depends on the trial
>>> respond = If(
...     lambda ctx: ctx['is_go'],
...     then=Response(20 * u.ms, outputs={'label': 1}, name='go'),
...     else_=Response(20 * u.ms, outputs={'label': 0}, name='nogo'),
... )
>>> respond
If(then=go, else=nogo)
>>> task = Task(
...     Fixation(20 * u.ms, inputs={'fixation': 1.0}) >> respond,
...     Feature(1, 'fixation'), Feature(2, 'choice'),
...     trial_init=lambda ctx: ctx.update(is_go=ctx['trial_index'] % 2 == 0),
...     dt=10.0 * u.ms,
... )
>>> task.is_variable_length
True
>>> [np.asarray(task.sample_trial(i)[1]).tolist() for i in range(2)]
[[0, 0, 1, 1], [0, 0, 0, 0]]
children()[source]#

Return the immediate child phases of a compound phase.

Leaf phases return []. Subclasses like Sequence, Repeat, Parallel, If, Switch, While override this so that the Task can traverse the whole tree to bind features.

encode_inputs(ctx)[source]#

Fill ctx.inputs[phase_start:phase_end] with input encoding.

Called once per phase after duration is determined. Must modify ctx.inputs in-place.

Parameters:

ctx (Context) – Context with input buffer and trial state.

Return type:

None

encode_outputs(ctx)[source]#

Fill ctx.outputs[phase_start:phase_end] with target encoding.

Called once per phase after duration is determined. Must modify ctx.outputs in-place.

Parameters:

ctx (Context) – Context with output buffer and trial state.

Return type:

None

execute(ctx)[source]#

Execute the appropriate branch based on condition.

Return type:

None

execute_packed(ctx)[source]#

Packed-mode branch using jax.lax.cond.

Both branches mutate ctx.inputs/outputs/mask/t_cursor. To make the cond functional we (a) snapshot ctx._state so per-branch scratch writes don’t leak across branches, and (b) thread the buffer state through lax.cond as a pytree. Anything not in that pytree (e.g. ctx.phase_history) is best-effort metadata and may contain entries from both branches during tracing — it is not part of the trial’s tensor output.

Return type:

None

get_duration(ctx)[source]#

Duration depends on which branch is taken.

Return type:

int

max_steps(ctx)[source]#

Static upper bound on this phase’s length in timesteps.

Must return a Python int with no dependence on traced values. Used by Task in variable-length mode to size shape-stable buffers. The default delegates to get_duration which is correct for fixed-duration phases. Variable-duration phases (e.g. those wrapping TruncExp/UniformDuration) override this to return the truncation upper bound divided by ctx.dt.

Parameters:

ctx (Context) – A stub or trial context providing ctx.dt. The default implementation does not read ctx.rng or trial state.

Returns:

Upper bound on number of timesteps for this phase.

Return type:

int

step_count(ctx)[source]#

Traced actual length of this phase in timesteps.

Returns a jax.Array int32 scalar. May depend on ctx[...] values populated by trial_init. Must satisfy 0 <= step_count(ctx) <= max_steps(ctx) for every trial.

The default returns a static value equal to get_duration; that is correct for any phase whose actual length matches its upper bound. Variable-duration phases override this to compute the traced length from ctx state without any int(...) cast.

Return type:

Array