2026SEL3-project-Brittle_Star_Controller_Modularity/docs/DEVELOPMENT.md

Development Guide

This guide outlines how to set up the development environment for this project, prioritizing reproducible builds, environment parity, and cross-hardware compatibility.

Reproducibility &uv

This project uses uv to manage dependencies and virtual environments. The uv.lock file is the absolute source of truth for package versions and must always be committed.

Source of Truth

• Never modify uv.lock manually.
• To add a dependency, run uv add <package>.
• To update dependencies, run uv lock --upgrade.
• To sync your environment with the lockfile, run uv sync --frozen.

Devcontainer Setup (Recommended)

The devcontainer provides an identical experience to local development but with all system dependencies pre-configured. It automatically detects your hardware (GPU vs CPU) and syncs the appropriate dependencies.

Prerequisites

• Docker Desktop or Docker Engine.
• NVIDIA Container Toolkit (for GPU support).

Setup for VS Code

1. Install the Dev Containers extension.
2. Open the project and click Reopen in Container.
3. On first launch, the post-create.sh script will:
   • Detect if an NVIDIA GPU is available via nvidia-smi.
   • Run uv sync --frozen --extra cuda if a GPU is found.
   • Run uv sync --frozen otherwise.
4. The environment is stored in a named volume for .venv to ensure persistence and performance.

Setup for JetBrains IDEs

1. The IDE will detect the .devcontainer/devcontainer.json file.
2. The environment is pre-configured to point to /workspaces/project/.venv.
3. The hardware-aware sync will run automatically during container creation.

Local Development (Alternative)

If you prefer not to use Docker:

1. Install uv.
2. Run uv sync --frozen (CPU) or uv sync --frozen --extra cuda (GPU).

Hardware Acceleration (JAX)

Verify your setup by running:

python -c "import jax; print(jax.devices())"

In the devcontainer, this will report a GpuDevice if a GPU is detected and the cuda extra was installed.