Class Stimulus
Finite-state-machine stimulus generator that produces structured sequences of target vectors.
JSON configuration
Use these block entries inside a pipeline configuration. Input names must match other blocks in that pipeline; device addresses and file paths must match your setup.
JSON configuration:
{
"Stimulus": {
"Type": "Stimulus",
"DesiredRate": 0,
"Inputs": [ "Timer" ],
"Params": [
"4.0",
"rest:0;0;0;0;0;0;0;0;0;0;0;0",
"power:1;1;1;1;1;1;0;0;0;0;0;0",
"flex:0;0;0;0;0;0;1;0;0;0;0;0",
"extend:0;0;0;0;0;0;0;1;0;0;0;0"
],
"Path": "C:/Data/session1"
}
}
Params:
| Index | Description |
|---|---|
| 0 |
CaptureDuration (double) — duration of the capture state in seconds.
|
| 1..N |
Task definitions as "name:v1;v2;v3;...". The name is used for display;
the semicolon-separated values form the target vector.
If no colon is present, the name defaults to "Task[i]".
|
How Type, Inputs and Params work · Block catalogue and parameter reference
Implements
Inherited Members
Namespace: MOSAIC.Models.Devices
Assembly: MOSAIC.dll
Syntax
public sealed class Stimulus : BaseBlock, INotifyPropertyChanged, INotifyPropertyChanging, ISubscriber, IPublisher, IBaseBlockProps, IJsonExportable, IDisposable, IAsyncDisposable
Remarks
Overview: The Stimulus block automates what the Trigger block does manually.
It walks through a list of tasks (target activation vectors) with timed FSM transitions,
optionally shuffling the order. During the capture state, downstream blocks
(e.g. IncrementalPredictor) can record data.
Each tick publishes a (string state, Vector<double> target) tuple downstream.
FSM States:
| State | Behavior |
|---|---|
| rest | Output zero vector for 2.0 s. |
| rise | Smooth sine² ramp from zero to task target over 0.5 s. |
| hold | Hold task target for 1.0 s. |
| capture | Hold task target for CaptureDuration s — data capture window. |
| fall | Smooth cosine² ramp from task target to zero over 1.0 s. |
| end | All tasks completed; FSM stops automatically. |
CSV logging: When a Path is specified in the JSON configuration, the base class
Dumper automatically logs every published (string, Vector<double>)
tuple as timestamp, state, v₀, v₁, … via EnqueueLabelled(double, string, Vector<double>).
Constructors
Stimulus(string, double)
Initializes a new Stimulus block.
Declaration
public Stimulus(string name = "Stimulus", double desiredRate = 0)
Parameters
| Type | Name | Description |
|---|---|---|
| string | name | Display name. |
| double | desiredRate | Processing rate in Hz (typically inherited from driving timer). |
Fields
_clock
Monotonic stopwatch for FSM elapsed-time tracking.
Declaration
private readonly Stopwatch _clock
Field Value
| Type | Description |
|---|---|
| Stopwatch |
_currentTaskIdx
Index into _remainingIndices for the current task.
Declaration
private int _currentTaskIdx
Field Value
| Type | Description |
|---|---|
| int |
_currentTaskName
Name of the current task being presented.
Declaration
[ObservableProperty]
private string _currentTaskName
Field Value
| Type | Description |
|---|---|
| string |
_isRunning
Whether the FSM is actively running.
Declaration
[ObservableProperty]
private bool _isRunning
Field Value
| Type | Description |
|---|---|
| bool |
_rand
RNG for shuffle mode.
Declaration
private readonly Random _rand
Field Value
| Type | Description |
|---|---|
| Random |
_remainingIndices
Indices of tasks not yet presented in the current run.
Declaration
private List<int> _remainingIndices
Field Value
| Type | Description |
|---|---|
| List<int> |
_shuffleEnabled
Whether task order is randomized each run.
Declaration
[ObservableProperty]
private bool _shuffleEnabled
Field Value
| Type | Description |
|---|---|
| bool |
_state
Current FSM state name (rest, rise, hold, capture, fall, end).
Declaration
[ObservableProperty]
private string _state
Field Value
| Type | Description |
|---|---|
| string |
_stateDurations
Duration of each FSM state in seconds. capture is configurable via Params[0].
Declaration
private readonly Dictionary<string, double> _stateDurations
Field Value
| Type | Description |
|---|---|
| Dictionary<string, double> |
_targetValue
Current output target vector.
Declaration
[ObservableProperty]
private Vector<double>? _targetValue
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_taskNames
Display names corresponding to _tasks.
Declaration
private readonly List<string> _taskNames
Field Value
| Type | Description |
|---|---|
| List<string> |
_tasks
Target activation vectors, one per task.
Declaration
private readonly List<Vector<double>> _tasks
Field Value
| Type | Description |
|---|---|
| List<Vector<double>> |
_tasksRemaining
Number of tasks remaining in the current run.
Declaration
[ObservableProperty]
private int _tasksRemaining
Field Value
| Type | Description |
|---|---|
| int |
_transitionTime
Stopwatch time (seconds) at which the current state began.
Declaration
private double _transitionTime
Field Value
| Type | Description |
|---|---|
| double |
_viz
Optional visualization bundle for the target output. Set by the ViewModel; fed during FSM ticks via Feed(Vector<double>?).
Declaration
private BlockVisualization? _viz
Field Value
| Type | Description |
|---|---|
| BlockVisualization |
Properties
CaptureDuration
Duration of the capture state in seconds.
Declaration
public double CaptureDuration { get; set; }
Property Value
| Type | Description |
|---|---|
| double |
CurrentTaskName
Name of the current task being presented.
Declaration
[ExcludeFromCodeCoverage]
public string CurrentTaskName { get; set; }
Property Value
| Type | Description |
|---|---|
| string |
DumpFilePrefix
Recordings from this block are named <block>_stimulus.csv.
Declaration
protected override string DumpFilePrefix { get; }
Property Value
| Type | Description |
|---|---|
| string |
Overrides
IsRunning
Whether the FSM is actively running.
Declaration
[ExcludeFromCodeCoverage]
public bool IsRunning { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
JsonTypeName
Block type identifier for JSON serialization. Override for a custom name.
Declaration
protected override string JsonTypeName { get; }
Property Value
| Type | Description |
|---|---|
| string |
Overrides
ShuffleEnabled
Whether task order is randomized each run.
Declaration
[ExcludeFromCodeCoverage]
public bool ShuffleEnabled { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
State
Current FSM state name (rest, rise, hold, capture, fall, end).
Declaration
[ExcludeFromCodeCoverage]
public string State { get; set; }
Property Value
| Type | Description |
|---|---|
| string |
TargetValue
Current output target vector.
Declaration
[ExcludeFromCodeCoverage]
public Vector<double>? TargetValue { get; set; }
Property Value
| Type | Description |
|---|---|
| Vector<double> |
TaskCount
Total number of configured tasks.
Declaration
public int TaskCount { get; }
Property Value
| Type | Description |
|---|---|
| int |
TaskNames
Ordered list of task names for UI display.
Declaration
public IReadOnlyList<string> TaskNames { get; }
Property Value
| Type | Description |
|---|---|
| IReadOnlyList<string> |
TasksRemaining
Number of tasks remaining in the current run.
Declaration
[ExcludeFromCodeCoverage]
public int TasksRemaining { get; set; }
Property Value
| Type | Description |
|---|---|
| int |
Visualization
This block's visualization, or null when it has none.
Declaration
protected override BlockVisualization? Visualization { get; }
Property Value
| Type | Description |
|---|---|
| BlockVisualization |
Overrides
Remarks
Blocks own their scope as a public Viz property rather than inheriting one, so the
base class has no way to reach it. Overriding this is what lets the rate below be wired up
automatically. With correct publication metadata, the bundle derives the time axis for
one vector per publication or fixed-size contiguous sample packets from the feed shape.
When a plot needs a rate that publication frequency and feed shape cannot express (for
example, variable-sized packets or overlapping windows), declare it with
Viz.UpdateSignalRate. An explicit declaration wins over the derived rate. A block
with several bundles must configure each one; this hook exposes only one bundle.
Viz
Live plot for this block. Assigned by the ViewModel, which owns the scope.
Declaration
public BlockVisualization? Viz { get; set; }
Property Value
| Type | Description |
|---|---|
| BlockVisualization |
Remarks
Setting this re-pushes the publish rate: the rate is normally pushed when it changes, which for these blocks happens during construction — before the ViewModel has handed over the scope — so without this the scope would never learn its time base.
Methods
AdvanceTask()
Advances to the next task after a fall state completes.
Removes the current task from _remainingIndices and transitions to
rest (or end if all tasks are done).
Declaration
private void AdvanceTask()
ConfigureInput(IServiceProvider, JsonModel)
Creates a Stimulus from a JSON pipeline definition.
Declaration
public static Stimulus ConfigureInput(IServiceProvider sp, JsonModel m)
Parameters
| Type | Name | Description |
|---|---|---|
| IServiceProvider | sp | Application service provider. |
| JsonModel | m | JSON model with |
Returns
| Type | Description |
|---|---|
| Stimulus | A fully configured Stimulus block. |
Dispose()
Stops the FSM, disposes visualization, and releases base class resources (including the CSV dumper if configured).
Declaration
public override void Dispose()
Overrides
GetCurrentTaskName()
Returns the display name of the current task, or "None" if no tasks remain.
Declaration
private string GetCurrentTaskName()
Returns
| Type | Description |
|---|---|
| string | The current task name string. |
GetCurrentTaskVector()
Returns the target vector for the current task, or a zero vector if no tasks remain.
Declaration
private Vector<double> GetCurrentTaskVector()
Returns
| Type | Description |
|---|---|
| Vector<double> | The current task's activation vector. |
GetJsonParams()
Block-specific parameters for JSON. Override to provide custom parameters.
Declaration
protected override IReadOnlyList<object>? GetJsonParams()
Returns
| Type | Description |
|---|---|
| IReadOnlyList<object> | The values for Params, in the order this block's |
Overrides
MoveTo(string)
Externally forces the FSM to a specific state. Used by the TAC protocol to advance
from capture to fall on trial success.
Declaration
public void MoveTo(string stateName)
Parameters
| Type | Name | Description |
|---|---|---|
| string | stateName | Target state name (e.g. |
OnCurrentTaskNameChanged(string)
Executes the logic for when CurrentTaskName just changed.
Declaration
private void OnCurrentTaskNameChanged(string value)
Parameters
| Type | Name | Description |
|---|---|---|
| string | value | The new property value that was set. |
Remarks
This method is invoked right after the value of CurrentTaskName is changed.
OnCurrentTaskNameChanged(string?, string)
Executes the logic for when CurrentTaskName just changed.
Declaration
private void OnCurrentTaskNameChanged(string? oldValue, string newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| string | oldValue | The previous property value that was replaced. |
| string | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of CurrentTaskName is changed.
OnCurrentTaskNameChanging(string)
Executes the logic for when CurrentTaskName is changing.
Declaration
private void OnCurrentTaskNameChanging(string value)
Parameters
| Type | Name | Description |
|---|---|---|
| string | value | The new property value being set. |
Remarks
This method is invoked right before the value of CurrentTaskName is changed.
OnCurrentTaskNameChanging(string?, string)
Executes the logic for when CurrentTaskName is changing.
Declaration
private void OnCurrentTaskNameChanging(string? oldValue, string newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| string | oldValue | The previous property value that is being replaced. |
| string | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of CurrentTaskName is changed.
OnIsRunningChanged(bool)
Executes the logic for when IsRunning just changed.
Declaration
private void OnIsRunningChanged(bool value)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | value | The new property value that was set. |
Remarks
This method is invoked right after the value of IsRunning is changed.
OnIsRunningChanged(bool, bool)
Executes the logic for when IsRunning just changed.
Declaration
private void OnIsRunningChanged(bool oldValue, bool newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | oldValue | The previous property value that was replaced. |
| bool | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of IsRunning is changed.
OnIsRunningChanging(bool)
Executes the logic for when IsRunning is changing.
Declaration
private void OnIsRunningChanging(bool value)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | value | The new property value being set. |
Remarks
This method is invoked right before the value of IsRunning is changed.
OnIsRunningChanging(bool, bool)
Executes the logic for when IsRunning is changing.
Declaration
private void OnIsRunningChanging(bool oldValue, bool newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | oldValue | The previous property value that is being replaced. |
| bool | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of IsRunning is changed.
OnReceive(object, object)
Receives timer ticks and advances the FSM. Only processes when IsRunning.
Declaration
protected override void OnReceive(object sender, object data)
Parameters
| Type | Name | Description |
|---|---|---|
| object | sender | The upstream clock/timer block. |
| object | data | Tick payload (ignored — timing is internal via _clock). |
Overrides
Remarks
Each tick computes the elapsed time since the last state transition and evaluates whether
the current state's duration has expired. The output vector is interpolated during
rise (sine² ramp-up) and fall (cosine² ramp-down) states.
The published tuple (State, TargetValue) is automatically logged to CSV
by Publish(object) when Dumper is configured,
producing rows: timestamp, state, v₀, v₁, ….
OnShuffleEnabledChanged(bool)
Executes the logic for when ShuffleEnabled just changed.
Declaration
private void OnShuffleEnabledChanged(bool value)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | value | The new property value that was set. |
Remarks
This method is invoked right after the value of ShuffleEnabled is changed.
OnShuffleEnabledChanged(bool, bool)
Executes the logic for when ShuffleEnabled just changed.
Declaration
private void OnShuffleEnabledChanged(bool oldValue, bool newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | oldValue | The previous property value that was replaced. |
| bool | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of ShuffleEnabled is changed.
OnShuffleEnabledChanging(bool)
Executes the logic for when ShuffleEnabled is changing.
Declaration
private void OnShuffleEnabledChanging(bool value)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | value | The new property value being set. |
Remarks
This method is invoked right before the value of ShuffleEnabled is changed.
OnShuffleEnabledChanging(bool, bool)
Executes the logic for when ShuffleEnabled is changing.
Declaration
private void OnShuffleEnabledChanging(bool oldValue, bool newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | oldValue | The previous property value that is being replaced. |
| bool | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of ShuffleEnabled is changed.
OnStateChanged(string)
Executes the logic for when State just changed.
Declaration
private void OnStateChanged(string value)
Parameters
| Type | Name | Description |
|---|---|---|
| string | value | The new property value that was set. |
Remarks
This method is invoked right after the value of State is changed.
OnStateChanged(string?, string)
Executes the logic for when State just changed.
Declaration
private void OnStateChanged(string? oldValue, string newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| string | oldValue | The previous property value that was replaced. |
| string | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of State is changed.
OnStateChanging(string)
Executes the logic for when State is changing.
Declaration
private void OnStateChanging(string value)
Parameters
| Type | Name | Description |
|---|---|---|
| string | value | The new property value being set. |
Remarks
This method is invoked right before the value of State is changed.
OnStateChanging(string?, string)
Executes the logic for when State is changing.
Declaration
private void OnStateChanging(string? oldValue, string newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| string | oldValue | The previous property value that is being replaced. |
| string | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of State is changed.
OnTargetValueChanged(Vector<double>?)
Executes the logic for when TargetValue just changed.
Declaration
private void OnTargetValueChanged(Vector<double>? value)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | value | The new property value that was set. |
Remarks
This method is invoked right after the value of TargetValue is changed.
OnTargetValueChanged(Vector<double>?, Vector<double>?)
Executes the logic for when TargetValue just changed.
Declaration
private void OnTargetValueChanged(Vector<double>? oldValue, Vector<double>? newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | oldValue | The previous property value that was replaced. |
| Vector<double> | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of TargetValue is changed.
OnTargetValueChanging(Vector<double>?)
Executes the logic for when TargetValue is changing.
Declaration
private void OnTargetValueChanging(Vector<double>? value)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | value | The new property value being set. |
Remarks
This method is invoked right before the value of TargetValue is changed.
OnTargetValueChanging(Vector<double>?, Vector<double>?)
Executes the logic for when TargetValue is changing.
Declaration
private void OnTargetValueChanging(Vector<double>? oldValue, Vector<double>? newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | oldValue | The previous property value that is being replaced. |
| Vector<double> | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of TargetValue is changed.
OnTasksRemainingChanged(int)
Executes the logic for when TasksRemaining just changed.
Declaration
private void OnTasksRemainingChanged(int value)
Parameters
| Type | Name | Description |
|---|---|---|
| int | value | The new property value that was set. |
Remarks
This method is invoked right after the value of TasksRemaining is changed.
OnTasksRemainingChanged(int, int)
Executes the logic for when TasksRemaining just changed.
Declaration
private void OnTasksRemainingChanged(int oldValue, int newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| int | oldValue | The previous property value that was replaced. |
| int | newValue | The new property value that was set. |
Remarks
This method is invoked right after the value of TasksRemaining is changed.
OnTasksRemainingChanging(int)
Executes the logic for when TasksRemaining is changing.
Declaration
private void OnTasksRemainingChanging(int value)
Parameters
| Type | Name | Description |
|---|---|---|
| int | value | The new property value being set. |
Remarks
This method is invoked right before the value of TasksRemaining is changed.
OnTasksRemainingChanging(int, int)
Executes the logic for when TasksRemaining is changing.
Declaration
private void OnTasksRemainingChanging(int oldValue, int newValue)
Parameters
| Type | Name | Description |
|---|---|---|
| int | oldValue | The previous property value that is being replaced. |
| int | newValue | The new property value being set. |
Remarks
This method is invoked right before the value of TasksRemaining is changed.
SetTaskOrder(List<string>)
Applies a custom task ordering before the FSM starts.
Declaration
public void SetTaskOrder(List<string> orderedNames)
Parameters
| Type | Name | Description |
|---|---|---|
| List<string> | orderedNames |
Start()
Starts the FSM, resetting task indices and transitioning to the first rest state.
Declaration
public void Start()
Stop()
Stops the FSM immediately and resets observable state.
Declaration
public void Stop()
TransitionTo(string)
Transitions to a new FSM state and resets the elapsed timer.
Declaration
private void TransitionTo(string newState)
Parameters
| Type | Name | Description |
|---|---|---|
| string | newState | The target FSM state name. |
Events
OnCompleted
Fired when the FSM completes all tasks.
Declaration
public event Action? OnCompleted
Event Type
| Type | Description |
|---|---|
| Action |
OnFsmStateChanged
Fired on each FSM state transition with (newState, taskName).
Declaration
public event Action<string, string?>? OnFsmStateChanged
Event Type
| Type | Description |
|---|---|
| Action<string, string> |