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 <https://hydra.cc/>`__ for configuration management, which allows you to modularly configure your simulation without modifying the code.

Configuration Structure
^^^^^^^^^^^^^^^^^^^^^^^

The configuration is organized into several groups:

.. code-block::

    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:

.. code-block:: bash

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

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

.. code-block:: bash

    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:

.. code-block:: bash

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

See also our tutorial :doc:`config` 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 :py:class:`~ethicalgardeners.metricscollector.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) <https://wandb.ai/>`__ for online visualization and experiment tracking.

You can configure every WandB initialization parameter using the ``metrics.wandb.*`` configuration options (See :ref:`Weights \& Biases parameters <wandb-parameters>` for more details).

Visualization Results
---------------------

The :py:mod:`~ethicalgardeners.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 <https://www.pygame.org/docs/>`__
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:

- **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:

.. code-block:: bash

    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.