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
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
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
$ 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
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.
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
while using a
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
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
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
You can subclass the desired class in the runner hierarchy (like the
if you are implementing a new training scheme, or the general
for some more general concept). Then, just create a custom config file for the
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: