While

class braintools.cogtask.While(condition, body, max_iterations=100, name='While')

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.

Examples

>>> # Evidence accumulation until threshold
>>> phases = (
...     Fixation(500 * u.ms)
...     >> While(
...         lambda ctx: ctx.get('accumulated_evidence', 0) < threshold,
...         body=EvidenceSample(50 * u.ms),
...         max_iterations=50
...     )
...     >> Response(500 * u.ms)
... )

>>> # Repeated sampling with early termination
>>> phases = While(
...     lambda ctx: ctx.get('sample_count', 0) < ctx['required_samples'],
...     body=Sample(100 * u.ms),
...     max_iterations=20
... )

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.

children()

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)

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)

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)

Execute body phase while condition is true.

Return type:

None

execute_packed(ctx)

Packed-mode loop. The condition must return a Python bool; tracer-valued conditions are not supported here (would require lax.while_loop with a state-as-pytree wrapper).

Return type:

None

get_duration(ctx)

Estimate duration using max_iterations.

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

Return type:

int

max_steps(ctx)

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)

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