Configuration File Setup

Configuration File (config.yaml)

SMOCS uses a combination of environment variables (.env file) and YAML configuration (config.yaml) to manage system settings. This separation keeps sensitive credentials separate from application logic.This section will go through the configuration file required for information you do want to publish and share.

Location and Loading

The main configuration file is located at:

SMOCS/orchestration/config.yaml

Override the path with:

CONFIG_PATH=/path/to/custom/config.yaml

Configuration Structure

The config.yaml file is organized into logical sections:

# Data source selection
source: "gymnasium"

# Source-specific configurations
mqtt:
  # MQTT topic configurations
  
epics:
  # EPICS PV configurations
  
gymnasium:
  # Gymnasium environment settings
  
# Kafka settings
kafka:
  # Topic management settings
  
# Agent configurations
autoencoder_agent1:
  # First autoencoder agent settings
  
rl_control_agent1:
  # First RL agent settings
  
# Project metadata
project:
  name: "smocs-project-name"

Source Configuration

source: "gymnasium"  # Options: "gymnasium", "mqtt", "epics"

Purpose: Identifies the primary data source for the system (for documentation/tracking).

MQTT Configuration

Basic MQTT Setup

mqtt:
  topics:
    - topic: "sensor/temperature/room1"
      channel_paths:
        temperature: "value"
        humidity: "humidity"
      timestamp_path: "timestamp"
      
    - topic: "sensor/pressure/tank1"
      channel_paths:
        pressure_value: "reading.pressure"
        pressure_unit: "reading.unit"
      timestamp_path: "reading.timestamp"

MQTT Topic Configuration Fields

Field	Type	Required	Description
`topic`	string	Yes	MQTT topic to subscribe to
`channel_paths`	dict	Yes	Mapping of channel names to JSON paths
`timestamp_path`	string	No	JSON path to timestamp field

Channel Path Syntax

Use dot notation to navigate nested JSON:

