Skip to content

RLSSM API (ssms.rl)

The ssms.rl namespace is the simulator-side API for reinforcement-learning sequential sampling models. It defines model structure, task environments, learning processes, simulation, validation, and the neutral assembled-model contract consumed by inference packages.

This page is a reference roll-up. For procedures, start with Simulate your first RLSSM, then use the advanced component guide, choice-only guide, or HSSM handoff guide.

Namespace exports

Use import ssms.rl as rl. The root namespace exports:

Export Contract
Simulator Trial-wise generative and observed-history-conditioned simulation
ModelConfig Structural model specification; concrete parameter values are passed separately
AssembledModel Validated, backend-resolved participant-function contract
resolve_model Resolve a preset name or validate a ModelConfig
env Task-environment protocols, implementations, and registry
learning Learning-process protocol and built-in implementations
preset Preset registry (get, list, info, register)

Model configuration contract

ModelConfig describes structure, not participant parameter values. Its main fields are:

Field Meaning
decision_process Registered SSM name such as angle or ddm
learning_process Object satisfying LearningProcess
task_environment Environment object or TaskConfig shorthand
response_to_choice Mapping from SSM response labels to zero-based learning choices
learning_backend, gradient Backend and differentiability policy
context_fields Observable trial-context columns such as feedback
include_choice Whether simulator output includes the derived zero-based choice

The private derived _ssm_config is built from the registered decision process and is not a constructor input. Public ModelConfig integration fields include list_params, bounds, params_default, required_params, and response_to_choice. After assembly, AssembledModel.computed_params exposes the ordered decision-process parameters supplied by the learning process.

Built-in learning processes

Class Computed output Action count
RescorlaWagnerDeltaRule State/update only 2 or more
RescorlaWagnerDrift v exactly 2
RescorlaWagnerSoftmax q0, q1, ... 2 or more
RescorlaWagnerRaceDrifts v0, v1, ... 2 or more
RescorlaWagnerDualAlphaRule State/update only 2 or more
RescorlaWagnerDualAlphaDrift v exactly 2
RescorlaWagnerDualAlphaSoftmax q0, q1, ... 2 or more

Drift learners compute trial-wise drift from learned value differences. Softmax learners expose Q-values and leave inverse-temperature application to the decision process. The dual-alpha variants distinguish positive and negative prediction errors.

Preset registry

ssms.rl.preset is the source of truth for built-in RLSSM structures. Query the runtime registry with preset.list() and inspect a resolved contract with preset.info(name).

Preset Decision process Learning process Response
2AB_RW_DDM ddm RescorlaWagnerDrift rt, response
2AB_RW_Angle angle RescorlaWagnerDrift rt, response
2AB_RW_Weibull weibull RescorlaWagnerDrift rt, response
2AB_RW_DualAlpha_Angle angle RescorlaWagnerDualAlphaDrift rt, response
2AB_RW_InvTempSoftmax inv_temp_softmax_2 RescorlaWagnerSoftmax response
2AB_RW_DualAlpha_InvTempSoftmax inv_temp_softmax_2 RescorlaWagnerDualAlphaSoftmax response
3AB_RW_InvTempSoftmax inv_temp_softmax_3 RescorlaWagnerSoftmax response
4AB_RW_InvTempSoftmax inv_temp_softmax_4 RescorlaWagnerSoftmax response
4AB_RW_RaceNoBiasAngle race_no_bias_angle_4 RescorlaWagnerRaceDrifts rt, response

Simulator contract

Simulator.simulate() accepts scalar parameter values shared by all participants or one-dimensional participant-wise values. All participant-wise arrays must have the same length; an explicit n_participants must match it.

The supported modes are:

Mode Contract
generative Sample task context, response, and learning updates end to end
ppc Condition learning on observed history while resimulating responses

PPC input must satisfy the same panel contract as inference validation. The observed response history conditions learning; returned responses are newly simulated.

Choice-only contract

