From 5716b73eb9620b4092d6910bd003ac000fb4079a Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Tue, 28 Apr 2026 16:25:05 +0200 Subject: [PATCH] docs: restructure API docs --- README.md | 44 ++++++++----------------------- docs/DEVELOPMENT.md | 21 +++------------ docs/README.md | 10 +++++-- docs/api/simulate.md | 14 ---------- docs/api/simulation.md | 39 +++++++++++++++++++++++++++ docs/api/tracking.md | 60 ++++++++++++++++++++++++++++++++++++++++++ docs/api/training.md | 49 ++++++++++++++++++++++++++++++++++ 7 files changed, 171 insertions(+), 66 deletions(-) delete mode 100644 docs/api/simulate.md create mode 100644 docs/api/simulation.md create mode 100644 docs/api/tracking.md create mode 100644 docs/api/training.md diff --git a/README.md b/README.md index dd85e12..572fd73 100644 --- a/README.md +++ b/README.md @@ -13,44 +13,22 @@ To set up the UV module, you can run the following command: uv sync --frozen ``` -### Configuration +## Usage -1. **Copy the default configuration:** +For detailed instructions on how to use the project, please refer to the **[API Documentation](docs/README.md)**. + +### Quick Start + +1. **Train a model:** ```bash - cp configs/default_ppo.yaml configs/my_experiment.yaml + uv run python scripts/train.py ppo.learning_rate=0.001 logging.track=true ``` -2. **Edit `configs/my_experiment.yaml`** to set your WandB credentials: - ```yaml - track: true # Enable WandB logging - wandb_entity: "your-wandb-username" # Replace with your username/team - wandb_project_name: "PPO-Modularity" - ``` +2. **Monitor progress:** + See [Tracking & Monitoring](docs/api/tracking.md). -3. **(Optional) Login to WandB:** - ```bash - uv run wandb login - ``` - -### Training - -example command: - -```bash -uv run python scripts/train.py -``` - -Or use a custom config file: - -```bash -uv run python scripts/train.py --config configs/my_experiment.yaml -``` - -Override specific parameters: - -```bash -uv run python scripts/train.py --learning-rate 0.001 --num-envs 32 --track -``` +3. **Simulate a trained model:** + See [Simulation & Evaluation](docs/api/simulation.md). ## HPC diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 5a01d26..3518b38 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -62,22 +62,9 @@ In the devcontainer, this will succeed on both CPU and GPU. A `GpuDevice` is exp ## Logging & Monitoring -This project uses a unified logging system through the `experiment_logger` package. For a full API reference, see the [package README](../src/experiment_logger/README.md). - -### Quick Setup - -1. **Authorization**: Export your API key in your terminal to enable WandB synchronization: - ```bash - export WANDB_API_KEY=your_copied_api_key_here - ``` -2. **Toggle Tracking**: Use the `--track` flag in `scripts/train.py` to enable online sync. -3. **Local Monitoring**: All runs are recorded in the `runs/` directory. View scalars with TensorBoard: - ```bash - tensorboard --logdir runs/ - ``` - -### Environment Awareness - -The logger automatically detects if it is running in an interactive terminal or a non-interactive environment (like an HPC Slurm job). It will automatically disable progress bars and switch to robust fallback modes (offline logging) to ensure your experiments never hang. +This project uses a unified logging system through the `experiment_logger` package. +- **Usage in Code**: To use the logger in your scripts, refer to the [package README](../src/experiment_logger/README.md) for the API reference. +- **WandB/TensorBoard Setup**: For information on how to configure tracking for experiments, see the [Tracking & Monitoring API Guide](./api/tracking.md). +The logger automatically detects if it is running in an interactive terminal or a non-interactive environment (like an HPC Slurm job), adjusting progress bars and fallback modes accordingly. diff --git a/docs/README.md b/docs/README.md index a4f4ea0..3c76684 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,8 @@ ## Design & architecture ([`/design`](./design/)) +If you are interested in the "why did you do it like this?" + - [Actor/critic architecture](./design/actor-critic.md): Description of the actor-critic pipeline. - [Communication](./design/communication.md): Message propagation, Nerve-Net style. - [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level. @@ -11,5 +13,9 @@ ## API reference ([`/api`](./api/)) -- [Environment](./api/environment.md): MuJoCo environment interaction, state retrieval, and configuration. -- [Simulate](./api/simulate.md): Simulation rendering. +If you are interested in the "how do I use it?" + +- [Training](./api/training.md): How to configure and run experiments. +- [Tracking & Monitoring](./api/tracking.md): Setting up WandB and TensorBoard to monitor runs. +- [Simulation](./api/simulation.md): Visualizing and evaluating models. +- [Environment](./api/environment.md): MuJoCo environment interaction and configuration. diff --git a/docs/api/simulate.md b/docs/api/simulate.md deleted file mode 100644 index 9c4b21b..0000000 --- a/docs/api/simulate.md +++ /dev/null @@ -1,14 +0,0 @@ -# Training and Simulation for Brittle Star Models - -## Simulating a model - -In order to simulate and view the behavior of a trained model, you can use the `simulate.py` script. This script allows you to specify the path to a trained model and will launch a simulation using that model. This script has the following parameters: - -- `--model`: The path to the trained model artifact to simulate. -- `--model-type`: The type of model to simulate (e.g., `random`, ...) -- `--task`: The task to simulate (e.g., `directed_locomotion`, ...) -- `--seed`: The random seed for reproducibility. - -```bash -python simulate.py --model artifacts/my_model --model-type random --task directed_locomotion --seed 0 -``` \ No newline at end of file diff --git a/docs/api/simulation.md b/docs/api/simulation.md new file mode 100644 index 0000000..0a0e041 --- /dev/null +++ b/docs/api/simulation.md @@ -0,0 +1,39 @@ +# Simulation & Evaluation + +The simulation pipeline allows you to visualize trained models and evaluate their performance under various conditions. + +## Overview + +The simulation pipeline is metadata-driven. Training-specific configurations (morphology, arena, environment, etc.) are automatically loaded from the `_metadata.yaml` file associated with the model checkpoint. + +## Basic Simulation + +To simulate a model in the MuJoCo viewer: + +```bash +uv run scripts/simulate.py simulation.model_path=runs/your_run/final_model.flax +``` + +## Amputation & Morphology Overrides + +You can test trained models on different morphologies (e.g., amputating legs) by providing a morphology override. The observations will be automatically padded up to the training morphology's dimensions: + +```bash +uv run scripts/simulate.py \ + simulation.model_path=runs/your_run/final_model.flax \ + simulation.morphology_override=configs/morphology/3_arms.yaml +``` + +## Video Recording + +Recording videos requires the `[evaluation]` extra: + +```bash +uv run scripts/simulate.py \ + simulation.model_path=runs/your_run/final_model.flax \ + simulation.record_video=true \ + simulation.max_steps=1000 +``` + +Videos and evaluation metadata are stored in timestamped folders alongside the model: +`runs/your_run/final_model_evaluations/eval_/simulation.mp4` diff --git a/docs/api/tracking.md b/docs/api/tracking.md new file mode 100644 index 0000000..226992b --- /dev/null +++ b/docs/api/tracking.md @@ -0,0 +1,60 @@ +# Tracking & Monitoring + +This guide explains how to monitor your experiments using Weights & Biases (WandB) and TensorBoard. + +## Weights & Biases (WandB) + +WandB is used for online synchronization and visualization of training metrics. + +### Authorization + +Export your API key in your terminal to enable WandB synchronization: + +```bash +export WANDB_API_KEY=your_copied_api_key_here +``` + +Alternatively, you can log in using the CLI: + +```bash +uv run wandb login +``` + +### Enabling Tracking + +To enable online sync during a training run, set `logging.track=true` on the command line: + +```bash +uv run python scripts/train.py logging.track=true +``` + +You can also configure your project and entity: + +```bash +uv run python scripts/train.py \ + logging.track=true \ + logging.wandb_project_name="MyProject" \ + logging.wandb_entity="my-team" +``` + +These can also be set in your configuration YAML file under the `logging` key. + +## Local Monitoring with TensorBoard + +All runs are recorded locally in the `runs/` directory (or the directory specified in `experiment.base_run_dir`). You can view scalars and other metrics with TensorBoard: + +```bash +tensorboard --logdir runs/ +``` + +Access the interface at `http://localhost:6006`. + +### CLI Exploration Tool + +For quick diagnostics or to export data to CSV without launching the full TensorBoard UI, you can use the `explore_tensorboard.py` script: + +```bash +uv run python scripts/analysis/explore_tensorboard.py runs/your_run_name/ +``` + +See the detailed description in [`/scripts/analysis/README.md`](../../scripts/analysis/README.md). diff --git a/docs/api/training.md b/docs/api/training.md new file mode 100644 index 0000000..a9678bb --- /dev/null +++ b/docs/api/training.md @@ -0,0 +1,49 @@ +# Training Models + +This guide covers how to configure and run training experiments for the Brittle Star project using Hydra-based configurations. + +## Configuration + +The project uses a modular configuration system powered by [Hydra](https://hydra.cc/). Instead of passing many command-line flags, you select and override configuration groups. + +### Creating a Custom Experiment + +1. **Create a new experiment file:** + Create a file at `configs/experiment/my_experiment.yaml`. You can copy an existing one as a template: + ```bash + cp configs/experiment/base.yaml configs/experiment/my_experiment.yaml + ``` + +2. **Edit `configs/experiment/my_experiment.yaml`** to set your experiment parameters: + ```yaml + # @package _global_ + experiment: + exp_name: "my_custom_run" + seed: 42 + ``` + +## Training Execution + +To start a training run with the default settings defined in `configs/main_config.yaml`: + +```bash +uv run python scripts/train.py +``` + +### Using a Custom Experiment Configuration + +To run with your custom experiment file: + +```bash +uv run python scripts/train.py experiment=my_experiment +``` + +### Command-Line Overrides + +You can override any parameter directly from the command line using Hydra's dot notation. This is useful for quick tests: + +```bash +uv run python scripts/train.py ppo.learning_rate=0.001 ppo.num_envs=32 logging.track=true +``` + +For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).