hydra-filter-sweeper
is a plugin for Hydra that extends the basic sweeper by the addition of filters, enabling more targeted parameter sweeps.
The plugin is compatible with any Hydra launcher plugin.
The minimum required Hydra version is 1.3.2
.
Customizable Filters
- Apply expressions, existence checks, or custom filter classes to the sweep.
Flexible Filter Conditions
- Include fail-safe conditions to gracefully handle possible exceptions raised by filters.
Interpolation Support
- Utilize OmegaConf's interpolation syntax to reference configuration values.
To install the plugin, use pip:
pip install hydra-filter-sweeper
To use hydra-filter-sweeper
, override the default sweeper with filter
at the end of the defaults list.
Filters are specified as a list of dictionaries and can be of type expr
, exists
, or class
.
If any filter evaluates to True
, the current configuration is excluded from the sweep.
If no filters
list is provided or all filters evaluate to False
, all configurations are included and the
sweeper resembles the default behavior of Hydra's basic sweeper.
Example Configuration
defaults:
- _self_
- override hydra/sweeper: filter
some_value: four
hydra:
mode: MULTIRUN
sweeper:
params:
+foo: 1,2,3
+bar: one, two, three
filters:
- type: expr
expr: foo == 1 and bar == "two"
- type: exists
path: some_directory/some.file
- type: class
target: some_filter.SomeFilter
some_arg: ${some_value}
Filter configurations based on a Python expression that evaluates to True
or False
.
The context of the expression is the configuration itself.
All keys in the configuration are added to the attributes list of the
evaluation model in addition to lists, tuples, and safe function calls
(e.g., str, int, float, len).
The configuration is excluded if the expression evaluates to True
.
Parameters:
expr
(str): Python expression to evaluate.fail
(bool): Whether to fail if the filter raises an exception. Default isTrue
.log
(bool): Whether to log the configuration if the filter evaluates toTrue
. Default isTrue
.
Example Configuration
hydra/sweeper/filters:
- type: expr
expr: foo == 1 and bar == "two"
- type: expr
expr: bar == ${some_value}
- type: expr
expr: undefined == 1 and bar == "two"
fail: false
log: false
Checks if a specified file or directory exists in the run's directory. The configuration is excluded if the file or directory exists.
Parameters:
path
(str): Path to the file or directory to check if it exists in the run's directory.fail
(bool): Whether to fail if the filter raises an exception. Default isTrue
.log
(bool): Whether to log the configuration if the filter evaluates toTrue
. Default isTrue
.
Example Configuration
hydra/sweeper/filters:
- type: exists
path: some_directory/some.file
- type: exists
path: some_directory
log: false
- type: exists
path: some_directory/${some_value}.file
- type: exists
path: null
fail: false
Applies a custom filter class to the sweep.
The configuration is excluded if the filter method returns True
.
Parameters:
target
(str): Python relative import path to the class.*
(Any): Additional keyword arguments passed to the filter method of the class.fail
(bool): Whether to fail if the filter raises an exception. Default isTrue
.log
(bool): Whether to log the configuration if the filter evaluates toTrue
. Default isTrue
.
Example Configuration
hydra/sweeper/filters:
- type: class
target: some_filter.SomeFilter
some_arg: ${some_value}
log: false
- type: class
target: some_filter.NonExistentFilter
some_arg: ${some_value}
fail: false
The SomeFilter
class should inherit from AbstractFilter
and implement the filter
method that returns True
if the configuration should be excluded.
The filter
method receives the configuration, the run's directory, and any additional keyword arguments as parameters.
from omegaconf import DictConfig
from hydra_filter_sweeper import AbstractFilter
class SomeFilter(AbstractFilter):
def filter(self, config: DictConfig, directory: str, some_arg: str) -> bool:
return config.foo == 1 and config.bar == "two" and some_arg == "four"
Contributions are welcome! For bug reports or requests, please submit an issue.
To contribute, please fork the repository and submit a pull request.
We use Poetry for dependency management, Ruff for code formatting, codespell for spell checking, pytest for testing, and pre-commit for managing the hooks.
Install the development dependencies with:
poetry install
pre-commit install
Both formatting and spell checking are enforced by pre-commit hooks.
We strive for 100% test coverage. To run the tests locally, use:
pytest