The inverse-temperature softmax presets declare response=["response"] and do not define an RT likelihood. Generative output retains rt=-1.0 only as a compatibility placeholder. That value is distinct from OMISSION_SENTINEL == -999.0.

Validation, PPC, and HSSM handoff use a response-only table with the placeholder column removed. Custom tasks may pair an inv_temp_softmax_N decision process with a compatible learning process and environment.

Task environments and registry

TaskEnvironment defines per-trial context and post-decision signals. DiscreteChoiceEnvironment adds n_choices and ordered response_labels. Built-in bandits satisfy the discrete protocol; Bandit.n_arms aliases n_choices.

TaskEnvironmentBuilder is the callable type stored by the task registry. register_task() adds a builder, registered_tasks() lists available names, and TaskConfig.build_environment() resolves one. The built-in bandit task supports Bernoulli and Gaussian rewards.

Data-validation contract

ModelConfig.validate_data() and validate_rlssm_data() return a DataValidationReport containing zero or more DataValidationIssue values. Call raise_for_errors() when invalid panels must fail fast.

Required columns are derived from the model:

  • participant_id;
  • every configured response column;
  • every observable context_fields entry.

Validation checks balanced panels, contiguous participant blocks, response labels and mappings, missing values, RT validity, and omission sentinels. Rows within each participant are processed in their existing order. trial_id is an ordinary column, not a reserved ordering instruction.

Assembled-model and HSSM contracts

ModelConfig.assemble() returns an AssembledModel with backend-resolved participant input fields and computed-parameter functions. Runtime choice is derived from response_to_choice; observable context comes from context_fields.

HSSM owns inference and exposes hssm.RLSSM(data, model=...) as the normal entry point for named ssms presets. An in-memory custom ModelConfig can use the advanced hssm.rl.RLSSMConfig.from_ssms_model(...) path. The HSSM handoff guide owns that procedure, and HSSM's rendered RLSSM reference owns inference-side options.

ModelConfig.to_hssm_config_dict() remains an inspection and compatibility surface. Its inference placeholders are not a complete HSSM model and should not be assembled manually.

Core objects

ssms.rl.config.ModelConfig dataclass 

ModelConfig(model_name: str, description: str, decision_process: str, learning_process: LearningProcess, task_environment: TaskEnvironment | TaskConfig, list_params: list[str] | None = None, bounds: dict[str, tuple[float, float]] | None = None, params_default: list[float] | None = None, choices: tuple[int, ...] | None = None, response: list[str] = (lambda: ['rt', 'response'])(), response_to_choice: Literal['auto'] | dict[int, int] = 'auto', learning_backend: Literal['auto', 'python', 'jax'] = 'auto', gradient: Literal['auto', 'available', 'unavailable'] = 'auto', include_choice: bool = False, context_fields: list[str] | None = None, computed_param_mapping: dict[str, str] | None = None, ssm_kwargs: dict[str, Any] = (lambda: {'delta_t': 0.001, 'max_t': 20.0})())

RLSSM model configuration for ssm-simulators.

Describes the structural specification of an RLSSM model: which learning process, which decision process (SSM), and which task environment. Concrete parameter values are NOT stored here — they are passed as theta to Simulator.simulate().

