How sarkarsaswata/booster_soccer_showdown works
Project type and purpose
• This is a robotics competition framework and research toolkit, combining:
• Teleoperation interface (“booster_control/”)
• Motion replay & analysis tools (“mimic/”)
• Imitation Learning algorithms (“imitation_learning/”)
• Reinforcement Learning training scripts (“training_scripts/”)
• It integrates MuJoCo environments via the SAI client, supports data collection, offline imitation, and online policy learning (DDPG).
File structure
• Top-level packages:
• booster_control/: keyboard teleop scripts + utilities
• mimic/: forward kinematics & visualization, assets (MuJoCo XML & meshes)
• imitation_learning/: agent implementations (BC, IQL, GCBC, etc.), data collection & preprocessing, training & evaluation utils, submission stubs
• training_scripts/: standalone DDPG implementation (model, buffer, training loop), main entrypoint, test harness
• Resources/requirements:
• requirements.txt (Python ≥3.10 + MuJoCo, JAX, PyTorch, SAI SDK)
• resources/: competition banner, config files
• External dependencies:
• Hugging Face (datasets & model hosting)
• SAI competition platform (env server & API)
README for additional insights
• Describes:
• Teleop usage & commands
• Mimic scripts arguments & workflows
• Training workflow: DDPG model, Preprocessor, SAI client integration
• Test & benchmarking post-training
Main components & interactions
a. Components
1. Teleoperation Module
– CLI script: booster_control/teleoperate.py
– Utilities (se3_keyboard, t1_utils)
2. Simulation Environment & Asset Store
– SAI Client ↔ MuJoCo Engine
– mimic/assets/booster_t1 XML + meshes
3. Data Flow & Storage
– Raw motion files (.npz) from Hugging Face
– Local dataset folder / imitation_learning/scripts/collect_data.py
4. Mimic Module
– forward_kinematics.py → computes derived signals
– visualize_data.py → replays motion in viewer
5. Imitation Learning Module
– Agents (bc, iql, gciql, etc.)
– Preprocessor & networks (utils/networks.py, flax_utils.py)
– Training & evaluation scripts (train.py, test.py)
– Submission tools (submission/model.py, model.pt, submit_sai.py)
6. Reinforcement Learning Module
– DDPG model (training_scripts/ddpg.py)
– ReplayBuffer & training loop (training_scripts/training.py)
– Main entrypoint & environment init (training_scripts/main.py)
– Test harness (training_scripts/test.py)
7. External Services
– Hugging Face (dataset & model hub)
– SAI competition API for environment instantiation, watch, benchmark
b. Relationships & data flows
1. Teleop → SAI Client → MuJoCo → live control → optional data recording → raw motion files
2. Raw motion files → Mimic Module → enriched kinematics → npz outputs
3. Raw motion files → Imitation Learning scripts (collect_data.py → preprocessor) → algorithmic agents → trained IL models → submission scripts
4. SAI Client → RL Training main.py → Preprocessor → DDPG Model → environment interaction → ReplayBuffer → training loop → saved RL checkpoint → optional watch/benchmark calls back to SAI
5. All modules may read/write to local disk or remote Hugging Face storage
c. Architectural patterns & design principles
– Modular Python packages, each with clear responsibility
– CLI-driven entrypoints for each workflow (teleop, mimic, IL, RL)
– Use of external services for data/model hosting (Hugging Face) and env access (SAI)
– Separation of concerns: data collection, offline processing, algorithmic training, inference/teleop
d. Key technologies/frameworks
– Python ≥3.10
– MuJoCo via SAI client
– JAX & Flax (imitation_learning)
– PyTorch (via jax2torch conversion script & RL training)
– SAI SDK (env instantiation, watch, benchmark)
– Hugging Face Datasets & Model Hub