Experiment Runner
=================

.. module:: structured_stochasticity.experiment

This module ties everything together and provides both CLI and programmatic
interfaces for running experiments.

Experiment Configuration
------------------------

.. autoclass:: ExperimentConfig
   :members:
   :show-inheritance:

   **Configuration Sections:**

   - **Model**: ``model_name``, ``device``, ``torch_dtype``
   - **Injection**: ``injection_layers``, ``noise_scale``, ``noise_strategy``, ``injection_mode``
   - **Task**: ``task_name``, ``complexity_range``, ``trials_per_complexity``
   - **Evaluation**: ``k_values``, ``selection_method``, ``max_new_tokens``
   - **Output**: ``output_dir``, ``experiment_name``

Experiment Class
----------------

.. autoclass:: Experiment
   :members:
   :show-inheritance:

   **Example Usage:**

   .. code-block:: python

      from structured_stochasticity.experiment import Experiment, ExperimentConfig

      config = ExperimentConfig(
          model_name="meta-llama/Llama-3.2-1B",
          noise_scale=0.1,
          complexity_range=(3, 6),
          k_values=[1, 5, 10]
      )

      experiment = Experiment(config)
      experiment.run()
      experiment.print_summary()
      experiment.save_results()

Quick Experiment
----------------

.. autofunction:: run_quick_experiment

   Convenience function for notebooks and quick tests:

   .. code-block:: python

      from structured_stochasticity import run_quick_experiment

      results = run_quick_experiment(
          model_name="meta-llama/Llama-3.2-1B",
          noise_scale=0.1,
          complexity_range=(3, 5),
          k_values=[1, 5],
          trials=5
      )

CLI Entry Point
---------------

.. autofunction:: main

   Run experiments from the command line:

   .. code-block:: bash

      # With config file
      ss-experiment --config configs/default.yaml

      # Override parameters
      ss-experiment --model meta-llama/Llama-3.2-1B --scale 0.15