Parameters:

  • model_name (str) –

    Unique identifier for this RLSSM model (e.g., "rlssm_angle_rw").

  • description (str) –

    Human-readable model description.

  • decision_process (str) –

    SSM model name in ssm-simulators registry (e.g., "angle", "ddm"). Must be resolvable via ModelConfigBuilder.from_model().

  • learning_process (LearningProcess) –

    Instance of a class satisfying the LearningProcess protocol.

  • task_environment (TaskEnvironment | TaskConfig) –

    Task environment instance or a TaskConfig to auto-build one. If TaskConfig, build_environment() is called in __post_init__.

  • list_params (list[str] | None, default: None ) –

    All free parameter names (RL + fixed SSM), in order. If None, auto-derived: learning_process.free_params + fixed SSM params.

  • bounds (dict[str, tuple[float, float]] | None, default: None ) –

    Parameter bounds. If None, auto-derived from learning_process.param_bounds + SSM model config param_bounds.

  • params_default (list[float] | None, default: None ) –

    Default values in same order as list_params. If None, auto-derived.

  • choices (tuple[int, ...] | None, default: None ) –

    SSM response labels (e.g., (-1, 1)). If None, taken from task_environment.

  • response (list[str], default: (lambda: ['rt', 'response'])() ) –

    Response column names. Default ["rt", "response"].

  • response_to_choice (Literal['auto'] | dict[int, int], default: 'auto' ) –

    Mapping from SSM response labels to zero-based learning choices. "auto" maps labels by task_environment.response_labels order.

  • learning_backend (Literal['auto', 'python', 'jax'], default: 'auto' ) –

    Learning-process backend used for simulation and exported HSSM metadata. "auto" selects JAX when the process implements it and JAX is installed; otherwise it selects Python.

  • gradient (Literal['auto', 'available', 'unavailable'], default: 'auto' ) –

    Gradient-support policy for HSSM integration metadata.

  • include_choice (bool, default: False ) –

    Whether simulator output includes the derived zero-based choice column. Default False.

  • context_fields (list[str] | None, default: None ) –

    Data/context columns beyond response required by the environment or learning process. Default derives a union from component declarations.

  • computed_param_mapping (dict[str, str] | None, default: None ) –

    Optional override for non-name-matching handshakes. Maps learning process output name -> SSM param name. E.g., {"drift": "v"} if learning process outputs "drift" but SSM expects "v". Default: None (same-name linking).

  • ssm_kwargs (dict, default: (lambda: {'delta_t': 0.001, 'max_t': 20.0})() ) –

    Default kwargs for the underlying SSM simulator call. Default: {"delta_t": 0.001, "max_t": 20.0}.

Methods:

  • assemble –

    Return a validated executable assembled model.

  • participant_contract –

    Return the derived participant input layout for this config.

  • to_hssm_config_dict –

    Produce a dict compatible with HSSM's RLSSMConfig.from_rlssm_dict().

  • validate –

    Validate config consistency. Called by Simulator.init().

  • validate_data –

    Validate trial-level data against this model's RLSSM contract.

Attributes:

ssms.rl.config.ModelConfig.required_params property 

required_params: list[str]

Parameters that simulation requires from theta.

ssms.rl.config.ModelConfig.resolved_response_to_choice property 

resolved_response_to_choice: dict[int, int]

Concrete response-label -> choice-index map.

__post_init__ normalizes response_to_choice (including the "auto" default) into a plain dict; this accessor exposes that post-init invariant with a narrowed type.

ssms.rl.config.ModelConfig.assemble 

assemble(backend: Literal['auto', 'python', 'jax'] = 'auto')

Return a validated executable assembled model.

ssms.rl.config.ModelConfig.participant_contract 

participant_contract(*, response_field: str = DEFAULT_RESPONSE_FIELD) -> _ParticipantContract

Return the derived participant input layout for this config.

ssms.rl.config.ModelConfig.to_hssm_config_dict 

to_hssm_config_dict() -> dict[str, Any]

Produce a dict compatible with HSSM's RLSSMConfig.from_rlssm_dict().

The output contains all fields from _HSSM_SHARED_FIELDS plus placeholder values for inference-only fields that the user must fill in on the HSSM side.

Returns:

  • dict[str, Any] –

    Dict ready for RLSSMConfig.from_rlssm_dict(result) after user fills in inference-only fields.

ssms.rl.config.ModelConfig.validate 

validate() -> None

Validate config consistency. Called by Simulator.init().

Checks: 1. decision_process exists in ssm-simulators registry 2. Handshake: computed + fixed params cover all SSM params exactly once 3. No param is both computed and fixed 4. list_params length matches params_default length 5. All list_params have bounds

ssms.rl.config.ModelConfig.validate_data 

validate_data(data: DataFrame) -> DataValidationReport

Validate trial-level data against this model's RLSSM contract.

