Launching the Ethical Gardeners Simulation¶

This tutorial explains how to launch and configure the Ethical Gardeners simulation environment, and how to interpret the results generated by the simulation.

Hydra Configuration System¶

The Ethical Gardeners project uses Hydra for configuration management, which allows you to modularly configure your simulation without modifying the code.

Configuration Structure¶

The configuration is organized into several groups:

configs/
├── config.yaml                # Main configuration file with default values
├── grid/                      # Grid initialization configurations
├── observation/               # Observation strategy configurations
├── metrics/                   # Metrics collection configurations
└── renderer/                  # Visualization configurations

Main Configuration Groups¶

Grid: Controls how the environment grid is initialized (random, from code, or from file)
Observation: Determines how agents perceive the environment (partial or total visibility)
Metrics: Controls how simulation metrics are collected and exported (export, send to Weights & Biases, or both)
Renderer: Controls how the simulation is visualized (console, graphical, or both)

Launching the Simulation¶

Basic Launch Command¶

To run the simulation with the default configuration. After cloning the project, at the project root, use the following command:

python ethicalgardeners/main.py --config-name config

After installing the package using pip, you can also run:

python -m ethicalgardeners.main --config-name config

By default, this will run a simulation with:

1000 iterations
A random grid
Partial observation
Metrics exported to CSV files
real-time and post visualizations

Modifying the Configuration¶

You can override configurations directly from the command line:

python -m ethicalgardeners.main \
  grid=from_code \
  observation=partial \
  observation.range=2 \
  metrics=export \
  renderer=graphical \
  num_iterations=1000

See also our tutorial Configuration Guide for Ethical Gardeners Simulation to learn how to configure the simulation.

Common Configuration Scenarios¶

Training (grid=random metrics=full renderer=none): Launch a simulation with a randomly initialized grid, ensuring a different run each time, full metrics (see below) to analyze the training results, and disabling the renderer to improve performances and reduce verbosity.
Visualization (grid=from_file renderer=graphical): Run with a predefined grid layout from a file with graphical visualization using Pygame. This configuration is ideal when you want to visually observe agent behaviors and environmental changes with a consistent, reproducible starting point.
Debugging (grid=from_code renderer=console): Run with a predefined grid with the possibility to personalise every environment parameters and text-based console visualization, making it easier to track specific events and agent actions. Console output provides more detailed state information that’s useful for identifying issues or understanding specific simulation behaviors.
Analysis (grid=from_file metrics=full render_mode=none renderer=graphical renderer.graphical.post_analysis_on=true): Load a predefined grid from a file for complete reproducibility, export metrics to CSV files for later analysis, and disable visualization to maximize performance. This configuration is optimal for running experiments where you need to analyze the data afterward without watching the simulation in real-time.

Understanding Metrics¶

The MetricsCollector tracks various metrics during the simulation execution.

Collected Metrics¶

Step Count: Current step in the simulation
Flower Statistics: Number of flowers planted and harvested (total and per agent)
Pollution Levels: Average pollution percentage and cells exceeding different pollution thresholds (25%, 50%, 75%, and 90%)
Rewards: Current and accumulated rewards for each agent
Active Agent: ID of the currently active agent

Where to Find Metrics¶

When metrics export is enabled (metrics=export or metrics=full), metrics are saved to:

Default path: ./metrics/metrics_run_[TIMESTAMP].csv
Custom path: Specified via metrics.out_dir_path=your/custom/path

The CSV file contains all metrics for each step of the simulation.

Sending Metrics to External Services¶

With metrics=send or metrics=full, metrics are also sent to Weights & Biases (WandB) for online visualization and experiment tracking.

You can configure every WandB initialization parameter using the metrics.wandb.* configuration options (See Weights & Biases parameters for more details).

Visualization Results¶

The renderer module provide visualization of the simulation environment during and after the simulation.

Available real-time visualization options¶

ConsoleRenderer: Text-based visualization in the terminal
GraphicalRenderer: Graphical visualization using Pygame
Both: Can be used simultaneously with renderer=full

Understanding the Visualization¶

In the graphical visualization, by default:

Grid cells: Light green indicates lower pollution, dark green indicates higher pollution
Obstacles: Gray cells
Agents: Colored squares of reddish to purple hues with agent IDs
Flowers: Colored circles from greenish to yelowish hues, with size depending on growth stage

In the console visualization, by default:

Ground: Represented by a space character
Obstacles: Represented by ‘#’
Flowers: Represented by ‘F’ followed by type and growth stage
Agents: Represented by ‘A’ followed by agent ID
Pollution: Displayed as a number after each cell type. Empty for obstacles

Where to Find post-analysis Videos¶

When post-analysis is enabled (renderer.console.post_analysis_on=True or renderer.graphical.post_analysis_on=True), videos using the graphical visualization are saved to:

Default path: ./videos/simulation_video_[TIMESTAMP].mp4
Custom path: Specified via renderer.console.out_dir_path or renderer.graphical.out_dir_path

Example: Complete Analysis Configuration¶

To run a complete analysis with metrics collection and visualization:

python -m ethicalgardeners.main \
  metrics=export \
  metrics.out_dir_path=./my_experiment/metrics \
  renderer=graphical \
  renderer.graphical.post_analysis_on=True \
  renderer.graphical.out_dir_path=./my_experiment/videos \
  num_iterations=2000

This will run a 2000-step simulation, save metrics to CSV files and generate a video of the simulation to the ./my_experiment/ folder (respectively, metrics and videos sub-folders). You can then analyze the results either “by eye”, looking at the video result, or by performing statistical analysis on the CSV data.