// MQTT Message
{
  "sensor": {
    "reading": {
      "value": 23.5,
      "unit": "celsius"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

# Configuration
channel_paths:
  temperature: "sensor.reading.value"
  unit: "sensor.reading.unit"
timestamp_path: "timestamp"

Complex MQTT Example

mqtt:
  topics:
    - topic: "bl-fermi-01-dump/blinky-hub/blinky-mqtt/flowMeter-01/reading"
      channel_paths:
        rate1_value: "rate1.value"
        rate1_low: "rate1.alarm.limits.low"
        rate1_high: "rate1.alarm.limits.high"
        rate2_value: "rate2.value"
        rate2_low: "rate2.alarm.limits.low"
        rate2_high: "rate2.alarm.limits.high"
        rate3_value: "rate3.value"
        rate3_low: "rate3.alarm.limits.low"
        rate3_high: "rate3.alarm.limits.high"
      timestamp_path: "timeStamp"

Result: Extracts 9 channels from a complex nested message structure.

EPICS Configuration

Basic EPICS Setup

epics:
  source: CEBAF
  PVs:
    - IPMK203.XPOS
    - IPMK203.YPOS
    - IPMK203.PHAS
    - IPMK101.XPOS
    - IPMK101.YPOS
    - IPMK101.PHAS

EPICS Configuration Fields

Field	Type	Required	Description
`source`	string	Yes	Source identifier (becomes Kafka topic)
`PVs`	list	Yes	List of EPICS Process Variable names

How EPICS Integration Works

EPICS IOCs → Channel Access → epics-kafka-producer → Kafka Topic
                                                        ↓
                                          Topic: "CEBAF"
                                          Message: {
                                            "timestamp": 1234567890,
                                            "channels": {
                                              "IPMK203.XPOS": 1.23,
                                              "IPMK203.YPOS": -0.45,
                                              ...
                                            }
                                          }

Key Points:

All PVs are polled at 1-second intervals
Data is published to a single Kafka topic (source name)
Channel names match PV names exactly

Gymnasium Configuration

Complete Gymnasium Configuration

gymnasium:
  # Environment Selection
  environment: "Pendulum-v1"  # Any Gym environment ID
  
  # Rendering
  render_mode: null  # Options: null, 'human', 'rgb_array'
  max_episode_steps: null  # null = use environment default
  
  # Kafka Topics
  input_topic: "gymnasium-action"
  output_topics:
    sarsa: "gymnasium-sarsa"      # Full SARSA tuples
    state: "gymnasium-state"       # State-only messages
    decomposed: "gymnasium-output" # Flattened data for monitoring
  
  # Operation Mode
  blocking_mode: false  # true = wait for Kafka actions
  default_action_strategy: "random"  # 'random' or 'zero'
  
  # Timing
  step_delay: 0.0  # Seconds between steps
  reset_on_start: true  # Reset environment on startup

Gymnasium Configuration Fields

Field	Type	Default	Description
`environment`	string	Required	Gymnasium environment ID
`render_mode`	string/null	null	Visualization mode
`max_episode_steps`	int/null	null	Episode length limit
`input_topic`	string	Required	Topic for actions
`output_topics`	dict	Required	Topics for observations
`blocking_mode`	bool	true	Wait for actions vs use defaults
`default_action_strategy`	string	"random"	Action when none received
`step_delay`	float	0.0	Delay between environment steps
`reset_on_start`	bool	true	Reset on container start

Gymnasium Environment Options

SMOCS supports any Gymnasium environment:

Classic Control:

CartPole-v1
Pendulum-v1
MountainCar-v0
Acrobot-v1

MuJoCo (requires MuJoCo license):

Ant-v4
HalfCheetah-v4
Hopper-v4
Humanoid-v4

Custom Environments:

gymnasium:
  environment: "SCORE-IndustryParticleAccelerator-v0"  # Custom registered env

Blocking vs Non-Blocking Mode

Blocking Mode (blocking_mode: true):

Environment → Wait for Kafka action → Execute → Publish state → Wait...

Use when: RL agent controls all actions
Behavior: Environment pauses until action received
Pros: Precise control, no wasted computation
Cons: Deadlocks if agent fails

Non-Blocking Mode (blocking_mode: false):

Environment → Check Kafka → Use action OR default → Execute → Publish → Loop

Use when: Testing, development, fallback behavior needed
Behavior: Uses default actions when none available
Pros: Keeps running even if agent fails
Cons: May execute unintended actions

Kafka Configuration

kafka:
  auto_create: true  # Automatically create topics
  partitions: 1      # Default partition count
  replication_factor: 1  # Replication factor

Kafka Configuration Fields

Field	Type	Default	Description
`auto_create`	bool	true	Create topics automatically
`partitions`	int	1	Number of partitions per topic
`replication_factor`	int	1	Replication factor for durability

Production Recommendations:

partitions: 3-6 for parallelism
replication_factor: 3 for high availability
auto_create: false (pre-create topics with proper config)

Agent Configuration

Autoencoder Agent Configuration

autoencoder_agent1:
  # Preprocessing Pipeline
  preprocessing_pipeline:
    - bounds_normalizer
    - window_processor
  
  # Model Architecture
  window_size: 5
  encoder_dims: [64, 32, 16]
  
  # Training Parameters
  min_training_samples: 100
  learning_rate: 0.0001
  batch_size: 16
  samples_multiplier: 3
  epochs: 10
  
  # Thread Control
  enabled_threads: ['ingest', 'training', 'inference']
  
  # Model Input Specification
  model_input:
    channels:
      - state_0
      - state_1
      - state_2
    bounds:
      - [-1.0, 1.0]
      - [-1.0, 1.0]
      - [-8.0, 8.0]
  
  # Model Output
  model_output:
    channels:
      - state_0
      - state_1
      - state_2
  
  # Kafka Topics
  kafka_topics:
    input: "gymnasium-output"
    output: "autoencoder1-anomalies"
    training_output: "autoencoder1-training-results"

Autoencoder Configuration Fields

Field	Type	Required	Description
`preprocessing_pipeline`	list	Yes	Ordered list of preprocessors
`window_size`	int	Yes	Timesteps per training window
`encoder_dims`	list	Yes	Layer sizes for encoder
`min_training_samples`	int	Yes	Minimum samples before training
`learning_rate`	float	Yes	Adam optimizer learning rate
`batch_size`	int	Yes	Training batch size
`samples_multiplier`	int	Yes	Multiplier for effective batch size
`epochs`	int	Yes	Training epochs per cycle
`enabled_threads`	list	Yes	Which threads to start
`model_input`	dict	Yes	Input channels and bounds
`model_output`	dict	Yes	Output channels
`kafka_topics`	dict	Yes	Input/output topic mapping

RL Control Agent Configuration

rl_control_agent1:
  # Environment
  environment: "Pendulum-v1"
  
  # SOCT Agent Type
  soct_agent_type: "KerasTD3-v0"  # Options: KerasTD3-v0, KerasSAC-v0
  soct_agent_config_path: "keras_td3.cfg"
  
  # Buffer Configuration
  buffer_type: "ER-v0"  # Experience Replay
  buffer_size: 1000000
  
  # Thread Control
  enabled_threads: ['ingest', 'training', 'inference']
  
  # Kafka Topics
  kafka_topics:
    input_sarsa: "gymnasium-sarsa"
    input_state: "gymnasium-state"
    output_action: "gymnasium-action"
  
  # Data Ingest Configuration
  data_ingest:
    use_pipeline_sync: true
    pipeline_timeout_sec: 100.0
  
  # Training Configuration
  training:
    check_interval_ms: 10
    use_pipeline_sync: true
    pipeline_timeout_sec: 100.0
    lock_timeout_sec: 2.0
  
  # Inference Configuration
  inference:
    train_mode: true  # Exploration vs exploitation
    use_pipeline_sync: true
    pipeline_timeout_sec: 100.0
    log_lock_wait_threshold_ms: 100
  
  # Logging
  logdir: "./logs/rl_agent1"

RL Agent Configuration Fields

Field	Type	Required	Description
`environment`	string	Yes	Gym environment ID
`soct_agent_type`	string	Yes	SOCT algorithm (TD3, SAC)
`soct_agent_config_path`	string	No	Path to SOCT config file
`buffer_type`	string	Yes	Replay buffer type
`buffer_size`	int	Yes	Replay buffer capacity
`enabled_threads`	list	Yes	Which threads to start
`kafka_topics`	dict	Yes	Topic mappings
`data_ingest`	dict	Yes	Ingestion thread config
`training`	dict	Yes	Training thread config
`inference`	dict	Yes	Inference thread config
`logdir`	string	Yes	TensorBoard log directory

SOCT Configuration Files

SOCT agent parameters are configured in separate .cfg files located in /orchestration/soct_configs/:

keras_td3.cfg:

{
    "warmup_size": "2500",
    "batch_size": "256",
    "critic_learning_rate": "0.0003",
    "actor_learning_rate": "0.0003",
    "tau": "0.005",
    "discount": "0.99",
    "exploration_noise_fraction": "0.1"
}

actor_fcnn.cfg (Actor network):

{
  "hidden_layers": 2,
  "nodes_per_layer": [256, 256],
  "activation_functions": ["relu", "relu", "tanh"]
}

critic_fcnn.cfg (Critic network):

{
  "hidden_layers": 2,
  "nodes_per_layer": [256, 256],
  "activation_functions": ["relu", "relu", "linear"],
  "use_bn": "True"
}

Project Configuration

project:
  name: "smocs-gymnasium-rl-control"

Purpose: Project identifier for logging, metrics, and organization.

Configuration File (config.yaml)​

Location and Loading​

Configuration Structure​

Source Configuration​

MQTT Configuration​

Basic MQTT Setup​

MQTT Topic Configuration Fields​

Channel Path Syntax​

Complex MQTT Example​

EPICS Configuration​

Basic EPICS Setup​

EPICS Configuration Fields​

How EPICS Integration Works​

Gymnasium Configuration​

Complete Gymnasium Configuration​

Gymnasium Configuration Fields​

Gymnasium Environment Options​

Blocking vs Non-Blocking Mode​

Kafka Configuration​

Kafka Configuration Fields​

Agent Configuration​

Autoencoder Agent Configuration​

Autoencoder Configuration Fields​

RL Control Agent Configuration​

RL Agent Configuration Fields​

SOCT Configuration Files​

Project Configuration​