Returns a report with readable print() output and raise_for_errors() for fail-fast usage.

ssms.rl.assembled.AssembledModel dataclass 

AssembledModel(config: ModelConfig, learning_backend: ResolvedLearningBackend, gradient: Literal['available', 'unavailable'], model_name: str, decision_process: str, list_params: list[str], bounds: dict[str, tuple[float, float]], params_default: list[float], response: list[str], choices: tuple[int, ...], context_fields: list[str], computed_params: list[str], response_to_choice: dict[int, int])

Validated executable form of an RLSSM ModelConfig.

The assembled model exposes package-neutral metadata and pure Python/JAX computed-parameter functions that downstream packages can wrap without importing HSSM or PyTensor in ssm-simulators.

Methods:

ssms.rl.assembled.AssembledModel.assemble_participant_fn 

assemble_participant_fn(input_fields: Sequence[str] | None = None, *, response_field: str = DEFAULT_RESPONSE_FIELD, output: AssembledFunctionOutput | str = AssembledFunctionOutput.ARRAY) -> Callable[[Any], Any]

Assemble a participant-wise computed-parameter function.

By default, input_fields are derived from the model config. Pass explicit values only for non-standard layouts.

The returned function accepts a (n_trials, n_fields) array whose columns match input_fields. It computes SSM parameters before each learning update, maps response labels to zero-based action indices, and updates learning state from the response and optional outcome.

ssms.rl.assembled.AssembledModel.from_config classmethod 

from_config(config: ModelConfig, backend: LearningBackendRequest | str = LearningBackendRequest.AUTO) -> AssembledModel

Build an assembled model from a structural model config.

ssms.rl.assembled.AssembledModel.get_participant_input_fields 

get_participant_input_fields(*, response_field: str = DEFAULT_RESPONSE_FIELD) -> list[str]

Return the default participant input columns derived from the config.

ssms.rl.assembled.AssembledModel.participant_input_fields 

participant_input_fields(*, response_field: str = DEFAULT_RESPONSE_FIELD) -> list[str]

Backward-compatible alias for :meth:get_participant_input_fields.

ssms.rl.simulator.Simulator 

Simulator(config: ModelConfig)

RLSSM simulator composing a learning process with an SSM decision process.

Runs the interleaved trial-by-trial loop: compute SSM params -> simulate SSM -> observe choice -> generate reward -> update learning.

Reuses the existing ssm-simulators simulator() function with n_samples=1 for each trial. No Cython modifications needed — all 40+ SSM models work as decision processes out of the box.

Parameters:

  • config (ModelConfig) –

    Structural model configuration. Validated on construction.

Methods:

  • simulate –

    Run full RLSSM simulation.

ssms.rl.simulator.Simulator.simulate 

simulate(theta: dict[str, Any], n_trials: int = 200, n_participants: int | None = None, random_state: int | None = None, mode: Literal['generative', 'ppc'] = 'generative', observed_data: DataFrame | None = None) -> pd.DataFrame

Run full RLSSM simulation.

Parameters:

  • theta (dict[str, Any]) –

    Concrete parameter values. Must contain all params required by the learning process and fixed SSM parameters. Each value can be a scalar shared by all participants or a one-dimensional list/array with one value per participant.

  • n_trials (int, default: 200 ) –

    Number of trials per participant. Default 200.

  • n_participants (int | None, default: None ) –

    Number of participants to simulate. If None, inferred from participant-wise theta values when present; otherwise defaults to 20.

  • random_state (int | None, default: None ) –

    Seed for reproducibility. If None, non-deterministic.

  • mode (('generative', 'ppc'), default: "generative" ) –

    Simulation mode. "generative" runs the unconstrained simulator loop. "ppc" runs observed-history-conditioned posterior predictive simulation.

  • observed_data (DataFrame | None, default: None ) –

    Observed participant history required for mode="ppc".

Returns:

  • DataFrame –

    Balanced panel with participant_id, trial_id, configured response columns, configured context fields, and optional derived choice.

ssms.rl.assembled.resolve_model 

