keyboard
import "github.com/umbralcalc/stochadex/pkg/keyboard"Package keyboard provides interactive user input capabilities for stochadex simulations.
Importing it registers the keyboard as a stream transport, so a config steers a run from the keyboard with a stream input, stream: {keyboard: {partition, keys}}, feeding params_from_input (see stream.go). That is the way to use it; UserInputIteration, which reads keys from inside an iteration, is kept for Go code that builds it directly. It enables real-time user interaction during simulation runs through keyboard events, allowing for dynamic control and parameter adjustment during execution.
Key Features:
- Real-time keyboard event handling
- Configurable key-to-action mapping
- Timeout-based input handling
- Graceful exit and cleanup
- Extensible input channel abstraction
Usage Patterns:
- Pause/resume simulations with keyboard shortcuts
- Adjust simulation parameters in real-time
- Trigger data export or analysis during runs
- Implement interactive debugging and monitoring
- Create user-controlled simulation scenarios
Index
type KeystrokeChannel
KeystrokeChannel abstracts a source of keyboard events.
Usage hints:
- Implement to inject custom key event sources (e.g., tests or GUIs).
- The default StandardKeystrokeChannel reads from the terminal.
type KeystrokeChannel interface {
Get(
partitionIndex int,
settings *simulator.Settings,
) (<-chan keyboard.KeyEvent, error)
}type StandardKeystrokeChannel
StandardKeystrokeChannel retrieves keystrokes from the terminal.
type StandardKeystrokeChannel struct{}func (*StandardKeystrokeChannel) Get
func (s *StandardKeystrokeChannel) Get(partitionIndex int, settings *simulator.Settings) (<-chan keyboard.KeyEvent, error)type UserInputIteration
UserInputIteration provides real-time user interaction during simulation runs through keyboard input handling and action mapping.
This iteration type enables interactive control of simulations by mapping keyboard events to simulation actions. It supports configurable key mappings, timeout handling, and graceful exit functionality.
Interactive Features:
- Real-time keyboard event processing
- Configurable key-to-action mapping
- Timeout-based input handling for non-blocking operation
- Graceful exit with ESC key
- Default value fallback for timeouts
Configuration Parameters:
- “user_input_keystroke_action_<key>”: Maps key characters to action IDs
- “wait_milliseconds”: Timeout duration for input waiting (optional)
- “default_value”: Default action ID used on timeout or exit
Key Mapping: Key mappings are configured using parameters named “user_input_keystroke_action_<key>” where <key> is the character that triggers the action. For example:
- “user_input_keystroke_action_p” => 1 (pause action)
- “user_input_keystroke_action_r” => 2 (resume action)
- “user_input_keystroke_action_s” => 3 (stop action)
Example Configuration:
iteration := &UserInputIteration{
Channel: &StandardKeystrokeChannel{},
}
// Configure key mappings
params.Set("user_input_keystroke_action_p", []float64{1}) // pause
params.Set("user_input_keystroke_action_r", []float64{2}) // resume
params.Set("user_input_keystroke_action_s", []float64{3}) // stop
params.Set("wait_milliseconds", []float64{100}) // 100ms timeout
params.Set("default_value", []float64{0}) // no actionUsage Patterns:
- Interactive simulation control: Allow users to pause, resume, or stop simulations
- Parameter adjustment: Enable real-time parameter modification
- Monitoring and intervention: Provide manual override capabilities
- Educational tools: Create interactive learning experiences
Thread Safety:
- Safe for concurrent use within simulation partitions
- Uses channels for thread-safe communication
- Automatic cleanup on exit
Performance:
- Non-blocking operation with timeout support
- Minimal memory overhead
- Efficient event processing
Error Handling:
- Graceful handling of keyboard initialization errors
- Automatic fallback to default values on timeout
- Clean exit on ESC key press
Deprecated: steer a run from the keyboard with a stream input instead, stream: {keyboard: {partition, keys}}, feeding a param_values partition through params_from_input (see stream.go). That works from a YAML config, records what was pressed for replay, and holds a value until the next key. This iteration is kept for Go code that builds it directly.
type UserInputIteration struct {
Channel KeystrokeChannel
// contains filtered or unexported fields
}func (*UserInputIteration) Configure
func (u *UserInputIteration) Configure(partitionIndex int, settings *simulator.Settings)func (*UserInputIteration) Iterate
func (u *UserInputIteration) Iterate(params *simulator.Params, partitionIndex int, stateHistories []*simulator.StateHistory, timestepsHistory *simulator.CumulativeTimestepsHistory) []float64Generated by gomarkdoc