Dora Search

Warnings

• gotcha The `xp.run()` function is primarily for quick local testing and does not fully leverage Dora's experiment management capabilities (like structured output directories, reproducibility, or distributed launching). For full features and robust experiment tracking, `dora.main()` is the recommended entry point.
  Fix: Always use `dora.main(your_experiment_function, grid=your_grid)` for production-grade experiment launches and grid searches.
• gotcha The experiment function passed to `dora.main` (or `xp.run`) must accept exactly one argument, which will be a dictionary containing the current experiment's configuration, including Dora's internal parameters (e.g., `_xp_id`, `_xp_dir`).
  Fix: Ensure your experiment entry point is defined with a single dictionary argument, e.g., `def my_experiment_func(config: Dict): ...`.
• gotcha While Dora manages experiment parameters and results, it does not automatically manage the specific Python environment (dependencies, versions) used by your experiment code. Reproducibility often depends on consistent external environments.
  Fix: Use external tools like `conda`, `virtualenv`, `poetry`, or Docker to containerize and manage your experiment's dependencies for true reproducibility. Document your environment carefully.
• gotcha Dora uses configuration keys prefixed with an underscore (e.g., `_xp_dir`, `_xp_id`) for its internal parameters. Defining your own grid arguments with keys starting with `_` can lead to conflicts or unexpected behavior.
  Fix: Avoid using keys that start with an underscore (`_`) in your custom grid definitions to prevent clashes with Dora's internal parameters.

Install

• pip install dora-search Install stable version

Imports

• xp

  import dora.xp as xp

  Commonly aliased as 'xp' for brevity when defining grids and args.
• main

  import dora

• dora

  import dora

  The top-level package provides entry points like `dora.main`.

Quickstart

This quickstart defines a simple `train_model` function that accepts a configuration dictionary. It then sets up a hyperparameter grid using `dora.xp.arg` and uses `dora.main` to launch multiple experiments, one for each combination in the grid. Dora automatically creates and manages experiment directories, passing configuration parameters and internal metadata (like `_xp_id` and `_xp_dir`) to your function.

import dora
import dora.xp as xp
import time
import os
from typing import Dict

def train_model(config: Dict):
    """Simulates a training run with a given configuration."""
    print(f"[Experiment {config.get('_xp_id', 'local')}] Running with config: {config}")
    # Simulate some work
    time.sleep(0.1)
    result = config["lr"] * config["batch_size"]
    print(f"[Experiment {config.get('_xp_id', 'local')}] Result: {result}")

    # Dora automatically saves results in the experiment directory
    xp_dir = config.get('_xp_dir')
    if xp_dir:
        os.makedirs(xp_dir, exist_ok=True)
        with open(os.path.join(xp_dir, 'metrics.json'), 'w') as f:
            import json
            json.dump({'loss': result, 'accuracy': 1 - result / 100}, f)

    return {"loss": result, "accuracy": 1 - result / 100}

# Define the grid search parameters
grid = [
    xp.arg("lr", [0.01, 0.1, 1.0]),
    xp.arg("batch_size", [16, 32])
]

if __name__ == "__main__":
    print("Launching Dora experiments...")
    # dora.main is the recommended way to launch experiments
    # It will iterate through the grid, call train_model for each configuration,
    # and manage experiment directories and logs.
    dora.main(train_model, grid=grid)
    print("Dora experiments finished.")