resolve_model(model: str | ModelConfig) -> ModelConfig

Resolve a preset name or validate an existing RLSSM model config.

Preset functions

ssms.rl.preset.get 

get(name: str) -> ModelConfig

Get a named RLSSM preset config. Returns a fresh instance.

ssms.rl.preset.list 

list() -> builtins.list[str]

List available RLSSM preset names.

ssms.rl.preset.info 

info(name: str) -> PresetInfo

Return readable metadata for a named RLSSM preset.

ssms.rl.preset.register 

register(name: str, factory: Callable[[], ModelConfig], *, metadata: dict[str, Any] | None = None) -> None

Register a named RLSSM preset.

Environment objects

ssms.rl.env.TaskEnvironment

Bases: Protocol

Protocol for RLSSM task environments.

A task environment provides per-trial context and optional post-decision signals. It is stateful and must be reset before each participant.

Discrete response/choice mapping requires :class:DiscreteChoiceEnvironment.

Methods:

  • get_trial_context –

    Return pre-decision per-trial context columns.

  • reset –

    Reset environment state for a new participant.

  • sample_context –

    Return post-decision context columns for learning/output.

Attributes:

ssms.rl.env.TaskEnvironment.context_fields property 

context_fields: list[str]

Names of per-trial context columns this environment provides.

ssms.rl.env.TaskEnvironment.get_trial_context 

get_trial_context(trial_idx: int) -> dict[str, float]

Return pre-decision per-trial context columns.

ssms.rl.env.TaskEnvironment.reset 

reset(rng: Generator | None = None) -> None

Reset environment state for a new participant.

ssms.rl.env.TaskEnvironment.sample_context 

sample_context(context: dict, trial_idx: int) -> dict[str, float]

Return post-decision context columns for learning/output.

ssms.rl.env.DiscreteChoiceEnvironment

Bases: TaskEnvironment, Protocol

Task environment with discrete SSM response labels and learning choices.

Attributes:

ssms.rl.env.DiscreteChoiceEnvironment.n_choices property 

n_choices: int

Number of available zero-based learning choices.

ssms.rl.env.DiscreteChoiceEnvironment.response_labels property 

response_labels: list[int]

SSM response labels corresponding to choices in order.

ssms.rl.env.TaskEnvironmentBuilder module-attribute 

TaskEnvironmentBuilder = Callable[[str | None, dict], TaskEnvironment]

ssms.rl.env.Bandit 

Bandit(rewards: _RewardDistribution, response_labels: list[int] | None = None)

Generic bandit task environment.

Public constructors are Bandit.bernoulli(...) and Bandit.gaussian(...). Rewards are sampled by zero-based choice index; response_labels define the SSM labels mapped onto those choices.

Methods:

  • bernoulli –

    Build a Bernoulli-reward bandit.

  • gaussian –

    Build a Gaussian-reward bandit.

  • get_extra_data –

    Compatibility wrapper around get_trial_context.

  • sample_reward –

    Compatibility wrapper around sample_context.

Attributes:

  • n_arms (int) –

    Alias for :attr:n_choices (bandit terminology).

ssms.rl.env.Bandit.n_arms property 

n_arms: int

Alias for :attr:n_choices (bandit terminology).

ssms.rl.env.Bandit.bernoulli classmethod 

bernoulli(probabilities: list[float] | None = None, response_labels: list[int] | None = None) -> Bandit

Build a Bernoulli-reward bandit.

ssms.rl.env.Bandit.gaussian classmethod 

gaussian(means: list[float] | None = None, sds: list[float] | None = None, response_labels: list[int] | None = None) -> Bandit

Build a Gaussian-reward bandit.

ssms.rl.env.Bandit.get_extra_data 

get_extra_data(trial_idx: int) -> dict[str, float]

Compatibility wrapper around get_trial_context.

ssms.rl.env.Bandit.sample_reward 

sample_reward(action: int, trial_idx: int) -> float

Compatibility wrapper around sample_context.

