Hydra: Your Own Configuration Files

We encourage you to add custom config or experiment files in your own project. These will make it easy for you to launch different versions of your environments and agents with different parameters.

To be able to use custom configuration files, you first need to create your config module and add it to the Hydra search path. Then, you can either

Step 1: Custom Config Module in Hydra Search Path

For this, first, create a module where your config will reside (let’s say your_project.conf) and place an __init__.py file in there.

Second, to make your project available to Hydra, make sure it is either installed using pip install -e ., or added to your Python path manually, using for example export PYTHONPATH="$PYTHONPATH:$PWD/" when in the project directory.

As a final step, you need to tell Hydra to look for your config files. This is can be done either by specifying your config directory along with each maze-run command using the -cd flag:

$ maze-run -cd your_project/conf ...

Or, to avoid specifying this with every command, you can add your config module to the Hydra search path by creating the following Hydra plugin (substitute your_project.conf with your actual config module path):

# Inside your project in: hydra_plugins/add_custom_config_to_search_path.py

"""Hydra plugin to register additional config packages in the search path."""
from hydra.core.config_search_path import ConfigSearchPath
from hydra.plugins.search_path_plugin import SearchPathPlugin


class AddCustomConfigToSearchPathPlugin(SearchPathPlugin):
    """Hydra plugin to register additional config packages in the search path."""

    def manipulate_search_path(self, search_path: ConfigSearchPath) -> None:
        """Add custom config to search path (part of SearchPathPlugin interface)."""
        search_path.append("project", "pkg://your_project.conf")

Now, you can add additional root config files as well as individual components into your config package.

For more information on search path customization, check Config Search Path and SearchPathPlugins in Hydra docs.

Step 2a: Custom Config Components

If what you are after is only providing custom options for some of the components Maze configuration uses (e.g., a custom environment configuration), then it suffices to add these into the relevant directory in your config module and you are good to go.

For example, if you want a custom configuration for the Gym Car Racing env, you might do:

# In your_project/conf/env/car_racing.yaml:

# @package env
_target_: maze.core.wrappers.maze_gym_env_wrapper.GymMazeEnv
env: CarRacing-v0

Then, you might call maze-run with the env=car_racing override and it will load the configuration from your file.

Depending on your needs, you can mix-and-match your custom configurations with configurations provided by Maze (e.g. use a custom env configuration while using a wrappers or models configuration provided by Maze).

Step 2b: Experiment Config

Another convenient way to assemble and maintain different configurations of your experiments is Hydra’s built-in Experiment Configuration.

It allows you to customize experiments by only specifying the changes to the default (master) configuration. You can for example change the trainer to PPO, the learning rate to 0.0001 and additionally activate the vector_obs wrapper stack by providing the following experiment configuration:

conf/experiment/cartpole_ppo_wrappers.yaml
# @package _global_

# defaults to override
defaults:
  - override /algorithm: ppo
  - override /wrappers: vector_obs

# overrides
algorithm:
  lr: 0.0001

To start the experiment from this experiment config file, run:

$ maze-run -cn conf_train +experiment=cartpole_ppo_wrappers

For more details on experimenting we refer to the experiment configuration docs.

Step 2c: Custom Root Config

If you require even more customization, you will likely need to define your own root config. This is usually useful for custom projects, as it allows you to create custom defaults for the individual config groups.

We suggest you start by copying one of the root configs already available in Maze (like conf_rollout or conf_train, depending on what you need), and then adding more required keys or removing those that are not needed. However, it is also not difficult to start from scratch if you know what you need.

Once you create your root config file (let’s say your_project/conf/my_own_conf.yaml), it suffices to point Hydra to it via the argument -cn my_own_conf, so your command would look like this (for illustrative purposes):

$ maze-run -cn my_own_conf

Then, all the defaults and available components that Hydra will look for depend on what you specified in your new root config.

For an overview of root config, check out config root & defaults.

Step 3: Custom Runners (Optional)

If you want to launch different types of jobs than what Maze provides by default, like implementing a custom training algorithm or deployment scenario that you would like to run via the CLI, you will benefit from creating a custom Runner.

You can subclass the desired class in the runner hierarchy (like the TrainingRunner if you are implementing a new training scheme, or the general Runner for some more general concept). Then, just create a custom config file for the runner config group that configures your new class, and you are good to go.

Where to Go Next

After understanding how custom configuration is done, you might want to: