While#

class braintools.cogtask.While(condition, body, max_iterations=100, name='While')[source]#

Loop phase while condition is true.

Useful for tasks with variable numbers of repetitions, such as evidence accumulation until a threshold is reached.

Note: The duration computed by get_duration uses max_iterations as an upper bound, but actual execution may be shorter.

Parameters:
  • condition (Callable[[Context], bool]) – Function that returns True to continue looping.

  • body (Phase) – Phase to execute each iteration.

  • max_iterations (int) – Maximum number of iterations (safety limit).

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

Examples

>>> import brainunit as u
>>> import numpy as np
>>> from braintools.cogtask import Feature, Response, Stimulus, Task, While
>>> # Present a sample until the trial's required count is reached
>>> sample = Stimulus(10 * u.ms, inputs={'stimulus': 1.0},
...                   on_enter=lambda ctx: ctx.update(seen=ctx.get('seen', 0) + 1))
>>> loop = While(lambda ctx: ctx.get('seen', 0) < ctx['n_samples'],
...              body=sample, max_iterations=4)
>>> task = Task(
...     loop >> Response(10 * u.ms, outputs={'label': 1}),
...     Feature(1, 'stimulus'), Feature(2, 'choice'),
...     trial_init=lambda ctx: ctx.update(n_samples=2 + ctx['trial_index']),
...     dt=10.0 * u.ms,
... )
>>> task.max_trial_duration()  # 4 samples + 1 response step
5
>>> X, Y, info = task.sample_trial(0)  # two samples, then the response
>>> np.asarray(X[:, 0]).tolist(), np.asarray(info['mask']).tolist()
([1.0, 1.0, 0.0, 0.0, 0.0], [True, True, True, False, False])
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 body phase while condition is true.

Return type:

None

execute_packed(ctx)[source]#

Packed-mode loop (eager-only).

The loop is unrolled in Python, so the condition must evaluate to a concrete bool. This works for eager sample_trial but NOT under jit/vmap (batch_sample) when the condition depends on a traced value: we detect that case and raise a clear NotImplementedError instead of a cryptic TracerBoolConversionError. Full traced support would require a jax.lax.while_loop with the buffers + trial state threaded as a pytree, which is not yet implemented.

Return type:

None

get_duration(ctx)[source]#

Estimate duration using max_iterations.

Note: Actual duration may be less if condition becomes False.

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