HabituationTaskKind

RL4CRN.utils.default_tasks.HabituationTaskKind

HabituationGapTaskKind

Bases: TaskKindBase

Habituation/sensitization task with two pulse trains separated by a gap.

pretty_help(*, width=100, bullet='-', return_str=False) classmethod

Pretty-print the task-kind help specification in a Markdown-like list format.

This uses cls.help() (a static method implemented by each TaskKind). The expected shape is:

{
  "required": {<key>: <description>, ...},
  "optional": {<key>: <description>, ...},
  "notes": <string or list of strings>
}

PARAMETER	DESCRIPTION
width	Maximum line width for wrapping descriptions. TYPE: int DEFAULT: 100
bullet	Bullet marker to use for list items (default "-"). TYPE: str DEFAULT: '-'
return_str	If True, return the formatted string instead of printing. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Optional[str]	If return_str=True, returns the formatted help string. Otherwise None.

build_time_horizon(task)

Build or reuse the time horizon.

PARAMETER	DESCRIPTION
task	TaskSpec instance. TYPE: TaskSpec

RETURNS	DESCRIPTION
ndarray	Time grid array of shape (n_t,) float32.

build_u_list(task, overrides)

Build or override the u_list for evaluation.

Precedence

overrides['u_list'] overrides['u_spec'] task.u_list (if user provided explicit list) task.u_spec (special tags only) TaskKind.default_u_list(task) # kind-specific semantics

PARAMETER	DESCRIPTION
task	TaskSpec instance. TYPE: TaskSpec
overrides	Override dictionary. TYPE: Dict[str, Any]

RETURNS	DESCRIPTION
List[ndarray]	List of input vectors (float32 arrays), each shape (p,).

build_ic(task, overrides)

Build the IC object from spec or override.

PARAMETER	DESCRIPTION
task	TaskSpec instance. TYPE: TaskSpec
overrides	Override dictionary, may contain 'ic_spec'. TYPE: Dict[str, Any]

RETURNS	DESCRIPTION
Any	RL4CRN IC object.

build_weights(task, overrides)

Build weights if needed by the task kind.

PARAMETER	DESCRIPTION
task	TaskSpec instance. TYPE: TaskSpec
overrides	Override dictionary, may contain 'weights_spec'. TYPE: Dict[str, Any]

RETURNS	DESCRIPTION
Optional[ndarray]	Weight matrix or None.

build_on_off_gap_time_horizon(*, t_on, t_off, t_gap, n_repeats_pre, n_repeats_post, n_t, dtype=np.float32)

Build a piecewise time horizon with an OFF gap between two pulse trains.

Each segment time grid is a local linspace from 0..Tseg (legacy format). Segment layout: [ON, OFF] * n_repeats_pre + [GAP_OFF] + [ON, OFF] * n_repeats_post

PARAMETER	DESCRIPTION
t_on	Duration of each ON segment. TYPE: float
t_off	Duration of each OFF segment. TYPE: float
t_gap	Duration of the long OFF gap between trains. TYPE: float
n_repeats_pre	Number of ON/OFF repetitions before the gap. TYPE: int
n_repeats_post	Number of ON/OFF repetitions after the gap. TYPE: int
n_t	Total number of time samples distributed across segments. TYPE: int
dtype	Numpy dtype for time arrays. DEFAULT: float32

RETURNS	DESCRIPTION
List[ndarray]	List of 1D numpy arrays, one per segment, each spanning [0, Tseg].

RAISES	DESCRIPTION
ValueError	If durations or repeats are invalid, or n_t too small.

build_u_nested_list_with_gap(*, u_list, n_repeats_pre, n_repeats_post, off_value=0.0)

Build ON/OFF input protocols with an OFF gap between trains.

For each u in u_list, produces: [u, u_off] * n_repeats_pre + [u_off] + [u, u_off] * n_repeats_post

PARAMETER	DESCRIPTION
u_list	List of constant input vectors (shape (p,)). TYPE: List[ndarray]
n_repeats_pre	Number of ON/OFF repetitions before the gap. TYPE: int
n_repeats_post	Number of ON/OFF repetitions after the gap. TYPE: int
off_value	Scalar OFF value broadcast to all inputs. TYPE: float DEFAULT: 0.0

RETURNS	DESCRIPTION
List[List[ndarray]]	List of protocols, one per u. Each protocol is a list of (p,) arrays,
List[List[ndarray]]	length (2n_repeats_pre + 1 + 2n_repeats_post).

