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:

IndexDescription
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

Inheritance
Stimulus
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:

StateBehavior
restOutput zero vector for 2.0 s.
riseSmooth sine² ramp from zero to task target over 0.5 s.
holdHold task target for 1.0 s.
captureHold task target for CaptureDuration s — data capture window.
fallSmooth cosine² ramp from task target to zero over 1.0 s.
endAll 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
BaseBlock.DumpFilePrefix

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
BaseBlock.JsonTypeName

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
BaseBlock.Visualization
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 Params: [captureDuration, "name:v1;v2;...", ...]. See the class-level example for details.

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
BaseBlock.Dispose()

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 ConfigureInput reads them, or null when the block takes no parameters.

Overrides
BaseBlock.GetJsonParams()

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. "fall").

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
BaseBlock.OnReceive(object, object)
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>

Implements

INotifyPropertyChanged
INotifyPropertyChanging
ISubscriber
IPublisher
IBaseBlockProps
IJsonExportable
IDisposable
IAsyncDisposable

Search documentation

Start typing to search the documentation.