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 withjax.lax.cond, so both branches are traced. The output buffers (X/Y/mask) are correct, but Python-sidectxstate written inside a branch (andphase_history) reflects whichever branch traced last, not the one actually taken. Do not read branch-writtenctx[...]values inget_trial_metaor downstream phases when batching; gate such state on the same condition at the top level instead.- Parameters:
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 likeSequence,Repeat,Parallel,If,Switch,Whileoverride this so that theTaskcan 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.
- 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.
- 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) snapshotctx._stateso per-branch scratch writes don’t leak across branches, and (b) thread the buffer state throughlax.condas 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:
- 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
Taskin variable-length mode to size shape-stable buffers. The default delegates toget_durationwhich is correct for fixed-duration phases. Variable-duration phases (e.g. those wrappingTruncExp/UniformDuration) override this to return the truncation upper bound divided byctx.dt.
- step_count(ctx)[source]#
Traced actual length of this phase in timesteps.
Returns a
jax.Arrayint32scalar. May depend onctx[...]values populated bytrial_init. Must satisfy0 <= 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 fromctxstate without anyint(...)cast.- Return type:
Array