ssms.rl.env.TaskConfig 

TaskConfig(task: str = 'bandit', reward: str | None = None, **options)

Convenience configuration for registered task environments.

TaskConfig is a shorthand that delegates task-specific options to a registry builder. Built in support currently includes task="bandit" with reward="bernoulli" or reward="gaussian".

ssms.rl.env.register_task 

register_task(task: str, builder: TaskEnvironmentBuilder, *, overwrite: bool = False) -> None

Register a task environment builder for TaskConfig.

ssms.rl.env.registered_tasks 

registered_tasks() -> list[str]

List task names available through TaskConfig.

Validation objects

ssms.rl.validation.DataValidationIssue dataclass 

DataValidationIssue(level: Literal['error', 'warning'], code: str, message: str, hint: str | None = None)

A single validation finding.

ssms.rl.validation.DataValidationReport dataclass 

DataValidationReport(issues: list[DataValidationIssue] = list(), n_participants: int | None = None, n_trials: int | None = None)

Aggregated validation results for an RLSSM data panel.

Methods:

  • print –

    Print a human-readable summary to stdout.

  • raise_for_errors –

    Raise ValueError if any error-level issues were recorded.

Attributes:

  • ok (bool) –

    True when there are no error-level issues.

ssms.rl.validation.DataValidationReport.ok property 

ok: bool

True when there are no error-level issues.

ssms.rl.validation.DataValidationReport.print 

print() -> None

Print a human-readable summary to stdout.

ssms.rl.validation.DataValidationReport.raise_for_errors 

raise_for_errors() -> None

Raise ValueError if any error-level issues were recorded.

ssms.rl.validation.validate_rlssm_data 

validate_rlssm_data(config: ModelConfig, data: DataFrame) -> DataValidationReport

Validate a data panel against the RLSSM model contract.

Parameters:

  • config (ModelConfig) –

    Structural RLSSM configuration. Should already pass config.validate().

  • data (DataFrame) –

    Empirical or simulated trial-level panel.

Returns:

Learning-process objects

ssms.rl.learning.LearningProcess

Bases: Protocol

Protocol for RLSSM learning processes.

A learning process maintains internal state (e.g., Q-values) and computes SSM parameters (e.g., drift rate) from that state on each trial. After each trial's decision and reward, the state is updated.

The computed_params property is the formal handshake between the learning process and the decision process: it declares which SSM parameters the learning process produces. The simulator validates that these, together with fixed SSM params provided by the user, cover all parameters required by the decision process model.

Methods:

  • compute_python –

    Compute SSM parameters from explicit Python/NumPy state.

  • compute_ssm_params –

    Compute SSM parameters from current learning state.

  • init_state –

    Return an explicit initial learning state for one participant.

  • reset –

    Reset internal state for a new participant.

  • update –

    Update learning state given the choice outcome.

  • update_python –

    Return the next explicit Python/NumPy state.

Attributes:

ssms.rl.learning.LearningProcess.available_backends property 

available_backends: tuple[str, ...]

Learning backends implemented by this process.

ssms.rl.learning.LearningProcess.computed_params property 

computed_params: list[str]

SSM parameter names this process computes (e.g., ['v']).

ssms.rl.learning.LearningProcess.default_params property 

default_params: dict[str, float]

Default values for each free param.

ssms.rl.learning.LearningProcess.free_params property 

free_params: list[str]

RL parameter names this process requires from theta.

ssms.rl.learning.LearningProcess.param_bounds property 

param_bounds: dict[str, tuple[float, float]]

Bounds for each free param.

ssms.rl.learning.LearningProcess.required_context_fields property 

required_context_fields: list[str]

Context keys this process needs for compute/update.

ssms.rl.learning.LearningProcess.supports_gradient property 

supports_gradient: bool

Whether the differentiable backend supports gradient-based inference.

ssms.rl.learning.LearningProcess.compute_python 

compute_python(state: LearningState, params: dict[str, float], context: dict[str, Any]) -> dict[str, float]

Compute SSM parameters from explicit Python/NumPy state.

