Merge pull request #4 from SELab-3-2026/chore/setup-dev-environment

chore: Configure development environment

docs/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contribution Guidelines
+
+This document outlines the contribution protocols for the scientific software engineering project focusing on bio-inspired control architectures for brittle-star-like robots. The primary objective of this project is to produce scientific insight, rather than a commercial product.
+
+## 1. Scientific Context & Methodology
+
+* **Research Focus:** The goal is to study how controller modularity affects learning speed, coordination, and fault tolerance in brittle-star locomotion.
+* **Hypothesis-Driven Design:** Clear hypotheses must dictate a structured methodology and rigorous evaluation. All design decisions must be formally documented prior to implementation.
+* **Scaffolding Approach:** Development must start with simple setups before progressively increasing the complexity of environments and morphologies.
+* **Evaluation of Results:** Negative results possess scientific validity when thoroughly analyzed. If a controller fails to learn locomotion, providing a comprehensive analysis of the failure is considered a strong scientific contribution.
+* **Reproducibility:** Contributors must utilize fixed library versions. Configuration systems (such as json, gin, or yaml) must be employed to ensure reproducible runs.
+
+## 2. Clean Code & Code Quality
+
+Code readability is paramount, as code is read far more frequently than it is written.
+
+* **Naming Conventions:** Variables and functions must utilize consistent, intention-revealing names. A long, descriptive name is strictly preferred over a short name accompanied by a comment.
+* **Function Design:** Functions must be modular and adhere to the single responsibility principle. Arguments must be minimized, and boolean flag arguments controlling behavior should be avoided.
+* **Commenting:** Code must document the "how," while comments are strictly reserved for documenting the "why". Commented-out code is prohibited and must be deleted via version control.
+* **YAGNI:** Contributors must adhere to the "You Aren't Gonna Need It" (YAGNI) principle and actively avoid premature optimization.
+* **Notebooks:** Jupyter Notebooks are strictly limited to quick prototyping, tutorials, demonstrations, or post-processing analysis. They are explicitly forbidden for general software development because they discourage modularity.
+
+## 3. Version Control & Repository Structure
+
+* **Git Practices:** Commits must be frequent and small. Each commit should relate to exactly one piece of functionality.
+* **Branching Strategy:** The `dev` branch serves as the integration branch for pushing and merging code. Only stable releases may be pushed to the `main` branch.
+* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see `DEVELOPMENT.md` for setup).
+* **Repository Layout:** The repository must maintain the following core directories: `src/` for algorithms, `env/` for MuJoCo wrappers, `config/` for experiment configurations, `experiments/` for scripts, `docs/` for Doxygen or ReadTheDocs documentation, and `tests/` for unit tests.
+
+## 4. Architecture & Tooling
+
+* **Algorithms & Frameworks:** Proximal Policy Optimization (PPO) is the recommended baseline algorithm. CleanRL should be used as a starting point and adapted for continuous action spaces. All Artificial Neural Network (ANN) controller architectures must be implemented using Flax.
+* **Simulation:** The simulation environment utilizes a MuJoCo brittle star. XML MuJoCo structures must remain realistic and respect morphological constraints.
+* **Experiment Tracking:** Weights & Biases (wandb) must be utilized for tracking and logging all experiments.
+* **Code Styling:** All code must conform to the chosen style guide (i.e. Google standard). This is enforced using build tools and pre-commit hooks such as flake8, black, or isort.

docs/DEVELOPMENT.md

@@ -0,0 +1,61 @@
+# 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](https://github.com/astral-sh/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`.
+
+## Git LFS (Critical)
+
+**All developers must have Git LFS installed locally.** This repository tracks model weights (`.pt`, `.safetensors`, etc.), recordings (`.mp4`), and datasets using Git LFS.
+
+- **Setup:** Run `git lfs install` after cloning this repository. If you are using the `.devcontainer` or `flake.nix`, LFS is typically available automatically.
+- If you clone without LFS installed, run `git lfs pull` after installation to fetch the actual data files instead of the small pointer files.
+
+## 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (for GPU support).
+
+### Setup for VS Code
+
+1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-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](https://docs.astral.sh/uv/getting-started/installation/).
+2. Run `uv sync --frozen` (CPU) or `uv sync --frozen --extra cuda` (GPU).
+
+## Hardware Acceleration (JAX)
+
+Verify your setup by running the JAX initialization test:
+
+```bash
+uv run pytest tests/test_jax_init.py
+```
+In the devcontainer, this will succeed on both CPU and GPU. A `GpuDevice` is expected if a GPU is detected and the `cuda` extra was installed.