extract_peaks_pre_post_from_piecewise(intervals, t, y, n_repeats_pre, n_repeats_post, LARGE_NUMBER=10000.0)

Extract stimulus peaks before and after a gap from a piecewise protocol.

Assumes segment layout

[ON, OFF]n_repeats_pre + [GAP_OFF] + [ON, OFF]n_repeats_post

Intervals are legacy local grids (0..Tseg). This function converts them to absolute [start, end] bounds by cumulative durations.

PARAMETER	DESCRIPTION
intervals	Segment intervals in legacy format (0..Tseg). TYPE: Sequence[Tuple[float, float]]
t	Stitched absolute time vector (T,). TYPE: ndarray
y	Single-scenario output trajectory, shape (q, T) or (T,). TYPE: ndarray
n_repeats_pre	Pulses before gap. TYPE: int
n_repeats_post	Pulses after gap. TYPE: int
LARGE_NUMBER	Value to return if a segment has no samples. TYPE: float DEFAULT: 10000.0

RETURNS	DESCRIPTION
peaks_pre	List of peaks in ON segments before the gap. TYPE: List[float]
peaks_post	List of peaks in ON segments after the gap. TYPE: List[float]

steady_state_ic_list(crn, u_list, x0_guess=None)

Compute steady-state initial conditions for a list of constant inputs.

Uses fsolve on: rate_function(t=0, x, u) = 0, warm-started from the previous solution.

PARAMETER	DESCRIPTION
crn	CRN object with rate_function(t, x, u).
u_list	List of input vectors to solve steady state for. TYPE: List[ndarray]
x0_guess	Optional initial guess for the first solve (shape (n,)). DEFAULT: None

RETURNS	DESCRIPTION
List[ndarray]	List of steady-state state vectors, one per u in u_list.

RAISES	DESCRIPTION
ValueError	If x0_guess has wrong length.
RuntimeError	If solver returns unexpected size.

habituation_metric_multifreq_with_gap(*, pulse_shapes, t_gap, n_repeats_pre, n_repeats_post, n_t, crn, u_nested_builder, u_list_local, x0_list, ratio_weights, gap_weight, recovery_tol, dishabituate_rho, min_peak, max_peak, freq_weight=1.0, LARGE_NUMBER=10000.0, single_frequency_mode=False, sensitization=False)

Evaluate habituation (or sensitization) across multiple pulse frequencies with a gap.

For each pulse shape (t_on, t_off), this function: 1) builds an ON/OFF protocol with a long OFF gap, 2) simulates the CRN, 3) computes a per-frequency loss via habituation_metric_with_gap, 4) optionally adds a cross-frequency monotonicity penalty based on early-peak slope.

The returned debug info includes a freq_runs payload suitable for plotting.

PARAMETER	DESCRIPTION
pulse_shapes	List of (t_on, t_off) pairs. TYPE: Sequence[Tuple[float, float]]
t_gap	Duration of the long OFF gap. TYPE: float
n_repeats_pre	Pulses before the gap. TYPE: int
n_repeats_post	Pulses after the gap. TYPE: int
n_t	Total time samples for each simulation. TYPE: int
crn	CRN object providing transient_response_piecewise(...).
u_nested_builder	Builder for the piecewise input list (kept for API compatibility).
u_list_local	List of constant input vectors defining scenarios. TYPE: List[ndarray]
x0_list	List of initial conditions (usually length 1 in your setup). TYPE: List[ndarray]
ratio_weights	Weights for ratio-based terms (passed through).
gap_weight	Weight for the gap-consistency penalty. TYPE: float
recovery_tol	Relative tolerance for recovery across the gap. TYPE: float
dishabituate_rho	Optional constraint on post-gap response. TYPE: float
min_peak	Minimum allowed peak amplitude. TYPE: float
max_peak	Maximum allowed peak amplitude. TYPE: float
freq_weight	Weight for the cross-frequency monotonicity penalty. TYPE: float DEFAULT: 1.0
LARGE_NUMBER	Penalty value for invalid simulations. TYPE: float DEFAULT: 10000.0
single_frequency_mode	If True, skip cross-frequency penalty. TYPE: bool DEFAULT: False
sensitization	If True, flip slope sign to encourage increasing response. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
total_loss	Scalar loss. TYPE: float
info	Debug dictionary including per-frequency losses and freq_runs. TYPE: Dict[str, Any]