CST-SUMO Controller

This repository contains a CST-Python based controller that orchestrates a SUMO mobility simulation, triggers a clustering step, and exchanges state through Redis.

This project was developed as part of the Cognitive Architectures research line from the Hub for Artificial Intelligence and Cognitive Architectures (H.IAAC) of the State University of Campinas (UNICAMP). See more projects from the group here.

Overview

The controller currently implements this execution flow:

Wait for a start signal in Redis.
Load a SumoConfiguration payload from Redis.
Build a CST-Python mind with four codelets.
Run the local SUMO backend on the bundled UNICAMP map.
Generate trajectory CSV files under sumo_backend/data/.
Call an external clustering API and extract its outputs.
Persist run metadata back to Redis.

Current Status

The current codebase behaves as follows:

The main execution path is implemented and starts in main.py.
Redis is mandatory for the default execution path.
SUMO assets for the UNICAMP map are committed under sumo_backend/src/sumo_map/unicamp/.
The clustering step depends on an HTTP service at http://localhost:8000/cluster.
config/project.yaml must define cluster.output_ui_dir, and the current default points to a machine-specific Unity project path.
The SUMO backend writes CSV outputs to disk, and the controller later runs clustering on sumo_backend/data/traffic/ego.csv.
The CST memories GPSData and InCreationGPSBuffer are present in the architecture, but the current SUMO backend writes trajectories directly to CSV instead of streaming timestamped samples into those memories. As a result, Redis persistence is currently more useful for run metadata than for a populated in-memory GPS buffer.

Repository Structure

main.py: default entry point that waits for Redis input and runs the controller.
sumo_controller/: main Python package.
sumo_controller/mind_factory.py: builds the CST mind and wires memories and codelets.
sumo_controller/adapters.py: Redis storage adapter and auxiliary adapters.
sumo_controller/interfaces.py: integration contracts and the current SUMO API wrapper.
sumo_controller/models.py: input model used to normalize SumoConfiguration.
sumo_controller/codelets/: CST codelets for simulation, buffering, transfer, and clustering.
sumo_backend/: local SUMO execution backend, map assets, generated data, notebooks, and helper scripts.
config/project.yaml: project-level configuration, currently used for cluster output export.
requirements.txt: practical runtime dependencies for local execution.
pyproject.toml: package metadata and minimal install dependencies.

Architecture

The CST mind currently uses four codelets:

SumoSimulatorCodelet: loads the configuration, runs the SUMO backend, and updates SimulationStatus.
BufferCreatorCodelet: intended to copy timestamped GPS samples into a perceptual buffer.
TFCClusterRunnerCodelet: posts a CSV to the clustering API, extracts the resulting ZIP, and publishes output file paths.
TransferCodelet: persists the final buffer and run metadata through the storage adapter.

The default ClusterConfig is built internally by sumo_controller/mind_factory.py and points the clustering step to sumo_backend/data/traffic/ego.csv.

Dependencies / Requirements

Minimum requirements:

Python 3.10 or newer
Redis server
SUMO installed locally
curl available on the system path
A clustering API listening on http://localhost:8000/cluster

Python dependencies actually used at runtime include:

cst-python
redis
pandas
numpy
scipy
sumolib
matplotlib
pyproj

Notes:

pyproject.toml declares only the package-level minimum dependencies.
requirements.txt is closer to the real local execution environment.
SUMO Python tooling may also require SUMO_HOME to be configured on your machine, depending on your installation.

Installation / Usage

Create a virtual environment and install the runtime dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

Install SUMO on Ubuntu:

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc

Start Redis locally or point the controller to an existing Redis instance through REDIS_URL.

Update config/project.yaml so that cluster.output_ui_dir points to a valid directory on your machine.

Provide a SumoConfiguration payload in Redis. A complete example is available in sumo_backend/configs/sumo_config.json.

Expected payload shape:

{
  "api": {
    "cut": 5,
    "epochs": 20
  },
  "sumo": {
    "behaviour": {
      "simulation": {
        "time_to_teleport": 100,
        "lateral_resolution": 0.8,
        "step_length": 0.01,
        "end_time": 1000,
        "end_time_random_trips": 1000
      },
      "vehicle": {
        "maxSpeed": 200,
        "accel": 2.6,
        "decel": 4.5,
        "speedFactor": 1.0,
        "minGap": 2.5,
        "emergencyDecel": 9.0,
        "vClass": "passenger"
      },
      "locations": [
        "home",
        "Instituto de Computação",
        "Instituto de Filosofia e Ciências Humanas",
        "Instituto de Geociências",
        "home"
      ]
    }
  }
}

Default Redis keys:

Configuration key: default_mind:memories:SumoConfiguration
Start signal key: default_mind:memories:SimulationStarted
Start signal field: I

To run the code:

python3 main.py

When the controller is waiting, trigger the run by running the Unity interface.

Optional environment variables:

REDIS_URL: Redis connection string. Default: redis://localhost:6379/0
REDIS_KEY_PREFIX: prefix for controller-managed output keys. Default: sumo_controller
REDIS_TTL_SECONDS: optional TTL for persisted Redis keys
SUMO_CONFIGURATION_KEY: overrides the Redis key used to load SumoConfiguration
SUMO_START_SIGNAL_KEY: overrides the Redis key used for the start signal
SUMO_START_POLL_INTERVAL_SECONDS: polling interval while waiting for the start signal
SUMO_START_TIMEOUT_SECONDS: optional timeout while waiting for the start signal

Outputs

After a successful run, the current implementation produces these artifacts:

SUMO CSV outputs under sumo_backend/data/no_traffic/ and sumo_backend/data/traffic/
Cluster outputs extracted to the directory defined by cluster.output_ui_dir
Redis entries under the configured key prefix for episode metadata and buffer payloads, which may be empty in the current integration

The clustering step expects enough rows in the input CSV. If the traffic CSV is too short, the codelet upsamples the data before sending it to the API.

Known Limitations

The controller currently assumes a local clustering API at a fixed URL instead of a configurable endpoint.
The cluster input CSV path is currently hard-coded in the mind factory.
The default config/project.yaml value is machine-specific and will need to be changed on any other workstation.
The current architecture includes memory objects for GPS streaming, but the active SUMO backend persists trajectories directly to files instead of filling those memories step by step.

Citation

@software{my_citation,
author = {Parede de Souza, Henrique and da Silva Florencio, Renan and  Yuji Sakabe, Eduardo and Dornhofer Paro Costa, Paula},
title = {CST-SUMO Controller},
url = {https://github.com/H-IAAC/CST-SUMO-controller}
}

Authors

(2026-) Henrique Parede de Souza: Computer Engineering student, FEEC-UNICAMP
(2026-) Renan Florencio: Computer Engineering student, FEEC-UNICAMP
(2026-) Eduardo Yuji Sakabe: PhD Candidate, FEEC-UNICAMP
(Advisor, 2026-) Paula Dornhofer Paro Costa: Professor, FEEC-UNICAMP

Acknowledgements

This study was financed, in part, by the São Paulo Research Foundation (FAPESP), Brazil. Process Number 2024/23473-6.

Project supported by the brazilian Ministry of Science, Technology and Innovations, with resources from Law No. 8,248, of October 23, 1991