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
create your own config components (e.g., when you just need to customize the environment config),
create dedicated experiment config files based on the default (master) config,
or create your own root config file if you have more custom needs.
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:
# @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:
Review the Hydra overview to see how you should structure your custom configuration
Read about the advanced concepts of Hydra