How matthewbuck36/dsim-lab works
1. This repository is a research workspace, not a single application. It has two main source systems:
- extremum-seeking/: a standalone Python package for extremum-seeking / optimization simulation.
- ros2_ws/: a ROS 2 workspace that turns those ideas into runnable nodes, interfaces, launch files, and a Turtlebot rotating-sensor setup.
2. The extremum_seeking Python package is the algorithmic core. Its main submodules are:
- objectives.py for cost/objective definitions.
- seekers/ for seeker dynamics and simulation orchestration.
- filters/ for filter primitives and combinations.
- averaging/ for perturbation-based estimation.
- modifiers/ for time-modifying logic such as prescribed-time behavior.
- systems.py for plant/system models.
This package is where the control/optimization math lives, independent of ROS.
3. The ROS 2 interface boundary is the ros_esc_interfaces package. It defines the message contracts used across nodes:
- StampedFloat64
- StampedFloat64MultiArray
- StampedString
- StampedTransformMultiArray
- Timekeeper
These messages are the glue between control, sensing, filtering, and logging components.
4. The runtime ROS 2 application is the ros_esc package. It is split into node-level subsystems:
- controller_node: produces control commands from tuning/config inputs.
- cost_function_node: computes objective/cost values from state or sensor data.
- filter_node: filters signals used by the optimizer/controller.
- encoder_node: converts raw motion/state into encoded signals.
- rotate_frame_node: handles frame rotation / spin-profile transforms for the sensor rig.
- sensor_pose_node: publishes or computes sensor transforms/poses.
- data_collection_node: records and visualizes streamed outputs.
- plotting_scripts/: offline analysis and visualization utilities.
config_parsing.py and helper_functions.py support these nodes with shared parsing and utility logic.
5. The main data flow in the ROS 2 system is message-driven:
- simulation or hardware state enters through the Turtlebot / sensor pose / encoder side,
- frame transforms are applied by the rotate-frame and sensor-pose components,
- the cost function consumes the transformed state,
- the filter and controller process the resulting signal,
- outputs are collected and plotted by data collection and plotting tools.
The Stamped* interfaces suggest most payloads are timestamped and move through the system as typed ROS messages.
6. The turtlebot3_rotating_sensor package is the physical/simulation platform around which the ROS nodes operate. It contains:
- URDF, meshes, Gazebo world, RViz config, and launch files.
- controller_config/ for joint/controller YAML.
- bash_scripts/ that encode ready-made experiment launches for different control methods.
- math_simulation/ for offline signal/cost/control modeling.
This package is the integration layer between the robotics platform and the extremum-seeking logic.
7. There is a strong configuration-driven design across the repo. Most experiments are not hard-coded; they are selected through JSON/YAML files under package-specific *_config_files/ directories. These configs encode variants for:
- vehicle type,
- rotation mode,
- cost function type,
- filter choice,
- controller family.
This makes the system easy to rewire without changing node code.
8. The repository supports multiple control families and experiment styles. You can see this in the config and example naming:
- gradient methods,
- adaptive methods such as AdaGrad and RMSProp,
- lie-bracket / GESC variants,
- Newton-style methods,
- forward/angular tuning,
- safety/barrier variants.
Architecturally, these are alternative controller/filter/cost pipelines, not separate apps.
9. Offline and reproducibility tooling is a first-class part of the architecture:
- scripts/ in extremum-seeking/ run benchmark functions such as Ackley, Beale, Rosenbrock, Rastrigin, Sphere, and custom demos.
- paper-recreations/ stores scenario-specific scripts and configs tied to published experiments.
- docs/ provides generated documentation for the Python package.
These support validation and analysis outside ROS execution.
10. The ROS 2 workspace is built with colcon, and the generated build/, install/, and log/ trees are present in the repository snapshot. Those directories are runtime/build artifacts, not source architecture, but they confirm the deployment model:
- packages are built independently,
- launch files start coordinated node sets,
- generated interfaces are shared via the ROS 2 install overlay.
11. The key architectural boundary is between simulation/robotics runtime and algorithmic logic:
- extremum_seeking/ holds reusable math and simulation primitives.
- ros2_ws/src/ros_esc and turtlebot3_rotating_sensor adapt those ideas into ROS 2 nodes and a robot platform.
This separation is important for any diagram: the math library feeds the ROS system, but does not depend on it.
12. If you are drawing the system, the highest-level boxes should likely be:
- Algorithm library
- ROS interface definitions
- ROS control/sensing nodes
- Turtlebot rotating-sensor platform
- Offline scripts/docs/examples
with arrows showing typed ROS messages flowing between the node boxes, and config files selecting experiment variants at startup.
Main entry points: launch Launch files · extremum_seeking Core math · msg Messages · config_parsing.py Config parsing
Components 24
Algorithm library
Standalone extremum-seeking math and simulation package.
- Core math · Reusable extremum-seeking algorithm core, independent of ROS.
extremum-seeking/src/extremum_seeking - Objectives · Objective and cost definitions used by seekers and simulations.
extremum-seeking/src/extremum_seeking/objectives.py - Seekers · Seeker dynamics and simulation orchestration.
extremum-seeking/src/extremum_seeking/seekers - Filters · Filter primitives and filter composition logic.
extremum-seeking/src/extremum_seeking/filters - Averaging · Perturbation-based estimation routines.
extremum-seeking/src/extremum_seeking/averaging - Modifiers · Prescribed-time and other time-modifying behavior.
extremum-seeking/src/extremum_seeking/modifiers - Systems · Plant and system models used in simulations.
extremum-seeking/src/extremum_seeking/systems.py
ROS 2 runtime
ROS nodes that turn the algorithms into a runnable system.
- Controller · Produces control commands from tuning and configuration inputs.
ros2_ws/src/ros_esc/ros_esc/controller_node/controller_node_script.py - Cost function · Computes objective values from state or sensor data.
ros2_ws/src/ros_esc/ros_esc/cost_function_node/cost_function_node_script.py - Filter node · Filters streamed signals for control and optimization.
ros2_ws/src/ros_esc/ros_esc/filter_node/filter_node_script.py - Encoder · Encodes raw motion or state into downstream signals.
ros2_ws/src/ros_esc/ros_esc/encoder_node/encoder_node_script.py - Rotate frame · Applies spin-profile and frame-rotation transforms.
ros2_ws/src/ros_esc/ros_esc/rotate_frame_node/rotate_frame_node_script.py - Sensor pose · Publishes or computes sensor transforms and poses.
ros2_ws/src/ros_esc/ros_esc/sensor_pose_node/sensor_pose_node_script.py - Data collection · Records streamed outputs and supports live plotting.
ros2_ws/src/ros_esc/ros_esc/data_collection_node/data_collection_node_script.py - Config parsing · Shared parsing and helper logic for ROS node startup.
ros2_ws/src/ros_esc/ros_esc/config_parsing.py
ROS interfaces
Shared message contracts for node-to-node communication.
- Messages · Shared typed message definitions for all ROS nodes.
ros2_ws/src/ros_esc_interfaces/msg
Robot platform
Turtlebot rotating-sensor integration, launch, and simulation assets.
- Launch files · Launch entry points for control, RViz, and Gazebo runs.
ros2_ws/src/turtlebot3_rotating_sensor/launch - Robot model · Robot description, meshes, and world assets for the rotating sensor rig.
ros2_ws/src/turtlebot3_rotating_sensor/urdf/turtlebot3_rotating_sensor.urdf - Controller cfg · Joint/controller configuration for the platform.
ros2_ws/src/turtlebot3_rotating_sensor/controller_config/joint_controller.yaml - Experiment scripts · Ready-made experiment entry points for control families and sensor modes.
ros2_ws/src/turtlebot3_rotating_sensor/bash_scripts - Math simulation · Offline platform-specific modeling of control, cost, filters, and signals.
ros2_ws/src/turtlebot3_rotating_sensor/math_simulation
Offline tooling
Scripts and docs for experiments, benchmarks, and reproducibility.
- Python scripts · Standalone benchmark and demo scripts for algorithm validation.
extremum-seeking/scripts - Docs · Generated documentation for the Python package.
extremum-seeking/docs/source/index.rst - Paper recreations · Scenario-specific scripts and configs mirroring published experiments.
ros2_ws/src/ros_esc/paper_recreations
Connections 34
- Core math → Objectives: defines · Algorithm core uses objective definitions.
- Core math → Seekers: simulates · Seekers orchestrate algorithm dynamics.
- Core math → Filters: uses · Algorithms compose filter primitives.
- Core math → Averaging: uses · Algorithms use perturbation-based estimation.
- Core math → Modifiers: uses · Algorithms apply timing modifiers.
- Core math → Systems: models · Core simulations depend on plant/system models.
- Messages → Controller: messages · Controller exchanges typed stamped messages.
- Messages → Cost function: messages · Cost function communicates through shared messages.
- Messages → Filter node: messages · Filter node consumes and emits shared messages.
- Messages → Encoder: messages · Encoder uses shared message contracts.
- Messages → Rotate frame: messages · Rotate-frame logic uses shared message contracts.
- Messages → Sensor pose: messages · Sensor pose logic uses shared message contracts.
- Messages → Data collection: messages · Data collection subscribes to typed messages.
- Config parsing → Controller: configures · Startup config selects controller variant.
- Config parsing → Cost function: configures · Startup config selects cost variant.
- Config parsing → Filter node: configures · Startup config selects filter variant.
- Config parsing → Rotate frame: configures · Startup config selects rotation mode.
- Config parsing → Sensor pose: configures · Startup config selects transform variant.
- Launch files → Controller: starts · Launch files start the node set.
- Launch files → Cost function: starts · Launch files start the node set.
- Launch files → Filter node: starts · Launch files start the node set.
- Launch files → Encoder: starts · Launch files start the node set.
- Launch files → Rotate frame: starts · Launch files start the node set.
- Launch files → Sensor pose: starts · Launch files start the node set.
- Launch files → Data collection: starts · Launch files start the node set.
- Robot model → Sensor pose: feeds · Robot geometry and frames inform sensor pose generation.
- Controller cfg → Launch files: used by · Joint/controller settings are loaded at startup.
- Experiment scripts → Launch files: wraps · Experiment scripts wrap coordinated launches.
- Math simulation → Core math: mirrors · Offline simulation mirrors the algorithmic core.
- Math simulation → Controller: prototypes · Platform math sim prototypes controller behavior.
- Python scripts → Core math: benchmarks · Standalone scripts exercise the algorithm library.
- Paper recreations → Controller: recreates · Paper scenarios recreate ROS control pipelines.
- Paper recreations → Cost function: recreates · Paper scenarios recreate cost pipelines.
- Docs → Core math: documents · Docs describe the Python package API.