ssms.rl.learning.LearningProcess.compute_ssm_params 

compute_ssm_params(trial_params: dict[str, float]) -> dict[str, float]

Compute SSM parameters from current learning state.

ssms.rl.learning.LearningProcess.init_state 

init_state() -> LearningState

Return an explicit initial learning state for one participant.

ssms.rl.learning.LearningProcess.reset 

reset(**kwargs) -> None

Reset internal state for a new participant.

ssms.rl.learning.LearningProcess.update 

update(action: int, reward: float, trial_params: dict[str, float]) -> None

Update learning state given the choice outcome.

ssms.rl.learning.LearningProcess.update_python 

update_python(state: LearningState, params: dict[str, float], context: dict[str, Any]) -> LearningState

Return the next explicit Python/NumPy state.

ssms.rl.learning.RescorlaWagnerDeltaRule 

RescorlaWagnerDeltaRule(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Rescorla-Wagner delta learning core.

Updates Q-values via Q[action] += alpha * (reward - Q[action]). This class owns Q-value state and replay/update behavior but emits no SSM parameters by itself. Use RescorlaWagnerDrift for two-action drift models and RescorlaWagnerSoftmax for inverse-temperature softmax models.

Methods:

  • compute_ssm_params –

    Compute pre-update SSM parameters from current learning state.

  • update –

    Update Q[action] from the observed outcome.

Attributes:

  • q_values (ndarray | None) –

    Current Q-values. None if reset() has not been called.

ssms.rl.learning.RescorlaWagnerDeltaRule.q_values property 

q_values: ndarray | None

Current Q-values. None if reset() has not been called.

ssms.rl.learning.RescorlaWagnerDeltaRule.compute_ssm_params 

compute_ssm_params(trial_params: dict[str, float]) -> dict[str, float]

Compute pre-update SSM parameters from current learning state.

ssms.rl.learning.RescorlaWagnerDeltaRule.update 

update(action: int, reward: float, trial_params: dict[str, float]) -> None

Update Q[action] from the observed outcome.

ssms.rl.learning.RescorlaWagnerDrift 

RescorlaWagnerDrift(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDeltaRule

Rescorla-Wagner learner emitting two-action drift v.

Computes drift rate as scaled Q-value difference: v = (Q[1] - Q[0]) * scaler.

ssms.rl.learning.RescorlaWagnerSoftmax 

RescorlaWagnerSoftmax(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDeltaRule

Rescorla-Wagner learner emitting pre-update Q-values q0..qN.

ssms.rl.learning.RescorlaWagnerRaceDrifts 

RescorlaWagnerRaceDrifts(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDeltaRule

Rescorla-Wagner learner emitting scaled race drifts v0..vN.

The scaling contract is explicit: on each trial, before the RW update, v_i = scaler * q_i for every action i.

ssms.rl.learning.RescorlaWagnerDualAlphaRule 

RescorlaWagnerDualAlphaRule(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDeltaRule

Rescorla-Wagner learning core with separate learning rates.

Positive prediction errors use rl_alpha and negative prediction errors use rl_alpha_neg.

Methods:

  • update_python –

    Update Q[action] with sign-dependent learning rates.

ssms.rl.learning.RescorlaWagnerDualAlphaRule.update_python 

update_python(state: LearningState, params: dict[str, float], context: dict[str, Any]) -> LearningState

Update Q[action] with sign-dependent learning rates.

ssms.rl.learning.RescorlaWagnerDualAlphaDrift 

RescorlaWagnerDualAlphaDrift(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDualAlphaRule

Dual-alpha Rescorla-Wagner learner emitting two-action drift v.

ssms.rl.learning.RescorlaWagnerDualAlphaSoftmax 

RescorlaWagnerDualAlphaSoftmax(n_actions: int = 2, initial_q: float = 0.5, feedback_field: str = 'feedback')

Bases: RescorlaWagnerDualAlphaRule

Dual-alpha Rescorla-Wagner learner emitting Q-values q0..qN.