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 or after installing the package using pypi, use the following command:

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: ./output/YEAR-MONTH-DAY/HOUR-MINUTE-SECOND/simulation_metrics.csv

  • Custom path: Specified via metrics.out_dir_path=your/custom/path

The CSV file contains all metrics for each step of the simulation. In this directory, you can also find the hydra configuration used for the simulation in .hydra and the logs.

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

  1. ConsoleRenderer: Text-based visualization in the terminal

  2. GraphicalRenderer: Graphical visualization using Pygame

  3. 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 the same directory as metrics:

  • Default path: ./output/YEAR-MONTH-DAY/HOUR-MINUTE-SECOND/simulation_video.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.