{"owner":"facebookresearch","repo":"hydra","hasSkills":true,"totalSkillsCount":31,"totalTokensCount":25235,"categories":["copilot-instructions","root-instruction","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md","AGENTS.md","examples/plugins/example_configsource_plugin/README.md","examples/plugins/example_generic_plugin/README.md","examples/plugins/example_launcher_plugin/README.md","examples/plugins/example_registered_plugin/README.md","examples/plugins/example_searchpath_plugin/README.md","examples/plugins/example_sweeper_plugin/README.md","plugins/hydra_ax_sweeper/README.md","plugins/hydra_colorlog/README.md","plugins/hydra_joblib_launcher/README.md","plugins/hydra_nevergrad_sweeper/README.md","plugins/hydra_optuna_sweeper/README.md","plugins/hydra_ray_launcher/README.md","plugins/hydra_ray_launcher/integration_test_tools/README.md","plugins/hydra_rq_launcher/README.md","plugins/hydra_submitit_launcher/README.md","tools/README.md","tools/configen/README.md","tools/landscape/README.md","tools/release/README.md","website/docs/advanced/plugins/develop.md","website/docs/advanced/plugins/intro.md","website/docs/plugins/ax_sweeper.md","website/docs/plugins/colorlog.md","website/docs/plugins/joblib_launcher.md","website/docs/plugins/nevergrad_sweeper.md","website/docs/plugins/optuna_sweeper.md","website/docs/plugins/ray_launcher.md","website/docs/plugins/rq_launcher.md","website/docs/plugins/submitit_launcher.md"],"skills":{".github/copilot-instructions.md":"# Copilot instructions\n\nWhen generating code or reviewing pull requests for this repository, use\n`CONTRIBUTING.md` as the source of truth for contributor requirements.\n\nFor pull request reviews, check the changed files against the contributor\nguidelines and call out only actionable gaps, especially:\n\n- missing or insufficient tests for code changes;\n- missing documentation updates for API or behavior changes;\n- missing news fragments for non-trivial user-visible changes;\n- news fragments in the wrong `news/` directory or with the wrong category;\n- non-trivial features, API changes, or behavior changes that do not link to\n prior maintainer agreement in an issue or design discussion;\n- validation claims that are not supported by the tests or checks shown in the\n pull request.\n\nDo not request a news fragment for developer-only tooling, repository\nmaintenance, or CI-only changes unless the change affects the shipped product\nexperience.\n\nKeep review comments specific and actionable. Prefer pointing to the relevant\nguideline in `CONTRIBUTING.md` over restating the whole policy.\n","AGENTS.md":"# AGENTS.md\n\nRepo-specific directives for coding agents working in this project.\n\n## Behavioral defaults\n\nThese guidelines are intended to reduce common LLM coding mistakes. Apply them\nalongside the repo-specific rules below. They bias toward caution over speed,\nand for truly trivial tasks you may use judgment.\n\n### Think before coding\n\n- Do not assume.\n- Do not hide confusion.\n- Surface tradeoffs.\n- State assumptions explicitly when they matter to the implementation.\n- If multiple reasonable interpretations exist, present them instead of silently picking one.\n- If a simpler approach exists, say so.\n- Push back when warranted.\n- If something material is unclear or risky, stop, name what is confusing, and ask instead of guessing.\n\n### Simplicity first\n\n- Solve the requested problem with the minimum code necessary.\n- No features beyond what was asked.\n- No abstractions for single-use code.\n- No flexibility or configurability that was not requested.\n- No error handling for scenarios that are effectively impossible in context.\n- If a solution feels overbuilt for the task, simplify it before considering it done.\n- If you write 200 lines and the same result could be achieved in 50, rewrite it.\n- Ask: would a senior engineer say this is overcomplicated? If yes, simplify.\n\n### Surgical changes\n\n- Touch only what is needed for the request.\n- Do not \"clean up\" adjacent code, comments, formatting, or structure unless the change requires it.\n- Match the existing style and patterns of the codebase unless the user asks for a broader refactor.\n- If you notice unrelated dead code or issues nearby, mention them instead of fixing them opportunistically.\n- Remove imports, variables, functions, or other artifacts that your change makes unused.\n- Do not delete unrelated pre-existing dead code unless asked.\n- Every changed line should trace directly to the user's request.\n\n### Prefer focused tools over ad hoc shell\n\nUse repository-aware file inspection and edit tools for file operations. Reserve\nshell commands for things that genuinely require shell execution: `sl`\n(Sapling) commands, `gh`, dependency installation, or `nox` / `pytest` /\n`python` for tests, linting, and other repo tooling.\n\n- Use `rg` for text search and `rg --files` for file discovery.\n- Avoid inline Python snippets (`python -c ...`) when a dedicated tool or standard CLI utility is sufficient.\n- Use structured tools such as `jq` to parse JSON shell output instead of piping to Python.\n\n### Goal-driven execution\n\n- Translate requests into concrete success criteria that can be verified.\n- For bug fixes, prefer reproducing the issue with a test or other reliable check before fixing it.\n- For refactors, prefer checks that demonstrate behavior is preserved before and after.\n- For multi-step tasks, keep a brief plan in mind and verify each step before calling the work complete.\n- Favor specific goals over vague ones:\n - \"Add validation\" -> write tests for invalid inputs, then make them pass.\n - \"Fix the bug\" -> reproduce it with a test or reliable check, then make it pass.\n - \"Refactor X\" -> verify behavior before and after the refactor.\n\n## Documentation map\n\n- Website and docs source: [`website/`](./website/)\n- Current docs: [`website/docs/`](./website/docs/)\n- Development docs: [`website/docs/development/`](./website/docs/development/)\n- Plugin docs: [`website/docs/plugins/`](./website/docs/plugins/)\n- Versioned docs: [`website/versioned_docs/`](./website/versioned_docs/)\n\n## Reproduction files\n\nWhen asked to create a reproduction for an issue, place files under\n`temp/repro/`:\n\n- Single-file repro: `temp/repro/.py`\n- Multi-file repro: `temp/repro//`\n\n## Scratch files\n\nPlace low-value, disposable temporary files under `temp/scratch/`. Its contents\nmay be cleared weekly without review. Do not store reproductions, resumable\nworkflow state, unique evidence, or drafts awaiting use there.\n\n## Stop and ask\n\n- If a tracked repo file appears unexpectedly renamed, moved, regenerated, deleted, or otherwise changed, stop and ask before reverting, recreating, reclassifying, or staging over that change.\n- Do not change supported Python versions, CI matrices, packaging metadata, release automation, or workflow triggers unless the request explicitly includes that scope.\n\n## Verification\n\n- For any new or changed functionality, test it in two layers when practical:\n - run relevant focused tests with `pytest path/to/test_file.py`\n - run the relevant `nox` session to ensure no regressions\n- Hydra core tests run with `pytest` from the repository root.\n- Plugin tests run from the plugin directory after installing the plugin, or via `nox -s test_plugins`.\n- Use `PLUGINS=` with `nox` when validating one plugin.\n- If the broader suite disagrees with focused tests, trust the broader result and do not call the change verified.\n- If live verification is blocked by the current environment, request escalation if that would unblock it. If not, stop and ask for guidance.\n\n## Linting and formatting\n\nRun linting through `nox -s lint lint_plugins` when validating broad changes.\nThe repo's lint sessions include formatting, import sorting, type checks, style,\nYAML linting, and security checks.\n\nFor focused local checks, use the same tools the noxfile runs:\n\n- `ruff format .` / `ruff format --check .`\n- `ruff check .` / `ruff check --fix .`\n- `pyrefly check --config pyproject.toml`\n- `yamllint --strict .`\n- `bandit --exclude ./.nox/** -ll -r .`\n\n## Environment and hooks\n\n- Run commands from the repo-local `.venv` by default. Prefer\n `.venv/bin/python`, `.venv/bin/pip`, `.venv/bin/pytest`, and\n `.venv/bin/nox` when those entry points exist.\n- If `.venv` is missing and dependency installation is in scope, create it\n with `python -m venv .venv`, then install `requirements/dev.txt` and the\n editable checkout into that environment.\n- Use a separate environment only when testing a specific supported Python\n version or reproducing an environment-specific issue.\n- When validating contributor setup, shell initialization, or hook behavior, verify it from the same environment a developer would actually use, such as a normal shell session or `sl commit`, not only from a temporary sandbox-only environment.\n- Prefer hooks that do not depend on nontrivial user-environment tooling.\n- If an environment override is required for one command, explain why it must be part of that same process invocation.\n- If a small system tool would materially simplify the workflow, it is fine to suggest it or ask the user to install it.\n\n## Source control and PRs\n\nUse the VCS tooling that matches the current checkout. Some Hydra worktrees are\nSapling (`sl`) checkouts, while others may be plain Git clones.\n\n- Prefer the checkout's native tool for local operations such as status, log, diff, commit, amend, and stack inspection.\n- In a Sapling checkout, use `sl` for normal local VCS operations.\n- Keep escalated VCS commands minimal and single-purpose.\n- Do not bundle staging, environment bootstrapping, dependency installation, and commit creation into one escalated shell command unless there is no practical alternative.\n- If a VCS operation requires escalation, ask only for the specific action that needs it.\n- Do not force-push, submit, or otherwise update a remote branch unless the user explicitly asks for that outward action.\n- Before using low-level fallback commands, such as `git --git-dir .sl/store/git` in a Sapling checkout, stop and explain why the normal workflow is not sufficient.\n\n## Release and news fragments\n\n- Do not commit, push, merge, publish, or otherwise send changes outside the local working tree unless the user explicitly asks for that outward action.\n- If a change alters release automation, workflow triggers, deployment behavior, or other externally visible project mechanics, require an explicit user review checkpoint before any commit, push, merge, publish, or deployment action.\n- All non-trivial product-user-visible changes should have a news fragment.\n- Core Hydra fragments go under `news/`; plugin-specific fragments go under the relevant plugin's `news/` directory.\n- Fragment filenames follow the pattern `.`.\n- Supported categories are `api_change`, `feature`, `bugfix`, `docs`, `config`, and `maintenance`.\n- Fragment text must be concise, user-facing, sentence case, and preferably under 80 characters.\n- Developer-only tooling, repo maintenance, and CI-only changes do not need a fragment unless they change the shipped product experience.\n- The user handles releases. Do not edit version numbers, create release files, assemble release notes, or otherwise perform release-cut steps unless explicitly asked.\n- The documented release process lives in [`website/docs/development/release.md`](./website/docs/development/release.md). Do not improvise a manual release flow.\n\n## Reviews\n\n- When asked to review a commit, pull request, or diff, cover correctness, completeness, documentation, and internal consistency.\n- Verify that each product-user-visible change includes an appropriate news fragment and that the fragment matches the implementation and docs.\n","examples/plugins/example_configsource_plugin/README.md":"# Hydra example config source\nUse this as the template a Hydra config source plugin\n\nConfig source plugins are allowing Hydra to recognize other search path schemas in addition to the built in \n`file://` (which provides access to configs in the file system) and \n`pkg://` (which provides access to configs installed with a Python package) \n\nThis config source hard codes all the responses so it's not very useful.\nPlease base your tests on the data in hydra_root/tests/test_apps/config_source_test/dir.\n\nAll config sources need to pass the ConfigSourceTestSuite tests, which are expecting those specific responses.\nWhen implementing a new config source, be sure to run it through the test suite to ensure it always behaves the same\nas the other config sources.\n","examples/plugins/example_generic_plugin/README.md":"# Hydra example plugin\nthis plugin is not very useful, but demonstrates the plugin discovery capability of Hydra.\n\nCore plugins (Plugins that are developed jointly with Hydra) lives in the plugins subdirectory inside the Hydra repo.\nThird party plugins can live anywhere (public or private Github repos, Organizations in-house SCM etc)","examples/plugins/example_launcher_plugin/README.md":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Launcher for Hydra.\nThe configuration for this launcher is in packages with the plugin:\n\n```yaml title=\"hydra_plugins/example_launcher_plugiun/conf/hydra/launcher/example.yaml\"\n_target_: hydra_plugins.example_launcher_plugin.example_launcher.ExampleLauncher\nfoo: 10\nbar: abcde\n```\nThe example application is overriding the Launcher used by Hydra.\nWhen the launcher is initialized, its \"using\" the foo and bar parameters.\n\nOutput of the example application:\n```text\n$ python example/my_app.py --multirun db=postgresql,mysql\n[2019-10-22 19:45:05,060] - Example Launcher(foo=10, bar=abcde) is launching 2 jobs locally\n[2019-10-22 19:45:05,060] - Sweep output dir : multirun/2019-10-22/19-45-05\n[2019-10-22 19:45:05,060] - #0 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n\n[2019-10-22 19:45:05,135] - #1 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n```\n","examples/plugins/example_registered_plugin/README.md":"# Hydra example plugin via `Plugins.register`\nThis plugin is not very useful, but it demonstrates how to register a plugin using the `Plugins.register` method.","examples/plugins/example_searchpath_plugin/README.md":"# Hydra example SearchPath plugin\n\nThis plugin provides an example for how to write a SearchPathPlugin that can manipulate the search path.\nTypical use cases includes:\n * A framework that wants to allow user code to discover its configurations and be able to compose with them.\n * A plugin that wants to extend Hydra or another plugin by providing additional configs in existing config groups like `hydra/launcher`.\n * A plugin that can replace the default configuration of another plugin or of Hydra itself by prepending its configurations before those that it want to replace.\n \nSearchPath plugins are discovered and enabled automatically once they are installed.\nYou can use `python foo.py --info` to see the search path and the installed plugins.\n","examples/plugins/example_sweeper_plugin/README.md":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Sweeper for Hydra.\nThe provided example has a custom configuration for the sweeper that takes overrides a few parameters:\n```yaml\n_target_: hydra_plugins.example_sweeper_plugin.example_sweeper.ExampleSweeper\n# max number of jobs to run in the same batch.\nmax_batch_size: null\nfoo: 10\nbar: abcde\n```\n\n#### Example app using custom sweeper:\n```text\n$ python example/my_app.py -m db=mysql,postgresql\n[2019-11-14 11:42:47,941][HYDRA] ExampleSweeper (foo=10, bar=abcde) sweeping\n[2019-11-14 11:42:47,941][HYDRA] Sweep output dir : multirun/2019-11-14/11-42-47\n[2019-11-14 11:42:47,942][HYDRA] Launching 2 jobs locally\n[2019-11-14 11:42:47,942][HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[2019-11-14 11:42:48,011][HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n```\n","plugins/hydra_ax_sweeper/README.md":"# Hydra Ax Sweeper\nProvides a [`Ax Sweeper`](https://ax.dev/) based Hydra Sweeper supporting parallel execution.\n\nHydra 1.4 will include the final first-party release, based on the existing\nimplementation. The plugin code will be removed in the Hydra 1.5 line, and no\nfirst-party releases will be published for Hydra 1.5 or later. Existing PyPI\nreleases will remain available. See the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506)\nfor the schedule and invitation for community ownership in a separate repository.\n\nSee [website](https://hydra.cc/docs/plugins/ax_sweeper/) for more information\n","plugins/hydra_colorlog/README.md":"# Hydra colorlog\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\nSee [website](https://hydra.cc/docs/plugins/colorlog) for more information\n","plugins/hydra_joblib_launcher/README.md":"# Hydra Joblib Launcher\nProvides a [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html) based Hydra Launcher supporting parallel execution.\n\nSee [website](https://hydra.cc/docs/plugins/joblib_launcher) for more information\n","plugins/hydra_nevergrad_sweeper/README.md":"# Hydra Nevergrad Sweeper plugin\n\nProvides a mechanism for Hydra applications to use [Nevergrad](https://github.com/facebookresearch/nevergrad) algorithms for the optimization of the parameters of any experiment.\n\nSee [website](https://hydra.cc/docs/plugins/nevergrad_sweeper) for more information","plugins/hydra_optuna_sweeper/README.md":"# Hydra Optuna Sweeper\n\nProvides an [Optuna](https://optuna.org) based Hydra Sweeper.\n\nSee [website](https://hydra.cc/docs/plugins/optuna_sweeper/) for more information.\n","plugins/hydra_ray_launcher/README.md":"# Hydra Ray Launcher\nProvides a [`Ray`](https://docs.ray.io/en/latest/) based Hydra Launcher supporting execution on AWS.\n\nSee [website](https://hydra.cc/docs/plugins/ray_launcher) for more information\n","plugins/hydra_ray_launcher/integration_test_tools/README.md":"## Setting up a new testing AMI for ray launcher.\n\nTo run the tool:\n\n- Make sure the dependencies in `setup_integration_test_ami.py` matches exactly ray launcher's `setup.py`.\n- Install AWS CLI, check AWS documentation for more details.\n- Before running the tool, set up your aws profile with admin access to the Hydra test AWS account.\n```\nAWS_PROFILE=jieru python create_integration_test_ami.py\n```\nYou will see a new AMI created in the output\n```commandline\nec2.Image(id='ami-0d65d5647e065a180') current state pending\n...\n```\nSometimes it could take hours for a new AMI to be created. Proceed to the next step once the \nAMI becomes available.\n\n- Run the tests locally with the new AMI:\n ```shell\n AWS_RAY_AMI= pytest ../tests/ray_aws_launcher_tests_disabled.py\n ```\n- Debug if needed.\n- Create a PR and make sure all CI pass!\n","plugins/hydra_rq_launcher/README.md":"# Hydra RQ Launcher\nProvides a [Redis Queue (RQ)](https://python-rq.org) launcher for Hydra supporting distributed execution and job queuing.\n\nSee [website](https://hydra.cc/docs/plugins/rq_launcher) for more information\n","plugins/hydra_submitit_launcher/README.md":"# Hydra Submitit Launcher\nProvides a [`Submitit`](https://github.com/facebookincubator/submitit) based Hydra Launcher supporting [SLURM ](https://slurm.schedmd.com/documentation.html).\n\nSee [website](https://hydra.cc/docs/plugins/submitit_launcher) for more information","tools/README.md":"Standalone Hydra related tools","tools/configen/README.md":"# configen\n\nAutomatically generates Structured Configs that can be used with hydra.utils.instantiate()\n\nThis is optional at two levels:\n1. Structured Configs are optional, one can use Hydra without them.\n2. One can manually code these dataclasses. The advantage of this tool is that it does the work automatically.\n\n# Setup\nConfigen requires config file per project. The config indicates what classes to generate code for, where to put\nthe generated code etc.\nConfigen will suggest creating a config on the first run:\n```\n$ configen\n[2020-08-14 12:06:11,359][configen.configen][ERROR] -\nUse --config-dir DIR --config-name NAME\ne.g:\n\tconfigen --config-dir conf --config-name configen\n\nIf you have no config dir yet use init_config_dir=DIR to create an initial config dir.\ne.g:\n\tconfigen init_config_dir=conf\n```\n\nThis will generate a basic config similar to:\n```yaml\n$ cat conf/configen.yaml\ndefaults:\n - configen_schema\n - _self_\n\nconfigen:\n # output directory\n output_dir: ${hydra:runtime.cwd}/example\n\n header: |\n # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n # Generated by configen, do not edit.\n # See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n # fmt: off\n # isort:skip_file\n # flake8: noqa\n\n module_path_pattern: 'config/{{module_path}}.py'\n\n # list of modules to generate configs for\n modules:\n - name: configen.samples.my_module\n # for each module, a list of classes\n classes:\n - User\n - Admin\n```\n\nConfigen comes with a few samples [classes](configen/samples) that are being processed by the default config.\nFor example:\n```python title=\"configen/samples/my_module.py\"\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n\n\nclass User:\n def __init__(self, age: int, name: str):\n self.age = age\n self.name = name\n\n def __repr__(self):\n return f\"User: name={self.name}, age={self.age}\"\n\n\nclass Admin(User):\n def __init__(self, private_key: str, age: int, name: str) -> None:\n super().__init__(age, name)\n self.private_key = private_key\n\n def __repr__(self):\n return (\n f\"Admin: name={self.name}, age={self.age}, private_key={self.private_key}\"\n )\n```\n\nRunning configen with this config directory:\n```\n$ configen --config-dir conf --config-name configen\n[2020-08-14 12:44:54,990][configen.configen][INFO] - configen.samples.my_module.configen.samples.my_module -> /home/omry/tmp/configen/example/config/configen/samples/my_module.py\n```\n\nWill result in a file `example/config/configen/samples/my_module.py` like:\n```python\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n# Generated by configen, do not edit.\n# See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n# fmt: off\n# isort:skip_file\n# flake8: noqa\n\nfrom dataclasses import dataclass, field\nfrom omegaconf import MISSING\n\n\n@dataclass\nclass UserConf:\n _target_: str = \"configen.samples.my_module.User\"\n age: int = MISSING\n name: str = MISSING\n\n\n@dataclass\nclass AdminConf:\n _target_: str = \"configen.samples.my_module.Admin\"\n private_key: str = MISSING\n age: int = MISSING\n name: str = MISSING\n```\n\nThe generated code can be used by a Hydra application to instantiate the user object.\nSee the [example application](example/my_app.py).\n","tools/landscape/README.md":"# Hydra Landscape tools\n\nThese tools support discovery, analysis, review, and publication of projects in\nthe [Hydra Landscape](../../website/docs/landscape.mdx). They do not approve\nprojects automatically. Inclusion and featured status are maintainer decisions.\n\nThe tracked files under this directory are reusable tooling and durable human\ndecisions. Large crawls, AI output, refreshed GitHub metadata, and generated\nreview queues remain under `temp/hydra-dependents/`.\n\nInstall the Python 3.10 compatibility dependency when needed:\n\n```bash\n.venv/bin/pip install -r tools/landscape/requirements.txt\n```\n\n`data/decisions.json` is the canonical source for both curation decisions and\nthe public listing of every included project. Do not edit\n`website/src/data/landscape.json` directly; website commands regenerate it from\nthe decision ledger.\n\n## Pipeline\n\n1. Collect mechanical Hydra usage evidence from the dependency crawl:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_usage.py\n ```\n\n2. Route projects for review, optionally using the locally authenticated Codex\n CLI to analyze a resumable batch:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_projects.py\n .venv/bin/python tools/landscape/analyze_hydra_projects.py --ai\n ```\n\n Analyze explicit repositories with repeated `--repo owner/name` arguments.\n The default AI model is `gpt-5.6-terra` with medium reasoning effort.\n\n3. Refresh current GitHub maintenance metadata:\n\n ```bash\n .venv/bin/python tools/landscape/refresh_landscape_metadata.py\n ```\n\n4. Build the evidence-backed human review queue:\n\n ```bash\n .venv/bin/python tools/landscape/build_landscape_review.py\n ```\n\n5. Record maintainer decisions in `data/decisions.json`. Every included\n decision must contain its complete public `listing`. Regenerate the public\n data directly when needed:\n\n ```bash\n .venv/bin/python tools/landscape/build_public_landscape.py\n ```\n\nThe public generator reads no crawl, AI, review, or live GitHub data. It writes\n`website/src/data/landscape.json` deterministically from the decision ledger.\nThe website's `start`, `build`, and `deploy` commands run it automatically.\n\n## Tests\n\nRun the focused suite with:\n\n```bash\nPYTHONPATH=tools/landscape .venv/bin/pytest tools/landscape\n```\n","tools/release/README.md":"## Release tool\n\nThis tool keeps Hydra release operations package-aware. It knows about\n`hydra-core`, the bundled plugins, and `hydra-configen`, and can check versions,\nset versions, and build distributions.\n\nPublishing is intentionally handled by GitHub Actions Trusted Publishing, not by\nthis local tool. The publish workflows call this tool to build artifacts, then\nupload them from GitHub Actions.\n\n### Package sets\n\n- `set=hydra-core`: `hydra-core` only.\n- `set=hydra-plugins`: all bundled Hydra plugins.\n- `set=hydra-full-release`: `hydra-core` plus all bundled Hydra plugins.\n- `set=configen`: `hydra-configen` only.\n- `set=all`: `hydra-core`, `hydra-configen`, and all bundled Hydra plugins.\n\nUse `only=[,...]` to narrow a package\nset without creating a new named set. Package config names are the keys under\n`tools/release/conf/packages/`, for example:\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n repository=pypi\n```\n\nQuote comma-separated filters so the quotes reach Hydra when passing more than\none package through a shell, for example\n`only=\\\"hydra_optuna_sweeper,hydra_ray_launcher\\\"`.\n\n### Check published versions\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-full-release \\\n repository=pypi\n```\n\nThis reports whether each local version already exists on the selected\nrepository, with the latest non-yanked wheel shown as context.\n\n### Set an explicit version\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev2\n```\n\nUse this for coordinated dev releases where `hydra-core` and the bundled plugins\nshould share the same version.\n\n### Validate prepared versions\n\n```shell\npython tools/release/release.py \\\n action=validate_versions \\\n set=hydra-full-release \\\n version=1.4.0\n```\n\nThis fails if any selected package is not already at the expected version. The\npublish workflow uses this to verify prepared release state before building and\nuploading artifacts.\n\n### Bump published packages\n\n```shell\npython tools/release/release.py action=bump set=hydra-full-release\n```\n\nThis increments only packages whose local version exactly matches the latest\npublished version on PyPI. It is useful for continuing an existing release\nseries, but less useful when aligning multiple packages to a specific version.\n\n### Build artifacts\n\nBuild only packages whose local version has not already been published to PyPI:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n repository=pypi \\\n clean_build_dir=true \\\n require_artifacts=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nBuild every package in a set, ignoring repository state:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n build_policy=all \\\n clean_build_dir=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nThe GitHub publish workflows use the repository-aware form so already-published\nfiles are not uploaded again.\n\nBoth build and dev-release validation reject source distributions containing a\nJAR without `ATTRIBUTION/LICENSE-antlr4`, and wheels containing any JAR. These\nchecks run before the publish workflow uploads distribution artifacts.\n\nThe workflows also write a release summary listing the target repository,\npublish mode, trigger, ref, commit, and every artifact that was built.\n\n### Dev release\n\nRun a dry run for a coordinated dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3\n```\n\nRun a dry run for a single plugin dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n version=1.4.0.dev3\n```\n\nThe dry run prints the selected packages, current local versions, target\nversions, PyPI status for the target version, and the exact publish workflow\ndispatch that would run. It also builds artifacts in a temporary release\nworkspace, runs `twine check`, and smoke-installs the built wheels without\ndependencies. It does not commit, push, dispatch GitHub Actions, create or edit\na GitHub Release, or upload anything to PyPI.\n\nTo publish the dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n publish=true\n```\n\nPublishing first confirms that the selected commit exists on the configured\nGitHub remote, without requiring it to be the branch tip. It also requires a\nclean working tree. In the normal release flow, the selected packages already\nhave the target version because it was set immediately after the previous\nrelease. The command dispatches `Publish to PyPI` with the selected package set,\nexpected version, and exact commit. If the versions differ, it can set, commit,\nand push the target version as a recovery path, then pins the resulting current\ncommit so later pushes cannot change what the workflow builds.\n\nIf the branch has already advanced past an unshipped dev release, select its\nexisting commit explicitly. The dry run archives that exact commit, requires\nthe selected package versions to already match, and builds its artifacts without\nchanging the current checkout:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n commit=\n```\n\nAfter the dry run passes, repeat the command with `publish=true`. Explicit\ncommit mode never sets versions, commits, or pushes; the commit must already\nexist locally and on GitHub. The tool uses `workflow_ref=main` by default; use\n`workflow_ref=` for unusual release lines.\n\nAfter the publish workflow succeeds, immediately set the next coordinated\ndevelopment version, commit, and push it before resuming development:\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev4\n```\n\nThis prevents new development from reporting a version that has already been\npublished.\n\n### Prepare and publish workflow responsibilities\n\nHydra release automation is split into prepare and publish phases.\n\nPrepare release should:\n\n- accept a release line, selected package set, and target version changes;\n- derive the release kind from the selected target versions;\n- derive the target branch from the release line and release kind;\n- validate package versions against the release line and selected package set;\n- compare selected packages against PyPI;\n- produce a release-validation matrix;\n- run release-only checks such as the core suite with all selected compatible\n plugins installed;\n- create or update release-prep PRs when needed.\n\nFor release candidates, stable releases, and patch releases, generated\nrelease-prep PRs are the maintainer approval surface for publishing. The PR body\nmust state clearly what happens when the PR is merged. Once release-prep PR\nautomation exists, merging such a PR should trigger PyPI publishing, and the PR\nbody must list the exact package set and version that will be published.\n\nPublish should:\n\n- revalidate the prepared release state;\n- build selected package artifacts;\n- check built artifacts;\n- publish only selected package artifacts through GitHub Actions Trusted\n Publishing;\n- eventually create or update the GitHub Release as a record of the published\n release.\n\nThe local release tool owns package metadata, version checks, repository\ncomparison, and artifact building. GitHub Actions owns release validation and\nTrusted Publishing. GitHub Release state transitions are intended release\nautomation work, but are not wired into the current publish workflow.\n\nThe current `Prepare Release` workflow implements the validation part of this\nsplit: it derives release kind and target branch, applies the target version\ninside the disposable workflow checkout, checks selected packages against PyPI,\nbuilds artifacts, and runs release validation. The current `Publish to PyPI`\nworkflow is manual-only. GitHub Release creation or edits do not trigger\npublishing. Release-prep PR automation is planned but not implemented yet.\n","website/docs/advanced/plugins/develop.md":"---\nid: develop\ntitle: Plugin development\nsidebar_label: Plugin development\n---\n\n:::info\nIf you develop plugins, please join the Plugin developer announcement chat channel.\n:::\n\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra plugins must be registered before they can be used. Declare an entry\npoint in the `hydra.plugins` group for each plugin class, or call the\n`register` method on Hydra's `Plugins` singleton. Hydra 1.4 also discovers\nplugins in the `hydra_plugins` namespace for compatibility, but this method is\ndeprecated. See the [plugin discovery migration guide](/docs/upgrades/1.3_to_1.4/plugin_discovery).\n\n## Entry point discovery\n\nFor example, in `setup.py`:\n\n```python\nsetup(\n # ...\n entry_points={\n \"hydra.plugins\": [\n \"my_launcher = my_package.my_launcher:MyLauncher\",\n ]\n },\n)\n```\n\nThe target must be a concrete Hydra plugin class. Its module should also\nregister any associated Hydra configuration when imported. Plugin classes no\nlonger need to live in the `hydra_plugins` namespace. Keep expensive optional\ndependencies out of module-level imports.\n\n## Legacy namespace discovery\n\nIf you create a Plugin and want it to be discovered automatically by Hydra, keep the following things in mind:\n- Namespace-discovered plugins can be either standalone packages or part of an\n existing package. They must be in the top-level `hydra_plugins` namespace.\n- Do __NOT__ place an `__init__.py` file in `hydra_plugins` (doing so may break other installed Hydra plugins).\n \nThe plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of `hydra_plugins`. Hydra will import each module and look for plugins defined in that module.\nAny module under `hydra_plugins` that is slow to import will slow down the startup of __ALL__ Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with `_` (but not `__`).\nFor example, the file `_my_plugin_lib.py` would not be imported and scanned, while `my_plugin_lib.py` would be.\n\n## Plugin registration via the `Plugins.register` method\n\nPlugins can be manually registered by calling the `register` method on the instance of Hydra's `Plugins` singleton class.\n```python\nfrom hydra.core.plugins import Plugins\nfrom hydra.plugins.plugin import Plugin\n\nclass MyPlugin(Plugin):\n ...\n\ndef register_my_plugin() -> None:\n \"\"\"Hydra users should call this function before invoking @hydra.main\"\"\"\n Plugins.instance().register(MyPlugin)\n```\n\n## Getting started\n\nThe best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:\n- Copy the subtree of the relevant example plugin into a standalone project.\n- Edit `setup.py`, rename the plugin module, and declare its entry point.\n- Install the new plugin (Run this in the plugin directory: `pip install -e .`)\n- Run the included example app and make sure that the plugin is discovered:\n```shell\n$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n```\n- Run the example application to see that that your plugin is doing something.\n- *[Optional]* Embed the plugin in your existing application or library. An\n entry-point plugin can use any importable package name.\n- Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.\n\nFor a `SearchPathPlugin` that provides organization-specific Hydra defaults,\nsee [Environment-specific overrides](../../patterns/environment_specific_overrides.md).\n","website/docs/advanced/plugins/intro.md":"---\nid: overview\ntitle: Plugins Overview\nsidebar_label: Plugins Overview\n---\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra can be extended via plugins.\nThe example plugins here can help you get started with plugin development.\n\n## Plugin types\nHydra has several plugin types:\n### Sweeper\nA sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:\n```\nbatch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n```\n\nAnd creates 4 jobs with the following parameters:\n```\nbatch_size=128 optimizer=nesterov learning_rate=0.01\nbatch_size=128 optimizer=nesterov learning_rate=0.1\nbatch_size=128 optimizer=adam learning_rate=0.01\nbatch_size=128 optimizer=adam learning_rate=0.1\n```\n\n### Launcher\nLaunchers are responsible for launching a job to a specific environment.\nA Launcher takes a batch of argument lists like the one above and launches a job for each one.\nThe job uses those arguments to compose its configuration.\nThe basic launcher simply launches the job locally. \n\n### SearchPathPlugin\nA config path plugin can manipulate the search path.\nThis can be used to influence the default Hydra configuration to be more appropriate to a specific environment,\nor just add new entries to the search path to make more configurations available to the Hydra app.\n\nSearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed.\n\nMany other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. \n\n### ConfigSource\nConfigSource plugins can be used to allow Hydra to access configuration in non-standard locations when composing the config.\nThis can be used to enable access to an in-house private config store, or as a way to access configs from public sources like GitHub or S3.\n","website/docs/plugins/ax_sweeper.md":"---\nid: ax_sweeper\ntitle: Ax Sweeper plugin\nsidebar_label: Ax Sweeper plugin\n---\n\nimport {ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ax-sweeper)](https://img.shields.io/pypi/v/hydra-ax-sweeper)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ax-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ax-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ax-sweeper/month)](https://pepy.tech/project/hydra-ax-sweeper)\n\n\nThis plugin provides a mechanism for Hydra applications to use the [Adaptive Experimentation Platform, aka Ax](https://ax.dev/). Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations.\n\n:::warning Retirement after Hydra 1.4\n\nHydra 1.4 will include the final first-party release of the Ax Sweeper, based on\nthe existing implementation. Further modernization is no longer planned. The\nplugin code will be removed in the Hydra 1.5 line, and no first-party Ax Sweeper\nreleases will be published for Hydra 1.5 or later. Existing PyPI releases will\nremain available.\n\nCommunity members interested in maintaining the plugin in a separate repository\nare invited to comment on the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506).\nHydra's documentation can link to that repository. Transferring control of the\n`hydra-ax-sweeper` PyPI package may be considered once new maintainers establish\na reliable track record and build trust.\n\n:::\n\n### Installation\n```commandline\npip install hydra-ax-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=ax` to your command line. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: ax\n```\n\nWe include an example of how to use this plugin. The file example/banana.py\nimplements the [Rosenbrock function (aka Banana function)](https://en.wikipedia.org/wiki/Rosenbrock_function).\nThe return value of the function should be the value that we want to optimize.\n\n\nTo compute the best parameters for the Banana function, clone the code and run the following command in the `plugins/hydra_ax_sweeper` directory:\n\n```\npython example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n```\n\nThe output of a run looks like:\n\n```\n[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5]\nbanana.y: range=[-5.0, 10.1]\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 trials, GPEI for subsequent trials]). Iterations after 5 will take longer to generate due to model-fitting.\n[HYDRA] AxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=2 banana.y=-0.988\n[__main__][INFO] - Banana_Function(x=2, y=-0.988)=2488.883\n[HYDRA] #1 : banana.x=-1 banana.y=7.701\n[__main__][INFO] - Banana_Function(x=-1, y=7.701)=4493.987\n[HYDRA] #2 : banana.x=-1 banana.y=-3.901\n[__main__][INFO] - Banana_Function(x=-1, y=-3.901)=2406.259\n[HYDRA] #3 : banana.x=-1 banana.y=0.209\n[__main__][INFO] - Banana_Function(x=-1, y=0.209)=66.639\n[HYDRA] #4 : banana.x=4 banana.y=-4.557\n[__main__][INFO] - Banana_Function(x=4, y=-4.557)=42270.006\n[HYDRA] New best value: 66.639, best parameters: {'banana.x': -1, 'banana.y': 0.209}\n```\n\nIn this example, we set the range of `x` parameter as an integer in the interval `[-5, 5]` and the range of `y` parameter as a float in the interval `[-5, 10.1]`. Note that in the case of `x`, we used `int(interval(...))` and hence only integers are sampled. In the case of `y`, we used `interval(...)` which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.` banana.x=5.0`), choice parameters (eg `banana.x=choice(1,2,3)`) and range (eg `banana.x=range(1, 10)`). Note that `interval`, `choice` etc. are functions provided by Hydra, and you can read more about them [here](/advanced/override_grammar/extended.md). An important thing to remember is, use [`interval`](/advanced/override_grammar/extended.md#interval-sweep) when we want Ax to sample values from an interval. [`RangeParameter`](https://ax.dev/api/ax.html#ax.RangeParameter) in Ax is equivalent to `interval` in Hydra. Remember to use `int(interval(...))` if you want to sample only integer points from the interval. [`range`](/advanced/override_grammar/extended.md#range-sweep) can be used as an alternate way of specifying choice parameters. For example `python example/banana.py -m banana.x=choice(1, 2, 3, 4)` is equivalent to `python example/banana.py -m banana.x=range(1, 5)`.\n\nThe values of the `x` and `y` parameters can also be set using the config file `plugins/hydra_ax_sweeper/example/conf/config.yaml`. For instance, the configuration corresponding to the commandline arguments is as follows:\n\n```\nbanana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n```\n\nTo sample in log space, you can tag the commandline override with `log`. E.g. `python example/banana.py -m banana.x=tag(log, interval(1, 1000))`. You can set `log_scale: true` in the input config to achieve the same.\n```\nbanana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n```\n\nIn general, the plugin supports setting all the Ax supported [Parameters](https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter) in the config. According to the [Ax documentation](https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment), the required elements in the config are:\n\n* `name` - Name of the parameter. It is of type string.\n* `type` - Type of the parameter. It can take the following values: `range`, `fixed`, or `choice`.\n* `bounds` - Required only for the `range` parameters. It should be a list of two values, with the lower bound first.\n* `values` - Required only for the `choice` parameters. It should be a list of values.\n* `value` - Required only for the `fixed` parameters. It should be a single value.\n\nNote that if you want to sample integers in the range `-5` to `5`, you need to specify the range as `int(interval(-5, 5))` (in the command line) or `[-5, 5]` (in config). If you want to sample floats in range `-5` to `5`, you need to specify the range as `interval(-5, 5)` (in the command line) or `[-5.0, 5.0]` (in config).\n\nThe Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the `is_noisy` parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero.\n\nIf measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the [standard error of the mean](https://en.wikipedia.org/wiki/Standard_error) of repeated measurements), the measurement function can return the tuple `(measurement_value, measurement_uncertainty)` instead of a scalar value.\n\nThe parameters for the optimization process can also be set in the config file. Specifying the Ax config is optional. You can discover the Ax Sweeper parameters with:\n\n```yaml title=\"$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_ax_sweeper.ax_sweeper.AxSweeper\nmax_batch_size: null\nax_config:\n max_trials: 10\n early_stop:\n minimize: true\n max_epochs_without_improvement: 10\n epsilon: 1.0e-05\n experiment:\n name: null\n objective_name: objective\n minimize: true\n parameter_constraints: null\n outcome_constraints: null\n status_quo: null\n client:\n verbose_logging: false\n random_seed: null\n is_noisy: true\n params: {}\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n","website/docs/plugins/colorlog.md":"---\nid: colorlog\ntitle: Colorlog plugin\nsidebar_label: Colorlog plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-colorlog)](https://pypi.org/project/hydra-colorlog/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-colorlog)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-colorlog)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-colorlog/month)](https://pepy.tech/project/hydra-colorlog)\n\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\n\n### Installation\n```commandline\npip install hydra_colorlog --upgrade\n```\n\n### Usage\nOverride `hydra/job_logging` and `hydra/hydra_logging` in your config:\n\n```yaml\ndefaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n```\n\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee included example application.\n \n![Colored log output](/plugins/colorlog/colorlog.png)\n","website/docs/plugins/joblib_launcher.md":"---\nid: joblib_launcher\ntitle: Joblib Launcher plugin\nsidebar_label: Joblib Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-joblib-launcher)](https://pypi.org/project/hydra-joblib-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-joblib-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-joblib-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-joblib-launcher/month)](https://pepy.tech/project/hydra-joblib-launcher)\n\nThe Joblib Launcher plugin provides a launcher for parallel tasks based on [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html).\n\n### Process backends\n\nThe launcher supports two process backends:\n\n| Backend | Advantages | Tradeoffs |\n| --- | --- | --- |\n| `loky` (default) | Robust process management and Cloudpickle support for dynamically defined Python objects. It remains the default for compatibility. | Workers are reused between Hydra jobs, so arbitrary application caches or process-global state can leak between jobs. Cloudpickling the task can also fail when it reaches some native-library objects. |\n| `multiprocessing` | Runs every Hydra job in a fresh worker process and sends module-level function tasks by reference instead of Cloudpickling them. This provides strict process isolation and avoids serializing module-level native-library objects referenced by the task. | Functions must be defined at module scope. Custom decorators around `@hydra.main` must use `functools.wraps`. |\n\nLoky runs jobs in the parent process when `n_jobs=1`. The multiprocessing\nbackend retains per-job worker isolation while executing one job at a time.\n\n### Installation\n```commandline\npip install hydra-joblib-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=joblib` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: joblib\n```\nBy default, the launcher uses process-based parallelism with all available CPU\ncores. Set `hydra.launcher.n_jobs` to limit the number of jobs that can run\nconcurrently.\n\nThe JobLibLauncherConf backing the config is defined here:\n\nYou can discover the Joblib Launcher parameters with:\n```yaml title=\"$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: -1\ninner_max_num_threads: null\nbackend: loky\nprefer: processes\nrequire: null\nverbose: 0\ntimeout: null\npre_dispatch: 2*n_jobs\nbatch_size: auto\ntemp_folder: null\nmax_nbytes: null\nmmap_mode: r\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee [`Joblib.Parallel` documentation](https://joblib.readthedocs.io/en/latest/parallel.html) for full details about the parameters above.\n\n`backend` selects the backend used by this launcher. Because a backend is\nalways selected explicitly, `prefer` does not change it. `require` must be\ncompatible with the selected backend; `require=sharedmem` is unsupported\nbecause this launcher does not support a thread-based backend.\n\n#### Controlling native library thread pools\n\nWhen using libraries that manage native thread pools, such as OpenBLAS, MKL, OpenMP, Numba, or NumExpr, set `inner_max_num_threads` to limit the number of native threads available to each Joblib worker process:\n\n```yaml\nhydra:\n launcher:\n n_jobs: 8\n inner_max_num_threads: 1\n```\n\nThis can help avoid oversubscription when multiple Hydra jobs run in parallel and each job calls into a multithreaded native library. For arbitrary environment variables, use [`hydra.job.env_set`](../configure_hydra/job.md#hydrajobenv_set) instead.\n\n
\nSelect the `multiprocessing` backend to execute every job in a fresh worker\nprocess:\n\n```yaml\nhydra:\n launcher:\n backend: multiprocessing\n n_jobs: 4\n```\n\nThe launcher automatically sets Joblib's `batch_size=1` so that each pool task\ncontains one Hydra job, and `maxtasksperchild=1` so that the worker exits after\nthat task. These are internal correctness settings, not user configuration.\nConflicting values are rejected.\n\n`inner_max_num_threads` is supported only by `loky`. Custom decorators around\n`@hydra.main` must follow the\n[Hydra task-decorator requirements](../advanced/decorating_main.md). Callable\ntask objects are copied to each worker, so all state stored on them must support\nPython pickling.\n

\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will launch five parallel executions:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=10,backend=loky,prefer=processes,require=None,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r) is launching 5 jobs\n[HYDRA] Launching jobs, sweep output dir : multirun/2020-02-18/10-00-00\n[__main__][INFO] - Process ID 14336 executing task 2 ...\n[__main__][INFO] - Process ID 14333 executing task 1 ...\n[__main__][INFO] - Process ID 14334 executing task 3 ...\n[__main__][INFO] - Process ID 14335 executing task 4 ...\n[__main__][INFO] - Process ID 14337 executing task 5 ...\n```\n","website/docs/plugins/nevergrad_sweeper.md":"---\nid: nevergrad_sweeper\ntitle: Nevergrad Sweeper plugin\nsidebar_label: Nevergrad Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-nevergrad-sweeper)](https://pypi.org/project/hydra-nevergrad-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-nevergrad-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-nevergrad-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-nevergrad-sweeper/month)](https://pepy.tech/project/hydra-nevergrad-sweeper)\n\n[Nevergrad](https://facebookresearch.github.io/nevergrad/) is a derivative-free optimization platform providing a library of state-of-the-art algorithms for hyperparameter search. This plugin provides Hydra applications a mechanism to use [Nevergrad](https://facebookresearch.github.io/nevergrad/) algorithms to optimize experiment/application parameters.\n\n### Installation\n```commandline\npip install hydra-nevergrad-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=nevergrad` to your command. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: nevergrad\n```\n\nThe default configuration is defined and documented here.\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Example of training using Nevergrad hyperparameter search\n\nWe include an example of how to use this plugin. The file example/my_app.py implements an example of minimizing a (dummy) function using a mixture of continuous and discrete parameters.\n\nYou can discover the Nevergrad sweeper parameters with:\n```yaml title=\"$ python your_app hydra/sweeper=nevergrad --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_nevergrad_sweeper.nevergrad_sweeper.NevergradSweeper\noptim:\n optimizer: NGOpt\n budget: 80\n num_workers: 10\n noisy: false\n maximize: false\n seed: null\n max_failure_rate: 0.0\nparams:\n db: choice(mnist, cifar)\n lr: {init: 0.02, step: 2.0, log: true}\n dropout: interval(0, 1)\n batch_size: int(interval(4, 16))\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\ndb: mnist\nlr: 0.12\ndropout: 0.33\nbatch_size: 4\n```\n\nTo run hyperparameter search and look for the best parameters for this function, clone the code and run the following command in the `plugins/hydra_nevergrad_sweeper` directory:\n```bash\npython example/my_app.py -m\n```\n\nYou can also override the search space parametrization:\n```bash\npython example/my_app.py --multirun db=mnist,cifar batch_size=4,8,16 \\\n'lr=tag(log, interval(0.001, 1))' 'dropout=interval(0,1)'\n```\n\nThe initialization of the sweep and the first 5 evaluations (out of 100) look like this:\n\n```text\n[2020-10-08 20:13:53,592][HYDRA] NevergradSweeper(optimizer=NGOpt, budget=100, num_workers=10) minimization\n[2020-10-08 20:13:53,593][HYDRA] with parametrization Dict(batch_size=Choice(choices=Tuple(4,8,16),weights=Array{(1,3)}),db=Choice(choices=Tuple(mnist,cifar),weights=Array{(1,2)}),dropout=Scalar{Cl(0,1,b)}[sigma=Log{exp=2.0}],lr=Log{exp=3.162277660168379,Cl(0.001,1,b)}):{'db': 'mnist', 'lr': 0.03162277660168379, 'dropout': 0.5, 'batch_size': 8}\n[2020-10-08 20:13:53,593][HYDRA] Sweep output dir: multirun/2020-10-08/20-13-53\n[2020-10-08 20:13:55,023][HYDRA] Launching 10 jobs locally\n[2020-10-08 20:13:55,023][HYDRA] #0 : db=mnist lr=0.03162277660168379 dropout=0.5 batch_size=16\n[2020-10-08 20:13:55,217][__main__][INFO] - dummy_training(dropout=0.500, lr=0.032, db=mnist, batch_size=16) = 13.258\n[2020-10-08 20:13:55,218][HYDRA] #1 : db=cifar lr=0.018178519762066934 dropout=0.5061074452336254 batch_size=4\n[2020-10-08 20:13:55,408][__main__][INFO] - dummy_training(dropout=0.506, lr=0.018, db=cifar, batch_size=4) = 0.278\n[2020-10-08 20:13:55,409][HYDRA] #2 : db=cifar lr=0.10056825918734161 dropout=0.6399687427725211 batch_size=4\n[2020-10-08 20:13:55,595][__main__][INFO] - dummy_training(dropout=0.640, lr=0.101, db=cifar, batch_size=4) = 0.329\n[2020-10-08 20:13:55,596][HYDRA] #3 : db=mnist lr=0.06617542958182834 dropout=0.5059497416026679 batch_size=8\n[2020-10-08 20:13:55,812][__main__][INFO] - dummy_training(dropout=0.506, lr=0.066, db=mnist, batch_size=8) = 5.230\n[2020-10-08 20:13:55,813][HYDRA] #4 : db=mnist lr=0.16717013388679514 dropout=0.6519070394318255 batch_size=4\n...\n[2020-10-08 20:14:27,988][HYDRA] Best parameters: db=cifar lr=0.11961221693764439 dropout=0.37285878409770895 batch_size=4\n```\n\n\nand the final 2 evaluations look like this:\n```text\n[HYDRA] \t#8 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] \t#9 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] Best parameters: db=mnist batch_size=4 lr=0.094 dropout=0.381\n```\n\n\nThe run also creates an `optimization_results.yaml` file in your sweep folder with the best evaluated parameters found during the sweep:\n```yaml\nbest_evaluated_result: 0.381\n\nbest_evaluated_params:\n batch_size: 4\n db: mnist\n dropout: 0.381\n lr: 0.094\n\nname: nevergrad\n```\n\n## Defining the parameters\n\nThe plugin supports two types of parameters: [Choices](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters) and [Scalars](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters). They can be defined either through a config file or command-line override.\n\n### Defining through command-line override\nHydra provides an override parser that supports rich syntax. More documentation can be found in ([Override Grammar/Basic](../advanced/override_grammar/basic.md)) and ([Override Grammar/Extended](../advanced/override_grammar/extended.md)). We recommend you go through them first before proceeding with this doc.\n\n#### Choices\nTo override a field with choices:\n```commandline\n'key=1,5'\n'key=shuffle(range(1, 8))'\n'key=range(1,5)'\n```\n\nYou can tag an override with `ordered` to indicate it's a [`TransitionChoice`](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters)\n```commandline\nkey=tag(ordered, choice(1,2,3))\n```\n\n#### Scalar\n```commandline\nkey=interval(1,12) # Intervals are floats by default\nkey=int(interval(1,8)) # Scalar bounds are cast to an int\nkey=tag(log, interval(1,12)) # call ng.p.Log if tagged with log\nkey={init: 0.02, step: 2.0, log: true} # Unbounded log-scale scalar\n```\n\n### Defining through config file\nThe search space can be defined under `hydra.sweeper.params`.\nThe definition is consistent with the equivalent command-line override.\n\n:::warning\n`hydra.sweeper.parametrization` is deprecated in Hydra 1.4 and will be removed\nin Hydra 1.5. Use `hydra.sweeper.params` instead.\n:::\n\n#### Choices\nChoices use the same syntax as command-line overrides. For example, translate\n`key=shuffle(range(1, 8))` to `key: shuffle(range(1, 8))` in the config file.\n\nFixed strings containing override grammar characters must retain quotes as part\nof the configured value. For example, use `label: \"'a,b'\"` to configure the\nliteral string `a,b`; `label: a,b` defines a choice sweep.\n\n#### Scalars\n`Scalar` definitions also support the override syntax shown above. The\nfollowing keys can be passed in a dictionary to define unbounded scalars:\n - `init`: optional initial value\n - `lower` : optional lower bound\n - `upper`: optional upper bound\n - `log`: set to `true` for log distributed values\n - `step`: optional step size for looking for better parameters. In linear mode, this is an additive step; in logarithmic mode it is multiplicative.\n - `integer`: set to `true` for integers (favor floats over integers whenever possible)\n\nProviding only `lower` and `upper` bound will set the initial value to the middle of the range and the step to a sixth of the range.\n","website/docs/plugins/optuna_sweeper.md":"---\nid: optuna_sweeper\ntitle: Optuna Sweeper plugin\nsidebar_label: Optuna Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-optuna-sweeper)](https://pypi.org/project/hydra-optuna-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-optuna-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-optuna-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-optuna-sweeper/month)](https://pepy.tech/project/hydra-optuna-sweeper)\n\n\nThis plugin enables Hydra applications to utilize [Optuna](https://optuna.org) for the optimization of the parameters of experiments.\n\n## Installation\n\nThis plugin requires Hydra Core 1.4 (`hydra-core>=1.4.0.dev1,<1.5.0.dev0`).\nPlease install it with the following command:\n\n```commandline\npip install --upgrade --pre \"hydra-core>=1.4.0.dev1,<1.5.0.dev0\"\n```\n\nYou can install the plugin via pip:\n\n```commandline\npip install --upgrade --pre \"hydra-optuna-sweeper>=1.4.0.dev1,<1.5.0.dev0\"\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Usage\n\nPlease set `hydra/sweeper` to `optuna` in your config file.\n\n```yaml\ndefaults:\n - override hydra/sweeper: optuna\n```\n\nAlternatively, add `hydra/sweeper=optuna` option to your command line.\n\nThe default configuration is here.\n\n## Example 1: Single-Objective Optimization\n\nWe include an example in this directory. `example/sphere.py` implements a simple benchmark function to be minimized.\n\n\n\n\nYou can discover the Optuna sweeper parameters with:\n\n```yaml title=\"python example/sphere.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\nsampler:\n _target_: optuna.samplers.TPESampler\n seed: 123\n n_startup_trials: 10\n n_ei_candidates: 24\n multivariate: false\n_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\ndirection: minimize\nstorage: null\nstudy_name: sphere\nn_trials: 20\nn_jobs: 1\nmax_failure_rate: 0.0\nparams:\n x: range(-5.5,5.5,step=0.5)\n y: choice(-5,0,5)\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\nx: 0\ny: 0\n```\n\nTo run optimization, clone the code and run the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/sphere.py --multirun\n```\n\nYou can also override the search space parametrization:\n\n```commandline\npython example/sphere.py --multirun 'x=interval(-5.0, 5.0)' 'y=interval(0, 10)'\n```\n\nYou might find the `optimization_results.yaml` file (i.e. best params and best value) under `multirun` logs folder:\n\n```yaml\nname: optuna\nbest_params:\n x: 0.0\n 'y': 0\nbest_value: 0.0\n```\n\n\n## Sampler configuration\nThis plugin supports Optuna's [samplers](https://optuna.readthedocs.io/en/stable/reference/samplers.html).\nYou can change the sampler by overriding `hydra/sweeper/sampler` or change sampler settings within `hydra.sweeper.sampler`.\n\n## Search space configuration\n\nThis plugin supports Optuna's [distributions](https://optuna.readthedocs.io/en/stable/reference/distributions.html) to configure search spaces. They can be defined either through commandline override or config file.\n\n### Configuring through commandline override\n\nHydra provides a override parser that support rich syntax. Please refer to [OverrideGrammer/Basic](../advanced/override_grammar/basic.md) and [OverrideGrammer/Extended](../advanced/override_grammar/extended.md) for details.\n\n#### Interval override\n\nBy default, `interval` is converted to [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html). You can use [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html) by casting the interval to `int`.\n\n
\n Example for interval override\n\n ```commandline\n python example/sphere.py --multirun 'x=int(interval(-5.0, 5.0))' 'y=tag(log, interval(1, 10))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=1.6859762540733367\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=5.237816870668193\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': 1.0929184723430116}\n [HYDRA] Best value: 1.1944707871885822\n ```\n\n
\n\n#### Range override\n\nInteger ranges are converted to [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html).\nFloat ranges, including sorted float ranges, use [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html).\nThe distribution includes exactly the discrete values in the range: its stop\nis exclusive, and descending ranges are supported. Empty ranges and zero steps\nare rejected. For example, `range(1,3)` permits only `1` and `2`, while\n`range(0,1,0.3)` permits `0.0`, `0.3`, `0.6`, and `0.9`.\n\nWhen converting a float range would make its Decimal endpoints or step\nunrepresentable as an Optuna numeric distribution, the sweeper uses a\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\nwith the generated values instead. This precision-boundary fallback preserves\nthe exact values and duplicates; representable ordinary uncast ranges remain\nnumeric and are converted without enumerating their values.\n\nApplying `shuffle`, `int`, or `float` to a range uses\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\ncontaining its generated values. Casts apply to each value, so\n`int(range(0,5,1.5))` permits `0`, `1`, `3`, and `4`. Duplicate cast values are\nretained. Sorting or shuffling does not change the permitted values. Optuna\ndoes not promise to evaluate trials in range order.\n\nGridSampler evaluates all values in each discrete distribution, including a\nsingleton or the distribution's inclusive upper endpoint.\n\nThese corrections changed range search spaces in Hydra 1.4; earlier unshuffled\nranges could admit an excluded stop. See the\n[migration guide](/docs/upgrades/1.3_to_1.4/breaking_changes#optuna-range-sweeps).\n\n
\n Example for range override\n\n ```commandline\n python example/sphere.py --multirun 'x=range(-5.0, 5.0)' 'y=shuffle(range(-5, 5))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=-4\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=-1\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': -1}\n [HYDRA] Best value: 1.0\n ```\n\n
\n\n#### Choice override\n\n`choice` is converted to [`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html).\n\n
\n Example for choice override\n\n ```commandline\n python example/sphere.py --multirun 'x=choice(-5.0, 0.0, 5.0)' 'y=choice(0, 1, 2, 3, 4, 5)'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=5.0 y=5\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=5.0 y=2\n ...\n [HYDRA] Best parameters: {'x': 0.0, 'y': 0}\n [HYDRA] Best value: 0.0\n ```\n\n
\n\n### Configuring through config file\n\nThe syntax in config file is consistent with the above commandline override. For example, a commandline override\n`x=range(1,4)` can be expressed in config file as `x: range(1,4)` under the `hydra.sweeper.params` node.\n\n## Example 2: Multi-Objective Optimization\n\nIn the same directory, `example/multi-objective.py` implements a simple benchmark function, which has two objective values. We want to minimize two objectives simultaneously.\n\nYou can discover the Optuna sweeper parameters with:\n\n```commandline\npython example/multi-objective.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\n```\n\n
\n Configuration of the multi-objective optimization example\n\n ```yaml\n # @package hydra.sweeper\n sampler:\n _target_: optuna.samplers.NSGAIISampler\n seed: 123\n population_size: 50\n mutation_prob: null\n crossover_prob: 0.9\n swapping_prob: 0.5\n constraints_func: null\n _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\n direction:\n - minimize\n - minimize\n storage: null\n study_name: multi-objective\n n_trials: 20\n n_jobs: 1\n params:\n x: range(0, 5, step=0.5)\n y: range(0, 3, step=0.5)\n ```\n
\n\n\nTo run the optimization, use the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/multi-objective.py --multirun\n```\n\nFor problems with trade-offs between two different objectives, there may be no single solution that simultaneously minimizes both objectives. Instead, we obtained a set of solutions, namely [Pareto optimal solutions](https://en.wikipedia.org/wiki/Pareto_efficiency), that show the best trade-offs possible between the objectives. In the following figure, the blue dots show the Pareto optimal solutions in the optimization results.\n\n![Pareto-optimal solutions](/plugins/optuna_sweeper/multi_objective_result.png)\n\n## EXPERIMENTAL: Custom-Search-Space Optimization\n\nHydra's Optuna Sweeper allows users to provide a hook for custom search space configuration.\nThis means you can work directly with the `optuna.trial.Trial` object to suggest parameters.\nTo use this feature, define a python function with signature `Callable[[DictConfig, optuna.trial.Trial], None]`\nand set the `hydra.sweeper.custom_search_space` key in your config to target that function.\n\nThe callback path is selected by configuration. When using an execution\nwhitelist, authorize that path from trusted Python code:\n\n```python\n@hydra.main(\n config_path=\"custom-search-space\",\n config_name=\"config\",\n execution_whitelist=\"custom-search-space-objective.configure\",\n)\ndef multi_dimensional_sphere(cfg: DictConfig) -> float:\n ...\n```\n\nYou can find a full example in the same directory as before, where `example/custom-search-space-objective.py` implements a benchmark function to be minimized.\nThe example shows the use of Optuna's [pythonic search spaces](https://optuna.readthedocs.io/en/stable/tutorial/10_key_features/002_configurations.html) in combination with Hydra.\nPart of the search space configuration is defined in config files, and part of it is written in Python.\n\n
\n Example: Custom search space configuration\n\n ```yaml\n defaults:\n - override hydra/sweeper: optuna\n\n hydra:\n sweeper:\n sampler:\n seed: 123\n direction: minimize\n study_name: custom-search-space\n storage: null\n n_trials: 20\n n_jobs: 1\n\n params:\n x: range(-5.5, 5.5, 0.5)\n y: choice(-5, 0, 5)\n # `custom_search_space` should be a dotpath pointing to a\n # callable that provides search-space configuration logic:\n custom_search_space: custom-search-space-objective.configure\n\n x: 1\n y: 1\n z: 100\n max_z_difference_from_x: 0.5\n ```\n ```python\n # example/custom-search-space-objective.py\n\n ...\n\n def configure(cfg: DictConfig, trial: Trial) -> None:\n x_value = trial.params[\"x\"]\n trial.suggest_float(\n \"z\",\n x_value - cfg.max_z_difference_from_x,\n x_value + cfg.max_z_difference_from_x,\n )\n trial.suggest_float(\"+w\", 0.0, 1.0) # note +w here, not w as w is a new parameter\n\n ...\n ```\n\n
\n\nThe method that `custom_search_space` points to must accepts both a DictConfig with already set options and a trial object which needs further configuration. In this example we limit `z` the difference between `x` and `z` to be no more than 0.5.\nNote that this `custom_search_space` API should be considered experimental and is subject to change.\n\n### Order of trial configuration\nConfiguring a trial object is done in the following sequence:\n - search space parameters are set from the `hydra.sweeper.params` key in the config\n - Command line overrides are set\n - `custom_search_space` parameters are set\n\nIt is not allowed to set search space parameters in the `custom_search_space` method for parameters which have a fixed value from command line overrides. [Trial.user_attrs](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.trial.Trial.html#optuna.trial.Trial.user_attrs) can be inspected to find any of such fixed parameters.\n","website/docs/plugins/ray_launcher.md":"---\nid: ray_launcher\ntitle: Ray Launcher plugin\nsidebar_label: Ray Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ray-launcher)](https://pypi.org/project/hydra-ray-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ray-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ray-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ray-launcher/month)](https://pepy.tech/project/hydra-ray-launcher)\n\nThe Ray Launcher plugin provides 2 launchers: `ray_aws` and `ray`.\n `ray_aws` launches jobs remotely on AWS and is built on top of [ray autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). `ray` launches jobs on your local machine or existing ray cluster.\n\n:::note Ray AWS support\nThe local `ray` launcher is supported as a normal Hydra plugin.\n\nThe `ray_aws` launcher is maintained on a best-effort basis. Historically, this path has required substantially more maintainer attention and infrastructure resources than other Hydra plugins. It depends on Ray autoscaler behavior and live AWS infrastructure, both of which are comparatively unstable external surfaces for Hydra to validate. Running reliable end-to-end coverage also has a real cloud-cost burden, which is difficult to justify within the project's limited maintenance budget.\n\nFixes for `ray_aws` are welcome from users who can validate them on AWS. PRs that change `ray_aws` behavior must include cheap local validation where possible and a clear report of real AWS testing for behavior that cannot be covered locally.\n\nIn the long term, if the `ray_aws` launcher becomes completely non-functional and there is no maintainer or user-contributor path to validate and repair it, support may be dropped entirely.\n:::\n\n### Installation\n\n```commandline\n$ pip install hydra-ray-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=ray_aws` or `hydra/launcher=ray` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: ray_aws\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe `ray_pkg_version` resolver now takes installed distribution names instead of\nPython import names and reads their metadata without importing the module.\nFor example, replace `${ray_pkg_version:yaml}` with `${ray_pkg_version:PyYAML}`.\n`${ray_pkg_version:hydra}` remains an alias for `hydra-core`.\nPackages must be installed, including editable installs.\nAn importable source directory alone is insufficient. If metadata is unavailable,\ninstall the package or set its version explicitly in `env_setup.pip_packages`.\n\n### `ray_aws` launcher\n\n:::important\n`ray_aws` launcher is built on top of ray's [autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). To get started, you need to\n[config your AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).\n`ray autoscaler sdk` expects your AWS credentials have certain permissions for [`EC2`](https://aws.amazon.com/ec2) and [`IAM`](https://aws.amazon.com/iam). Read [this](https://github.com/ray-project/ray/issues/9327) for more information.\n:::\n\n`ray autoscaler sdk` expects a configuration for the EC2 cluster; we've schematized the configs in here\n\n
\n Discover ray_aws launcher's config\n\n ```commandline\n $ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n # @package hydra.launcher\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\n env_setup:\n pip_packages:\n omegaconf: ${ray_pkg_version:omegaconf}\n hydra_core: ${ray_pkg_version:hydra}\n ray: ${ray_pkg_version:ray}\n cloudpickle: ${ray_pkg_version:cloudpickle}\n pickle5: 0.0.11\n hydra_ray_launcher: 1.2.0.dev1\n commands:\n - conda create -n hydra_${python_version:micro} python=${python_version:micro} -y\n - echo 'export PATH=\"$HOME/anaconda3/envs/hydra_${python_version:micro}/bin:$PATH\"'\n >> ~/.bashrc\n ray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n upscaling_speed: 1.0\n max_workers: 1\n idle_timeout_minutes: 5\n docker:\n image: ''\n container_name: ''\n pull_before_run: true\n run_options: []\n provider:\n type: aws\n region: us-west-2\n availability_zone: us-west-2a,us-west-2b\n cache_stopped_nodes: false\n key_pair:\n key_name: hydra-${oc.env:USER,user}\n auth:\n ssh_user: ubuntu\n available_node_types:\n ray.head.default:\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n ray.worker.default:\n min_workers: 0\n max_workers: 2\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n InstanceMarketOptions:\n MarketType: spot\n head_node_type: ray.head.default\n file_mounts: {}\n initialization_commands: []\n cluster_synced_files: []\n setup_commands: []\n head_setup_commands: []\n worker_setup_commands: []\n head_start_ray_commands:\n - ray stop\n - ulimit -n 65536;ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml\n worker_start_ray_commands:\n - ray stop\n - ulimit -n 65536; ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076\n run_env: auto\n stop_cluster: true\n sync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n sync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n logging:\n log_style: auto\n color_mode: auto\n verbosity: 0\n create_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\n teardown_cluster:\n workers_only: false\n keep_min_workers: false\n ```\n
\n\n\n#### Examples\n\nThe following examples can be found here.\n\n
\n Simple app\n\n ```commandline\n $ python my_app.py --multirun task=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : task=1\n [HYDRA] #1 : task=2\n [HYDRA] #2 : task=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmpqqg4v4i7/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=3374) [__main__][INFO] - Executing task 1\n (pid=3374) [__main__][INFO] - Executing task 2\n (pid=3374) [__main__][INFO] - Executing task 3\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n
\n Upload & Download from remote cluster\n\n If your application is dependent on multiple modules, you can configure `hydra.launcher.sync_up` to upload dependency modules to the remote cluster.\n You can also configure `hydra.launcher.sync_down` to download output from remote cluster if needed. This functionality is built on top of `rsync`, `include` and `exclude` is consistent with how it works in `rsync`.\n\n ```commandline\n $ python train.py --multirun random_seed=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : random_seed=1\n [HYDRA] #1 : random_seed=2\n [HYDRA] #2 : random_seed=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmptdkye9of/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n Loaded cached provider configuration\n ...\n [HYDRA] Output: receiving file list ... done\n 16-32-25/\n 16-32-25/0/\n 16-32-25/0/checkpoint/\n 16-32-25/0/checkpoint/checkpoint_1.pt\n 16-32-25/1/\n 16-32-25/1/checkpoint/\n 16-32-25/1/checkpoint/checkpoint_2.pt\n 16-32-25/2/\n 16-32-25/2/checkpoint/\n 16-32-25/2/checkpoint/checkpoint_3.pt\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n##### Manage Cluster LifeCycle\nYou can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:\n\n- Default setting (no need to specify on commandline): delete cluster after job finishes remotely:\n ```commandline\n hydra.launcher.stop_cluster=true\n hydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\n hydra.launcher.teardown_cluster.workers_only=false\n hydra.launcher.teardown_cluster.keep_min_workers=false\n ```\n\n- Keep cluster running after jobs finishes remotely\n ```commandline\n hydra.launcher.stop_cluster=false\n ```\n\n- Power off EC2 instances and control node termination using `hydra.launcher.ray.cluster.provider.cache_stopped_nodes`\nand `hydra.launcher.teardown_cluster.workers_only`\n\n | cache_stopped_nodes | workers_only | behavior |\n |---------------------|--------------|----------|\n | false | false | All nodes are terminated |\n | false | true | Keeps head node running and terminates only worker node |\n | true | false | Keeps both head node and worker node and stops both of them |\n | true | true | Keeps both head node and worker node and stops only worker node |\n\n- Keep `hydra.launcher.ray.cluster.min_workers` worker nodes\nand delete the rest of the worker nodes\n ```commandline\n hydra.launcher.teardown_cluster.keep_min_workers=true\n ```\n\nAdditionally, you can configure how to create or update the cluster:\n\n- Default config: run setup commands, restart Ray and use\nthe config cache if available\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=false\n hydra.launcher.create_update_cluster.restart_only=false\n hydra.launcher.create_update_cluster.no_config_cache=false\n ```\n\n- Skip restarting Ray services when updating the cluster config\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=true\n ```\n\n- Skip running setup commands and only restart Ray (cannot be used with\n`hydra.launcher.create_update_cluster.no_restart`)\n ```commandline\n hydra.launcher.create_update_cluster.restart_only=true\n ```\n\n- Fully resolve all environment settings from the cloud provider again\n ```commandline\n hydra.launcher.create_update_cluster.no_config_cache=true\n ```\n\n\n##### Configure Ray Logging\nYou can manage Ray specific logging by configuring the flags provided by the plugin:\n\n- Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode\n ```commandline\n hydra.launcher.logging.log_style=\"auto\"\n hydra.launcher.logging.color_mode=\"auto\"\n hydra.launcher.logging.verbosity=0\n ```\n\n- Disable pretty-print\n ```commandline\n hydra.launcher.logging.log_style=\"record\"\n ```\n\n- Disable color mode\n ```commandline\n hydra.launcher.logging.color_mode=\"false\"\n ```\n\n- Increase Ray logging verbosity\n ```commandline\n hydra.launcher.logging.verbosity=3\n ```\n\n### `ray` launcher\n\n`ray` launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing `ray` launcher's configuration here\n `~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml`\n\n The example application starts a new ray cluster.\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-16-28\n[HYDRA] Initializing ray with config: {}\nINFO services.py:1164 -- View the Ray dashboard at http://127.0.0.1:8266\n[HYDRA] #0 :\n(pid=97801) [__main__][INFO] - Executing task 1\n```\n\nYou can run the example application on your existing ray cluster as well by overriding `hydra.launcher.ray.init.address`:\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray hydra.launcher.ray.init.address=localhost:6379\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-13-32\n[HYDRA] Initializing ray with config: {'num_cpus': None, 'num_gpus': None, 'address': 'localhost:6379'}\nINFO worker.py:633 -- Connecting to existing Ray cluster at address: 10.30.99.17:6379\n[HYDRA] #0 :\n(pid=93358) [__main__][INFO] - Executing task 1\n```\n\n### Configure `ray.init()` and `ray.remote()`\nRay launcher is built on top of [`ray.init()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init)\nand [`ray.remote()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote).\nYou can configure `ray` by overriding `hydra.launcher.ray.init` and `hydra.launcher.ray.remote`.\nCheck out an example config.\n","website/docs/plugins/rq_launcher.md":"---\nid: rq_launcher\ntitle: RQ Launcher plugin\nsidebar_label: RQ Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-rq-launcher)](https://pypi.org/project/hydra-rq-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-rq-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-rq-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-rq-launcher/month)](https://pepy.tech/project/hydra-rq-launcher)\n\nThe RQ Launcher plugin provides a launcher for distributed execution and job queuing based on [Redis Queue (RQ)](https://python-rq.org).\n\nRQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a [Redis server](https://redis.io/topics/quickstart). When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database.\n\n\n### Installation\n```commandline\npip install hydra-rq-launcher --upgrade\n```\nUsage of this plugin requires a [Redis server](https://redis.io/topics/quickstart).\n\nNote that RQ does [not support Windows](https://python-rq.org/docs/#limitations).\n\n### Usage\nOnce installed, add `hydra/launcher=rq` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: rq\n```\n\nThe default configuration is as follows:\n\n```yaml title=\"$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_rq_launcher.rq_launcher.RQLauncher\nenqueue:\n job_timeout: null\n ttl: null\n result_ttl: null\n failure_ttl: null\n at_front: false\n job_id: null\n description: null\nqueue: default \nredis:\n host: ${oc.env:REDIS_HOST,localhost}\n port: ${oc.env:REDIS_PORT,6379}\n db: ${oc.env:REDIS_DB,0}\n password: ${oc.env:REDIS_PASSWORD,null}\n ssl: ${oc.env:REDIS_SSL,False}\n ssl_ca_certs: ${oc.env:REDIS_SSL_CA_CERTS,null\n mock: ${oc.env:REDIS_MOCK,False}\nstop_after_enqueue: false\nwait_polling: 1.0\n```\n\nFurther descriptions on the variables can be found in the plugin config file, defined here. There are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe plugin is using environment variables to store Redis connection information. The environment variables `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, and `REDIS_PASSWORD`, are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through `REDIS_SSL` and `REDIS_SSL_CA_CERTS`; see [redis-py](https://github.com/andymccurdy/redis-py#ssl-connections) documentation.\n\nFor example, they might be set as follows when using `bash` or `zsh` as a shell:\n\n```commandline\nexport REDIS_HOST=\"localhost\"\nexport REDIS_PORT=\"6379\"\nexport REDIS_DB=\"0\"\nexport REDIS_PASSWORD=\"\"\n```\n\nEnable SSL by setting the relevant environment variables. e.g:\n```commandline\nexport REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n```\n\nAssuming configured environment variables, workers connecting to the Redis server can be launched using:\n\n```commandline\nrq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB \\\n -S hydra_plugins.hydra_rq_launcher.serializer.CloudpickleSerializer\n```\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will enqueue five jobs to be processed by worker instances:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n\n[HYDRA] RQ Launcher is enqueuing 5 job(s) in queue : default\n[HYDRA] Sweep output dir : multirun/2020-06-15/18-00-00\n[HYDRA] Enqueued 13b3da4e-03f7-4d16-9ca8-cfb3c48afeae\n[HYDRA] \t#1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] \t#2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] \t#3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] \t#4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] \t#5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n```\n\nNote that any dependencies need to be installed in the Python environment used to run the RQ worker. Workers must use Hydra's cloudpickle serializer so that job results are serialized compatibly with the RQ launcher.\n\nThe [RQ documentation](https://python-rq.org/) holds further information on [job monitoring](http://python-rq.org/docs/monitoring/), which can be done via console or [web interfaces](https://github.com/nvie/rq-dashboard), and provides [patterns](https://python-rq.org/patterns/) for worker and exception handling.\n","website/docs/plugins/submitit_launcher.md":"---\nid: submitit_launcher\ntitle: Submitit Launcher plugin\nsidebar_label: Submitit Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-submitit-launcher)](https://pypi.org/project/hydra-submitit-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-submitit-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-submitit-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-submitit-launcher/month)](https://pepy.tech/project/hydra-submitit-launcher)\n\nThe Submitit Launcher plugin provides a [SLURM](https://slurm.schedmd.com/documentation.html) Launcher based on [Submitit](https://github.com/facebookincubator/submitit).\n\n### Installation\n```commandline\npip install hydra-submitit-launcher --upgrade\n```\n\n\n### Usage\nOnce installed, add `hydra/launcher=submitit_slurm` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: submitit_slurm\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\nNote that this plugin expects a valid environment in the target host. Usually this means a shared file system between\nthe launching host and the target host.\n\nThe Submitit Plugin implements 2 different launchers: `submitit_slurm` to run on a SLURM cluster, and `submitit_local` for basic local tests.\n\n
\n Discover the SLURM Launcher parameters (Expand)\n\n ```yaml title=\"$ python your_app.py hydra/launcher=submitit_slurm --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: null\n gpus_per_node: null\n tasks_per_node: 1\n mem_gb: null\n nodes: 1\n name: ${hydra.job.name}\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.SlurmLauncher\n partition: null\n qos: null\n comment: null\n constraint: null\n exclude: null\n gres: null\n cpus_per_gpu: null\n gpus_per_task: null\n mem_per_gpu: null\n mem_per_cpu: null\n account: null\n signal_delay_s: 120\n max_num_timeout: 0\n python: null\n additional_parameters: {}\n array_parallelism: 256\n setup: null\n srun_args: null\n use_srun: true\n ```\n
\n
\n Discover the Local Launcher parameters (Expand)\n\n ```yaml title=\"$ python example/my_app.py hydra/launcher=submitit_local --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.LocalLauncher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: 1\n gpus_per_node: 0\n tasks_per_node: 1\n mem_gb: 4\n nodes: 1\n name: ${hydra.job.name}\n ```\n
\n\n
\nYou can set all these parameters in your configuration file and/or override them in the command-line:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.timeout_min=3\n```\nSet `hydra.launcher.tasks_per_node=null` to omit `--ntasks-per-node` from the\ngenerated Slurm submission.\n\nSet `hydra.launcher.use_srun=false` to run Python directly in the batch script\ninstead of through `srun`. The default is `true`. When disabled, Python runs\nonce on the batch node, and `srun_args` is ignored; Slurm does not automatically\nlaunch the other requested tasks.\n\nSet `hydra.launcher.python` to use a Python executable other than the one\nrunning Hydra:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.python=/opt/venv/bin/python\n```\n\nFor more details, including descriptions for each parameter, check out the config file.\nYou can also check the [Submitit documentation](https://github.com/facebookincubator/submitit).\n\n\n**Caution**: use of `--multirun` is required for the launcher to be picked up.\n\n### Example\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py task=1,2,3 --multirun` (see [Multi-run](../tutorials/basic/running_your_app/2_multirun.md) for details) will launch 3 executions (you can override the launcher to run locally for testing by adding `hydra/launcher=submitit_local`):\n\n```text\n$ python my_app.py task=1,2,3 --multirun\n[HYDRA] Sweep output dir : multirun/2020-05-28/15-05-22\n[HYDRA] #0 : task=1\n[HYDRA] #1 : task=2\n[HYDRA] #2 : task=3\n```\nYou will be able to see the output of the app in the output dir:\n```commandline\n$ tree\n.\n├── 0\n│   └── my_app.log\n├── 1\n│   └── my_app.log\n├── 2\n│   └── my_app.log\n└── multirun.yaml\n\n$ cat 0/my_app.log\n[2020-05-28 15:05:23,511][__main__][INFO] - Process ID 15887 executing task 1 ...\n[2020-05-28 15:05:24,514][submitit][INFO] - Job completed successfully\n```\n"},"files":{".github/copilot-instructions.md":"# Copilot instructions\n\nWhen generating code or reviewing pull requests for this repository, use\n`CONTRIBUTING.md` as the source of truth for contributor requirements.\n\nFor pull request reviews, check the changed files against the contributor\nguidelines and call out only actionable gaps, especially:\n\n- missing or insufficient tests for code changes;\n- missing documentation updates for API or behavior changes;\n- missing news fragments for non-trivial user-visible changes;\n- news fragments in the wrong `news/` directory or with the wrong category;\n- non-trivial features, API changes, or behavior changes that do not link to\n prior maintainer agreement in an issue or design discussion;\n- validation claims that are not supported by the tests or checks shown in the\n pull request.\n\nDo not request a news fragment for developer-only tooling, repository\nmaintenance, or CI-only changes unless the change affects the shipped product\nexperience.\n\nKeep review comments specific and actionable. Prefer pointing to the relevant\nguideline in `CONTRIBUTING.md` over restating the whole policy.\n","AGENTS.md":"# AGENTS.md\n\nRepo-specific directives for coding agents working in this project.\n\n## Behavioral defaults\n\nThese guidelines are intended to reduce common LLM coding mistakes. Apply them\nalongside the repo-specific rules below. They bias toward caution over speed,\nand for truly trivial tasks you may use judgment.\n\n### Think before coding\n\n- Do not assume.\n- Do not hide confusion.\n- Surface tradeoffs.\n- State assumptions explicitly when they matter to the implementation.\n- If multiple reasonable interpretations exist, present them instead of silently picking one.\n- If a simpler approach exists, say so.\n- Push back when warranted.\n- If something material is unclear or risky, stop, name what is confusing, and ask instead of guessing.\n\n### Simplicity first\n\n- Solve the requested problem with the minimum code necessary.\n- No features beyond what was asked.\n- No abstractions for single-use code.\n- No flexibility or configurability that was not requested.\n- No error handling for scenarios that are effectively impossible in context.\n- If a solution feels overbuilt for the task, simplify it before considering it done.\n- If you write 200 lines and the same result could be achieved in 50, rewrite it.\n- Ask: would a senior engineer say this is overcomplicated? If yes, simplify.\n\n### Surgical changes\n\n- Touch only what is needed for the request.\n- Do not \"clean up\" adjacent code, comments, formatting, or structure unless the change requires it.\n- Match the existing style and patterns of the codebase unless the user asks for a broader refactor.\n- If you notice unrelated dead code or issues nearby, mention them instead of fixing them opportunistically.\n- Remove imports, variables, functions, or other artifacts that your change makes unused.\n- Do not delete unrelated pre-existing dead code unless asked.\n- Every changed line should trace directly to the user's request.\n\n### Prefer focused tools over ad hoc shell\n\nUse repository-aware file inspection and edit tools for file operations. Reserve\nshell commands for things that genuinely require shell execution: `sl`\n(Sapling) commands, `gh`, dependency installation, or `nox` / `pytest` /\n`python` for tests, linting, and other repo tooling.\n\n- Use `rg` for text search and `rg --files` for file discovery.\n- Avoid inline Python snippets (`python -c ...`) when a dedicated tool or standard CLI utility is sufficient.\n- Use structured tools such as `jq` to parse JSON shell output instead of piping to Python.\n\n### Goal-driven execution\n\n- Translate requests into concrete success criteria that can be verified.\n- For bug fixes, prefer reproducing the issue with a test or other reliable check before fixing it.\n- For refactors, prefer checks that demonstrate behavior is preserved before and after.\n- For multi-step tasks, keep a brief plan in mind and verify each step before calling the work complete.\n- Favor specific goals over vague ones:\n - \"Add validation\" -> write tests for invalid inputs, then make them pass.\n - \"Fix the bug\" -> reproduce it with a test or reliable check, then make it pass.\n - \"Refactor X\" -> verify behavior before and after the refactor.\n\n## Documentation map\n\n- Website and docs source: [`website/`](./website/)\n- Current docs: [`website/docs/`](./website/docs/)\n- Development docs: [`website/docs/development/`](./website/docs/development/)\n- Plugin docs: [`website/docs/plugins/`](./website/docs/plugins/)\n- Versioned docs: [`website/versioned_docs/`](./website/versioned_docs/)\n\n## Reproduction files\n\nWhen asked to create a reproduction for an issue, place files under\n`temp/repro/`:\n\n- Single-file repro: `temp/repro/.py`\n- Multi-file repro: `temp/repro//`\n\n## Scratch files\n\nPlace low-value, disposable temporary files under `temp/scratch/`. Its contents\nmay be cleared weekly without review. Do not store reproductions, resumable\nworkflow state, unique evidence, or drafts awaiting use there.\n\n## Stop and ask\n\n- If a tracked repo file appears unexpectedly renamed, moved, regenerated, deleted, or otherwise changed, stop and ask before reverting, recreating, reclassifying, or staging over that change.\n- Do not change supported Python versions, CI matrices, packaging metadata, release automation, or workflow triggers unless the request explicitly includes that scope.\n\n## Verification\n\n- For any new or changed functionality, test it in two layers when practical:\n - run relevant focused tests with `pytest path/to/test_file.py`\n - run the relevant `nox` session to ensure no regressions\n- Hydra core tests run with `pytest` from the repository root.\n- Plugin tests run from the plugin directory after installing the plugin, or via `nox -s test_plugins`.\n- Use `PLUGINS=` with `nox` when validating one plugin.\n- If the broader suite disagrees with focused tests, trust the broader result and do not call the change verified.\n- If live verification is blocked by the current environment, request escalation if that would unblock it. If not, stop and ask for guidance.\n\n## Linting and formatting\n\nRun linting through `nox -s lint lint_plugins` when validating broad changes.\nThe repo's lint sessions include formatting, import sorting, type checks, style,\nYAML linting, and security checks.\n\nFor focused local checks, use the same tools the noxfile runs:\n\n- `ruff format .` / `ruff format --check .`\n- `ruff check .` / `ruff check --fix .`\n- `pyrefly check --config pyproject.toml`\n- `yamllint --strict .`\n- `bandit --exclude ./.nox/** -ll -r .`\n\n## Environment and hooks\n\n- Run commands from the repo-local `.venv` by default. Prefer\n `.venv/bin/python`, `.venv/bin/pip`, `.venv/bin/pytest`, and\n `.venv/bin/nox` when those entry points exist.\n- If `.venv` is missing and dependency installation is in scope, create it\n with `python -m venv .venv`, then install `requirements/dev.txt` and the\n editable checkout into that environment.\n- Use a separate environment only when testing a specific supported Python\n version or reproducing an environment-specific issue.\n- When validating contributor setup, shell initialization, or hook behavior, verify it from the same environment a developer would actually use, such as a normal shell session or `sl commit`, not only from a temporary sandbox-only environment.\n- Prefer hooks that do not depend on nontrivial user-environment tooling.\n- If an environment override is required for one command, explain why it must be part of that same process invocation.\n- If a small system tool would materially simplify the workflow, it is fine to suggest it or ask the user to install it.\n\n## Source control and PRs\n\nUse the VCS tooling that matches the current checkout. Some Hydra worktrees are\nSapling (`sl`) checkouts, while others may be plain Git clones.\n\n- Prefer the checkout's native tool for local operations such as status, log, diff, commit, amend, and stack inspection.\n- In a Sapling checkout, use `sl` for normal local VCS operations.\n- Keep escalated VCS commands minimal and single-purpose.\n- Do not bundle staging, environment bootstrapping, dependency installation, and commit creation into one escalated shell command unless there is no practical alternative.\n- If a VCS operation requires escalation, ask only for the specific action that needs it.\n- Do not force-push, submit, or otherwise update a remote branch unless the user explicitly asks for that outward action.\n- Before using low-level fallback commands, such as `git --git-dir .sl/store/git` in a Sapling checkout, stop and explain why the normal workflow is not sufficient.\n\n## Release and news fragments\n\n- Do not commit, push, merge, publish, or otherwise send changes outside the local working tree unless the user explicitly asks for that outward action.\n- If a change alters release automation, workflow triggers, deployment behavior, or other externally visible project mechanics, require an explicit user review checkpoint before any commit, push, merge, publish, or deployment action.\n- All non-trivial product-user-visible changes should have a news fragment.\n- Core Hydra fragments go under `news/`; plugin-specific fragments go under the relevant plugin's `news/` directory.\n- Fragment filenames follow the pattern `.`.\n- Supported categories are `api_change`, `feature`, `bugfix`, `docs`, `config`, and `maintenance`.\n- Fragment text must be concise, user-facing, sentence case, and preferably under 80 characters.\n- Developer-only tooling, repo maintenance, and CI-only changes do not need a fragment unless they change the shipped product experience.\n- The user handles releases. Do not edit version numbers, create release files, assemble release notes, or otherwise perform release-cut steps unless explicitly asked.\n- The documented release process lives in [`website/docs/development/release.md`](./website/docs/development/release.md). Do not improvise a manual release flow.\n\n## Reviews\n\n- When asked to review a commit, pull request, or diff, cover correctness, completeness, documentation, and internal consistency.\n- Verify that each product-user-visible change includes an appropriate news fragment and that the fragment matches the implementation and docs.\n","examples/plugins/example_configsource_plugin/README.md":"# Hydra example config source\nUse this as the template a Hydra config source plugin\n\nConfig source plugins are allowing Hydra to recognize other search path schemas in addition to the built in \n`file://` (which provides access to configs in the file system) and \n`pkg://` (which provides access to configs installed with a Python package) \n\nThis config source hard codes all the responses so it's not very useful.\nPlease base your tests on the data in hydra_root/tests/test_apps/config_source_test/dir.\n\nAll config sources need to pass the ConfigSourceTestSuite tests, which are expecting those specific responses.\nWhen implementing a new config source, be sure to run it through the test suite to ensure it always behaves the same\nas the other config sources.\n","examples/plugins/example_generic_plugin/README.md":"# Hydra example plugin\nthis plugin is not very useful, but demonstrates the plugin discovery capability of Hydra.\n\nCore plugins (Plugins that are developed jointly with Hydra) lives in the plugins subdirectory inside the Hydra repo.\nThird party plugins can live anywhere (public or private Github repos, Organizations in-house SCM etc)","examples/plugins/example_launcher_plugin/README.md":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Launcher for Hydra.\nThe configuration for this launcher is in packages with the plugin:\n\n```yaml title=\"hydra_plugins/example_launcher_plugiun/conf/hydra/launcher/example.yaml\"\n_target_: hydra_plugins.example_launcher_plugin.example_launcher.ExampleLauncher\nfoo: 10\nbar: abcde\n```\nThe example application is overriding the Launcher used by Hydra.\nWhen the launcher is initialized, its \"using\" the foo and bar parameters.\n\nOutput of the example application:\n```text\n$ python example/my_app.py --multirun db=postgresql,mysql\n[2019-10-22 19:45:05,060] - Example Launcher(foo=10, bar=abcde) is launching 2 jobs locally\n[2019-10-22 19:45:05,060] - Sweep output dir : multirun/2019-10-22/19-45-05\n[2019-10-22 19:45:05,060] - #0 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n\n[2019-10-22 19:45:05,135] - #1 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n```\n","examples/plugins/example_registered_plugin/README.md":"# Hydra example plugin via `Plugins.register`\nThis plugin is not very useful, but it demonstrates how to register a plugin using the `Plugins.register` method.","examples/plugins/example_searchpath_plugin/README.md":"# Hydra example SearchPath plugin\n\nThis plugin provides an example for how to write a SearchPathPlugin that can manipulate the search path.\nTypical use cases includes:\n * A framework that wants to allow user code to discover its configurations and be able to compose with them.\n * A plugin that wants to extend Hydra or another plugin by providing additional configs in existing config groups like `hydra/launcher`.\n * A plugin that can replace the default configuration of another plugin or of Hydra itself by prepending its configurations before those that it want to replace.\n \nSearchPath plugins are discovered and enabled automatically once they are installed.\nYou can use `python foo.py --info` to see the search path and the installed plugins.\n","examples/plugins/example_sweeper_plugin/README.md":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Sweeper for Hydra.\nThe provided example has a custom configuration for the sweeper that takes overrides a few parameters:\n```yaml\n_target_: hydra_plugins.example_sweeper_plugin.example_sweeper.ExampleSweeper\n# max number of jobs to run in the same batch.\nmax_batch_size: null\nfoo: 10\nbar: abcde\n```\n\n#### Example app using custom sweeper:\n```text\n$ python example/my_app.py -m db=mysql,postgresql\n[2019-11-14 11:42:47,941][HYDRA] ExampleSweeper (foo=10, bar=abcde) sweeping\n[2019-11-14 11:42:47,941][HYDRA] Sweep output dir : multirun/2019-11-14/11-42-47\n[2019-11-14 11:42:47,942][HYDRA] Launching 2 jobs locally\n[2019-11-14 11:42:47,942][HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[2019-11-14 11:42:48,011][HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n```\n","plugins/hydra_ax_sweeper/README.md":"# Hydra Ax Sweeper\nProvides a [`Ax Sweeper`](https://ax.dev/) based Hydra Sweeper supporting parallel execution.\n\nHydra 1.4 will include the final first-party release, based on the existing\nimplementation. The plugin code will be removed in the Hydra 1.5 line, and no\nfirst-party releases will be published for Hydra 1.5 or later. Existing PyPI\nreleases will remain available. See the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506)\nfor the schedule and invitation for community ownership in a separate repository.\n\nSee [website](https://hydra.cc/docs/plugins/ax_sweeper/) for more information\n","plugins/hydra_colorlog/README.md":"# Hydra colorlog\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\nSee [website](https://hydra.cc/docs/plugins/colorlog) for more information\n","plugins/hydra_joblib_launcher/README.md":"# Hydra Joblib Launcher\nProvides a [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html) based Hydra Launcher supporting parallel execution.\n\nSee [website](https://hydra.cc/docs/plugins/joblib_launcher) for more information\n","plugins/hydra_nevergrad_sweeper/README.md":"# Hydra Nevergrad Sweeper plugin\n\nProvides a mechanism for Hydra applications to use [Nevergrad](https://github.com/facebookresearch/nevergrad) algorithms for the optimization of the parameters of any experiment.\n\nSee [website](https://hydra.cc/docs/plugins/nevergrad_sweeper) for more information","plugins/hydra_optuna_sweeper/README.md":"# Hydra Optuna Sweeper\n\nProvides an [Optuna](https://optuna.org) based Hydra Sweeper.\n\nSee [website](https://hydra.cc/docs/plugins/optuna_sweeper/) for more information.\n","plugins/hydra_ray_launcher/README.md":"# Hydra Ray Launcher\nProvides a [`Ray`](https://docs.ray.io/en/latest/) based Hydra Launcher supporting execution on AWS.\n\nSee [website](https://hydra.cc/docs/plugins/ray_launcher) for more information\n","plugins/hydra_ray_launcher/integration_test_tools/README.md":"## Setting up a new testing AMI for ray launcher.\n\nTo run the tool:\n\n- Make sure the dependencies in `setup_integration_test_ami.py` matches exactly ray launcher's `setup.py`.\n- Install AWS CLI, check AWS documentation for more details.\n- Before running the tool, set up your aws profile with admin access to the Hydra test AWS account.\n```\nAWS_PROFILE=jieru python create_integration_test_ami.py\n```\nYou will see a new AMI created in the output\n```commandline\nec2.Image(id='ami-0d65d5647e065a180') current state pending\n...\n```\nSometimes it could take hours for a new AMI to be created. Proceed to the next step once the \nAMI becomes available.\n\n- Run the tests locally with the new AMI:\n ```shell\n AWS_RAY_AMI= pytest ../tests/ray_aws_launcher_tests_disabled.py\n ```\n- Debug if needed.\n- Create a PR and make sure all CI pass!\n","plugins/hydra_rq_launcher/README.md":"# Hydra RQ Launcher\nProvides a [Redis Queue (RQ)](https://python-rq.org) launcher for Hydra supporting distributed execution and job queuing.\n\nSee [website](https://hydra.cc/docs/plugins/rq_launcher) for more information\n","plugins/hydra_submitit_launcher/README.md":"# Hydra Submitit Launcher\nProvides a [`Submitit`](https://github.com/facebookincubator/submitit) based Hydra Launcher supporting [SLURM ](https://slurm.schedmd.com/documentation.html).\n\nSee [website](https://hydra.cc/docs/plugins/submitit_launcher) for more information","tools/README.md":"Standalone Hydra related tools","tools/configen/README.md":"# configen\n\nAutomatically generates Structured Configs that can be used with hydra.utils.instantiate()\n\nThis is optional at two levels:\n1. Structured Configs are optional, one can use Hydra without them.\n2. One can manually code these dataclasses. The advantage of this tool is that it does the work automatically.\n\n# Setup\nConfigen requires config file per project. The config indicates what classes to generate code for, where to put\nthe generated code etc.\nConfigen will suggest creating a config on the first run:\n```\n$ configen\n[2020-08-14 12:06:11,359][configen.configen][ERROR] -\nUse --config-dir DIR --config-name NAME\ne.g:\n\tconfigen --config-dir conf --config-name configen\n\nIf you have no config dir yet use init_config_dir=DIR to create an initial config dir.\ne.g:\n\tconfigen init_config_dir=conf\n```\n\nThis will generate a basic config similar to:\n```yaml\n$ cat conf/configen.yaml\ndefaults:\n - configen_schema\n - _self_\n\nconfigen:\n # output directory\n output_dir: ${hydra:runtime.cwd}/example\n\n header: |\n # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n # Generated by configen, do not edit.\n # See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n # fmt: off\n # isort:skip_file\n # flake8: noqa\n\n module_path_pattern: 'config/{{module_path}}.py'\n\n # list of modules to generate configs for\n modules:\n - name: configen.samples.my_module\n # for each module, a list of classes\n classes:\n - User\n - Admin\n```\n\nConfigen comes with a few samples [classes](configen/samples) that are being processed by the default config.\nFor example:\n```python title=\"configen/samples/my_module.py\"\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n\n\nclass User:\n def __init__(self, age: int, name: str):\n self.age = age\n self.name = name\n\n def __repr__(self):\n return f\"User: name={self.name}, age={self.age}\"\n\n\nclass Admin(User):\n def __init__(self, private_key: str, age: int, name: str) -> None:\n super().__init__(age, name)\n self.private_key = private_key\n\n def __repr__(self):\n return (\n f\"Admin: name={self.name}, age={self.age}, private_key={self.private_key}\"\n )\n```\n\nRunning configen with this config directory:\n```\n$ configen --config-dir conf --config-name configen\n[2020-08-14 12:44:54,990][configen.configen][INFO] - configen.samples.my_module.configen.samples.my_module -> /home/omry/tmp/configen/example/config/configen/samples/my_module.py\n```\n\nWill result in a file `example/config/configen/samples/my_module.py` like:\n```python\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n# Generated by configen, do not edit.\n# See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n# fmt: off\n# isort:skip_file\n# flake8: noqa\n\nfrom dataclasses import dataclass, field\nfrom omegaconf import MISSING\n\n\n@dataclass\nclass UserConf:\n _target_: str = \"configen.samples.my_module.User\"\n age: int = MISSING\n name: str = MISSING\n\n\n@dataclass\nclass AdminConf:\n _target_: str = \"configen.samples.my_module.Admin\"\n private_key: str = MISSING\n age: int = MISSING\n name: str = MISSING\n```\n\nThe generated code can be used by a Hydra application to instantiate the user object.\nSee the [example application](example/my_app.py).\n","tools/landscape/README.md":"# Hydra Landscape tools\n\nThese tools support discovery, analysis, review, and publication of projects in\nthe [Hydra Landscape](../../website/docs/landscape.mdx). They do not approve\nprojects automatically. Inclusion and featured status are maintainer decisions.\n\nThe tracked files under this directory are reusable tooling and durable human\ndecisions. Large crawls, AI output, refreshed GitHub metadata, and generated\nreview queues remain under `temp/hydra-dependents/`.\n\nInstall the Python 3.10 compatibility dependency when needed:\n\n```bash\n.venv/bin/pip install -r tools/landscape/requirements.txt\n```\n\n`data/decisions.json` is the canonical source for both curation decisions and\nthe public listing of every included project. Do not edit\n`website/src/data/landscape.json` directly; website commands regenerate it from\nthe decision ledger.\n\n## Pipeline\n\n1. Collect mechanical Hydra usage evidence from the dependency crawl:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_usage.py\n ```\n\n2. Route projects for review, optionally using the locally authenticated Codex\n CLI to analyze a resumable batch:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_projects.py\n .venv/bin/python tools/landscape/analyze_hydra_projects.py --ai\n ```\n\n Analyze explicit repositories with repeated `--repo owner/name` arguments.\n The default AI model is `gpt-5.6-terra` with medium reasoning effort.\n\n3. Refresh current GitHub maintenance metadata:\n\n ```bash\n .venv/bin/python tools/landscape/refresh_landscape_metadata.py\n ```\n\n4. Build the evidence-backed human review queue:\n\n ```bash\n .venv/bin/python tools/landscape/build_landscape_review.py\n ```\n\n5. Record maintainer decisions in `data/decisions.json`. Every included\n decision must contain its complete public `listing`. Regenerate the public\n data directly when needed:\n\n ```bash\n .venv/bin/python tools/landscape/build_public_landscape.py\n ```\n\nThe public generator reads no crawl, AI, review, or live GitHub data. It writes\n`website/src/data/landscape.json` deterministically from the decision ledger.\nThe website's `start`, `build`, and `deploy` commands run it automatically.\n\n## Tests\n\nRun the focused suite with:\n\n```bash\nPYTHONPATH=tools/landscape .venv/bin/pytest tools/landscape\n```\n","tools/release/README.md":"## Release tool\n\nThis tool keeps Hydra release operations package-aware. It knows about\n`hydra-core`, the bundled plugins, and `hydra-configen`, and can check versions,\nset versions, and build distributions.\n\nPublishing is intentionally handled by GitHub Actions Trusted Publishing, not by\nthis local tool. The publish workflows call this tool to build artifacts, then\nupload them from GitHub Actions.\n\n### Package sets\n\n- `set=hydra-core`: `hydra-core` only.\n- `set=hydra-plugins`: all bundled Hydra plugins.\n- `set=hydra-full-release`: `hydra-core` plus all bundled Hydra plugins.\n- `set=configen`: `hydra-configen` only.\n- `set=all`: `hydra-core`, `hydra-configen`, and all bundled Hydra plugins.\n\nUse `only=[,...]` to narrow a package\nset without creating a new named set. Package config names are the keys under\n`tools/release/conf/packages/`, for example:\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n repository=pypi\n```\n\nQuote comma-separated filters so the quotes reach Hydra when passing more than\none package through a shell, for example\n`only=\\\"hydra_optuna_sweeper,hydra_ray_launcher\\\"`.\n\n### Check published versions\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-full-release \\\n repository=pypi\n```\n\nThis reports whether each local version already exists on the selected\nrepository, with the latest non-yanked wheel shown as context.\n\n### Set an explicit version\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev2\n```\n\nUse this for coordinated dev releases where `hydra-core` and the bundled plugins\nshould share the same version.\n\n### Validate prepared versions\n\n```shell\npython tools/release/release.py \\\n action=validate_versions \\\n set=hydra-full-release \\\n version=1.4.0\n```\n\nThis fails if any selected package is not already at the expected version. The\npublish workflow uses this to verify prepared release state before building and\nuploading artifacts.\n\n### Bump published packages\n\n```shell\npython tools/release/release.py action=bump set=hydra-full-release\n```\n\nThis increments only packages whose local version exactly matches the latest\npublished version on PyPI. It is useful for continuing an existing release\nseries, but less useful when aligning multiple packages to a specific version.\n\n### Build artifacts\n\nBuild only packages whose local version has not already been published to PyPI:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n repository=pypi \\\n clean_build_dir=true \\\n require_artifacts=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nBuild every package in a set, ignoring repository state:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n build_policy=all \\\n clean_build_dir=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nThe GitHub publish workflows use the repository-aware form so already-published\nfiles are not uploaded again.\n\nBoth build and dev-release validation reject source distributions containing a\nJAR without `ATTRIBUTION/LICENSE-antlr4`, and wheels containing any JAR. These\nchecks run before the publish workflow uploads distribution artifacts.\n\nThe workflows also write a release summary listing the target repository,\npublish mode, trigger, ref, commit, and every artifact that was built.\n\n### Dev release\n\nRun a dry run for a coordinated dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3\n```\n\nRun a dry run for a single plugin dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n version=1.4.0.dev3\n```\n\nThe dry run prints the selected packages, current local versions, target\nversions, PyPI status for the target version, and the exact publish workflow\ndispatch that would run. It also builds artifacts in a temporary release\nworkspace, runs `twine check`, and smoke-installs the built wheels without\ndependencies. It does not commit, push, dispatch GitHub Actions, create or edit\na GitHub Release, or upload anything to PyPI.\n\nTo publish the dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n publish=true\n```\n\nPublishing first confirms that the selected commit exists on the configured\nGitHub remote, without requiring it to be the branch tip. It also requires a\nclean working tree. In the normal release flow, the selected packages already\nhave the target version because it was set immediately after the previous\nrelease. The command dispatches `Publish to PyPI` with the selected package set,\nexpected version, and exact commit. If the versions differ, it can set, commit,\nand push the target version as a recovery path, then pins the resulting current\ncommit so later pushes cannot change what the workflow builds.\n\nIf the branch has already advanced past an unshipped dev release, select its\nexisting commit explicitly. The dry run archives that exact commit, requires\nthe selected package versions to already match, and builds its artifacts without\nchanging the current checkout:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n commit=\n```\n\nAfter the dry run passes, repeat the command with `publish=true`. Explicit\ncommit mode never sets versions, commits, or pushes; the commit must already\nexist locally and on GitHub. The tool uses `workflow_ref=main` by default; use\n`workflow_ref=` for unusual release lines.\n\nAfter the publish workflow succeeds, immediately set the next coordinated\ndevelopment version, commit, and push it before resuming development:\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev4\n```\n\nThis prevents new development from reporting a version that has already been\npublished.\n\n### Prepare and publish workflow responsibilities\n\nHydra release automation is split into prepare and publish phases.\n\nPrepare release should:\n\n- accept a release line, selected package set, and target version changes;\n- derive the release kind from the selected target versions;\n- derive the target branch from the release line and release kind;\n- validate package versions against the release line and selected package set;\n- compare selected packages against PyPI;\n- produce a release-validation matrix;\n- run release-only checks such as the core suite with all selected compatible\n plugins installed;\n- create or update release-prep PRs when needed.\n\nFor release candidates, stable releases, and patch releases, generated\nrelease-prep PRs are the maintainer approval surface for publishing. The PR body\nmust state clearly what happens when the PR is merged. Once release-prep PR\nautomation exists, merging such a PR should trigger PyPI publishing, and the PR\nbody must list the exact package set and version that will be published.\n\nPublish should:\n\n- revalidate the prepared release state;\n- build selected package artifacts;\n- check built artifacts;\n- publish only selected package artifacts through GitHub Actions Trusted\n Publishing;\n- eventually create or update the GitHub Release as a record of the published\n release.\n\nThe local release tool owns package metadata, version checks, repository\ncomparison, and artifact building. GitHub Actions owns release validation and\nTrusted Publishing. GitHub Release state transitions are intended release\nautomation work, but are not wired into the current publish workflow.\n\nThe current `Prepare Release` workflow implements the validation part of this\nsplit: it derives release kind and target branch, applies the target version\ninside the disposable workflow checkout, checks selected packages against PyPI,\nbuilds artifacts, and runs release validation. The current `Publish to PyPI`\nworkflow is manual-only. GitHub Release creation or edits do not trigger\npublishing. Release-prep PR automation is planned but not implemented yet.\n","website/docs/advanced/plugins/develop.md":"---\nid: develop\ntitle: Plugin development\nsidebar_label: Plugin development\n---\n\n:::info\nIf you develop plugins, please join the Plugin developer announcement chat channel.\n:::\n\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra plugins must be registered before they can be used. Declare an entry\npoint in the `hydra.plugins` group for each plugin class, or call the\n`register` method on Hydra's `Plugins` singleton. Hydra 1.4 also discovers\nplugins in the `hydra_plugins` namespace for compatibility, but this method is\ndeprecated. See the [plugin discovery migration guide](/docs/upgrades/1.3_to_1.4/plugin_discovery).\n\n## Entry point discovery\n\nFor example, in `setup.py`:\n\n```python\nsetup(\n # ...\n entry_points={\n \"hydra.plugins\": [\n \"my_launcher = my_package.my_launcher:MyLauncher\",\n ]\n },\n)\n```\n\nThe target must be a concrete Hydra plugin class. Its module should also\nregister any associated Hydra configuration when imported. Plugin classes no\nlonger need to live in the `hydra_plugins` namespace. Keep expensive optional\ndependencies out of module-level imports.\n\n## Legacy namespace discovery\n\nIf you create a Plugin and want it to be discovered automatically by Hydra, keep the following things in mind:\n- Namespace-discovered plugins can be either standalone packages or part of an\n existing package. They must be in the top-level `hydra_plugins` namespace.\n- Do __NOT__ place an `__init__.py` file in `hydra_plugins` (doing so may break other installed Hydra plugins).\n \nThe plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of `hydra_plugins`. Hydra will import each module and look for plugins defined in that module.\nAny module under `hydra_plugins` that is slow to import will slow down the startup of __ALL__ Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with `_` (but not `__`).\nFor example, the file `_my_plugin_lib.py` would not be imported and scanned, while `my_plugin_lib.py` would be.\n\n## Plugin registration via the `Plugins.register` method\n\nPlugins can be manually registered by calling the `register` method on the instance of Hydra's `Plugins` singleton class.\n```python\nfrom hydra.core.plugins import Plugins\nfrom hydra.plugins.plugin import Plugin\n\nclass MyPlugin(Plugin):\n ...\n\ndef register_my_plugin() -> None:\n \"\"\"Hydra users should call this function before invoking @hydra.main\"\"\"\n Plugins.instance().register(MyPlugin)\n```\n\n## Getting started\n\nThe best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:\n- Copy the subtree of the relevant example plugin into a standalone project.\n- Edit `setup.py`, rename the plugin module, and declare its entry point.\n- Install the new plugin (Run this in the plugin directory: `pip install -e .`)\n- Run the included example app and make sure that the plugin is discovered:\n```shell\n$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n```\n- Run the example application to see that that your plugin is doing something.\n- *[Optional]* Embed the plugin in your existing application or library. An\n entry-point plugin can use any importable package name.\n- Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.\n\nFor a `SearchPathPlugin` that provides organization-specific Hydra defaults,\nsee [Environment-specific overrides](../../patterns/environment_specific_overrides.md).\n","website/docs/advanced/plugins/intro.md":"---\nid: overview\ntitle: Plugins Overview\nsidebar_label: Plugins Overview\n---\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra can be extended via plugins.\nThe example plugins here can help you get started with plugin development.\n\n## Plugin types\nHydra has several plugin types:\n### Sweeper\nA sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:\n```\nbatch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n```\n\nAnd creates 4 jobs with the following parameters:\n```\nbatch_size=128 optimizer=nesterov learning_rate=0.01\nbatch_size=128 optimizer=nesterov learning_rate=0.1\nbatch_size=128 optimizer=adam learning_rate=0.01\nbatch_size=128 optimizer=adam learning_rate=0.1\n```\n\n### Launcher\nLaunchers are responsible for launching a job to a specific environment.\nA Launcher takes a batch of argument lists like the one above and launches a job for each one.\nThe job uses those arguments to compose its configuration.\nThe basic launcher simply launches the job locally. \n\n### SearchPathPlugin\nA config path plugin can manipulate the search path.\nThis can be used to influence the default Hydra configuration to be more appropriate to a specific environment,\nor just add new entries to the search path to make more configurations available to the Hydra app.\n\nSearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed.\n\nMany other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. \n\n### ConfigSource\nConfigSource plugins can be used to allow Hydra to access configuration in non-standard locations when composing the config.\nThis can be used to enable access to an in-house private config store, or as a way to access configs from public sources like GitHub or S3.\n","website/docs/plugins/ax_sweeper.md":"---\nid: ax_sweeper\ntitle: Ax Sweeper plugin\nsidebar_label: Ax Sweeper plugin\n---\n\nimport {ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ax-sweeper)](https://img.shields.io/pypi/v/hydra-ax-sweeper)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ax-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ax-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ax-sweeper/month)](https://pepy.tech/project/hydra-ax-sweeper)\n\n\nThis plugin provides a mechanism for Hydra applications to use the [Adaptive Experimentation Platform, aka Ax](https://ax.dev/). Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations.\n\n:::warning Retirement after Hydra 1.4\n\nHydra 1.4 will include the final first-party release of the Ax Sweeper, based on\nthe existing implementation. Further modernization is no longer planned. The\nplugin code will be removed in the Hydra 1.5 line, and no first-party Ax Sweeper\nreleases will be published for Hydra 1.5 or later. Existing PyPI releases will\nremain available.\n\nCommunity members interested in maintaining the plugin in a separate repository\nare invited to comment on the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506).\nHydra's documentation can link to that repository. Transferring control of the\n`hydra-ax-sweeper` PyPI package may be considered once new maintainers establish\na reliable track record and build trust.\n\n:::\n\n### Installation\n```commandline\npip install hydra-ax-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=ax` to your command line. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: ax\n```\n\nWe include an example of how to use this plugin. The file example/banana.py\nimplements the [Rosenbrock function (aka Banana function)](https://en.wikipedia.org/wiki/Rosenbrock_function).\nThe return value of the function should be the value that we want to optimize.\n\n\nTo compute the best parameters for the Banana function, clone the code and run the following command in the `plugins/hydra_ax_sweeper` directory:\n\n```\npython example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n```\n\nThe output of a run looks like:\n\n```\n[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5]\nbanana.y: range=[-5.0, 10.1]\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 trials, GPEI for subsequent trials]). Iterations after 5 will take longer to generate due to model-fitting.\n[HYDRA] AxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=2 banana.y=-0.988\n[__main__][INFO] - Banana_Function(x=2, y=-0.988)=2488.883\n[HYDRA] #1 : banana.x=-1 banana.y=7.701\n[__main__][INFO] - Banana_Function(x=-1, y=7.701)=4493.987\n[HYDRA] #2 : banana.x=-1 banana.y=-3.901\n[__main__][INFO] - Banana_Function(x=-1, y=-3.901)=2406.259\n[HYDRA] #3 : banana.x=-1 banana.y=0.209\n[__main__][INFO] - Banana_Function(x=-1, y=0.209)=66.639\n[HYDRA] #4 : banana.x=4 banana.y=-4.557\n[__main__][INFO] - Banana_Function(x=4, y=-4.557)=42270.006\n[HYDRA] New best value: 66.639, best parameters: {'banana.x': -1, 'banana.y': 0.209}\n```\n\nIn this example, we set the range of `x` parameter as an integer in the interval `[-5, 5]` and the range of `y` parameter as a float in the interval `[-5, 10.1]`. Note that in the case of `x`, we used `int(interval(...))` and hence only integers are sampled. In the case of `y`, we used `interval(...)` which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.` banana.x=5.0`), choice parameters (eg `banana.x=choice(1,2,3)`) and range (eg `banana.x=range(1, 10)`). Note that `interval`, `choice` etc. are functions provided by Hydra, and you can read more about them [here](/advanced/override_grammar/extended.md). An important thing to remember is, use [`interval`](/advanced/override_grammar/extended.md#interval-sweep) when we want Ax to sample values from an interval. [`RangeParameter`](https://ax.dev/api/ax.html#ax.RangeParameter) in Ax is equivalent to `interval` in Hydra. Remember to use `int(interval(...))` if you want to sample only integer points from the interval. [`range`](/advanced/override_grammar/extended.md#range-sweep) can be used as an alternate way of specifying choice parameters. For example `python example/banana.py -m banana.x=choice(1, 2, 3, 4)` is equivalent to `python example/banana.py -m banana.x=range(1, 5)`.\n\nThe values of the `x` and `y` parameters can also be set using the config file `plugins/hydra_ax_sweeper/example/conf/config.yaml`. For instance, the configuration corresponding to the commandline arguments is as follows:\n\n```\nbanana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n```\n\nTo sample in log space, you can tag the commandline override with `log`. E.g. `python example/banana.py -m banana.x=tag(log, interval(1, 1000))`. You can set `log_scale: true` in the input config to achieve the same.\n```\nbanana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n```\n\nIn general, the plugin supports setting all the Ax supported [Parameters](https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter) in the config. According to the [Ax documentation](https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment), the required elements in the config are:\n\n* `name` - Name of the parameter. It is of type string.\n* `type` - Type of the parameter. It can take the following values: `range`, `fixed`, or `choice`.\n* `bounds` - Required only for the `range` parameters. It should be a list of two values, with the lower bound first.\n* `values` - Required only for the `choice` parameters. It should be a list of values.\n* `value` - Required only for the `fixed` parameters. It should be a single value.\n\nNote that if you want to sample integers in the range `-5` to `5`, you need to specify the range as `int(interval(-5, 5))` (in the command line) or `[-5, 5]` (in config). If you want to sample floats in range `-5` to `5`, you need to specify the range as `interval(-5, 5)` (in the command line) or `[-5.0, 5.0]` (in config).\n\nThe Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the `is_noisy` parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero.\n\nIf measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the [standard error of the mean](https://en.wikipedia.org/wiki/Standard_error) of repeated measurements), the measurement function can return the tuple `(measurement_value, measurement_uncertainty)` instead of a scalar value.\n\nThe parameters for the optimization process can also be set in the config file. Specifying the Ax config is optional. You can discover the Ax Sweeper parameters with:\n\n```yaml title=\"$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_ax_sweeper.ax_sweeper.AxSweeper\nmax_batch_size: null\nax_config:\n max_trials: 10\n early_stop:\n minimize: true\n max_epochs_without_improvement: 10\n epsilon: 1.0e-05\n experiment:\n name: null\n objective_name: objective\n minimize: true\n parameter_constraints: null\n outcome_constraints: null\n status_quo: null\n client:\n verbose_logging: false\n random_seed: null\n is_noisy: true\n params: {}\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n","website/docs/plugins/colorlog.md":"---\nid: colorlog\ntitle: Colorlog plugin\nsidebar_label: Colorlog plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-colorlog)](https://pypi.org/project/hydra-colorlog/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-colorlog)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-colorlog)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-colorlog/month)](https://pepy.tech/project/hydra-colorlog)\n\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\n\n### Installation\n```commandline\npip install hydra_colorlog --upgrade\n```\n\n### Usage\nOverride `hydra/job_logging` and `hydra/hydra_logging` in your config:\n\n```yaml\ndefaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n```\n\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee included example application.\n \n![Colored log output](/plugins/colorlog/colorlog.png)\n","website/docs/plugins/joblib_launcher.md":"---\nid: joblib_launcher\ntitle: Joblib Launcher plugin\nsidebar_label: Joblib Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-joblib-launcher)](https://pypi.org/project/hydra-joblib-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-joblib-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-joblib-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-joblib-launcher/month)](https://pepy.tech/project/hydra-joblib-launcher)\n\nThe Joblib Launcher plugin provides a launcher for parallel tasks based on [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html).\n\n### Process backends\n\nThe launcher supports two process backends:\n\n| Backend | Advantages | Tradeoffs |\n| --- | --- | --- |\n| `loky` (default) | Robust process management and Cloudpickle support for dynamically defined Python objects. It remains the default for compatibility. | Workers are reused between Hydra jobs, so arbitrary application caches or process-global state can leak between jobs. Cloudpickling the task can also fail when it reaches some native-library objects. |\n| `multiprocessing` | Runs every Hydra job in a fresh worker process and sends module-level function tasks by reference instead of Cloudpickling them. This provides strict process isolation and avoids serializing module-level native-library objects referenced by the task. | Functions must be defined at module scope. Custom decorators around `@hydra.main` must use `functools.wraps`. |\n\nLoky runs jobs in the parent process when `n_jobs=1`. The multiprocessing\nbackend retains per-job worker isolation while executing one job at a time.\n\n### Installation\n```commandline\npip install hydra-joblib-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=joblib` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: joblib\n```\nBy default, the launcher uses process-based parallelism with all available CPU\ncores. Set `hydra.launcher.n_jobs` to limit the number of jobs that can run\nconcurrently.\n\nThe JobLibLauncherConf backing the config is defined here:\n\nYou can discover the Joblib Launcher parameters with:\n```yaml title=\"$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: -1\ninner_max_num_threads: null\nbackend: loky\nprefer: processes\nrequire: null\nverbose: 0\ntimeout: null\npre_dispatch: 2*n_jobs\nbatch_size: auto\ntemp_folder: null\nmax_nbytes: null\nmmap_mode: r\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee [`Joblib.Parallel` documentation](https://joblib.readthedocs.io/en/latest/parallel.html) for full details about the parameters above.\n\n`backend` selects the backend used by this launcher. Because a backend is\nalways selected explicitly, `prefer` does not change it. `require` must be\ncompatible with the selected backend; `require=sharedmem` is unsupported\nbecause this launcher does not support a thread-based backend.\n\n#### Controlling native library thread pools\n\nWhen using libraries that manage native thread pools, such as OpenBLAS, MKL, OpenMP, Numba, or NumExpr, set `inner_max_num_threads` to limit the number of native threads available to each Joblib worker process:\n\n```yaml\nhydra:\n launcher:\n n_jobs: 8\n inner_max_num_threads: 1\n```\n\nThis can help avoid oversubscription when multiple Hydra jobs run in parallel and each job calls into a multithreaded native library. For arbitrary environment variables, use [`hydra.job.env_set`](../configure_hydra/job.md#hydrajobenv_set) instead.\n\n
\nSelect the `multiprocessing` backend to execute every job in a fresh worker\nprocess:\n\n```yaml\nhydra:\n launcher:\n backend: multiprocessing\n n_jobs: 4\n```\n\nThe launcher automatically sets Joblib's `batch_size=1` so that each pool task\ncontains one Hydra job, and `maxtasksperchild=1` so that the worker exits after\nthat task. These are internal correctness settings, not user configuration.\nConflicting values are rejected.\n\n`inner_max_num_threads` is supported only by `loky`. Custom decorators around\n`@hydra.main` must follow the\n[Hydra task-decorator requirements](../advanced/decorating_main.md). Callable\ntask objects are copied to each worker, so all state stored on them must support\nPython pickling.\n

\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will launch five parallel executions:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=10,backend=loky,prefer=processes,require=None,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r) is launching 5 jobs\n[HYDRA] Launching jobs, sweep output dir : multirun/2020-02-18/10-00-00\n[__main__][INFO] - Process ID 14336 executing task 2 ...\n[__main__][INFO] - Process ID 14333 executing task 1 ...\n[__main__][INFO] - Process ID 14334 executing task 3 ...\n[__main__][INFO] - Process ID 14335 executing task 4 ...\n[__main__][INFO] - Process ID 14337 executing task 5 ...\n```\n","website/docs/plugins/nevergrad_sweeper.md":"---\nid: nevergrad_sweeper\ntitle: Nevergrad Sweeper plugin\nsidebar_label: Nevergrad Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-nevergrad-sweeper)](https://pypi.org/project/hydra-nevergrad-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-nevergrad-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-nevergrad-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-nevergrad-sweeper/month)](https://pepy.tech/project/hydra-nevergrad-sweeper)\n\n[Nevergrad](https://facebookresearch.github.io/nevergrad/) is a derivative-free optimization platform providing a library of state-of-the-art algorithms for hyperparameter search. This plugin provides Hydra applications a mechanism to use [Nevergrad](https://facebookresearch.github.io/nevergrad/) algorithms to optimize experiment/application parameters.\n\n### Installation\n```commandline\npip install hydra-nevergrad-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=nevergrad` to your command. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: nevergrad\n```\n\nThe default configuration is defined and documented here.\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Example of training using Nevergrad hyperparameter search\n\nWe include an example of how to use this plugin. The file example/my_app.py implements an example of minimizing a (dummy) function using a mixture of continuous and discrete parameters.\n\nYou can discover the Nevergrad sweeper parameters with:\n```yaml title=\"$ python your_app hydra/sweeper=nevergrad --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_nevergrad_sweeper.nevergrad_sweeper.NevergradSweeper\noptim:\n optimizer: NGOpt\n budget: 80\n num_workers: 10\n noisy: false\n maximize: false\n seed: null\n max_failure_rate: 0.0\nparams:\n db: choice(mnist, cifar)\n lr: {init: 0.02, step: 2.0, log: true}\n dropout: interval(0, 1)\n batch_size: int(interval(4, 16))\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\ndb: mnist\nlr: 0.12\ndropout: 0.33\nbatch_size: 4\n```\n\nTo run hyperparameter search and look for the best parameters for this function, clone the code and run the following command in the `plugins/hydra_nevergrad_sweeper` directory:\n```bash\npython example/my_app.py -m\n```\n\nYou can also override the search space parametrization:\n```bash\npython example/my_app.py --multirun db=mnist,cifar batch_size=4,8,16 \\\n'lr=tag(log, interval(0.001, 1))' 'dropout=interval(0,1)'\n```\n\nThe initialization of the sweep and the first 5 evaluations (out of 100) look like this:\n\n```text\n[2020-10-08 20:13:53,592][HYDRA] NevergradSweeper(optimizer=NGOpt, budget=100, num_workers=10) minimization\n[2020-10-08 20:13:53,593][HYDRA] with parametrization Dict(batch_size=Choice(choices=Tuple(4,8,16),weights=Array{(1,3)}),db=Choice(choices=Tuple(mnist,cifar),weights=Array{(1,2)}),dropout=Scalar{Cl(0,1,b)}[sigma=Log{exp=2.0}],lr=Log{exp=3.162277660168379,Cl(0.001,1,b)}):{'db': 'mnist', 'lr': 0.03162277660168379, 'dropout': 0.5, 'batch_size': 8}\n[2020-10-08 20:13:53,593][HYDRA] Sweep output dir: multirun/2020-10-08/20-13-53\n[2020-10-08 20:13:55,023][HYDRA] Launching 10 jobs locally\n[2020-10-08 20:13:55,023][HYDRA] #0 : db=mnist lr=0.03162277660168379 dropout=0.5 batch_size=16\n[2020-10-08 20:13:55,217][__main__][INFO] - dummy_training(dropout=0.500, lr=0.032, db=mnist, batch_size=16) = 13.258\n[2020-10-08 20:13:55,218][HYDRA] #1 : db=cifar lr=0.018178519762066934 dropout=0.5061074452336254 batch_size=4\n[2020-10-08 20:13:55,408][__main__][INFO] - dummy_training(dropout=0.506, lr=0.018, db=cifar, batch_size=4) = 0.278\n[2020-10-08 20:13:55,409][HYDRA] #2 : db=cifar lr=0.10056825918734161 dropout=0.6399687427725211 batch_size=4\n[2020-10-08 20:13:55,595][__main__][INFO] - dummy_training(dropout=0.640, lr=0.101, db=cifar, batch_size=4) = 0.329\n[2020-10-08 20:13:55,596][HYDRA] #3 : db=mnist lr=0.06617542958182834 dropout=0.5059497416026679 batch_size=8\n[2020-10-08 20:13:55,812][__main__][INFO] - dummy_training(dropout=0.506, lr=0.066, db=mnist, batch_size=8) = 5.230\n[2020-10-08 20:13:55,813][HYDRA] #4 : db=mnist lr=0.16717013388679514 dropout=0.6519070394318255 batch_size=4\n...\n[2020-10-08 20:14:27,988][HYDRA] Best parameters: db=cifar lr=0.11961221693764439 dropout=0.37285878409770895 batch_size=4\n```\n\n\nand the final 2 evaluations look like this:\n```text\n[HYDRA] \t#8 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] \t#9 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] Best parameters: db=mnist batch_size=4 lr=0.094 dropout=0.381\n```\n\n\nThe run also creates an `optimization_results.yaml` file in your sweep folder with the best evaluated parameters found during the sweep:\n```yaml\nbest_evaluated_result: 0.381\n\nbest_evaluated_params:\n batch_size: 4\n db: mnist\n dropout: 0.381\n lr: 0.094\n\nname: nevergrad\n```\n\n## Defining the parameters\n\nThe plugin supports two types of parameters: [Choices](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters) and [Scalars](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters). They can be defined either through a config file or command-line override.\n\n### Defining through command-line override\nHydra provides an override parser that supports rich syntax. More documentation can be found in ([Override Grammar/Basic](../advanced/override_grammar/basic.md)) and ([Override Grammar/Extended](../advanced/override_grammar/extended.md)). We recommend you go through them first before proceeding with this doc.\n\n#### Choices\nTo override a field with choices:\n```commandline\n'key=1,5'\n'key=shuffle(range(1, 8))'\n'key=range(1,5)'\n```\n\nYou can tag an override with `ordered` to indicate it's a [`TransitionChoice`](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters)\n```commandline\nkey=tag(ordered, choice(1,2,3))\n```\n\n#### Scalar\n```commandline\nkey=interval(1,12) # Intervals are floats by default\nkey=int(interval(1,8)) # Scalar bounds are cast to an int\nkey=tag(log, interval(1,12)) # call ng.p.Log if tagged with log\nkey={init: 0.02, step: 2.0, log: true} # Unbounded log-scale scalar\n```\n\n### Defining through config file\nThe search space can be defined under `hydra.sweeper.params`.\nThe definition is consistent with the equivalent command-line override.\n\n:::warning\n`hydra.sweeper.parametrization` is deprecated in Hydra 1.4 and will be removed\nin Hydra 1.5. Use `hydra.sweeper.params` instead.\n:::\n\n#### Choices\nChoices use the same syntax as command-line overrides. For example, translate\n`key=shuffle(range(1, 8))` to `key: shuffle(range(1, 8))` in the config file.\n\nFixed strings containing override grammar characters must retain quotes as part\nof the configured value. For example, use `label: \"'a,b'\"` to configure the\nliteral string `a,b`; `label: a,b` defines a choice sweep.\n\n#### Scalars\n`Scalar` definitions also support the override syntax shown above. The\nfollowing keys can be passed in a dictionary to define unbounded scalars:\n - `init`: optional initial value\n - `lower` : optional lower bound\n - `upper`: optional upper bound\n - `log`: set to `true` for log distributed values\n - `step`: optional step size for looking for better parameters. In linear mode, this is an additive step; in logarithmic mode it is multiplicative.\n - `integer`: set to `true` for integers (favor floats over integers whenever possible)\n\nProviding only `lower` and `upper` bound will set the initial value to the middle of the range and the step to a sixth of the range.\n","website/docs/plugins/optuna_sweeper.md":"---\nid: optuna_sweeper\ntitle: Optuna Sweeper plugin\nsidebar_label: Optuna Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-optuna-sweeper)](https://pypi.org/project/hydra-optuna-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-optuna-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-optuna-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-optuna-sweeper/month)](https://pepy.tech/project/hydra-optuna-sweeper)\n\n\nThis plugin enables Hydra applications to utilize [Optuna](https://optuna.org) for the optimization of the parameters of experiments.\n\n## Installation\n\nThis plugin requires Hydra Core 1.4 (`hydra-core>=1.4.0.dev1,<1.5.0.dev0`).\nPlease install it with the following command:\n\n```commandline\npip install --upgrade --pre \"hydra-core>=1.4.0.dev1,<1.5.0.dev0\"\n```\n\nYou can install the plugin via pip:\n\n```commandline\npip install --upgrade --pre \"hydra-optuna-sweeper>=1.4.0.dev1,<1.5.0.dev0\"\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Usage\n\nPlease set `hydra/sweeper` to `optuna` in your config file.\n\n```yaml\ndefaults:\n - override hydra/sweeper: optuna\n```\n\nAlternatively, add `hydra/sweeper=optuna` option to your command line.\n\nThe default configuration is here.\n\n## Example 1: Single-Objective Optimization\n\nWe include an example in this directory. `example/sphere.py` implements a simple benchmark function to be minimized.\n\n\n\n\nYou can discover the Optuna sweeper parameters with:\n\n```yaml title=\"python example/sphere.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\nsampler:\n _target_: optuna.samplers.TPESampler\n seed: 123\n n_startup_trials: 10\n n_ei_candidates: 24\n multivariate: false\n_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\ndirection: minimize\nstorage: null\nstudy_name: sphere\nn_trials: 20\nn_jobs: 1\nmax_failure_rate: 0.0\nparams:\n x: range(-5.5,5.5,step=0.5)\n y: choice(-5,0,5)\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\nx: 0\ny: 0\n```\n\nTo run optimization, clone the code and run the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/sphere.py --multirun\n```\n\nYou can also override the search space parametrization:\n\n```commandline\npython example/sphere.py --multirun 'x=interval(-5.0, 5.0)' 'y=interval(0, 10)'\n```\n\nYou might find the `optimization_results.yaml` file (i.e. best params and best value) under `multirun` logs folder:\n\n```yaml\nname: optuna\nbest_params:\n x: 0.0\n 'y': 0\nbest_value: 0.0\n```\n\n\n## Sampler configuration\nThis plugin supports Optuna's [samplers](https://optuna.readthedocs.io/en/stable/reference/samplers.html).\nYou can change the sampler by overriding `hydra/sweeper/sampler` or change sampler settings within `hydra.sweeper.sampler`.\n\n## Search space configuration\n\nThis plugin supports Optuna's [distributions](https://optuna.readthedocs.io/en/stable/reference/distributions.html) to configure search spaces. They can be defined either through commandline override or config file.\n\n### Configuring through commandline override\n\nHydra provides a override parser that support rich syntax. Please refer to [OverrideGrammer/Basic](../advanced/override_grammar/basic.md) and [OverrideGrammer/Extended](../advanced/override_grammar/extended.md) for details.\n\n#### Interval override\n\nBy default, `interval` is converted to [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html). You can use [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html) by casting the interval to `int`.\n\n
\n Example for interval override\n\n ```commandline\n python example/sphere.py --multirun 'x=int(interval(-5.0, 5.0))' 'y=tag(log, interval(1, 10))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=1.6859762540733367\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=5.237816870668193\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': 1.0929184723430116}\n [HYDRA] Best value: 1.1944707871885822\n ```\n\n
\n\n#### Range override\n\nInteger ranges are converted to [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html).\nFloat ranges, including sorted float ranges, use [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html).\nThe distribution includes exactly the discrete values in the range: its stop\nis exclusive, and descending ranges are supported. Empty ranges and zero steps\nare rejected. For example, `range(1,3)` permits only `1` and `2`, while\n`range(0,1,0.3)` permits `0.0`, `0.3`, `0.6`, and `0.9`.\n\nWhen converting a float range would make its Decimal endpoints or step\nunrepresentable as an Optuna numeric distribution, the sweeper uses a\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\nwith the generated values instead. This precision-boundary fallback preserves\nthe exact values and duplicates; representable ordinary uncast ranges remain\nnumeric and are converted without enumerating their values.\n\nApplying `shuffle`, `int`, or `float` to a range uses\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\ncontaining its generated values. Casts apply to each value, so\n`int(range(0,5,1.5))` permits `0`, `1`, `3`, and `4`. Duplicate cast values are\nretained. Sorting or shuffling does not change the permitted values. Optuna\ndoes not promise to evaluate trials in range order.\n\nGridSampler evaluates all values in each discrete distribution, including a\nsingleton or the distribution's inclusive upper endpoint.\n\nThese corrections changed range search spaces in Hydra 1.4; earlier unshuffled\nranges could admit an excluded stop. See the\n[migration guide](/docs/upgrades/1.3_to_1.4/breaking_changes#optuna-range-sweeps).\n\n
\n Example for range override\n\n ```commandline\n python example/sphere.py --multirun 'x=range(-5.0, 5.0)' 'y=shuffle(range(-5, 5))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=-4\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=-1\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': -1}\n [HYDRA] Best value: 1.0\n ```\n\n
\n\n#### Choice override\n\n`choice` is converted to [`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html).\n\n
\n Example for choice override\n\n ```commandline\n python example/sphere.py --multirun 'x=choice(-5.0, 0.0, 5.0)' 'y=choice(0, 1, 2, 3, 4, 5)'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=5.0 y=5\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=5.0 y=2\n ...\n [HYDRA] Best parameters: {'x': 0.0, 'y': 0}\n [HYDRA] Best value: 0.0\n ```\n\n
\n\n### Configuring through config file\n\nThe syntax in config file is consistent with the above commandline override. For example, a commandline override\n`x=range(1,4)` can be expressed in config file as `x: range(1,4)` under the `hydra.sweeper.params` node.\n\n## Example 2: Multi-Objective Optimization\n\nIn the same directory, `example/multi-objective.py` implements a simple benchmark function, which has two objective values. We want to minimize two objectives simultaneously.\n\nYou can discover the Optuna sweeper parameters with:\n\n```commandline\npython example/multi-objective.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\n```\n\n
\n Configuration of the multi-objective optimization example\n\n ```yaml\n # @package hydra.sweeper\n sampler:\n _target_: optuna.samplers.NSGAIISampler\n seed: 123\n population_size: 50\n mutation_prob: null\n crossover_prob: 0.9\n swapping_prob: 0.5\n constraints_func: null\n _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\n direction:\n - minimize\n - minimize\n storage: null\n study_name: multi-objective\n n_trials: 20\n n_jobs: 1\n params:\n x: range(0, 5, step=0.5)\n y: range(0, 3, step=0.5)\n ```\n
\n\n\nTo run the optimization, use the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/multi-objective.py --multirun\n```\n\nFor problems with trade-offs between two different objectives, there may be no single solution that simultaneously minimizes both objectives. Instead, we obtained a set of solutions, namely [Pareto optimal solutions](https://en.wikipedia.org/wiki/Pareto_efficiency), that show the best trade-offs possible between the objectives. In the following figure, the blue dots show the Pareto optimal solutions in the optimization results.\n\n![Pareto-optimal solutions](/plugins/optuna_sweeper/multi_objective_result.png)\n\n## EXPERIMENTAL: Custom-Search-Space Optimization\n\nHydra's Optuna Sweeper allows users to provide a hook for custom search space configuration.\nThis means you can work directly with the `optuna.trial.Trial` object to suggest parameters.\nTo use this feature, define a python function with signature `Callable[[DictConfig, optuna.trial.Trial], None]`\nand set the `hydra.sweeper.custom_search_space` key in your config to target that function.\n\nThe callback path is selected by configuration. When using an execution\nwhitelist, authorize that path from trusted Python code:\n\n```python\n@hydra.main(\n config_path=\"custom-search-space\",\n config_name=\"config\",\n execution_whitelist=\"custom-search-space-objective.configure\",\n)\ndef multi_dimensional_sphere(cfg: DictConfig) -> float:\n ...\n```\n\nYou can find a full example in the same directory as before, where `example/custom-search-space-objective.py` implements a benchmark function to be minimized.\nThe example shows the use of Optuna's [pythonic search spaces](https://optuna.readthedocs.io/en/stable/tutorial/10_key_features/002_configurations.html) in combination with Hydra.\nPart of the search space configuration is defined in config files, and part of it is written in Python.\n\n
\n Example: Custom search space configuration\n\n ```yaml\n defaults:\n - override hydra/sweeper: optuna\n\n hydra:\n sweeper:\n sampler:\n seed: 123\n direction: minimize\n study_name: custom-search-space\n storage: null\n n_trials: 20\n n_jobs: 1\n\n params:\n x: range(-5.5, 5.5, 0.5)\n y: choice(-5, 0, 5)\n # `custom_search_space` should be a dotpath pointing to a\n # callable that provides search-space configuration logic:\n custom_search_space: custom-search-space-objective.configure\n\n x: 1\n y: 1\n z: 100\n max_z_difference_from_x: 0.5\n ```\n ```python\n # example/custom-search-space-objective.py\n\n ...\n\n def configure(cfg: DictConfig, trial: Trial) -> None:\n x_value = trial.params[\"x\"]\n trial.suggest_float(\n \"z\",\n x_value - cfg.max_z_difference_from_x,\n x_value + cfg.max_z_difference_from_x,\n )\n trial.suggest_float(\"+w\", 0.0, 1.0) # note +w here, not w as w is a new parameter\n\n ...\n ```\n\n
\n\nThe method that `custom_search_space` points to must accepts both a DictConfig with already set options and a trial object which needs further configuration. In this example we limit `z` the difference between `x` and `z` to be no more than 0.5.\nNote that this `custom_search_space` API should be considered experimental and is subject to change.\n\n### Order of trial configuration\nConfiguring a trial object is done in the following sequence:\n - search space parameters are set from the `hydra.sweeper.params` key in the config\n - Command line overrides are set\n - `custom_search_space` parameters are set\n\nIt is not allowed to set search space parameters in the `custom_search_space` method for parameters which have a fixed value from command line overrides. [Trial.user_attrs](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.trial.Trial.html#optuna.trial.Trial.user_attrs) can be inspected to find any of such fixed parameters.\n","website/docs/plugins/ray_launcher.md":"---\nid: ray_launcher\ntitle: Ray Launcher plugin\nsidebar_label: Ray Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ray-launcher)](https://pypi.org/project/hydra-ray-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ray-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ray-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ray-launcher/month)](https://pepy.tech/project/hydra-ray-launcher)\n\nThe Ray Launcher plugin provides 2 launchers: `ray_aws` and `ray`.\n `ray_aws` launches jobs remotely on AWS and is built on top of [ray autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). `ray` launches jobs on your local machine or existing ray cluster.\n\n:::note Ray AWS support\nThe local `ray` launcher is supported as a normal Hydra plugin.\n\nThe `ray_aws` launcher is maintained on a best-effort basis. Historically, this path has required substantially more maintainer attention and infrastructure resources than other Hydra plugins. It depends on Ray autoscaler behavior and live AWS infrastructure, both of which are comparatively unstable external surfaces for Hydra to validate. Running reliable end-to-end coverage also has a real cloud-cost burden, which is difficult to justify within the project's limited maintenance budget.\n\nFixes for `ray_aws` are welcome from users who can validate them on AWS. PRs that change `ray_aws` behavior must include cheap local validation where possible and a clear report of real AWS testing for behavior that cannot be covered locally.\n\nIn the long term, if the `ray_aws` launcher becomes completely non-functional and there is no maintainer or user-contributor path to validate and repair it, support may be dropped entirely.\n:::\n\n### Installation\n\n```commandline\n$ pip install hydra-ray-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=ray_aws` or `hydra/launcher=ray` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: ray_aws\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe `ray_pkg_version` resolver now takes installed distribution names instead of\nPython import names and reads their metadata without importing the module.\nFor example, replace `${ray_pkg_version:yaml}` with `${ray_pkg_version:PyYAML}`.\n`${ray_pkg_version:hydra}` remains an alias for `hydra-core`.\nPackages must be installed, including editable installs.\nAn importable source directory alone is insufficient. If metadata is unavailable,\ninstall the package or set its version explicitly in `env_setup.pip_packages`.\n\n### `ray_aws` launcher\n\n:::important\n`ray_aws` launcher is built on top of ray's [autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). To get started, you need to\n[config your AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).\n`ray autoscaler sdk` expects your AWS credentials have certain permissions for [`EC2`](https://aws.amazon.com/ec2) and [`IAM`](https://aws.amazon.com/iam). Read [this](https://github.com/ray-project/ray/issues/9327) for more information.\n:::\n\n`ray autoscaler sdk` expects a configuration for the EC2 cluster; we've schematized the configs in here\n\n
\n Discover ray_aws launcher's config\n\n ```commandline\n $ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n # @package hydra.launcher\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\n env_setup:\n pip_packages:\n omegaconf: ${ray_pkg_version:omegaconf}\n hydra_core: ${ray_pkg_version:hydra}\n ray: ${ray_pkg_version:ray}\n cloudpickle: ${ray_pkg_version:cloudpickle}\n pickle5: 0.0.11\n hydra_ray_launcher: 1.2.0.dev1\n commands:\n - conda create -n hydra_${python_version:micro} python=${python_version:micro} -y\n - echo 'export PATH=\"$HOME/anaconda3/envs/hydra_${python_version:micro}/bin:$PATH\"'\n >> ~/.bashrc\n ray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n upscaling_speed: 1.0\n max_workers: 1\n idle_timeout_minutes: 5\n docker:\n image: ''\n container_name: ''\n pull_before_run: true\n run_options: []\n provider:\n type: aws\n region: us-west-2\n availability_zone: us-west-2a,us-west-2b\n cache_stopped_nodes: false\n key_pair:\n key_name: hydra-${oc.env:USER,user}\n auth:\n ssh_user: ubuntu\n available_node_types:\n ray.head.default:\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n ray.worker.default:\n min_workers: 0\n max_workers: 2\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n InstanceMarketOptions:\n MarketType: spot\n head_node_type: ray.head.default\n file_mounts: {}\n initialization_commands: []\n cluster_synced_files: []\n setup_commands: []\n head_setup_commands: []\n worker_setup_commands: []\n head_start_ray_commands:\n - ray stop\n - ulimit -n 65536;ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml\n worker_start_ray_commands:\n - ray stop\n - ulimit -n 65536; ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076\n run_env: auto\n stop_cluster: true\n sync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n sync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n logging:\n log_style: auto\n color_mode: auto\n verbosity: 0\n create_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\n teardown_cluster:\n workers_only: false\n keep_min_workers: false\n ```\n
\n\n\n#### Examples\n\nThe following examples can be found here.\n\n
\n Simple app\n\n ```commandline\n $ python my_app.py --multirun task=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : task=1\n [HYDRA] #1 : task=2\n [HYDRA] #2 : task=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmpqqg4v4i7/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=3374) [__main__][INFO] - Executing task 1\n (pid=3374) [__main__][INFO] - Executing task 2\n (pid=3374) [__main__][INFO] - Executing task 3\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n
\n Upload & Download from remote cluster\n\n If your application is dependent on multiple modules, you can configure `hydra.launcher.sync_up` to upload dependency modules to the remote cluster.\n You can also configure `hydra.launcher.sync_down` to download output from remote cluster if needed. This functionality is built on top of `rsync`, `include` and `exclude` is consistent with how it works in `rsync`.\n\n ```commandline\n $ python train.py --multirun random_seed=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : random_seed=1\n [HYDRA] #1 : random_seed=2\n [HYDRA] #2 : random_seed=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmptdkye9of/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n Loaded cached provider configuration\n ...\n [HYDRA] Output: receiving file list ... done\n 16-32-25/\n 16-32-25/0/\n 16-32-25/0/checkpoint/\n 16-32-25/0/checkpoint/checkpoint_1.pt\n 16-32-25/1/\n 16-32-25/1/checkpoint/\n 16-32-25/1/checkpoint/checkpoint_2.pt\n 16-32-25/2/\n 16-32-25/2/checkpoint/\n 16-32-25/2/checkpoint/checkpoint_3.pt\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n##### Manage Cluster LifeCycle\nYou can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:\n\n- Default setting (no need to specify on commandline): delete cluster after job finishes remotely:\n ```commandline\n hydra.launcher.stop_cluster=true\n hydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\n hydra.launcher.teardown_cluster.workers_only=false\n hydra.launcher.teardown_cluster.keep_min_workers=false\n ```\n\n- Keep cluster running after jobs finishes remotely\n ```commandline\n hydra.launcher.stop_cluster=false\n ```\n\n- Power off EC2 instances and control node termination using `hydra.launcher.ray.cluster.provider.cache_stopped_nodes`\nand `hydra.launcher.teardown_cluster.workers_only`\n\n | cache_stopped_nodes | workers_only | behavior |\n |---------------------|--------------|----------|\n | false | false | All nodes are terminated |\n | false | true | Keeps head node running and terminates only worker node |\n | true | false | Keeps both head node and worker node and stops both of them |\n | true | true | Keeps both head node and worker node and stops only worker node |\n\n- Keep `hydra.launcher.ray.cluster.min_workers` worker nodes\nand delete the rest of the worker nodes\n ```commandline\n hydra.launcher.teardown_cluster.keep_min_workers=true\n ```\n\nAdditionally, you can configure how to create or update the cluster:\n\n- Default config: run setup commands, restart Ray and use\nthe config cache if available\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=false\n hydra.launcher.create_update_cluster.restart_only=false\n hydra.launcher.create_update_cluster.no_config_cache=false\n ```\n\n- Skip restarting Ray services when updating the cluster config\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=true\n ```\n\n- Skip running setup commands and only restart Ray (cannot be used with\n`hydra.launcher.create_update_cluster.no_restart`)\n ```commandline\n hydra.launcher.create_update_cluster.restart_only=true\n ```\n\n- Fully resolve all environment settings from the cloud provider again\n ```commandline\n hydra.launcher.create_update_cluster.no_config_cache=true\n ```\n\n\n##### Configure Ray Logging\nYou can manage Ray specific logging by configuring the flags provided by the plugin:\n\n- Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode\n ```commandline\n hydra.launcher.logging.log_style=\"auto\"\n hydra.launcher.logging.color_mode=\"auto\"\n hydra.launcher.logging.verbosity=0\n ```\n\n- Disable pretty-print\n ```commandline\n hydra.launcher.logging.log_style=\"record\"\n ```\n\n- Disable color mode\n ```commandline\n hydra.launcher.logging.color_mode=\"false\"\n ```\n\n- Increase Ray logging verbosity\n ```commandline\n hydra.launcher.logging.verbosity=3\n ```\n\n### `ray` launcher\n\n`ray` launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing `ray` launcher's configuration here\n `~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml`\n\n The example application starts a new ray cluster.\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-16-28\n[HYDRA] Initializing ray with config: {}\nINFO services.py:1164 -- View the Ray dashboard at http://127.0.0.1:8266\n[HYDRA] #0 :\n(pid=97801) [__main__][INFO] - Executing task 1\n```\n\nYou can run the example application on your existing ray cluster as well by overriding `hydra.launcher.ray.init.address`:\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray hydra.launcher.ray.init.address=localhost:6379\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-13-32\n[HYDRA] Initializing ray with config: {'num_cpus': None, 'num_gpus': None, 'address': 'localhost:6379'}\nINFO worker.py:633 -- Connecting to existing Ray cluster at address: 10.30.99.17:6379\n[HYDRA] #0 :\n(pid=93358) [__main__][INFO] - Executing task 1\n```\n\n### Configure `ray.init()` and `ray.remote()`\nRay launcher is built on top of [`ray.init()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init)\nand [`ray.remote()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote).\nYou can configure `ray` by overriding `hydra.launcher.ray.init` and `hydra.launcher.ray.remote`.\nCheck out an example config.\n","website/docs/plugins/rq_launcher.md":"---\nid: rq_launcher\ntitle: RQ Launcher plugin\nsidebar_label: RQ Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-rq-launcher)](https://pypi.org/project/hydra-rq-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-rq-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-rq-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-rq-launcher/month)](https://pepy.tech/project/hydra-rq-launcher)\n\nThe RQ Launcher plugin provides a launcher for distributed execution and job queuing based on [Redis Queue (RQ)](https://python-rq.org).\n\nRQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a [Redis server](https://redis.io/topics/quickstart). When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database.\n\n\n### Installation\n```commandline\npip install hydra-rq-launcher --upgrade\n```\nUsage of this plugin requires a [Redis server](https://redis.io/topics/quickstart).\n\nNote that RQ does [not support Windows](https://python-rq.org/docs/#limitations).\n\n### Usage\nOnce installed, add `hydra/launcher=rq` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: rq\n```\n\nThe default configuration is as follows:\n\n```yaml title=\"$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_rq_launcher.rq_launcher.RQLauncher\nenqueue:\n job_timeout: null\n ttl: null\n result_ttl: null\n failure_ttl: null\n at_front: false\n job_id: null\n description: null\nqueue: default \nredis:\n host: ${oc.env:REDIS_HOST,localhost}\n port: ${oc.env:REDIS_PORT,6379}\n db: ${oc.env:REDIS_DB,0}\n password: ${oc.env:REDIS_PASSWORD,null}\n ssl: ${oc.env:REDIS_SSL,False}\n ssl_ca_certs: ${oc.env:REDIS_SSL_CA_CERTS,null\n mock: ${oc.env:REDIS_MOCK,False}\nstop_after_enqueue: false\nwait_polling: 1.0\n```\n\nFurther descriptions on the variables can be found in the plugin config file, defined here. There are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe plugin is using environment variables to store Redis connection information. The environment variables `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, and `REDIS_PASSWORD`, are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through `REDIS_SSL` and `REDIS_SSL_CA_CERTS`; see [redis-py](https://github.com/andymccurdy/redis-py#ssl-connections) documentation.\n\nFor example, they might be set as follows when using `bash` or `zsh` as a shell:\n\n```commandline\nexport REDIS_HOST=\"localhost\"\nexport REDIS_PORT=\"6379\"\nexport REDIS_DB=\"0\"\nexport REDIS_PASSWORD=\"\"\n```\n\nEnable SSL by setting the relevant environment variables. e.g:\n```commandline\nexport REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n```\n\nAssuming configured environment variables, workers connecting to the Redis server can be launched using:\n\n```commandline\nrq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB \\\n -S hydra_plugins.hydra_rq_launcher.serializer.CloudpickleSerializer\n```\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will enqueue five jobs to be processed by worker instances:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n\n[HYDRA] RQ Launcher is enqueuing 5 job(s) in queue : default\n[HYDRA] Sweep output dir : multirun/2020-06-15/18-00-00\n[HYDRA] Enqueued 13b3da4e-03f7-4d16-9ca8-cfb3c48afeae\n[HYDRA] \t#1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] \t#2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] \t#3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] \t#4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] \t#5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n```\n\nNote that any dependencies need to be installed in the Python environment used to run the RQ worker. Workers must use Hydra's cloudpickle serializer so that job results are serialized compatibly with the RQ launcher.\n\nThe [RQ documentation](https://python-rq.org/) holds further information on [job monitoring](http://python-rq.org/docs/monitoring/), which can be done via console or [web interfaces](https://github.com/nvie/rq-dashboard), and provides [patterns](https://python-rq.org/patterns/) for worker and exception handling.\n","website/docs/plugins/submitit_launcher.md":"---\nid: submitit_launcher\ntitle: Submitit Launcher plugin\nsidebar_label: Submitit Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-submitit-launcher)](https://pypi.org/project/hydra-submitit-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-submitit-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-submitit-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-submitit-launcher/month)](https://pepy.tech/project/hydra-submitit-launcher)\n\nThe Submitit Launcher plugin provides a [SLURM](https://slurm.schedmd.com/documentation.html) Launcher based on [Submitit](https://github.com/facebookincubator/submitit).\n\n### Installation\n```commandline\npip install hydra-submitit-launcher --upgrade\n```\n\n\n### Usage\nOnce installed, add `hydra/launcher=submitit_slurm` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: submitit_slurm\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\nNote that this plugin expects a valid environment in the target host. Usually this means a shared file system between\nthe launching host and the target host.\n\nThe Submitit Plugin implements 2 different launchers: `submitit_slurm` to run on a SLURM cluster, and `submitit_local` for basic local tests.\n\n
\n Discover the SLURM Launcher parameters (Expand)\n\n ```yaml title=\"$ python your_app.py hydra/launcher=submitit_slurm --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: null\n gpus_per_node: null\n tasks_per_node: 1\n mem_gb: null\n nodes: 1\n name: ${hydra.job.name}\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.SlurmLauncher\n partition: null\n qos: null\n comment: null\n constraint: null\n exclude: null\n gres: null\n cpus_per_gpu: null\n gpus_per_task: null\n mem_per_gpu: null\n mem_per_cpu: null\n account: null\n signal_delay_s: 120\n max_num_timeout: 0\n python: null\n additional_parameters: {}\n array_parallelism: 256\n setup: null\n srun_args: null\n use_srun: true\n ```\n
\n
\n Discover the Local Launcher parameters (Expand)\n\n ```yaml title=\"$ python example/my_app.py hydra/launcher=submitit_local --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.LocalLauncher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: 1\n gpus_per_node: 0\n tasks_per_node: 1\n mem_gb: 4\n nodes: 1\n name: ${hydra.job.name}\n ```\n
\n\n
\nYou can set all these parameters in your configuration file and/or override them in the command-line:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.timeout_min=3\n```\nSet `hydra.launcher.tasks_per_node=null` to omit `--ntasks-per-node` from the\ngenerated Slurm submission.\n\nSet `hydra.launcher.use_srun=false` to run Python directly in the batch script\ninstead of through `srun`. The default is `true`. When disabled, Python runs\nonce on the batch node, and `srun_args` is ignored; Slurm does not automatically\nlaunch the other requested tasks.\n\nSet `hydra.launcher.python` to use a Python executable other than the one\nrunning Hydra:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.python=/opt/venv/bin/python\n```\n\nFor more details, including descriptions for each parameter, check out the config file.\nYou can also check the [Submitit documentation](https://github.com/facebookincubator/submitit).\n\n\n**Caution**: use of `--multirun` is required for the launcher to be picked up.\n\n### Example\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py task=1,2,3 --multirun` (see [Multi-run](../tutorials/basic/running_your_app/2_multirun.md) for details) will launch 3 executions (you can override the launcher to run locally for testing by adding `hydra/launcher=submitit_local`):\n\n```text\n$ python my_app.py task=1,2,3 --multirun\n[HYDRA] Sweep output dir : multirun/2020-05-28/15-05-22\n[HYDRA] #0 : task=1\n[HYDRA] #1 : task=2\n[HYDRA] #2 : task=3\n```\nYou will be able to see the output of the app in the output dir:\n```commandline\n$ tree\n.\n├── 0\n│   └── my_app.log\n├── 1\n│   └── my_app.log\n├── 2\n│   └── my_app.log\n└── multirun.yaml\n\n$ cat 0/my_app.log\n[2020-05-28 15:05:23,511][__main__][INFO] - Process ID 15887 executing task 1 ...\n[2020-05-28 15:05:24,514][submitit][INFO] - Job completed successfully\n```\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\nRepo-specific directives for coding agents working in this project.\n\n## Behavioral defaults\n\nThese guidelines are intended to reduce common LLM coding mistakes. Apply them\nalongside the repo-specific rules below. They bias toward caution over speed,\nand for truly trivial tasks you may use judgment.\n\n### Think before coding\n\n- Do not assume.\n- Do not hide confusion.\n- Surface tradeoffs.\n- State assumptions explicitly when they matter to the implementation.\n- If multiple reasonable interpretations exist, present them instead of silently picking one.\n- If a simpler approach exists, say so.\n- Push back when warranted.\n- If something material is unclear or risky, stop, name what is confusing, and ask instead of guessing.\n\n### Simplicity first\n\n- Solve the requested problem with the minimum code necessary.\n- No features beyond what was asked.\n- No abstractions for single-use code.\n- No flexibility or configurability that was not requested.\n- No error handling for scenarios that are effectively impossible in context.\n- If a solution feels overbuilt for the task, simplify it before considering it done.\n- If you write 200 lines and the same result could be achieved in 50, rewrite it.\n- Ask: would a senior engineer say this is overcomplicated? If yes, simplify.\n\n### Surgical changes\n\n- Touch only what is needed for the request.\n- Do not \"clean up\" adjacent code, comments, formatting, or structure unless the change requires it.\n- Match the existing style and patterns of the codebase unless the user asks for a broader refactor.\n- If you notice unrelated dead code or issues nearby, mention them instead of fixing them opportunistically.\n- Remove imports, variables, functions, or other artifacts that your change makes unused.\n- Do not delete unrelated pre-existing dead code unless asked.\n- Every changed line should trace directly to the user's request.\n\n### Prefer focused tools over ad hoc shell\n\nUse repository-aware file inspection and edit tools for file operations. Reserve\nshell commands for things that genuinely require shell execution: `sl`\n(Sapling) commands, `gh`, dependency installation, or `nox` / `pytest` /\n`python` for tests, linting, and other repo tooling.\n\n- Use `rg` for text search and `rg --files` for file discovery.\n- Avoid inline Python snippets (`python -c ...`) when a dedicated tool or standard CLI utility is sufficient.\n- Use structured tools such as `jq` to parse JSON shell output instead of piping to Python.\n\n### Goal-driven execution\n\n- Translate requests into concrete success criteria that can be verified.\n- For bug fixes, prefer reproducing the issue with a test or other reliable check before fixing it.\n- For refactors, prefer checks that demonstrate behavior is preserved before and after.\n- For multi-step tasks, keep a brief plan in mind and verify each step before calling the work complete.\n- Favor specific goals over vague ones:\n - \"Add validation\" -> write tests for invalid inputs, then make them pass.\n - \"Fix the bug\" -> reproduce it with a test or reliable check, then make it pass.\n - \"Refactor X\" -> verify behavior before and after the refactor.\n\n## Documentation map\n\n- Website and docs source: [`website/`](./website/)\n- Current docs: [`website/docs/`](./website/docs/)\n- Development docs: [`website/docs/development/`](./website/docs/development/)\n- Plugin docs: [`website/docs/plugins/`](./website/docs/plugins/)\n- Versioned docs: [`website/versioned_docs/`](./website/versioned_docs/)\n\n## Reproduction files\n\nWhen asked to create a reproduction for an issue, place files under\n`temp/repro/`:\n\n- Single-file repro: `temp/repro/.py`\n- Multi-file repro: `temp/repro//`\n\n## Scratch files\n\nPlace low-value, disposable temporary files under `temp/scratch/`. Its contents\nmay be cleared weekly without review. Do not store reproductions, resumable\nworkflow state, unique evidence, or drafts awaiting use there.\n\n## Stop and ask\n\n- If a tracked repo file appears unexpectedly renamed, moved, regenerated, deleted, or otherwise changed, stop and ask before reverting, recreating, reclassifying, or staging over that change.\n- Do not change supported Python versions, CI matrices, packaging metadata, release automation, or workflow triggers unless the request explicitly includes that scope.\n\n## Verification\n\n- For any new or changed functionality, test it in two layers when practical:\n - run relevant focused tests with `pytest path/to/test_file.py`\n - run the relevant `nox` session to ensure no regressions\n- Hydra core tests run with `pytest` from the repository root.\n- Plugin tests run from the plugin directory after installing the plugin, or via `nox -s test_plugins`.\n- Use `PLUGINS=` with `nox` when validating one plugin.\n- If the broader suite disagrees with focused tests, trust the broader result and do not call the change verified.\n- If live verification is blocked by the current environment, request escalation if that would unblock it. If not, stop and ask for guidance.\n\n## Linting and formatting\n\nRun linting through `nox -s lint lint_plugins` when validating broad changes.\nThe repo's lint sessions include formatting, import sorting, type checks, style,\nYAML linting, and security checks.\n\nFor focused local checks, use the same tools the noxfile runs:\n\n- `ruff format .` / `ruff format --check .`\n- `ruff check .` / `ruff check --fix .`\n- `pyrefly check --config pyproject.toml`\n- `yamllint --strict .`\n- `bandit --exclude ./.nox/** -ll -r .`\n\n## Environment and hooks\n\n- Run commands from the repo-local `.venv` by default. Prefer\n `.venv/bin/python`, `.venv/bin/pip`, `.venv/bin/pytest`, and\n `.venv/bin/nox` when those entry points exist.\n- If `.venv` is missing and dependency installation is in scope, create it\n with `python -m venv .venv`, then install `requirements/dev.txt` and the\n editable checkout into that environment.\n- Use a separate environment only when testing a specific supported Python\n version or reproducing an environment-specific issue.\n- When validating contributor setup, shell initialization, or hook behavior, verify it from the same environment a developer would actually use, such as a normal shell session or `sl commit`, not only from a temporary sandbox-only environment.\n- Prefer hooks that do not depend on nontrivial user-environment tooling.\n- If an environment override is required for one command, explain why it must be part of that same process invocation.\n- If a small system tool would materially simplify the workflow, it is fine to suggest it or ask the user to install it.\n\n## Source control and PRs\n\nUse the VCS tooling that matches the current checkout. Some Hydra worktrees are\nSapling (`sl`) checkouts, while others may be plain Git clones.\n\n- Prefer the checkout's native tool for local operations such as status, log, diff, commit, amend, and stack inspection.\n- In a Sapling checkout, use `sl` for normal local VCS operations.\n- Keep escalated VCS commands minimal and single-purpose.\n- Do not bundle staging, environment bootstrapping, dependency installation, and commit creation into one escalated shell command unless there is no practical alternative.\n- If a VCS operation requires escalation, ask only for the specific action that needs it.\n- Do not force-push, submit, or otherwise update a remote branch unless the user explicitly asks for that outward action.\n- Before using low-level fallback commands, such as `git --git-dir .sl/store/git` in a Sapling checkout, stop and explain why the normal workflow is not sufficient.\n\n## Release and news fragments\n\n- Do not commit, push, merge, publish, or otherwise send changes outside the local working tree unless the user explicitly asks for that outward action.\n- If a change alters release automation, workflow triggers, deployment behavior, or other externally visible project mechanics, require an explicit user review checkpoint before any commit, push, merge, publish, or deployment action.\n- All non-trivial product-user-visible changes should have a news fragment.\n- Core Hydra fragments go under `news/`; plugin-specific fragments go under the relevant plugin's `news/` directory.\n- Fragment filenames follow the pattern `.`.\n- Supported categories are `api_change`, `feature`, `bugfix`, `docs`, `config`, and `maintenance`.\n- Fragment text must be concise, user-facing, sentence case, and preferably under 80 characters.\n- Developer-only tooling, repo maintenance, and CI-only changes do not need a fragment unless they change the shipped product experience.\n- The user handles releases. Do not edit version numbers, create release files, assemble release notes, or otherwise perform release-cut steps unless explicitly asked.\n- The documented release process lives in [`website/docs/development/release.md`](./website/docs/development/release.md). Do not improvise a manual release flow.\n\n## Reviews\n\n- When asked to review a commit, pull request, or diff, cover correctness, completeness, documentation, and internal consistency.\n- Verify that each product-user-visible change includes an appropriate news fragment and that the fragment matches the implementation and docs.\n","isInternal":false,"tokens":1963,"sizeBytes":9191},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Copilot instructions\n\nWhen generating code or reviewing pull requests for this repository, use\n`CONTRIBUTING.md` as the source of truth for contributor requirements.\n\nFor pull request reviews, check the changed files against the contributor\nguidelines and call out only actionable gaps, especially:\n\n- missing or insufficient tests for code changes;\n- missing documentation updates for API or behavior changes;\n- missing news fragments for non-trivial user-visible changes;\n- news fragments in the wrong `news/` directory or with the wrong category;\n- non-trivial features, API changes, or behavior changes that do not link to\n prior maintainer agreement in an issue or design discussion;\n- validation claims that are not supported by the tests or checks shown in the\n pull request.\n\nDo not request a news fragment for developer-only tooling, repository\nmaintenance, or CI-only changes unless the change affects the shipped product\nexperience.\n\nKeep review comments specific and actionable. Prefer pointing to the relevant\nguideline in `CONTRIBUTING.md` over restating the whole policy.\n","isInternal":false,"tokens":216,"sizeBytes":1091},{"name":"develop.md","path":"website/docs/advanced/plugins/develop.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/advanced/plugins/develop.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: develop\ntitle: Plugin development\nsidebar_label: Plugin development\n---\n\n:::info\nIf you develop plugins, please join the Plugin developer announcement chat channel.\n:::\n\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra plugins must be registered before they can be used. Declare an entry\npoint in the `hydra.plugins` group for each plugin class, or call the\n`register` method on Hydra's `Plugins` singleton. Hydra 1.4 also discovers\nplugins in the `hydra_plugins` namespace for compatibility, but this method is\ndeprecated. See the [plugin discovery migration guide](/docs/upgrades/1.3_to_1.4/plugin_discovery).\n\n## Entry point discovery\n\nFor example, in `setup.py`:\n\n```python\nsetup(\n # ...\n entry_points={\n \"hydra.plugins\": [\n \"my_launcher = my_package.my_launcher:MyLauncher\",\n ]\n },\n)\n```\n\nThe target must be a concrete Hydra plugin class. Its module should also\nregister any associated Hydra configuration when imported. Plugin classes no\nlonger need to live in the `hydra_plugins` namespace. Keep expensive optional\ndependencies out of module-level imports.\n\n## Legacy namespace discovery\n\nIf you create a Plugin and want it to be discovered automatically by Hydra, keep the following things in mind:\n- Namespace-discovered plugins can be either standalone packages or part of an\n existing package. They must be in the top-level `hydra_plugins` namespace.\n- Do __NOT__ place an `__init__.py` file in `hydra_plugins` (doing so may break other installed Hydra plugins).\n \nThe plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of `hydra_plugins`. Hydra will import each module and look for plugins defined in that module.\nAny module under `hydra_plugins` that is slow to import will slow down the startup of __ALL__ Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with `_` (but not `__`).\nFor example, the file `_my_plugin_lib.py` would not be imported and scanned, while `my_plugin_lib.py` would be.\n\n## Plugin registration via the `Plugins.register` method\n\nPlugins can be manually registered by calling the `register` method on the instance of Hydra's `Plugins` singleton class.\n```python\nfrom hydra.core.plugins import Plugins\nfrom hydra.plugins.plugin import Plugin\n\nclass MyPlugin(Plugin):\n ...\n\ndef register_my_plugin() -> None:\n \"\"\"Hydra users should call this function before invoking @hydra.main\"\"\"\n Plugins.instance().register(MyPlugin)\n```\n\n## Getting started\n\nThe best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:\n- Copy the subtree of the relevant example plugin into a standalone project.\n- Edit `setup.py`, rename the plugin module, and declare its entry point.\n- Install the new plugin (Run this in the plugin directory: `pip install -e .`)\n- Run the included example app and make sure that the plugin is discovered:\n```shell\n$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n```\n- Run the example application to see that that your plugin is doing something.\n- *[Optional]* Embed the plugin in your existing application or library. An\n entry-point plugin can use any importable package name.\n- Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.\n\nFor a `SearchPathPlugin` that provides organization-specific Hydra defaults,\nsee [Environment-specific overrides](../../patterns/environment_specific_overrides.md).\n","frontmatter":{"id":"develop","title":"Plugin development","sidebar_label":"Plugin development"},"isInternal":false,"tokens":829,"sizeBytes":3849},{"name":"intro.md","path":"website/docs/advanced/plugins/intro.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/advanced/plugins/intro.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: overview\ntitle: Plugins Overview\nsidebar_label: Plugins Overview\n---\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra can be extended via plugins.\nThe example plugins here can help you get started with plugin development.\n\n## Plugin types\nHydra has several plugin types:\n### Sweeper\nA sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:\n```\nbatch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n```\n\nAnd creates 4 jobs with the following parameters:\n```\nbatch_size=128 optimizer=nesterov learning_rate=0.01\nbatch_size=128 optimizer=nesterov learning_rate=0.1\nbatch_size=128 optimizer=adam learning_rate=0.01\nbatch_size=128 optimizer=adam learning_rate=0.1\n```\n\n### Launcher\nLaunchers are responsible for launching a job to a specific environment.\nA Launcher takes a batch of argument lists like the one above and launches a job for each one.\nThe job uses those arguments to compose its configuration.\nThe basic launcher simply launches the job locally. \n\n### SearchPathPlugin\nA config path plugin can manipulate the search path.\nThis can be used to influence the default Hydra configuration to be more appropriate to a specific environment,\nor just add new entries to the search path to make more configurations available to the Hydra app.\n\nSearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed.\n\nMany other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. \n\n### ConfigSource\nConfigSource plugins can be used to allow Hydra to access configuration in non-standard locations when composing the config.\nThis can be used to enable access to an in-house private config store, or as a way to access configs from public sources like GitHub or S3.\n","frontmatter":{"id":"overview","title":"Plugins Overview","sidebar_label":"Plugins Overview"},"isInternal":false,"tokens":415,"sizeBytes":1983},{"name":"ax_sweeper.md","path":"website/docs/plugins/ax_sweeper.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/ax_sweeper.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: ax_sweeper\ntitle: Ax Sweeper plugin\nsidebar_label: Ax Sweeper plugin\n---\n\nimport {ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ax-sweeper)](https://img.shields.io/pypi/v/hydra-ax-sweeper)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ax-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ax-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ax-sweeper/month)](https://pepy.tech/project/hydra-ax-sweeper)\n\n\nThis plugin provides a mechanism for Hydra applications to use the [Adaptive Experimentation Platform, aka Ax](https://ax.dev/). Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations.\n\n:::warning Retirement after Hydra 1.4\n\nHydra 1.4 will include the final first-party release of the Ax Sweeper, based on\nthe existing implementation. Further modernization is no longer planned. The\nplugin code will be removed in the Hydra 1.5 line, and no first-party Ax Sweeper\nreleases will be published for Hydra 1.5 or later. Existing PyPI releases will\nremain available.\n\nCommunity members interested in maintaining the plugin in a separate repository\nare invited to comment on the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506).\nHydra's documentation can link to that repository. Transferring control of the\n`hydra-ax-sweeper` PyPI package may be considered once new maintainers establish\na reliable track record and build trust.\n\n:::\n\n### Installation\n```commandline\npip install hydra-ax-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=ax` to your command line. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: ax\n```\n\nWe include an example of how to use this plugin. The file example/banana.py\nimplements the [Rosenbrock function (aka Banana function)](https://en.wikipedia.org/wiki/Rosenbrock_function).\nThe return value of the function should be the value that we want to optimize.\n\n\nTo compute the best parameters for the Banana function, clone the code and run the following command in the `plugins/hydra_ax_sweeper` directory:\n\n```\npython example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n```\n\nThe output of a run looks like:\n\n```\n[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5]\nbanana.y: range=[-5.0, 10.1]\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 trials, GPEI for subsequent trials]). Iterations after 5 will take longer to generate due to model-fitting.\n[HYDRA] AxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=2 banana.y=-0.988\n[__main__][INFO] - Banana_Function(x=2, y=-0.988)=2488.883\n[HYDRA] #1 : banana.x=-1 banana.y=7.701\n[__main__][INFO] - Banana_Function(x=-1, y=7.701)=4493.987\n[HYDRA] #2 : banana.x=-1 banana.y=-3.901\n[__main__][INFO] - Banana_Function(x=-1, y=-3.901)=2406.259\n[HYDRA] #3 : banana.x=-1 banana.y=0.209\n[__main__][INFO] - Banana_Function(x=-1, y=0.209)=66.639\n[HYDRA] #4 : banana.x=4 banana.y=-4.557\n[__main__][INFO] - Banana_Function(x=4, y=-4.557)=42270.006\n[HYDRA] New best value: 66.639, best parameters: {'banana.x': -1, 'banana.y': 0.209}\n```\n\nIn this example, we set the range of `x` parameter as an integer in the interval `[-5, 5]` and the range of `y` parameter as a float in the interval `[-5, 10.1]`. Note that in the case of `x`, we used `int(interval(...))` and hence only integers are sampled. In the case of `y`, we used `interval(...)` which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.` banana.x=5.0`), choice parameters (eg `banana.x=choice(1,2,3)`) and range (eg `banana.x=range(1, 10)`). Note that `interval`, `choice` etc. are functions provided by Hydra, and you can read more about them [here](/advanced/override_grammar/extended.md). An important thing to remember is, use [`interval`](/advanced/override_grammar/extended.md#interval-sweep) when we want Ax to sample values from an interval. [`RangeParameter`](https://ax.dev/api/ax.html#ax.RangeParameter) in Ax is equivalent to `interval` in Hydra. Remember to use `int(interval(...))` if you want to sample only integer points from the interval. [`range`](/advanced/override_grammar/extended.md#range-sweep) can be used as an alternate way of specifying choice parameters. For example `python example/banana.py -m banana.x=choice(1, 2, 3, 4)` is equivalent to `python example/banana.py -m banana.x=range(1, 5)`.\n\nThe values of the `x` and `y` parameters can also be set using the config file `plugins/hydra_ax_sweeper/example/conf/config.yaml`. For instance, the configuration corresponding to the commandline arguments is as follows:\n\n```\nbanana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n```\n\nTo sample in log space, you can tag the commandline override with `log`. E.g. `python example/banana.py -m banana.x=tag(log, interval(1, 1000))`. You can set `log_scale: true` in the input config to achieve the same.\n```\nbanana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n```\n\nIn general, the plugin supports setting all the Ax supported [Parameters](https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter) in the config. According to the [Ax documentation](https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment), the required elements in the config are:\n\n* `name` - Name of the parameter. It is of type string.\n* `type` - Type of the parameter. It can take the following values: `range`, `fixed`, or `choice`.\n* `bounds` - Required only for the `range` parameters. It should be a list of two values, with the lower bound first.\n* `values` - Required only for the `choice` parameters. It should be a list of values.\n* `value` - Required only for the `fixed` parameters. It should be a single value.\n\nNote that if you want to sample integers in the range `-5` to `5`, you need to specify the range as `int(interval(-5, 5))` (in the command line) or `[-5, 5]` (in config). If you want to sample floats in range `-5` to `5`, you need to specify the range as `interval(-5, 5)` (in the command line) or `[-5.0, 5.0]` (in config).\n\nThe Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the `is_noisy` parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero.\n\nIf measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the [standard error of the mean](https://en.wikipedia.org/wiki/Standard_error) of repeated measurements), the measurement function can return the tuple `(measurement_value, measurement_uncertainty)` instead of a scalar value.\n\nThe parameters for the optimization process can also be set in the config file. Specifying the Ax config is optional. You can discover the Ax Sweeper parameters with:\n\n```yaml title=\"$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_ax_sweeper.ax_sweeper.AxSweeper\nmax_batch_size: null\nax_config:\n max_trials: 10\n early_stop:\n minimize: true\n max_epochs_without_improvement: 10\n epsilon: 1.0e-05\n experiment:\n name: null\n objective_name: objective\n minimize: true\n parameter_constraints: null\n outcome_constraints: null\n status_quo: null\n client:\n verbose_logging: false\n random_seed: null\n is_noisy: true\n params: {}\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n","frontmatter":{"id":"ax_sweeper","title":"Ax Sweeper plugin","sidebar_label":"Ax Sweeper plugin"},"isInternal":false,"tokens":2202,"sizeBytes":8041},{"name":"colorlog.md","path":"website/docs/plugins/colorlog.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/colorlog.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: colorlog\ntitle: Colorlog plugin\nsidebar_label: Colorlog plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-colorlog)](https://pypi.org/project/hydra-colorlog/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-colorlog)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-colorlog)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-colorlog/month)](https://pepy.tech/project/hydra-colorlog)\n\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\n\n### Installation\n```commandline\npip install hydra_colorlog --upgrade\n```\n\n### Usage\nOverride `hydra/job_logging` and `hydra/hydra_logging` in your config:\n\n```yaml\ndefaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n```\n\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee included example application.\n \n![Colored log output](/plugins/colorlog/colorlog.png)\n","frontmatter":{"id":"colorlog","title":"Colorlog plugin","sidebar_label":"Colorlog plugin"},"isInternal":false,"tokens":372,"sizeBytes":1417},{"name":"joblib_launcher.md","path":"website/docs/plugins/joblib_launcher.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/joblib_launcher.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: joblib_launcher\ntitle: Joblib Launcher plugin\nsidebar_label: Joblib Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-joblib-launcher)](https://pypi.org/project/hydra-joblib-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-joblib-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-joblib-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-joblib-launcher/month)](https://pepy.tech/project/hydra-joblib-launcher)\n\nThe Joblib Launcher plugin provides a launcher for parallel tasks based on [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html).\n\n### Process backends\n\nThe launcher supports two process backends:\n\n| Backend | Advantages | Tradeoffs |\n| --- | --- | --- |\n| `loky` (default) | Robust process management and Cloudpickle support for dynamically defined Python objects. It remains the default for compatibility. | Workers are reused between Hydra jobs, so arbitrary application caches or process-global state can leak between jobs. Cloudpickling the task can also fail when it reaches some native-library objects. |\n| `multiprocessing` | Runs every Hydra job in a fresh worker process and sends module-level function tasks by reference instead of Cloudpickling them. This provides strict process isolation and avoids serializing module-level native-library objects referenced by the task. | Functions must be defined at module scope. Custom decorators around `@hydra.main` must use `functools.wraps`. |\n\nLoky runs jobs in the parent process when `n_jobs=1`. The multiprocessing\nbackend retains per-job worker isolation while executing one job at a time.\n\n### Installation\n```commandline\npip install hydra-joblib-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=joblib` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: joblib\n```\nBy default, the launcher uses process-based parallelism with all available CPU\ncores. Set `hydra.launcher.n_jobs` to limit the number of jobs that can run\nconcurrently.\n\nThe JobLibLauncherConf backing the config is defined here:\n\nYou can discover the Joblib Launcher parameters with:\n```yaml title=\"$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: -1\ninner_max_num_threads: null\nbackend: loky\nprefer: processes\nrequire: null\nverbose: 0\ntimeout: null\npre_dispatch: 2*n_jobs\nbatch_size: auto\ntemp_folder: null\nmax_nbytes: null\nmmap_mode: r\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee [`Joblib.Parallel` documentation](https://joblib.readthedocs.io/en/latest/parallel.html) for full details about the parameters above.\n\n`backend` selects the backend used by this launcher. Because a backend is\nalways selected explicitly, `prefer` does not change it. `require` must be\ncompatible with the selected backend; `require=sharedmem` is unsupported\nbecause this launcher does not support a thread-based backend.\n\n#### Controlling native library thread pools\n\nWhen using libraries that manage native thread pools, such as OpenBLAS, MKL, OpenMP, Numba, or NumExpr, set `inner_max_num_threads` to limit the number of native threads available to each Joblib worker process:\n\n```yaml\nhydra:\n launcher:\n n_jobs: 8\n inner_max_num_threads: 1\n```\n\nThis can help avoid oversubscription when multiple Hydra jobs run in parallel and each job calls into a multithreaded native library. For arbitrary environment variables, use [`hydra.job.env_set`](../configure_hydra/job.md#hydrajobenv_set) instead.\n\n
\nSelect the `multiprocessing` backend to execute every job in a fresh worker\nprocess:\n\n```yaml\nhydra:\n launcher:\n backend: multiprocessing\n n_jobs: 4\n```\n\nThe launcher automatically sets Joblib's `batch_size=1` so that each pool task\ncontains one Hydra job, and `maxtasksperchild=1` so that the worker exits after\nthat task. These are internal correctness settings, not user configuration.\nConflicting values are rejected.\n\n`inner_max_num_threads` is supported only by `loky`. Custom decorators around\n`@hydra.main` must follow the\n[Hydra task-decorator requirements](../advanced/decorating_main.md). Callable\ntask objects are copied to each worker, so all state stored on them must support\nPython pickling.\n

\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will launch five parallel executions:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=10,backend=loky,prefer=processes,require=None,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r) is launching 5 jobs\n[HYDRA] Launching jobs, sweep output dir : multirun/2020-02-18/10-00-00\n[__main__][INFO] - Process ID 14336 executing task 2 ...\n[__main__][INFO] - Process ID 14333 executing task 1 ...\n[__main__][INFO] - Process ID 14334 executing task 3 ...\n[__main__][INFO] - Process ID 14335 executing task 4 ...\n[__main__][INFO] - Process ID 14337 executing task 5 ...\n```\n","frontmatter":{"id":"joblib_launcher","title":"Joblib Launcher plugin","sidebar_label":"Joblib Launcher plugin"},"isInternal":false,"tokens":1428,"sizeBytes":5763},{"name":"nevergrad_sweeper.md","path":"website/docs/plugins/nevergrad_sweeper.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/nevergrad_sweeper.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: nevergrad_sweeper\ntitle: Nevergrad Sweeper plugin\nsidebar_label: Nevergrad Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-nevergrad-sweeper)](https://pypi.org/project/hydra-nevergrad-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-nevergrad-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-nevergrad-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-nevergrad-sweeper/month)](https://pepy.tech/project/hydra-nevergrad-sweeper)\n\n[Nevergrad](https://facebookresearch.github.io/nevergrad/) is a derivative-free optimization platform providing a library of state-of-the-art algorithms for hyperparameter search. This plugin provides Hydra applications a mechanism to use [Nevergrad](https://facebookresearch.github.io/nevergrad/) algorithms to optimize experiment/application parameters.\n\n### Installation\n```commandline\npip install hydra-nevergrad-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=nevergrad` to your command. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: nevergrad\n```\n\nThe default configuration is defined and documented here.\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Example of training using Nevergrad hyperparameter search\n\nWe include an example of how to use this plugin. The file example/my_app.py implements an example of minimizing a (dummy) function using a mixture of continuous and discrete parameters.\n\nYou can discover the Nevergrad sweeper parameters with:\n```yaml title=\"$ python your_app hydra/sweeper=nevergrad --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_nevergrad_sweeper.nevergrad_sweeper.NevergradSweeper\noptim:\n optimizer: NGOpt\n budget: 80\n num_workers: 10\n noisy: false\n maximize: false\n seed: null\n max_failure_rate: 0.0\nparams:\n db: choice(mnist, cifar)\n lr: {init: 0.02, step: 2.0, log: true}\n dropout: interval(0, 1)\n batch_size: int(interval(4, 16))\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\ndb: mnist\nlr: 0.12\ndropout: 0.33\nbatch_size: 4\n```\n\nTo run hyperparameter search and look for the best parameters for this function, clone the code and run the following command in the `plugins/hydra_nevergrad_sweeper` directory:\n```bash\npython example/my_app.py -m\n```\n\nYou can also override the search space parametrization:\n```bash\npython example/my_app.py --multirun db=mnist,cifar batch_size=4,8,16 \\\n'lr=tag(log, interval(0.001, 1))' 'dropout=interval(0,1)'\n```\n\nThe initialization of the sweep and the first 5 evaluations (out of 100) look like this:\n\n```text\n[2020-10-08 20:13:53,592][HYDRA] NevergradSweeper(optimizer=NGOpt, budget=100, num_workers=10) minimization\n[2020-10-08 20:13:53,593][HYDRA] with parametrization Dict(batch_size=Choice(choices=Tuple(4,8,16),weights=Array{(1,3)}),db=Choice(choices=Tuple(mnist,cifar),weights=Array{(1,2)}),dropout=Scalar{Cl(0,1,b)}[sigma=Log{exp=2.0}],lr=Log{exp=3.162277660168379,Cl(0.001,1,b)}):{'db': 'mnist', 'lr': 0.03162277660168379, 'dropout': 0.5, 'batch_size': 8}\n[2020-10-08 20:13:53,593][HYDRA] Sweep output dir: multirun/2020-10-08/20-13-53\n[2020-10-08 20:13:55,023][HYDRA] Launching 10 jobs locally\n[2020-10-08 20:13:55,023][HYDRA] #0 : db=mnist lr=0.03162277660168379 dropout=0.5 batch_size=16\n[2020-10-08 20:13:55,217][__main__][INFO] - dummy_training(dropout=0.500, lr=0.032, db=mnist, batch_size=16) = 13.258\n[2020-10-08 20:13:55,218][HYDRA] #1 : db=cifar lr=0.018178519762066934 dropout=0.5061074452336254 batch_size=4\n[2020-10-08 20:13:55,408][__main__][INFO] - dummy_training(dropout=0.506, lr=0.018, db=cifar, batch_size=4) = 0.278\n[2020-10-08 20:13:55,409][HYDRA] #2 : db=cifar lr=0.10056825918734161 dropout=0.6399687427725211 batch_size=4\n[2020-10-08 20:13:55,595][__main__][INFO] - dummy_training(dropout=0.640, lr=0.101, db=cifar, batch_size=4) = 0.329\n[2020-10-08 20:13:55,596][HYDRA] #3 : db=mnist lr=0.06617542958182834 dropout=0.5059497416026679 batch_size=8\n[2020-10-08 20:13:55,812][__main__][INFO] - dummy_training(dropout=0.506, lr=0.066, db=mnist, batch_size=8) = 5.230\n[2020-10-08 20:13:55,813][HYDRA] #4 : db=mnist lr=0.16717013388679514 dropout=0.6519070394318255 batch_size=4\n...\n[2020-10-08 20:14:27,988][HYDRA] Best parameters: db=cifar lr=0.11961221693764439 dropout=0.37285878409770895 batch_size=4\n```\n\n\nand the final 2 evaluations look like this:\n```text\n[HYDRA] \t#8 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] \t#9 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] Best parameters: db=mnist batch_size=4 lr=0.094 dropout=0.381\n```\n\n\nThe run also creates an `optimization_results.yaml` file in your sweep folder with the best evaluated parameters found during the sweep:\n```yaml\nbest_evaluated_result: 0.381\n\nbest_evaluated_params:\n batch_size: 4\n db: mnist\n dropout: 0.381\n lr: 0.094\n\nname: nevergrad\n```\n\n## Defining the parameters\n\nThe plugin supports two types of parameters: [Choices](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters) and [Scalars](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters). They can be defined either through a config file or command-line override.\n\n### Defining through command-line override\nHydra provides an override parser that supports rich syntax. More documentation can be found in ([Override Grammar/Basic](../advanced/override_grammar/basic.md)) and ([Override Grammar/Extended](../advanced/override_grammar/extended.md)). We recommend you go through them first before proceeding with this doc.\n\n#### Choices\nTo override a field with choices:\n```commandline\n'key=1,5'\n'key=shuffle(range(1, 8))'\n'key=range(1,5)'\n```\n\nYou can tag an override with `ordered` to indicate it's a [`TransitionChoice`](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters)\n```commandline\nkey=tag(ordered, choice(1,2,3))\n```\n\n#### Scalar\n```commandline\nkey=interval(1,12) # Intervals are floats by default\nkey=int(interval(1,8)) # Scalar bounds are cast to an int\nkey=tag(log, interval(1,12)) # call ng.p.Log if tagged with log\nkey={init: 0.02, step: 2.0, log: true} # Unbounded log-scale scalar\n```\n\n### Defining through config file\nThe search space can be defined under `hydra.sweeper.params`.\nThe definition is consistent with the equivalent command-line override.\n\n:::warning\n`hydra.sweeper.parametrization` is deprecated in Hydra 1.4 and will be removed\nin Hydra 1.5. Use `hydra.sweeper.params` instead.\n:::\n\n#### Choices\nChoices use the same syntax as command-line overrides. For example, translate\n`key=shuffle(range(1, 8))` to `key: shuffle(range(1, 8))` in the config file.\n\nFixed strings containing override grammar characters must retain quotes as part\nof the configured value. For example, use `label: \"'a,b'\"` to configure the\nliteral string `a,b`; `label: a,b` defines a choice sweep.\n\n#### Scalars\n`Scalar` definitions also support the override syntax shown above. The\nfollowing keys can be passed in a dictionary to define unbounded scalars:\n - `init`: optional initial value\n - `lower` : optional lower bound\n - `upper`: optional upper bound\n - `log`: set to `true` for log distributed values\n - `step`: optional step size for looking for better parameters. In linear mode, this is an additive step; in logarithmic mode it is multiplicative.\n - `integer`: set to `true` for integers (favor floats over integers whenever possible)\n\nProviding only `lower` and `upper` bound will set the initial value to the middle of the range and the step to a sixth of the range.\n","frontmatter":{"id":"nevergrad_sweeper","title":"Nevergrad Sweeper plugin","sidebar_label":"Nevergrad Sweeper plugin"},"isInternal":false,"tokens":2588,"sizeBytes":8405},{"name":"optuna_sweeper.md","path":"website/docs/plugins/optuna_sweeper.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/optuna_sweeper.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: optuna_sweeper\ntitle: Optuna Sweeper plugin\nsidebar_label: Optuna Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-optuna-sweeper)](https://pypi.org/project/hydra-optuna-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-optuna-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-optuna-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-optuna-sweeper/month)](https://pepy.tech/project/hydra-optuna-sweeper)\n\n\nThis plugin enables Hydra applications to utilize [Optuna](https://optuna.org) for the optimization of the parameters of experiments.\n\n## Installation\n\nThis plugin requires Hydra Core 1.4 (`hydra-core>=1.4.0.dev1,<1.5.0.dev0`).\nPlease install it with the following command:\n\n```commandline\npip install --upgrade --pre \"hydra-core>=1.4.0.dev1,<1.5.0.dev0\"\n```\n\nYou can install the plugin via pip:\n\n```commandline\npip install --upgrade --pre \"hydra-optuna-sweeper>=1.4.0.dev1,<1.5.0.dev0\"\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Usage\n\nPlease set `hydra/sweeper` to `optuna` in your config file.\n\n```yaml\ndefaults:\n - override hydra/sweeper: optuna\n```\n\nAlternatively, add `hydra/sweeper=optuna` option to your command line.\n\nThe default configuration is here.\n\n## Example 1: Single-Objective Optimization\n\nWe include an example in this directory. `example/sphere.py` implements a simple benchmark function to be minimized.\n\n\n\n\nYou can discover the Optuna sweeper parameters with:\n\n```yaml title=\"python example/sphere.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\nsampler:\n _target_: optuna.samplers.TPESampler\n seed: 123\n n_startup_trials: 10\n n_ei_candidates: 24\n multivariate: false\n_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\ndirection: minimize\nstorage: null\nstudy_name: sphere\nn_trials: 20\nn_jobs: 1\nmax_failure_rate: 0.0\nparams:\n x: range(-5.5,5.5,step=0.5)\n y: choice(-5,0,5)\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\nx: 0\ny: 0\n```\n\nTo run optimization, clone the code and run the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/sphere.py --multirun\n```\n\nYou can also override the search space parametrization:\n\n```commandline\npython example/sphere.py --multirun 'x=interval(-5.0, 5.0)' 'y=interval(0, 10)'\n```\n\nYou might find the `optimization_results.yaml` file (i.e. best params and best value) under `multirun` logs folder:\n\n```yaml\nname: optuna\nbest_params:\n x: 0.0\n 'y': 0\nbest_value: 0.0\n```\n\n\n## Sampler configuration\nThis plugin supports Optuna's [samplers](https://optuna.readthedocs.io/en/stable/reference/samplers.html).\nYou can change the sampler by overriding `hydra/sweeper/sampler` or change sampler settings within `hydra.sweeper.sampler`.\n\n## Search space configuration\n\nThis plugin supports Optuna's [distributions](https://optuna.readthedocs.io/en/stable/reference/distributions.html) to configure search spaces. They can be defined either through commandline override or config file.\n\n### Configuring through commandline override\n\nHydra provides a override parser that support rich syntax. Please refer to [OverrideGrammer/Basic](../advanced/override_grammar/basic.md) and [OverrideGrammer/Extended](../advanced/override_grammar/extended.md) for details.\n\n#### Interval override\n\nBy default, `interval` is converted to [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html). You can use [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html) by casting the interval to `int`.\n\n
\n Example for interval override\n\n ```commandline\n python example/sphere.py --multirun 'x=int(interval(-5.0, 5.0))' 'y=tag(log, interval(1, 10))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=1.6859762540733367\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=5.237816870668193\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': 1.0929184723430116}\n [HYDRA] Best value: 1.1944707871885822\n ```\n\n
\n\n#### Range override\n\nInteger ranges are converted to [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html).\nFloat ranges, including sorted float ranges, use [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html).\nThe distribution includes exactly the discrete values in the range: its stop\nis exclusive, and descending ranges are supported. Empty ranges and zero steps\nare rejected. For example, `range(1,3)` permits only `1` and `2`, while\n`range(0,1,0.3)` permits `0.0`, `0.3`, `0.6`, and `0.9`.\n\nWhen converting a float range would make its Decimal endpoints or step\nunrepresentable as an Optuna numeric distribution, the sweeper uses a\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\nwith the generated values instead. This precision-boundary fallback preserves\nthe exact values and duplicates; representable ordinary uncast ranges remain\nnumeric and are converted without enumerating their values.\n\nApplying `shuffle`, `int`, or `float` to a range uses\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\ncontaining its generated values. Casts apply to each value, so\n`int(range(0,5,1.5))` permits `0`, `1`, `3`, and `4`. Duplicate cast values are\nretained. Sorting or shuffling does not change the permitted values. Optuna\ndoes not promise to evaluate trials in range order.\n\nGridSampler evaluates all values in each discrete distribution, including a\nsingleton or the distribution's inclusive upper endpoint.\n\nThese corrections changed range search spaces in Hydra 1.4; earlier unshuffled\nranges could admit an excluded stop. See the\n[migration guide](/docs/upgrades/1.3_to_1.4/breaking_changes#optuna-range-sweeps).\n\n
\n Example for range override\n\n ```commandline\n python example/sphere.py --multirun 'x=range(-5.0, 5.0)' 'y=shuffle(range(-5, 5))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=-4\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=-1\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': -1}\n [HYDRA] Best value: 1.0\n ```\n\n
\n\n#### Choice override\n\n`choice` is converted to [`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html).\n\n
\n Example for choice override\n\n ```commandline\n python example/sphere.py --multirun 'x=choice(-5.0, 0.0, 5.0)' 'y=choice(0, 1, 2, 3, 4, 5)'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=5.0 y=5\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=5.0 y=2\n ...\n [HYDRA] Best parameters: {'x': 0.0, 'y': 0}\n [HYDRA] Best value: 0.0\n ```\n\n
\n\n### Configuring through config file\n\nThe syntax in config file is consistent with the above commandline override. For example, a commandline override\n`x=range(1,4)` can be expressed in config file as `x: range(1,4)` under the `hydra.sweeper.params` node.\n\n## Example 2: Multi-Objective Optimization\n\nIn the same directory, `example/multi-objective.py` implements a simple benchmark function, which has two objective values. We want to minimize two objectives simultaneously.\n\nYou can discover the Optuna sweeper parameters with:\n\n```commandline\npython example/multi-objective.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\n```\n\n
\n Configuration of the multi-objective optimization example\n\n ```yaml\n # @package hydra.sweeper\n sampler:\n _target_: optuna.samplers.NSGAIISampler\n seed: 123\n population_size: 50\n mutation_prob: null\n crossover_prob: 0.9\n swapping_prob: 0.5\n constraints_func: null\n _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\n direction:\n - minimize\n - minimize\n storage: null\n study_name: multi-objective\n n_trials: 20\n n_jobs: 1\n params:\n x: range(0, 5, step=0.5)\n y: range(0, 3, step=0.5)\n ```\n
\n\n\nTo run the optimization, use the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/multi-objective.py --multirun\n```\n\nFor problems with trade-offs between two different objectives, there may be no single solution that simultaneously minimizes both objectives. Instead, we obtained a set of solutions, namely [Pareto optimal solutions](https://en.wikipedia.org/wiki/Pareto_efficiency), that show the best trade-offs possible between the objectives. In the following figure, the blue dots show the Pareto optimal solutions in the optimization results.\n\n![Pareto-optimal solutions](/plugins/optuna_sweeper/multi_objective_result.png)\n\n## EXPERIMENTAL: Custom-Search-Space Optimization\n\nHydra's Optuna Sweeper allows users to provide a hook for custom search space configuration.\nThis means you can work directly with the `optuna.trial.Trial` object to suggest parameters.\nTo use this feature, define a python function with signature `Callable[[DictConfig, optuna.trial.Trial], None]`\nand set the `hydra.sweeper.custom_search_space` key in your config to target that function.\n\nThe callback path is selected by configuration. When using an execution\nwhitelist, authorize that path from trusted Python code:\n\n```python\n@hydra.main(\n config_path=\"custom-search-space\",\n config_name=\"config\",\n execution_whitelist=\"custom-search-space-objective.configure\",\n)\ndef multi_dimensional_sphere(cfg: DictConfig) -> float:\n ...\n```\n\nYou can find a full example in the same directory as before, where `example/custom-search-space-objective.py` implements a benchmark function to be minimized.\nThe example shows the use of Optuna's [pythonic search spaces](https://optuna.readthedocs.io/en/stable/tutorial/10_key_features/002_configurations.html) in combination with Hydra.\nPart of the search space configuration is defined in config files, and part of it is written in Python.\n\n
\n Example: Custom search space configuration\n\n ```yaml\n defaults:\n - override hydra/sweeper: optuna\n\n hydra:\n sweeper:\n sampler:\n seed: 123\n direction: minimize\n study_name: custom-search-space\n storage: null\n n_trials: 20\n n_jobs: 1\n\n params:\n x: range(-5.5, 5.5, 0.5)\n y: choice(-5, 0, 5)\n # `custom_search_space` should be a dotpath pointing to a\n # callable that provides search-space configuration logic:\n custom_search_space: custom-search-space-objective.configure\n\n x: 1\n y: 1\n z: 100\n max_z_difference_from_x: 0.5\n ```\n ```python\n # example/custom-search-space-objective.py\n\n ...\n\n def configure(cfg: DictConfig, trial: Trial) -> None:\n x_value = trial.params[\"x\"]\n trial.suggest_float(\n \"z\",\n x_value - cfg.max_z_difference_from_x,\n x_value + cfg.max_z_difference_from_x,\n )\n trial.suggest_float(\"+w\", 0.0, 1.0) # note +w here, not w as w is a new parameter\n\n ...\n ```\n\n
\n\nThe method that `custom_search_space` points to must accepts both a DictConfig with already set options and a trial object which needs further configuration. In this example we limit `z` the difference between `x` and `z` to be no more than 0.5.\nNote that this `custom_search_space` API should be considered experimental and is subject to change.\n\n### Order of trial configuration\nConfiguring a trial object is done in the following sequence:\n - search space parameters are set from the `hydra.sweeper.params` key in the config\n - Command line overrides are set\n - `custom_search_space` parameters are set\n\nIt is not allowed to set search space parameters in the `custom_search_space` method for parameters which have a fixed value from command line overrides. [Trial.user_attrs](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.trial.Trial.html#optuna.trial.Trial.user_attrs) can be inspected to find any of such fixed parameters.\n","frontmatter":{"id":"optuna_sweeper","title":"Optuna Sweeper plugin","sidebar_label":"Optuna Sweeper plugin"},"isInternal":false,"tokens":3641,"sizeBytes":13300},{"name":"ray_launcher.md","path":"website/docs/plugins/ray_launcher.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/ray_launcher.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: ray_launcher\ntitle: Ray Launcher plugin\nsidebar_label: Ray Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ray-launcher)](https://pypi.org/project/hydra-ray-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ray-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ray-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ray-launcher/month)](https://pepy.tech/project/hydra-ray-launcher)\n\nThe Ray Launcher plugin provides 2 launchers: `ray_aws` and `ray`.\n `ray_aws` launches jobs remotely on AWS and is built on top of [ray autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). `ray` launches jobs on your local machine or existing ray cluster.\n\n:::note Ray AWS support\nThe local `ray` launcher is supported as a normal Hydra plugin.\n\nThe `ray_aws` launcher is maintained on a best-effort basis. Historically, this path has required substantially more maintainer attention and infrastructure resources than other Hydra plugins. It depends on Ray autoscaler behavior and live AWS infrastructure, both of which are comparatively unstable external surfaces for Hydra to validate. Running reliable end-to-end coverage also has a real cloud-cost burden, which is difficult to justify within the project's limited maintenance budget.\n\nFixes for `ray_aws` are welcome from users who can validate them on AWS. PRs that change `ray_aws` behavior must include cheap local validation where possible and a clear report of real AWS testing for behavior that cannot be covered locally.\n\nIn the long term, if the `ray_aws` launcher becomes completely non-functional and there is no maintainer or user-contributor path to validate and repair it, support may be dropped entirely.\n:::\n\n### Installation\n\n```commandline\n$ pip install hydra-ray-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=ray_aws` or `hydra/launcher=ray` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: ray_aws\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe `ray_pkg_version` resolver now takes installed distribution names instead of\nPython import names and reads their metadata without importing the module.\nFor example, replace `${ray_pkg_version:yaml}` with `${ray_pkg_version:PyYAML}`.\n`${ray_pkg_version:hydra}` remains an alias for `hydra-core`.\nPackages must be installed, including editable installs.\nAn importable source directory alone is insufficient. If metadata is unavailable,\ninstall the package or set its version explicitly in `env_setup.pip_packages`.\n\n### `ray_aws` launcher\n\n:::important\n`ray_aws` launcher is built on top of ray's [autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). To get started, you need to\n[config your AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).\n`ray autoscaler sdk` expects your AWS credentials have certain permissions for [`EC2`](https://aws.amazon.com/ec2) and [`IAM`](https://aws.amazon.com/iam). Read [this](https://github.com/ray-project/ray/issues/9327) for more information.\n:::\n\n`ray autoscaler sdk` expects a configuration for the EC2 cluster; we've schematized the configs in here\n\n
\n Discover ray_aws launcher's config\n\n ```commandline\n $ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n # @package hydra.launcher\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\n env_setup:\n pip_packages:\n omegaconf: ${ray_pkg_version:omegaconf}\n hydra_core: ${ray_pkg_version:hydra}\n ray: ${ray_pkg_version:ray}\n cloudpickle: ${ray_pkg_version:cloudpickle}\n pickle5: 0.0.11\n hydra_ray_launcher: 1.2.0.dev1\n commands:\n - conda create -n hydra_${python_version:micro} python=${python_version:micro} -y\n - echo 'export PATH=\"$HOME/anaconda3/envs/hydra_${python_version:micro}/bin:$PATH\"'\n >> ~/.bashrc\n ray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n upscaling_speed: 1.0\n max_workers: 1\n idle_timeout_minutes: 5\n docker:\n image: ''\n container_name: ''\n pull_before_run: true\n run_options: []\n provider:\n type: aws\n region: us-west-2\n availability_zone: us-west-2a,us-west-2b\n cache_stopped_nodes: false\n key_pair:\n key_name: hydra-${oc.env:USER,user}\n auth:\n ssh_user: ubuntu\n available_node_types:\n ray.head.default:\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n ray.worker.default:\n min_workers: 0\n max_workers: 2\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n InstanceMarketOptions:\n MarketType: spot\n head_node_type: ray.head.default\n file_mounts: {}\n initialization_commands: []\n cluster_synced_files: []\n setup_commands: []\n head_setup_commands: []\n worker_setup_commands: []\n head_start_ray_commands:\n - ray stop\n - ulimit -n 65536;ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml\n worker_start_ray_commands:\n - ray stop\n - ulimit -n 65536; ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076\n run_env: auto\n stop_cluster: true\n sync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n sync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n logging:\n log_style: auto\n color_mode: auto\n verbosity: 0\n create_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\n teardown_cluster:\n workers_only: false\n keep_min_workers: false\n ```\n
\n\n\n#### Examples\n\nThe following examples can be found here.\n\n
\n Simple app\n\n ```commandline\n $ python my_app.py --multirun task=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : task=1\n [HYDRA] #1 : task=2\n [HYDRA] #2 : task=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmpqqg4v4i7/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=3374) [__main__][INFO] - Executing task 1\n (pid=3374) [__main__][INFO] - Executing task 2\n (pid=3374) [__main__][INFO] - Executing task 3\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n
\n Upload & Download from remote cluster\n\n If your application is dependent on multiple modules, you can configure `hydra.launcher.sync_up` to upload dependency modules to the remote cluster.\n You can also configure `hydra.launcher.sync_down` to download output from remote cluster if needed. This functionality is built on top of `rsync`, `include` and `exclude` is consistent with how it works in `rsync`.\n\n ```commandline\n $ python train.py --multirun random_seed=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : random_seed=1\n [HYDRA] #1 : random_seed=2\n [HYDRA] #2 : random_seed=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmptdkye9of/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n Loaded cached provider configuration\n ...\n [HYDRA] Output: receiving file list ... done\n 16-32-25/\n 16-32-25/0/\n 16-32-25/0/checkpoint/\n 16-32-25/0/checkpoint/checkpoint_1.pt\n 16-32-25/1/\n 16-32-25/1/checkpoint/\n 16-32-25/1/checkpoint/checkpoint_2.pt\n 16-32-25/2/\n 16-32-25/2/checkpoint/\n 16-32-25/2/checkpoint/checkpoint_3.pt\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n##### Manage Cluster LifeCycle\nYou can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:\n\n- Default setting (no need to specify on commandline): delete cluster after job finishes remotely:\n ```commandline\n hydra.launcher.stop_cluster=true\n hydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\n hydra.launcher.teardown_cluster.workers_only=false\n hydra.launcher.teardown_cluster.keep_min_workers=false\n ```\n\n- Keep cluster running after jobs finishes remotely\n ```commandline\n hydra.launcher.stop_cluster=false\n ```\n\n- Power off EC2 instances and control node termination using `hydra.launcher.ray.cluster.provider.cache_stopped_nodes`\nand `hydra.launcher.teardown_cluster.workers_only`\n\n | cache_stopped_nodes | workers_only | behavior |\n |---------------------|--------------|----------|\n | false | false | All nodes are terminated |\n | false | true | Keeps head node running and terminates only worker node |\n | true | false | Keeps both head node and worker node and stops both of them |\n | true | true | Keeps both head node and worker node and stops only worker node |\n\n- Keep `hydra.launcher.ray.cluster.min_workers` worker nodes\nand delete the rest of the worker nodes\n ```commandline\n hydra.launcher.teardown_cluster.keep_min_workers=true\n ```\n\nAdditionally, you can configure how to create or update the cluster:\n\n- Default config: run setup commands, restart Ray and use\nthe config cache if available\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=false\n hydra.launcher.create_update_cluster.restart_only=false\n hydra.launcher.create_update_cluster.no_config_cache=false\n ```\n\n- Skip restarting Ray services when updating the cluster config\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=true\n ```\n\n- Skip running setup commands and only restart Ray (cannot be used with\n`hydra.launcher.create_update_cluster.no_restart`)\n ```commandline\n hydra.launcher.create_update_cluster.restart_only=true\n ```\n\n- Fully resolve all environment settings from the cloud provider again\n ```commandline\n hydra.launcher.create_update_cluster.no_config_cache=true\n ```\n\n\n##### Configure Ray Logging\nYou can manage Ray specific logging by configuring the flags provided by the plugin:\n\n- Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode\n ```commandline\n hydra.launcher.logging.log_style=\"auto\"\n hydra.launcher.logging.color_mode=\"auto\"\n hydra.launcher.logging.verbosity=0\n ```\n\n- Disable pretty-print\n ```commandline\n hydra.launcher.logging.log_style=\"record\"\n ```\n\n- Disable color mode\n ```commandline\n hydra.launcher.logging.color_mode=\"false\"\n ```\n\n- Increase Ray logging verbosity\n ```commandline\n hydra.launcher.logging.verbosity=3\n ```\n\n### `ray` launcher\n\n`ray` launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing `ray` launcher's configuration here\n `~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml`\n\n The example application starts a new ray cluster.\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-16-28\n[HYDRA] Initializing ray with config: {}\nINFO services.py:1164 -- View the Ray dashboard at http://127.0.0.1:8266\n[HYDRA] #0 :\n(pid=97801) [__main__][INFO] - Executing task 1\n```\n\nYou can run the example application on your existing ray cluster as well by overriding `hydra.launcher.ray.init.address`:\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray hydra.launcher.ray.init.address=localhost:6379\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-13-32\n[HYDRA] Initializing ray with config: {'num_cpus': None, 'num_gpus': None, 'address': 'localhost:6379'}\nINFO worker.py:633 -- Connecting to existing Ray cluster at address: 10.30.99.17:6379\n[HYDRA] #0 :\n(pid=93358) [__main__][INFO] - Executing task 1\n```\n\n### Configure `ray.init()` and `ray.remote()`\nRay launcher is built on top of [`ray.init()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init)\nand [`ray.remote()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote).\nYou can configure `ray` by overriding `hydra.launcher.ray.init` and `hydra.launcher.ray.remote`.\nCheck out an example config.\n","frontmatter":{"id":"ray_launcher","title":"Ray Launcher plugin","sidebar_label":"Ray Launcher plugin"},"isInternal":false,"tokens":3727,"sizeBytes":13962},{"name":"rq_launcher.md","path":"website/docs/plugins/rq_launcher.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/rq_launcher.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: rq_launcher\ntitle: RQ Launcher plugin\nsidebar_label: RQ Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-rq-launcher)](https://pypi.org/project/hydra-rq-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-rq-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-rq-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-rq-launcher/month)](https://pepy.tech/project/hydra-rq-launcher)\n\nThe RQ Launcher plugin provides a launcher for distributed execution and job queuing based on [Redis Queue (RQ)](https://python-rq.org).\n\nRQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a [Redis server](https://redis.io/topics/quickstart). When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database.\n\n\n### Installation\n```commandline\npip install hydra-rq-launcher --upgrade\n```\nUsage of this plugin requires a [Redis server](https://redis.io/topics/quickstart).\n\nNote that RQ does [not support Windows](https://python-rq.org/docs/#limitations).\n\n### Usage\nOnce installed, add `hydra/launcher=rq` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: rq\n```\n\nThe default configuration is as follows:\n\n```yaml title=\"$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_rq_launcher.rq_launcher.RQLauncher\nenqueue:\n job_timeout: null\n ttl: null\n result_ttl: null\n failure_ttl: null\n at_front: false\n job_id: null\n description: null\nqueue: default \nredis:\n host: ${oc.env:REDIS_HOST,localhost}\n port: ${oc.env:REDIS_PORT,6379}\n db: ${oc.env:REDIS_DB,0}\n password: ${oc.env:REDIS_PASSWORD,null}\n ssl: ${oc.env:REDIS_SSL,False}\n ssl_ca_certs: ${oc.env:REDIS_SSL_CA_CERTS,null\n mock: ${oc.env:REDIS_MOCK,False}\nstop_after_enqueue: false\nwait_polling: 1.0\n```\n\nFurther descriptions on the variables can be found in the plugin config file, defined here. There are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe plugin is using environment variables to store Redis connection information. The environment variables `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, and `REDIS_PASSWORD`, are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through `REDIS_SSL` and `REDIS_SSL_CA_CERTS`; see [redis-py](https://github.com/andymccurdy/redis-py#ssl-connections) documentation.\n\nFor example, they might be set as follows when using `bash` or `zsh` as a shell:\n\n```commandline\nexport REDIS_HOST=\"localhost\"\nexport REDIS_PORT=\"6379\"\nexport REDIS_DB=\"0\"\nexport REDIS_PASSWORD=\"\"\n```\n\nEnable SSL by setting the relevant environment variables. e.g:\n```commandline\nexport REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n```\n\nAssuming configured environment variables, workers connecting to the Redis server can be launched using:\n\n```commandline\nrq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB \\\n -S hydra_plugins.hydra_rq_launcher.serializer.CloudpickleSerializer\n```\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will enqueue five jobs to be processed by worker instances:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n\n[HYDRA] RQ Launcher is enqueuing 5 job(s) in queue : default\n[HYDRA] Sweep output dir : multirun/2020-06-15/18-00-00\n[HYDRA] Enqueued 13b3da4e-03f7-4d16-9ca8-cfb3c48afeae\n[HYDRA] \t#1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] \t#2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] \t#3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] \t#4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] \t#5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n```\n\nNote that any dependencies need to be installed in the Python environment used to run the RQ worker. Workers must use Hydra's cloudpickle serializer so that job results are serialized compatibly with the RQ launcher.\n\nThe [RQ documentation](https://python-rq.org/) holds further information on [job monitoring](http://python-rq.org/docs/monitoring/), which can be done via console or [web interfaces](https://github.com/nvie/rq-dashboard), and provides [patterns](https://python-rq.org/patterns/) for worker and exception handling.\n","frontmatter":{"id":"rq_launcher","title":"RQ Launcher plugin","sidebar_label":"RQ Launcher plugin"},"isInternal":false,"tokens":1444,"sizeBytes":5081},{"name":"submitit_launcher.md","path":"website/docs/plugins/submitit_launcher.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/website/docs/plugins/submitit_launcher.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\nid: submitit_launcher\ntitle: Submitit Launcher plugin\nsidebar_label: Submitit Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-submitit-launcher)](https://pypi.org/project/hydra-submitit-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-submitit-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-submitit-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-submitit-launcher/month)](https://pepy.tech/project/hydra-submitit-launcher)\n\nThe Submitit Launcher plugin provides a [SLURM](https://slurm.schedmd.com/documentation.html) Launcher based on [Submitit](https://github.com/facebookincubator/submitit).\n\n### Installation\n```commandline\npip install hydra-submitit-launcher --upgrade\n```\n\n\n### Usage\nOnce installed, add `hydra/launcher=submitit_slurm` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: submitit_slurm\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\nNote that this plugin expects a valid environment in the target host. Usually this means a shared file system between\nthe launching host and the target host.\n\nThe Submitit Plugin implements 2 different launchers: `submitit_slurm` to run on a SLURM cluster, and `submitit_local` for basic local tests.\n\n
\n Discover the SLURM Launcher parameters (Expand)\n\n ```yaml title=\"$ python your_app.py hydra/launcher=submitit_slurm --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: null\n gpus_per_node: null\n tasks_per_node: 1\n mem_gb: null\n nodes: 1\n name: ${hydra.job.name}\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.SlurmLauncher\n partition: null\n qos: null\n comment: null\n constraint: null\n exclude: null\n gres: null\n cpus_per_gpu: null\n gpus_per_task: null\n mem_per_gpu: null\n mem_per_cpu: null\n account: null\n signal_delay_s: 120\n max_num_timeout: 0\n python: null\n additional_parameters: {}\n array_parallelism: 256\n setup: null\n srun_args: null\n use_srun: true\n ```\n
\n
\n Discover the Local Launcher parameters (Expand)\n\n ```yaml title=\"$ python example/my_app.py hydra/launcher=submitit_local --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.LocalLauncher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: 1\n gpus_per_node: 0\n tasks_per_node: 1\n mem_gb: 4\n nodes: 1\n name: ${hydra.job.name}\n ```\n
\n\n
\nYou can set all these parameters in your configuration file and/or override them in the command-line:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.timeout_min=3\n```\nSet `hydra.launcher.tasks_per_node=null` to omit `--ntasks-per-node` from the\ngenerated Slurm submission.\n\nSet `hydra.launcher.use_srun=false` to run Python directly in the batch script\ninstead of through `srun`. The default is `true`. When disabled, Python runs\nonce on the batch node, and `srun_args` is ignored; Slurm does not automatically\nlaunch the other requested tasks.\n\nSet `hydra.launcher.python` to use a Python executable other than the one\nrunning Hydra:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.python=/opt/venv/bin/python\n```\n\nFor more details, including descriptions for each parameter, check out the config file.\nYou can also check the [Submitit documentation](https://github.com/facebookincubator/submitit).\n\n\n**Caution**: use of `--multirun` is required for the launcher to be picked up.\n\n### Example\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py task=1,2,3 --multirun` (see [Multi-run](../tutorials/basic/running_your_app/2_multirun.md) for details) will launch 3 executions (you can override the launcher to run locally for testing by adding `hydra/launcher=submitit_local`):\n\n```text\n$ python my_app.py task=1,2,3 --multirun\n[HYDRA] Sweep output dir : multirun/2020-05-28/15-05-22\n[HYDRA] #0 : task=1\n[HYDRA] #1 : task=2\n[HYDRA] #2 : task=3\n```\nYou will be able to see the output of the app in the output dir:\n```commandline\n$ tree\n.\n├── 0\n│   └── my_app.log\n├── 1\n│   └── my_app.log\n├── 2\n│   └── my_app.log\n└── multirun.yaml\n\n$ cat 0/my_app.log\n[2020-05-28 15:05:23,511][__main__][INFO] - Process ID 15887 executing task 1 ...\n[2020-05-28 15:05:24,514][submitit][INFO] - Job completed successfully\n```\n","frontmatter":{"id":"submitit_launcher","title":"Submitit Launcher plugin","sidebar_label":"Submitit Launcher plugin"},"isInternal":false,"tokens":1471,"sizeBytes":5216},{"name":"README.md","path":"examples/plugins/example_configsource_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_configsource_plugin/README.md","title":"example_configsource_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example config source\nUse this as the template a Hydra config source plugin\n\nConfig source plugins are allowing Hydra to recognize other search path schemas in addition to the built in \n`file://` (which provides access to configs in the file system) and \n`pkg://` (which provides access to configs installed with a Python package) \n\nThis config source hard codes all the responses so it's not very useful.\nPlease base your tests on the data in hydra_root/tests/test_apps/config_source_test/dir.\n\nAll config sources need to pass the ConfigSourceTestSuite tests, which are expecting those specific responses.\nWhen implementing a new config source, be sure to run it through the test suite to ensure it always behaves the same\nas the other config sources.\n","isInternal":false,"tokens":155,"sizeBytes":762},{"name":"README.md","path":"examples/plugins/example_generic_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_generic_plugin/README.md","title":"example_generic_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example plugin\nthis plugin is not very useful, but demonstrates the plugin discovery capability of Hydra.\n\nCore plugins (Plugins that are developed jointly with Hydra) lives in the plugins subdirectory inside the Hydra repo.\nThird party plugins can live anywhere (public or private Github repos, Organizations in-house SCM etc)","isInternal":false,"tokens":62,"sizeBytes":335},{"name":"README.md","path":"examples/plugins/example_launcher_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_launcher_plugin/README.md","title":"example_launcher_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Launcher for Hydra.\nThe configuration for this launcher is in packages with the plugin:\n\n```yaml title=\"hydra_plugins/example_launcher_plugiun/conf/hydra/launcher/example.yaml\"\n_target_: hydra_plugins.example_launcher_plugin.example_launcher.ExampleLauncher\nfoo: 10\nbar: abcde\n```\nThe example application is overriding the Launcher used by Hydra.\nWhen the launcher is initialized, its \"using\" the foo and bar parameters.\n\nOutput of the example application:\n```text\n$ python example/my_app.py --multirun db=postgresql,mysql\n[2019-10-22 19:45:05,060] - Example Launcher(foo=10, bar=abcde) is launching 2 jobs locally\n[2019-10-22 19:45:05,060] - Sweep output dir : multirun/2019-10-22/19-45-05\n[2019-10-22 19:45:05,060] - #0 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n\n[2019-10-22 19:45:05,135] - #1 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n```\n","isInternal":false,"tokens":302,"sizeBytes":1010},{"name":"README.md","path":"examples/plugins/example_registered_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_registered_plugin/README.md","title":"example_registered_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example plugin via `Plugins.register`\nThis plugin is not very useful, but it demonstrates how to register a plugin using the `Plugins.register` method.","isInternal":false,"tokens":32,"sizeBytes":159},{"name":"README.md","path":"examples/plugins/example_searchpath_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_searchpath_plugin/README.md","title":"example_searchpath_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example SearchPath plugin\n\nThis plugin provides an example for how to write a SearchPathPlugin that can manipulate the search path.\nTypical use cases includes:\n * A framework that wants to allow user code to discover its configurations and be able to compose with them.\n * A plugin that wants to extend Hydra or another plugin by providing additional configs in existing config groups like `hydra/launcher`.\n * A plugin that can replace the default configuration of another plugin or of Hydra itself by prepending its configurations before those that it want to replace.\n \nSearchPath plugins are discovered and enabled automatically once they are installed.\nYou can use `python foo.py --info` to see the search path and the installed plugins.\n","isInternal":false,"tokens":143,"sizeBytes":751},{"name":"README.md","path":"examples/plugins/example_sweeper_plugin/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/examples/plugins/example_sweeper_plugin/README.md","title":"example_sweeper_plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Sweeper for Hydra.\nThe provided example has a custom configuration for the sweeper that takes overrides a few parameters:\n```yaml\n_target_: hydra_plugins.example_sweeper_plugin.example_sweeper.ExampleSweeper\n# max number of jobs to run in the same batch.\nmax_batch_size: null\nfoo: 10\nbar: abcde\n```\n\n#### Example app using custom sweeper:\n```text\n$ python example/my_app.py -m db=mysql,postgresql\n[2019-11-14 11:42:47,941][HYDRA] ExampleSweeper (foo=10, bar=abcde) sweeping\n[2019-11-14 11:42:47,941][HYDRA] Sweep output dir : multirun/2019-11-14/11-42-47\n[2019-11-14 11:42:47,942][HYDRA] Launching 2 jobs locally\n[2019-11-14 11:42:47,942][HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[2019-11-14 11:42:48,011][HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n```\n","isInternal":false,"tokens":324,"sizeBytes":948},{"name":"README.md","path":"plugins/hydra_ax_sweeper/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_ax_sweeper/README.md","title":"hydra_ax_sweeper Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Ax Sweeper\nProvides a [`Ax Sweeper`](https://ax.dev/) based Hydra Sweeper supporting parallel execution.\n\nHydra 1.4 will include the final first-party release, based on the existing\nimplementation. The plugin code will be removed in the Hydra 1.5 line, and no\nfirst-party releases will be published for Hydra 1.5 or later. Existing PyPI\nreleases will remain available. See the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506)\nfor the schedule and invitation for community ownership in a separate repository.\n\nSee [website](https://hydra.cc/docs/plugins/ax_sweeper/) for more information\n","isInternal":false,"tokens":150,"sizeBytes":619},{"name":"README.md","path":"plugins/hydra_colorlog/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_colorlog/README.md","title":"hydra_colorlog Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra colorlog\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\nSee [website](https://hydra.cc/docs/plugins/colorlog) for more information\n","isInternal":false,"tokens":72,"sizeBytes":264},{"name":"README.md","path":"plugins/hydra_joblib_launcher/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_joblib_launcher/README.md","title":"hydra_joblib_launcher Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Joblib Launcher\nProvides a [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html) based Hydra Launcher supporting parallel execution.\n\nSee [website](https://hydra.cc/docs/plugins/joblib_launcher) for more information\n","isInternal":false,"tokens":54,"sizeBytes":245},{"name":"README.md","path":"plugins/hydra_nevergrad_sweeper/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_nevergrad_sweeper/README.md","title":"hydra_nevergrad_sweeper Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Nevergrad Sweeper plugin\n\nProvides a mechanism for Hydra applications to use [Nevergrad](https://github.com/facebookresearch/nevergrad) algorithms for the optimization of the parameters of any experiment.\n\nSee [website](https://hydra.cc/docs/plugins/nevergrad_sweeper) for more information","isInternal":false,"tokens":62,"sizeBytes":297},{"name":"README.md","path":"plugins/hydra_optuna_sweeper/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_optuna_sweeper/README.md","title":"hydra_optuna_sweeper Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Optuna Sweeper\n\nProvides an [Optuna](https://optuna.org) based Hydra Sweeper.\n\nSee [website](https://hydra.cc/docs/plugins/optuna_sweeper/) for more information.\n","isInternal":false,"tokens":45,"sizeBytes":170},{"name":"README.md","path":"plugins/hydra_ray_launcher/integration_test_tools/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_ray_launcher/integration_test_tools/README.md","title":"integration_test_tools Documentation","category":"plugin-manifest","format":"markdown","content":"## Setting up a new testing AMI for ray launcher.\n\nTo run the tool:\n\n- Make sure the dependencies in `setup_integration_test_ami.py` matches exactly ray launcher's `setup.py`.\n- Install AWS CLI, check AWS documentation for more details.\n- Before running the tool, set up your aws profile with admin access to the Hydra test AWS account.\n```\nAWS_PROFILE=jieru python create_integration_test_ami.py\n```\nYou will see a new AMI created in the output\n```commandline\nec2.Image(id='ami-0d65d5647e065a180') current state pending\n...\n```\nSometimes it could take hours for a new AMI to be created. Proceed to the next step once the \nAMI becomes available.\n\n- Run the tests locally with the new AMI:\n ```shell\n AWS_RAY_AMI= pytest ../tests/ray_aws_launcher_tests_disabled.py\n ```\n- Debug if needed.\n- Create a PR and make sure all CI pass!\n","isInternal":false,"tokens":212,"sizeBytes":840},{"name":"README.md","path":"plugins/hydra_ray_launcher/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_ray_launcher/README.md","title":"hydra_ray_launcher Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Ray Launcher\nProvides a [`Ray`](https://docs.ray.io/en/latest/) based Hydra Launcher supporting execution on AWS.\n\nSee [website](https://hydra.cc/docs/plugins/ray_launcher) for more information\n","isInternal":false,"tokens":46,"sizeBytes":202},{"name":"README.md","path":"plugins/hydra_rq_launcher/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_rq_launcher/README.md","title":"hydra_rq_launcher Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra RQ Launcher\nProvides a [Redis Queue (RQ)](https://python-rq.org) launcher for Hydra supporting distributed execution and job queuing.\n\nSee [website](https://hydra.cc/docs/plugins/rq_launcher) for more information\n","isInternal":false,"tokens":53,"sizeBytes":221},{"name":"README.md","path":"plugins/hydra_submitit_launcher/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/plugins/hydra_submitit_launcher/README.md","title":"hydra_submitit_launcher Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Submitit Launcher\nProvides a [`Submitit`](https://github.com/facebookincubator/submitit) based Hydra Launcher supporting [SLURM ](https://slurm.schedmd.com/documentation.html).\n\nSee [website](https://hydra.cc/docs/plugins/submitit_launcher) for more information","isInternal":false,"tokens":64,"sizeBytes":269},{"name":"README.md","path":"tools/configen/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/tools/configen/README.md","title":"configen Documentation","category":"plugin-manifest","format":"markdown","content":"# configen\n\nAutomatically generates Structured Configs that can be used with hydra.utils.instantiate()\n\nThis is optional at two levels:\n1. Structured Configs are optional, one can use Hydra without them.\n2. One can manually code these dataclasses. The advantage of this tool is that it does the work automatically.\n\n# Setup\nConfigen requires config file per project. The config indicates what classes to generate code for, where to put\nthe generated code etc.\nConfigen will suggest creating a config on the first run:\n```\n$ configen\n[2020-08-14 12:06:11,359][configen.configen][ERROR] -\nUse --config-dir DIR --config-name NAME\ne.g:\n\tconfigen --config-dir conf --config-name configen\n\nIf you have no config dir yet use init_config_dir=DIR to create an initial config dir.\ne.g:\n\tconfigen init_config_dir=conf\n```\n\nThis will generate a basic config similar to:\n```yaml\n$ cat conf/configen.yaml\ndefaults:\n - configen_schema\n - _self_\n\nconfigen:\n # output directory\n output_dir: ${hydra:runtime.cwd}/example\n\n header: |\n # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n # Generated by configen, do not edit.\n # See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n # fmt: off\n # isort:skip_file\n # flake8: noqa\n\n module_path_pattern: 'config/{{module_path}}.py'\n\n # list of modules to generate configs for\n modules:\n - name: configen.samples.my_module\n # for each module, a list of classes\n classes:\n - User\n - Admin\n```\n\nConfigen comes with a few samples [classes](configen/samples) that are being processed by the default config.\nFor example:\n```python title=\"configen/samples/my_module.py\"\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n\n\nclass User:\n def __init__(self, age: int, name: str):\n self.age = age\n self.name = name\n\n def __repr__(self):\n return f\"User: name={self.name}, age={self.age}\"\n\n\nclass Admin(User):\n def __init__(self, private_key: str, age: int, name: str) -> None:\n super().__init__(age, name)\n self.private_key = private_key\n\n def __repr__(self):\n return (\n f\"Admin: name={self.name}, age={self.age}, private_key={self.private_key}\"\n )\n```\n\nRunning configen with this config directory:\n```\n$ configen --config-dir conf --config-name configen\n[2020-08-14 12:44:54,990][configen.configen][INFO] - configen.samples.my_module.configen.samples.my_module -> /home/omry/tmp/configen/example/config/configen/samples/my_module.py\n```\n\nWill result in a file `example/config/configen/samples/my_module.py` like:\n```python\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n# Generated by configen, do not edit.\n# See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n# fmt: off\n# isort:skip_file\n# flake8: noqa\n\nfrom dataclasses import dataclass, field\nfrom omegaconf import MISSING\n\n\n@dataclass\nclass UserConf:\n _target_: str = \"configen.samples.my_module.User\"\n age: int = MISSING\n name: str = MISSING\n\n\n@dataclass\nclass AdminConf:\n _target_: str = \"configen.samples.my_module.Admin\"\n private_key: str = MISSING\n age: int = MISSING\n name: str = MISSING\n```\n\nThe generated code can be used by a Hydra application to instantiate the user object.\nSee the [example application](example/my_app.py).\n","isInternal":false,"tokens":871,"sizeBytes":3353},{"name":"README.md","path":"tools/landscape/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/tools/landscape/README.md","title":"landscape Documentation","category":"plugin-manifest","format":"markdown","content":"# Hydra Landscape tools\n\nThese tools support discovery, analysis, review, and publication of projects in\nthe [Hydra Landscape](../../website/docs/landscape.mdx). They do not approve\nprojects automatically. Inclusion and featured status are maintainer decisions.\n\nThe tracked files under this directory are reusable tooling and durable human\ndecisions. Large crawls, AI output, refreshed GitHub metadata, and generated\nreview queues remain under `temp/hydra-dependents/`.\n\nInstall the Python 3.10 compatibility dependency when needed:\n\n```bash\n.venv/bin/pip install -r tools/landscape/requirements.txt\n```\n\n`data/decisions.json` is the canonical source for both curation decisions and\nthe public listing of every included project. Do not edit\n`website/src/data/landscape.json` directly; website commands regenerate it from\nthe decision ledger.\n\n## Pipeline\n\n1. Collect mechanical Hydra usage evidence from the dependency crawl:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_usage.py\n ```\n\n2. Route projects for review, optionally using the locally authenticated Codex\n CLI to analyze a resumable batch:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_projects.py\n .venv/bin/python tools/landscape/analyze_hydra_projects.py --ai\n ```\n\n Analyze explicit repositories with repeated `--repo owner/name` arguments.\n The default AI model is `gpt-5.6-terra` with medium reasoning effort.\n\n3. Refresh current GitHub maintenance metadata:\n\n ```bash\n .venv/bin/python tools/landscape/refresh_landscape_metadata.py\n ```\n\n4. Build the evidence-backed human review queue:\n\n ```bash\n .venv/bin/python tools/landscape/build_landscape_review.py\n ```\n\n5. Record maintainer decisions in `data/decisions.json`. Every included\n decision must contain its complete public `listing`. Regenerate the public\n data directly when needed:\n\n ```bash\n .venv/bin/python tools/landscape/build_public_landscape.py\n ```\n\nThe public generator reads no crawl, AI, review, or live GitHub data. It writes\n`website/src/data/landscape.json` deterministically from the decision ledger.\nThe website's `start`, `build`, and `deploy` commands run it automatically.\n\n## Tests\n\nRun the focused suite with:\n\n```bash\nPYTHONPATH=tools/landscape .venv/bin/pytest tools/landscape\n```\n","isInternal":false,"tokens":527,"sizeBytes":2296},{"name":"README.md","path":"tools/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/tools/README.md","title":"tools Documentation","category":"plugin-manifest","format":"markdown","content":"Standalone Hydra related tools","isInternal":false,"tokens":5,"sizeBytes":30},{"name":"README.md","path":"tools/release/README.md","rawUrl":"https://raw.githubusercontent.com/facebookresearch/hydra/HEAD/tools/release/README.md","title":"release Documentation","category":"plugin-manifest","format":"markdown","content":"## Release tool\n\nThis tool keeps Hydra release operations package-aware. It knows about\n`hydra-core`, the bundled plugins, and `hydra-configen`, and can check versions,\nset versions, and build distributions.\n\nPublishing is intentionally handled by GitHub Actions Trusted Publishing, not by\nthis local tool. The publish workflows call this tool to build artifacts, then\nupload them from GitHub Actions.\n\n### Package sets\n\n- `set=hydra-core`: `hydra-core` only.\n- `set=hydra-plugins`: all bundled Hydra plugins.\n- `set=hydra-full-release`: `hydra-core` plus all bundled Hydra plugins.\n- `set=configen`: `hydra-configen` only.\n- `set=all`: `hydra-core`, `hydra-configen`, and all bundled Hydra plugins.\n\nUse `only=[,...]` to narrow a package\nset without creating a new named set. Package config names are the keys under\n`tools/release/conf/packages/`, for example:\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n repository=pypi\n```\n\nQuote comma-separated filters so the quotes reach Hydra when passing more than\none package through a shell, for example\n`only=\\\"hydra_optuna_sweeper,hydra_ray_launcher\\\"`.\n\n### Check published versions\n\n```shell\npython tools/release/release.py \\\n action=check \\\n set=hydra-full-release \\\n repository=pypi\n```\n\nThis reports whether each local version already exists on the selected\nrepository, with the latest non-yanked wheel shown as context.\n\n### Set an explicit version\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev2\n```\n\nUse this for coordinated dev releases where `hydra-core` and the bundled plugins\nshould share the same version.\n\n### Validate prepared versions\n\n```shell\npython tools/release/release.py \\\n action=validate_versions \\\n set=hydra-full-release \\\n version=1.4.0\n```\n\nThis fails if any selected package is not already at the expected version. The\npublish workflow uses this to verify prepared release state before building and\nuploading artifacts.\n\n### Bump published packages\n\n```shell\npython tools/release/release.py action=bump set=hydra-full-release\n```\n\nThis increments only packages whose local version exactly matches the latest\npublished version on PyPI. It is useful for continuing an existing release\nseries, but less useful when aligning multiple packages to a specific version.\n\n### Build artifacts\n\nBuild only packages whose local version has not already been published to PyPI:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n repository=pypi \\\n clean_build_dir=true \\\n require_artifacts=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nBuild every package in a set, ignoring repository state:\n\n```shell\npython tools/release/release.py \\\n action=build \\\n set=hydra-full-release \\\n build_policy=all \\\n clean_build_dir=true \\\n build_dir=\"${PWD}/dist\"\n```\n\nThe GitHub publish workflows use the repository-aware form so already-published\nfiles are not uploaded again.\n\nBoth build and dev-release validation reject source distributions containing a\nJAR without `ATTRIBUTION/LICENSE-antlr4`, and wheels containing any JAR. These\nchecks run before the publish workflow uploads distribution artifacts.\n\nThe workflows also write a release summary listing the target repository,\npublish mode, trigger, ref, commit, and every artifact that was built.\n\n### Dev release\n\nRun a dry run for a coordinated dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3\n```\n\nRun a dry run for a single plugin dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-plugins \\\n only=hydra_optuna_sweeper \\\n version=1.4.0.dev3\n```\n\nThe dry run prints the selected packages, current local versions, target\nversions, PyPI status for the target version, and the exact publish workflow\ndispatch that would run. It also builds artifacts in a temporary release\nworkspace, runs `twine check`, and smoke-installs the built wheels without\ndependencies. It does not commit, push, dispatch GitHub Actions, create or edit\na GitHub Release, or upload anything to PyPI.\n\nTo publish the dev release:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n publish=true\n```\n\nPublishing first confirms that the selected commit exists on the configured\nGitHub remote, without requiring it to be the branch tip. It also requires a\nclean working tree. In the normal release flow, the selected packages already\nhave the target version because it was set immediately after the previous\nrelease. The command dispatches `Publish to PyPI` with the selected package set,\nexpected version, and exact commit. If the versions differ, it can set, commit,\nand push the target version as a recovery path, then pins the resulting current\ncommit so later pushes cannot change what the workflow builds.\n\nIf the branch has already advanced past an unshipped dev release, select its\nexisting commit explicitly. The dry run archives that exact commit, requires\nthe selected package versions to already match, and builds its artifacts without\nchanging the current checkout:\n\n```shell\npython tools/release/release.py \\\n action=dev_release \\\n set=hydra-full-release \\\n version=1.4.0.dev3 \\\n commit=\n```\n\nAfter the dry run passes, repeat the command with `publish=true`. Explicit\ncommit mode never sets versions, commits, or pushes; the commit must already\nexist locally and on GitHub. The tool uses `workflow_ref=main` by default; use\n`workflow_ref=` for unusual release lines.\n\nAfter the publish workflow succeeds, immediately set the next coordinated\ndevelopment version, commit, and push it before resuming development:\n\n```shell\npython tools/release/release.py \\\n action=set_version \\\n set=hydra-full-release \\\n version=1.4.0.dev4\n```\n\nThis prevents new development from reporting a version that has already been\npublished.\n\n### Prepare and publish workflow responsibilities\n\nHydra release automation is split into prepare and publish phases.\n\nPrepare release should:\n\n- accept a release line, selected package set, and target version changes;\n- derive the release kind from the selected target versions;\n- derive the target branch from the release line and release kind;\n- validate package versions against the release line and selected package set;\n- compare selected packages against PyPI;\n- produce a release-validation matrix;\n- run release-only checks such as the core suite with all selected compatible\n plugins installed;\n- create or update release-prep PRs when needed.\n\nFor release candidates, stable releases, and patch releases, generated\nrelease-prep PRs are the maintainer approval surface for publishing. The PR body\nmust state clearly what happens when the PR is merged. Once release-prep PR\nautomation exists, merging such a PR should trigger PyPI publishing, and the PR\nbody must list the exact package set and version that will be published.\n\nPublish should:\n\n- revalidate the prepared release state;\n- build selected package artifacts;\n- check built artifacts;\n- publish only selected package artifacts through GitHub Actions Trusted\n Publishing;\n- eventually create or update the GitHub Release as a record of the published\n release.\n\nThe local release tool owns package metadata, version checks, repository\ncomparison, and artifact building. GitHub Actions owns release validation and\nTrusted Publishing. GitHub Release state transitions are intended release\nautomation work, but are not wired into the current publish workflow.\n\nThe current `Prepare Release` workflow implements the validation part of this\nsplit: it derives release kind and target branch, applies the target version\ninside the disposable workflow checkout, checks selected packages against PyPI,\nbuilds artifacts, and runs release validation. The current `Publish to PyPI`\nworkflow is manual-only. GitHub Release creation or edits do not trigger\npublishing. Release-prep PR automation is planned but not implemented yet.\n","isInternal":false,"tokens":1760,"sizeBytes":8147}],"systemPromptSnippet":"\n\n# AGENTS.md\n\nRepo-specific directives for coding agents working in this project.\n\n## Behavioral defaults\n\nThese guidelines are intended to reduce common LLM coding mistakes. Apply them\nalongside the repo-specific rules below. They bias toward caution over speed,\nand for truly trivial tasks you may use judgment.\n\n### Think before coding\n\n- Do not assume.\n- Do not hide confusion.\n- Surface tradeoffs.\n- State assumptions explicitly when they matter to the implementation.\n- If multiple reasonable interpretations exist, present them instead of silently picking one.\n- If a simpler approach exists, say so.\n- Push back when warranted.\n- If something material is unclear or risky, stop, name what is confusing, and ask instead of guessing.\n\n### Simplicity first\n\n- Solve the requested problem with the minimum code necessary.\n- No features beyond what was asked.\n- No abstractions for single-use code.\n- No flexibility or configurability that was not requested.\n- No error handling for scenarios that are effectively impossible in context.\n- If a solution feels overbuilt for the task, simplify it before considering it done.\n- If you write 200 lines and the same result could be achieved in 50, rewrite it.\n- Ask: would a senior engineer say this is overcomplicated? If yes, simplify.\n\n### Surgical changes\n\n- Touch only what is needed for the request.\n- Do not \"clean up\" adjacent code, comments, formatting, or structure unless the change requires it.\n- Match the existing style and patterns of the codebase unless the user asks for a broader refactor.\n- If you notice unrelated dead code or issues nearby, mention them instead of fixing them opportunistically.\n- Remove imports, variables, functions, or other artifacts that your change makes unused.\n- Do not delete unrelated pre-existing dead code unless asked.\n- Every changed line should trace directly to the user's request.\n\n### Prefer focused tools over ad hoc shell\n\nUse repository-aware file inspection and edit tools for file operations. Reserve\nshell commands for things that genuinely require shell execution: `sl`\n(Sapling) commands, `gh`, dependency installation, or `nox` / `pytest` /\n`python` for tests, linting, and other repo tooling.\n\n- Use `rg` for text search and `rg --files` for file discovery.\n- Avoid inline Python snippets (`python -c ...`) when a dedicated tool or standard CLI utility is sufficient.\n- Use structured tools such as `jq` to parse JSON shell output instead of piping to Python.\n\n### Goal-driven execution\n\n- Translate requests into concrete success criteria that can be verified.\n- For bug fixes, prefer reproducing the issue with a test or other reliable check before fixing it.\n- For refactors, prefer checks that demonstrate behavior is preserved before and after.\n- For multi-step tasks, keep a brief plan in mind and verify each step before calling the work complete.\n- Favor specific goals over vague ones:\n - \"Add validation\" -> write tests for invalid inputs, then make them pass.\n - \"Fix the bug\" -> reproduce it with a test or reliable check, then make it pass.\n - \"Refactor X\" -> verify behavior before and after the refactor.\n\n## Documentation map\n\n- Website and docs source: [`website/`](./website/)\n- Current docs: [`website/docs/`](./website/docs/)\n- Development docs: [`website/docs/development/`](./website/docs/development/)\n- Plugin docs: [`website/docs/plugins/`](./website/docs/plugins/)\n- Versioned docs: [`website/versioned_docs/`](./website/versioned_docs/)\n\n## Reproduction files\n\nWhen asked to create a reproduction for an issue, place files under\n`temp/repro/`:\n\n- Single-file repro: `temp/repro/.py`\n- Multi-file repro: `temp/repro//`\n\n## Scratch files\n\nPlace low-value, disposable temporary files under `temp/scratch/`. Its contents\nmay be cleared weekly without review. Do not store reproductions, resumable\nworkflow state, unique evidence, or drafts awaiting use there.\n\n## Stop and ask\n\n- If a tracked repo file appears unexpectedly renamed, moved, regenerated, deleted, or otherwise changed, stop and ask before reverting, recreating, reclassifying, or staging over that change.\n- Do not change supported Python versions, CI matrices, packaging metadata, release automation, or workflow triggers unless the request explicitly includes that scope.\n\n## Verification\n\n- For any new or changed functionality, test it in two layers when practical:\n - run relevant focused tests with `pytest path/to/test_file.py`\n - run the relevant `nox` session to ensure no regressions\n- Hydra core tests run with `pytest` from the repository root.\n- Plugin tests run from the plugin directory after installing the plugin, or via `nox -s test_plugins`.\n- Use `PLUGINS=` with `nox` when validating one plugin.\n- If the broader suite disagrees with focused tests, trust the broader result and do not call the change verified.\n- If live verification is blocked by the current environment, request escalation if that would unblock it. If not, stop and ask for guidance.\n\n## Linting and formatting\n\nRun linting through `nox -s lint lint_plugins` when validating broad changes.\nThe repo's lint sessions include formatting, import sorting, type checks, style,\nYAML linting, and security checks.\n\nFor focused local checks, use the same tools the noxfile runs:\n\n- `ruff format .` / `ruff format --check .`\n- `ruff check .` / `ruff check --fix .`\n- `pyrefly check --config pyproject.toml`\n- `yamllint --strict .`\n- `bandit --exclude ./.nox/** -ll -r .`\n\n## Environment and hooks\n\n- Run commands from the repo-local `.venv` by default. Prefer\n `.venv/bin/python`, `.venv/bin/pip`, `.venv/bin/pytest`, and\n `.venv/bin/nox` when those entry points exist.\n- If `.venv` is missing and dependency installation is in scope, create it\n with `python -m venv .venv`, then install `requirements/dev.txt` and the\n editable checkout into that environment.\n- Use a separate environment only when testing a specific supported Python\n version or reproducing an environment-specific issue.\n- When validating contributor setup, shell initialization, or hook behavior, verify it from the same environment a developer would actually use, such as a normal shell session or `sl commit`, not only from a temporary sandbox-only environment.\n- Prefer hooks that do not depend on nontrivial user-environment tooling.\n- If an environment override is required for one command, explain why it must be part of that same process invocation.\n- If a small system tool would materially simplify the workflow, it is fine to suggest it or ask the user to install it.\n\n## Source control and PRs\n\nUse the VCS tooling that matches the current checkout. Some Hydra worktrees are\nSapling (`sl`) checkouts, while others may be plain Git clones.\n\n- Prefer the checkout's native tool for local operations such as status, log, diff, commit, amend, and stack inspection.\n- In a Sapling checkout, use `sl` for normal local VCS operations.\n- Keep escalated VCS commands minimal and single-purpose.\n- Do not bundle staging, environment bootstrapping, dependency installation, and commit creation into one escalated shell command unless there is no practical alternative.\n- If a VCS operation requires escalation, ask only for the specific action that needs it.\n- Do not force-push, submit, or otherwise update a remote branch unless the user explicitly asks for that outward action.\n- Before using low-level fallback commands, such as `git --git-dir .sl/store/git` in a Sapling checkout, stop and explain why the normal workflow is not sufficient.\n\n## Release and news fragments\n\n- Do not commit, push, merge, publish, or otherwise send changes outside the local working tree unless the user explicitly asks for that outward action.\n- If a change alters release automation, workflow triggers, deployment behavior, or other externally visible project mechanics, require an explicit user review checkpoint before any commit, push, merge, publish, or deployment action.\n- All non-trivial product-user-visible changes should have a news fragment.\n- Core Hydra fragments go under `news/`; plugin-specific fragments go under the relevant plugin's `news/` directory.\n- Fragment filenames follow the pattern `.`.\n- Supported categories are `api_change`, `feature`, `bugfix`, `docs`, `config`, and `maintenance`.\n- Fragment text must be concise, user-facing, sentence case, and preferably under 80 characters.\n- Developer-only tooling, repo maintenance, and CI-only changes do not need a fragment unless they change the shipped product experience.\n- The user handles releases. Do not edit version numbers, create release files, assemble release notes, or otherwise perform release-cut steps unless explicitly asked.\n- The documented release process lives in [`website/docs/development/release.md`](./website/docs/development/release.md). Do not improvise a manual release flow.\n\n## Reviews\n\n- When asked to review a commit, pull request, or diff, cover correctness, completeness, documentation, and internal consistency.\n- Verify that each product-user-visible change includes an appropriate news fragment and that the fragment matches the implementation and docs.\n\n\n# Copilot instructions\n\nWhen generating code or reviewing pull requests for this repository, use\n`CONTRIBUTING.md` as the source of truth for contributor requirements.\n\nFor pull request reviews, check the changed files against the contributor\nguidelines and call out only actionable gaps, especially:\n\n- missing or insufficient tests for code changes;\n- missing documentation updates for API or behavior changes;\n- missing news fragments for non-trivial user-visible changes;\n- news fragments in the wrong `news/` directory or with the wrong category;\n- non-trivial features, API changes, or behavior changes that do not link to\n prior maintainer agreement in an issue or design discussion;\n- validation claims that are not supported by the tests or checks shown in the\n pull request.\n\nDo not request a news fragment for developer-only tooling, repository\nmaintenance, or CI-only changes unless the change affects the shipped product\nexperience.\n\nKeep review comments specific and actionable. Prefer pointing to the relevant\nguideline in `CONTRIBUTING.md` over restating the whole policy.\n\n\n---\nid: develop\ntitle: Plugin development\nsidebar_label: Plugin development\n---\n\n:::info\nIf you develop plugins, please join the Plugin developer announcement chat channel.\n:::\n\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra plugins must be registered before they can be used. Declare an entry\npoint in the `hydra.plugins` group for each plugin class, or call the\n`register` method on Hydra's `Plugins` singleton. Hydra 1.4 also discovers\nplugins in the `hydra_plugins` namespace for compatibility, but this method is\ndeprecated. See the [plugin discovery migration guide](/docs/upgrades/1.3_to_1.4/plugin_discovery).\n\n## Entry point discovery\n\nFor example, in `setup.py`:\n\n```python\nsetup(\n # ...\n entry_points={\n \"hydra.plugins\": [\n \"my_launcher = my_package.my_launcher:MyLauncher\",\n ]\n },\n)\n```\n\nThe target must be a concrete Hydra plugin class. Its module should also\nregister any associated Hydra configuration when imported. Plugin classes no\nlonger need to live in the `hydra_plugins` namespace. Keep expensive optional\ndependencies out of module-level imports.\n\n## Legacy namespace discovery\n\nIf you create a Plugin and want it to be discovered automatically by Hydra, keep the following things in mind:\n- Namespace-discovered plugins can be either standalone packages or part of an\n existing package. They must be in the top-level `hydra_plugins` namespace.\n- Do __NOT__ place an `__init__.py` file in `hydra_plugins` (doing so may break other installed Hydra plugins).\n \nThe plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of `hydra_plugins`. Hydra will import each module and look for plugins defined in that module.\nAny module under `hydra_plugins` that is slow to import will slow down the startup of __ALL__ Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with `_` (but not `__`).\nFor example, the file `_my_plugin_lib.py` would not be imported and scanned, while `my_plugin_lib.py` would be.\n\n## Plugin registration via the `Plugins.register` method\n\nPlugins can be manually registered by calling the `register` method on the instance of Hydra's `Plugins` singleton class.\n```python\nfrom hydra.core.plugins import Plugins\nfrom hydra.plugins.plugin import Plugin\n\nclass MyPlugin(Plugin):\n ...\n\ndef register_my_plugin() -> None:\n \"\"\"Hydra users should call this function before invoking @hydra.main\"\"\"\n Plugins.instance().register(MyPlugin)\n```\n\n## Getting started\n\nThe best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:\n- Copy the subtree of the relevant example plugin into a standalone project.\n- Edit `setup.py`, rename the plugin module, and declare its entry point.\n- Install the new plugin (Run this in the plugin directory: `pip install -e .`)\n- Run the included example app and make sure that the plugin is discovered:\n```shell\n$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n```\n- Run the example application to see that that your plugin is doing something.\n- *[Optional]* Embed the plugin in your existing application or library. An\n entry-point plugin can use any importable package name.\n- Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.\n\nFor a `SearchPathPlugin` that provides organization-specific Hydra defaults,\nsee [Environment-specific overrides](../../patterns/environment_specific_overrides.md).\n\n\n---\nid: overview\ntitle: Plugins Overview\nsidebar_label: Plugins Overview\n---\n\nimport GithubLink from \"@site/src/components/GithubLink\"\n\nHydra can be extended via plugins.\nThe example plugins here can help you get started with plugin development.\n\n## Plugin types\nHydra has several plugin types:\n### Sweeper\nA sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:\n```\nbatch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n```\n\nAnd creates 4 jobs with the following parameters:\n```\nbatch_size=128 optimizer=nesterov learning_rate=0.01\nbatch_size=128 optimizer=nesterov learning_rate=0.1\nbatch_size=128 optimizer=adam learning_rate=0.01\nbatch_size=128 optimizer=adam learning_rate=0.1\n```\n\n### Launcher\nLaunchers are responsible for launching a job to a specific environment.\nA Launcher takes a batch of argument lists like the one above and launches a job for each one.\nThe job uses those arguments to compose its configuration.\nThe basic launcher simply launches the job locally. \n\n### SearchPathPlugin\nA config path plugin can manipulate the search path.\nThis can be used to influence the default Hydra configuration to be more appropriate to a specific environment,\nor just add new entries to the search path to make more configurations available to the Hydra app.\n\nSearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed.\n\nMany other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. \n\n### ConfigSource\nConfigSource plugins can be used to allow Hydra to access configuration in non-standard locations when composing the config.\nThis can be used to enable access to an in-house private config store, or as a way to access configs from public sources like GitHub or S3.\n\n\n---\nid: ax_sweeper\ntitle: Ax Sweeper plugin\nsidebar_label: Ax Sweeper plugin\n---\n\nimport {ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ax-sweeper)](https://img.shields.io/pypi/v/hydra-ax-sweeper)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ax-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ax-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ax-sweeper/month)](https://pepy.tech/project/hydra-ax-sweeper)\n\n\nThis plugin provides a mechanism for Hydra applications to use the [Adaptive Experimentation Platform, aka Ax](https://ax.dev/). Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations.\n\n:::warning Retirement after Hydra 1.4\n\nHydra 1.4 will include the final first-party release of the Ax Sweeper, based on\nthe existing implementation. Further modernization is no longer planned. The\nplugin code will be removed in the Hydra 1.5 line, and no first-party Ax Sweeper\nreleases will be published for Hydra 1.5 or later. Existing PyPI releases will\nremain available.\n\nCommunity members interested in maintaining the plugin in a separate repository\nare invited to comment on the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506).\nHydra's documentation can link to that repository. Transferring control of the\n`hydra-ax-sweeper` PyPI package may be considered once new maintainers establish\na reliable track record and build trust.\n\n:::\n\n### Installation\n```commandline\npip install hydra-ax-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=ax` to your command line. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: ax\n```\n\nWe include an example of how to use this plugin. The file example/banana.py\nimplements the [Rosenbrock function (aka Banana function)](https://en.wikipedia.org/wiki/Rosenbrock_function).\nThe return value of the function should be the value that we want to optimize.\n\n\nTo compute the best parameters for the Banana function, clone the code and run the following command in the `plugins/hydra_ax_sweeper` directory:\n\n```\npython example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n```\n\nThe output of a run looks like:\n\n```\n[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5]\nbanana.y: range=[-5.0, 10.1]\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 trials, GPEI for subsequent trials]). Iterations after 5 will take longer to generate due to model-fitting.\n[HYDRA] AxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=2 banana.y=-0.988\n[__main__][INFO] - Banana_Function(x=2, y=-0.988)=2488.883\n[HYDRA] #1 : banana.x=-1 banana.y=7.701\n[__main__][INFO] - Banana_Function(x=-1, y=7.701)=4493.987\n[HYDRA] #2 : banana.x=-1 banana.y=-3.901\n[__main__][INFO] - Banana_Function(x=-1, y=-3.901)=2406.259\n[HYDRA] #3 : banana.x=-1 banana.y=0.209\n[__main__][INFO] - Banana_Function(x=-1, y=0.209)=66.639\n[HYDRA] #4 : banana.x=4 banana.y=-4.557\n[__main__][INFO] - Banana_Function(x=4, y=-4.557)=42270.006\n[HYDRA] New best value: 66.639, best parameters: {'banana.x': -1, 'banana.y': 0.209}\n```\n\nIn this example, we set the range of `x` parameter as an integer in the interval `[-5, 5]` and the range of `y` parameter as a float in the interval `[-5, 10.1]`. Note that in the case of `x`, we used `int(interval(...))` and hence only integers are sampled. In the case of `y`, we used `interval(...)` which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.` banana.x=5.0`), choice parameters (eg `banana.x=choice(1,2,3)`) and range (eg `banana.x=range(1, 10)`). Note that `interval`, `choice` etc. are functions provided by Hydra, and you can read more about them [here](/advanced/override_grammar/extended.md). An important thing to remember is, use [`interval`](/advanced/override_grammar/extended.md#interval-sweep) when we want Ax to sample values from an interval. [`RangeParameter`](https://ax.dev/api/ax.html#ax.RangeParameter) in Ax is equivalent to `interval` in Hydra. Remember to use `int(interval(...))` if you want to sample only integer points from the interval. [`range`](/advanced/override_grammar/extended.md#range-sweep) can be used as an alternate way of specifying choice parameters. For example `python example/banana.py -m banana.x=choice(1, 2, 3, 4)` is equivalent to `python example/banana.py -m banana.x=range(1, 5)`.\n\nThe values of the `x` and `y` parameters can also be set using the config file `plugins/hydra_ax_sweeper/example/conf/config.yaml`. For instance, the configuration corresponding to the commandline arguments is as follows:\n\n```\nbanana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n```\n\nTo sample in log space, you can tag the commandline override with `log`. E.g. `python example/banana.py -m banana.x=tag(log, interval(1, 1000))`. You can set `log_scale: true` in the input config to achieve the same.\n```\nbanana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n```\n\nIn general, the plugin supports setting all the Ax supported [Parameters](https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter) in the config. According to the [Ax documentation](https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment), the required elements in the config are:\n\n* `name` - Name of the parameter. It is of type string.\n* `type` - Type of the parameter. It can take the following values: `range`, `fixed`, or `choice`.\n* `bounds` - Required only for the `range` parameters. It should be a list of two values, with the lower bound first.\n* `values` - Required only for the `choice` parameters. It should be a list of values.\n* `value` - Required only for the `fixed` parameters. It should be a single value.\n\nNote that if you want to sample integers in the range `-5` to `5`, you need to specify the range as `int(interval(-5, 5))` (in the command line) or `[-5, 5]` (in config). If you want to sample floats in range `-5` to `5`, you need to specify the range as `interval(-5, 5)` (in the command line) or `[-5.0, 5.0]` (in config).\n\nThe Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the `is_noisy` parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero.\n\nIf measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the [standard error of the mean](https://en.wikipedia.org/wiki/Standard_error) of repeated measurements), the measurement function can return the tuple `(measurement_value, measurement_uncertainty)` instead of a scalar value.\n\nThe parameters for the optimization process can also be set in the config file. Specifying the Ax config is optional. You can discover the Ax Sweeper parameters with:\n\n```yaml title=\"$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_ax_sweeper.ax_sweeper.AxSweeper\nmax_batch_size: null\nax_config:\n max_trials: 10\n early_stop:\n minimize: true\n max_epochs_without_improvement: 10\n epsilon: 1.0e-05\n experiment:\n name: null\n objective_name: objective\n minimize: true\n parameter_constraints: null\n outcome_constraints: null\n status_quo: null\n client:\n verbose_logging: false\n random_seed: null\n is_noisy: true\n params: {}\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n\n---\nid: colorlog\ntitle: Colorlog plugin\nsidebar_label: Colorlog plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-colorlog)](https://pypi.org/project/hydra-colorlog/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-colorlog)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-colorlog)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-colorlog/month)](https://pepy.tech/project/hydra-colorlog)\n\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\n\n### Installation\n```commandline\npip install hydra_colorlog --upgrade\n```\n\n### Usage\nOverride `hydra/job_logging` and `hydra/hydra_logging` in your config:\n\n```yaml\ndefaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n```\n\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee included example application.\n \n![Colored log output](/plugins/colorlog/colorlog.png)\n\n\n---\nid: joblib_launcher\ntitle: Joblib Launcher plugin\nsidebar_label: Joblib Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-joblib-launcher)](https://pypi.org/project/hydra-joblib-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-joblib-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-joblib-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-joblib-launcher/month)](https://pepy.tech/project/hydra-joblib-launcher)\n\nThe Joblib Launcher plugin provides a launcher for parallel tasks based on [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html).\n\n### Process backends\n\nThe launcher supports two process backends:\n\n| Backend | Advantages | Tradeoffs |\n| --- | --- | --- |\n| `loky` (default) | Robust process management and Cloudpickle support for dynamically defined Python objects. It remains the default for compatibility. | Workers are reused between Hydra jobs, so arbitrary application caches or process-global state can leak between jobs. Cloudpickling the task can also fail when it reaches some native-library objects. |\n| `multiprocessing` | Runs every Hydra job in a fresh worker process and sends module-level function tasks by reference instead of Cloudpickling them. This provides strict process isolation and avoids serializing module-level native-library objects referenced by the task. | Functions must be defined at module scope. Custom decorators around `@hydra.main` must use `functools.wraps`. |\n\nLoky runs jobs in the parent process when `n_jobs=1`. The multiprocessing\nbackend retains per-job worker isolation while executing one job at a time.\n\n### Installation\n```commandline\npip install hydra-joblib-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=joblib` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: joblib\n```\nBy default, the launcher uses process-based parallelism with all available CPU\ncores. Set `hydra.launcher.n_jobs` to limit the number of jobs that can run\nconcurrently.\n\nThe JobLibLauncherConf backing the config is defined here:\n\nYou can discover the Joblib Launcher parameters with:\n```yaml title=\"$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: -1\ninner_max_num_threads: null\nbackend: loky\nprefer: processes\nrequire: null\nverbose: 0\ntimeout: null\npre_dispatch: 2*n_jobs\nbatch_size: auto\ntemp_folder: null\nmax_nbytes: null\nmmap_mode: r\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nSee [`Joblib.Parallel` documentation](https://joblib.readthedocs.io/en/latest/parallel.html) for full details about the parameters above.\n\n`backend` selects the backend used by this launcher. Because a backend is\nalways selected explicitly, `prefer` does not change it. `require` must be\ncompatible with the selected backend; `require=sharedmem` is unsupported\nbecause this launcher does not support a thread-based backend.\n\n#### Controlling native library thread pools\n\nWhen using libraries that manage native thread pools, such as OpenBLAS, MKL, OpenMP, Numba, or NumExpr, set `inner_max_num_threads` to limit the number of native threads available to each Joblib worker process:\n\n```yaml\nhydra:\n launcher:\n n_jobs: 8\n inner_max_num_threads: 1\n```\n\nThis can help avoid oversubscription when multiple Hydra jobs run in parallel and each job calls into a multithreaded native library. For arbitrary environment variables, use [`hydra.job.env_set`](../configure_hydra/job.md#hydrajobenv_set) instead.\n\n
\nSelect the `multiprocessing` backend to execute every job in a fresh worker\nprocess:\n\n```yaml\nhydra:\n launcher:\n backend: multiprocessing\n n_jobs: 4\n```\n\nThe launcher automatically sets Joblib's `batch_size=1` so that each pool task\ncontains one Hydra job, and `maxtasksperchild=1` so that the worker exits after\nthat task. These are internal correctness settings, not user configuration.\nConflicting values are rejected.\n\n`inner_max_num_threads` is supported only by `loky`. Custom decorators around\n`@hydra.main` must follow the\n[Hydra task-decorator requirements](../advanced/decorating_main.md). Callable\ntask objects are copied to each worker, so all state stored on them must support\nPython pickling.\n

\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will launch five parallel executions:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=10,backend=loky,prefer=processes,require=None,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r) is launching 5 jobs\n[HYDRA] Launching jobs, sweep output dir : multirun/2020-02-18/10-00-00\n[__main__][INFO] - Process ID 14336 executing task 2 ...\n[__main__][INFO] - Process ID 14333 executing task 1 ...\n[__main__][INFO] - Process ID 14334 executing task 3 ...\n[__main__][INFO] - Process ID 14335 executing task 4 ...\n[__main__][INFO] - Process ID 14337 executing task 5 ...\n```\n\n\n---\nid: nevergrad_sweeper\ntitle: Nevergrad Sweeper plugin\nsidebar_label: Nevergrad Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-nevergrad-sweeper)](https://pypi.org/project/hydra-nevergrad-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-nevergrad-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-nevergrad-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-nevergrad-sweeper/month)](https://pepy.tech/project/hydra-nevergrad-sweeper)\n\n[Nevergrad](https://facebookresearch.github.io/nevergrad/) is a derivative-free optimization platform providing a library of state-of-the-art algorithms for hyperparameter search. This plugin provides Hydra applications a mechanism to use [Nevergrad](https://facebookresearch.github.io/nevergrad/) algorithms to optimize experiment/application parameters.\n\n### Installation\n```commandline\npip install hydra-nevergrad-sweeper --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/sweeper=nevergrad` to your command. Alternatively, override `hydra/sweeper` in your config:\n\n```yaml\ndefaults:\n - override hydra/sweeper: nevergrad\n```\n\nThe default configuration is defined and documented here.\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Example of training using Nevergrad hyperparameter search\n\nWe include an example of how to use this plugin. The file example/my_app.py implements an example of minimizing a (dummy) function using a mixture of continuous and discrete parameters.\n\nYou can discover the Nevergrad sweeper parameters with:\n```yaml title=\"$ python your_app hydra/sweeper=nevergrad --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\n_target_: hydra_plugins.hydra_nevergrad_sweeper.nevergrad_sweeper.NevergradSweeper\noptim:\n optimizer: NGOpt\n budget: 80\n num_workers: 10\n noisy: false\n maximize: false\n seed: null\n max_failure_rate: 0.0\nparams:\n db: choice(mnist, cifar)\n lr: {init: 0.02, step: 2.0, log: true}\n dropout: interval(0, 1)\n batch_size: int(interval(4, 16))\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\ndb: mnist\nlr: 0.12\ndropout: 0.33\nbatch_size: 4\n```\n\nTo run hyperparameter search and look for the best parameters for this function, clone the code and run the following command in the `plugins/hydra_nevergrad_sweeper` directory:\n```bash\npython example/my_app.py -m\n```\n\nYou can also override the search space parametrization:\n```bash\npython example/my_app.py --multirun db=mnist,cifar batch_size=4,8,16 \\\n'lr=tag(log, interval(0.001, 1))' 'dropout=interval(0,1)'\n```\n\nThe initialization of the sweep and the first 5 evaluations (out of 100) look like this:\n\n```text\n[2020-10-08 20:13:53,592][HYDRA] NevergradSweeper(optimizer=NGOpt, budget=100, num_workers=10) minimization\n[2020-10-08 20:13:53,593][HYDRA] with parametrization Dict(batch_size=Choice(choices=Tuple(4,8,16),weights=Array{(1,3)}),db=Choice(choices=Tuple(mnist,cifar),weights=Array{(1,2)}),dropout=Scalar{Cl(0,1,b)}[sigma=Log{exp=2.0}],lr=Log{exp=3.162277660168379,Cl(0.001,1,b)}):{'db': 'mnist', 'lr': 0.03162277660168379, 'dropout': 0.5, 'batch_size': 8}\n[2020-10-08 20:13:53,593][HYDRA] Sweep output dir: multirun/2020-10-08/20-13-53\n[2020-10-08 20:13:55,023][HYDRA] Launching 10 jobs locally\n[2020-10-08 20:13:55,023][HYDRA] #0 : db=mnist lr=0.03162277660168379 dropout=0.5 batch_size=16\n[2020-10-08 20:13:55,217][__main__][INFO] - dummy_training(dropout=0.500, lr=0.032, db=mnist, batch_size=16) = 13.258\n[2020-10-08 20:13:55,218][HYDRA] #1 : db=cifar lr=0.018178519762066934 dropout=0.5061074452336254 batch_size=4\n[2020-10-08 20:13:55,408][__main__][INFO] - dummy_training(dropout=0.506, lr=0.018, db=cifar, batch_size=4) = 0.278\n[2020-10-08 20:13:55,409][HYDRA] #2 : db=cifar lr=0.10056825918734161 dropout=0.6399687427725211 batch_size=4\n[2020-10-08 20:13:55,595][__main__][INFO] - dummy_training(dropout=0.640, lr=0.101, db=cifar, batch_size=4) = 0.329\n[2020-10-08 20:13:55,596][HYDRA] #3 : db=mnist lr=0.06617542958182834 dropout=0.5059497416026679 batch_size=8\n[2020-10-08 20:13:55,812][__main__][INFO] - dummy_training(dropout=0.506, lr=0.066, db=mnist, batch_size=8) = 5.230\n[2020-10-08 20:13:55,813][HYDRA] #4 : db=mnist lr=0.16717013388679514 dropout=0.6519070394318255 batch_size=4\n...\n[2020-10-08 20:14:27,988][HYDRA] Best parameters: db=cifar lr=0.11961221693764439 dropout=0.37285878409770895 batch_size=4\n```\n\n\nand the final 2 evaluations look like this:\n```text\n[HYDRA] \t#8 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] \t#9 : db=mnist batch_size=4 lr=0.094 dropout=0.381\n[__main__][INFO] - my_app.py(dropout=0.381, lr=0.094, db=mnist, batch_size=4) = 1.077\n[HYDRA] Best parameters: db=mnist batch_size=4 lr=0.094 dropout=0.381\n```\n\n\nThe run also creates an `optimization_results.yaml` file in your sweep folder with the best evaluated parameters found during the sweep:\n```yaml\nbest_evaluated_result: 0.381\n\nbest_evaluated_params:\n batch_size: 4\n db: mnist\n dropout: 0.381\n lr: 0.094\n\nname: nevergrad\n```\n\n## Defining the parameters\n\nThe plugin supports two types of parameters: [Choices](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters) and [Scalars](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters). They can be defined either through a config file or command-line override.\n\n### Defining through command-line override\nHydra provides an override parser that supports rich syntax. More documentation can be found in ([Override Grammar/Basic](../advanced/override_grammar/basic.md)) and ([Override Grammar/Extended](../advanced/override_grammar/extended.md)). We recommend you go through them first before proceeding with this doc.\n\n#### Choices\nTo override a field with choices:\n```commandline\n'key=1,5'\n'key=shuffle(range(1, 8))'\n'key=range(1,5)'\n```\n\nYou can tag an override with `ordered` to indicate it's a [`TransitionChoice`](https://facebookresearch.github.io/nevergrad/parametrization.html#parameters)\n```commandline\nkey=tag(ordered, choice(1,2,3))\n```\n\n#### Scalar\n```commandline\nkey=interval(1,12) # Intervals are floats by default\nkey=int(interval(1,8)) # Scalar bounds are cast to an int\nkey=tag(log, interval(1,12)) # call ng.p.Log if tagged with log\nkey={init: 0.02, step: 2.0, log: true} # Unbounded log-scale scalar\n```\n\n### Defining through config file\nThe search space can be defined under `hydra.sweeper.params`.\nThe definition is consistent with the equivalent command-line override.\n\n:::warning\n`hydra.sweeper.parametrization` is deprecated in Hydra 1.4 and will be removed\nin Hydra 1.5. Use `hydra.sweeper.params` instead.\n:::\n\n#### Choices\nChoices use the same syntax as command-line overrides. For example, translate\n`key=shuffle(range(1, 8))` to `key: shuffle(range(1, 8))` in the config file.\n\nFixed strings containing override grammar characters must retain quotes as part\nof the configured value. For example, use `label: \"'a,b'\"` to configure the\nliteral string `a,b`; `label: a,b` defines a choice sweep.\n\n#### Scalars\n`Scalar` definitions also support the override syntax shown above. The\nfollowing keys can be passed in a dictionary to define unbounded scalars:\n - `init`: optional initial value\n - `lower` : optional lower bound\n - `upper`: optional upper bound\n - `log`: set to `true` for log distributed values\n - `step`: optional step size for looking for better parameters. In linear mode, this is an additive step; in logarithmic mode it is multiplicative.\n - `integer`: set to `true` for integers (favor floats over integers whenever possible)\n\nProviding only `lower` and `upper` bound will set the initial value to the middle of the range and the step to a sixth of the range.\n\n\n---\nid: optuna_sweeper\ntitle: Optuna Sweeper plugin\nsidebar_label: Optuna Sweeper plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-optuna-sweeper)](https://pypi.org/project/hydra-optuna-sweeper/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-optuna-sweeper)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-optuna-sweeper)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-optuna-sweeper/month)](https://pepy.tech/project/hydra-optuna-sweeper)\n\n\nThis plugin enables Hydra applications to utilize [Optuna](https://optuna.org) for the optimization of the parameters of experiments.\n\n## Installation\n\nThis plugin requires Hydra Core 1.4 (`hydra-core>=1.4.0.dev1,<1.5.0.dev0`).\nPlease install it with the following command:\n\n```commandline\npip install --upgrade --pre \"hydra-core>=1.4.0.dev1,<1.5.0.dev0\"\n```\n\nYou can install the plugin via pip:\n\n```commandline\npip install --upgrade --pre \"hydra-optuna-sweeper>=1.4.0.dev1,<1.5.0.dev0\"\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\n## Usage\n\nPlease set `hydra/sweeper` to `optuna` in your config file.\n\n```yaml\ndefaults:\n - override hydra/sweeper: optuna\n```\n\nAlternatively, add `hydra/sweeper=optuna` option to your command line.\n\nThe default configuration is here.\n\n## Example 1: Single-Objective Optimization\n\nWe include an example in this directory. `example/sphere.py` implements a simple benchmark function to be minimized.\n\n\n\n\nYou can discover the Optuna sweeper parameters with:\n\n```yaml title=\"python example/sphere.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\"\n# @package hydra.sweeper\nsampler:\n _target_: optuna.samplers.TPESampler\n seed: 123\n n_startup_trials: 10\n n_ei_candidates: 24\n multivariate: false\n_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\ndirection: minimize\nstorage: null\nstudy_name: sphere\nn_trials: 20\nn_jobs: 1\nmax_failure_rate: 0.0\nparams:\n x: range(-5.5,5.5,step=0.5)\n y: choice(-5,0,5)\n```\n\nThe function decorated with `@hydra.main()` returns a float which we want to minimize, the minimum is 0 and reached for:\n```yaml\nx: 0\ny: 0\n```\n\nTo run optimization, clone the code and run the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/sphere.py --multirun\n```\n\nYou can also override the search space parametrization:\n\n```commandline\npython example/sphere.py --multirun 'x=interval(-5.0, 5.0)' 'y=interval(0, 10)'\n```\n\nYou might find the `optimization_results.yaml` file (i.e. best params and best value) under `multirun` logs folder:\n\n```yaml\nname: optuna\nbest_params:\n x: 0.0\n 'y': 0\nbest_value: 0.0\n```\n\n\n## Sampler configuration\nThis plugin supports Optuna's [samplers](https://optuna.readthedocs.io/en/stable/reference/samplers.html).\nYou can change the sampler by overriding `hydra/sweeper/sampler` or change sampler settings within `hydra.sweeper.sampler`.\n\n## Search space configuration\n\nThis plugin supports Optuna's [distributions](https://optuna.readthedocs.io/en/stable/reference/distributions.html) to configure search spaces. They can be defined either through commandline override or config file.\n\n### Configuring through commandline override\n\nHydra provides a override parser that support rich syntax. Please refer to [OverrideGrammer/Basic](../advanced/override_grammar/basic.md) and [OverrideGrammer/Extended](../advanced/override_grammar/extended.md) for details.\n\n#### Interval override\n\nBy default, `interval` is converted to [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html). You can use [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html) by casting the interval to `int`.\n\n
\n Example for interval override\n\n ```commandline\n python example/sphere.py --multirun 'x=int(interval(-5.0, 5.0))' 'y=tag(log, interval(1, 10))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=1.6859762540733367\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=5.237816870668193\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': 1.0929184723430116}\n [HYDRA] Best value: 1.1944707871885822\n ```\n\n
\n\n#### Range override\n\nInteger ranges are converted to [`IntDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.IntDistribution.html).\nFloat ranges, including sorted float ranges, use [`FloatDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.FloatDistribution.html).\nThe distribution includes exactly the discrete values in the range: its stop\nis exclusive, and descending ranges are supported. Empty ranges and zero steps\nare rejected. For example, `range(1,3)` permits only `1` and `2`, while\n`range(0,1,0.3)` permits `0.0`, `0.3`, `0.6`, and `0.9`.\n\nWhen converting a float range would make its Decimal endpoints or step\nunrepresentable as an Optuna numeric distribution, the sweeper uses a\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\nwith the generated values instead. This precision-boundary fallback preserves\nthe exact values and duplicates; representable ordinary uncast ranges remain\nnumeric and are converted without enumerating their values.\n\nApplying `shuffle`, `int`, or `float` to a range uses\n[`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html)\ncontaining its generated values. Casts apply to each value, so\n`int(range(0,5,1.5))` permits `0`, `1`, `3`, and `4`. Duplicate cast values are\nretained. Sorting or shuffling does not change the permitted values. Optuna\ndoes not promise to evaluate trials in range order.\n\nGridSampler evaluates all values in each discrete distribution, including a\nsingleton or the distribution's inclusive upper endpoint.\n\nThese corrections changed range search spaces in Hydra 1.4; earlier unshuffled\nranges could admit an excluded stop. See the\n[migration guide](/docs/upgrades/1.3_to_1.4/breaking_changes#optuna-range-sweeps).\n\n
\n Example for range override\n\n ```commandline\n python example/sphere.py --multirun 'x=range(-5.0, 5.0)' 'y=shuffle(range(-5, 5))'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=-3 y=-4\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=1 y=-1\n ...\n [HYDRA] Best parameters: {'x': 0, 'y': -1}\n [HYDRA] Best value: 1.0\n ```\n\n
\n\n#### Choice override\n\n`choice` is converted to [`CategoricalDistribution`](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.distributions.CategoricalDistribution.html).\n\n
\n Example for choice override\n\n ```commandline\n python example/sphere.py --multirun 'x=choice(-5.0, 0.0, 5.0)' 'y=choice(0, 1, 2, 3, 4, 5)'\n ```\n\n The output is as follows:\n\n ```commandline\n [HYDRA] Study name: sphere\n [HYDRA] Storage: None\n [HYDRA] Sampler: TPESampler\n [HYDRA] Directions: ['minimize']\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#0 : x=5.0 y=5\n [HYDRA] Launching 1 jobs locally\n [HYDRA] \t#1 : x=5.0 y=2\n ...\n [HYDRA] Best parameters: {'x': 0.0, 'y': 0}\n [HYDRA] Best value: 0.0\n ```\n\n
\n\n### Configuring through config file\n\nThe syntax in config file is consistent with the above commandline override. For example, a commandline override\n`x=range(1,4)` can be expressed in config file as `x: range(1,4)` under the `hydra.sweeper.params` node.\n\n## Example 2: Multi-Objective Optimization\n\nIn the same directory, `example/multi-objective.py` implements a simple benchmark function, which has two objective values. We want to minimize two objectives simultaneously.\n\nYou can discover the Optuna sweeper parameters with:\n\n```commandline\npython example/multi-objective.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper\n```\n\n
\n Configuration of the multi-objective optimization example\n\n ```yaml\n # @package hydra.sweeper\n sampler:\n _target_: optuna.samplers.NSGAIISampler\n seed: 123\n population_size: 50\n mutation_prob: null\n crossover_prob: 0.9\n swapping_prob: 0.5\n constraints_func: null\n _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper\n direction:\n - minimize\n - minimize\n storage: null\n study_name: multi-objective\n n_trials: 20\n n_jobs: 1\n params:\n x: range(0, 5, step=0.5)\n y: range(0, 3, step=0.5)\n ```\n
\n\n\nTo run the optimization, use the following command in the `plugins/hydra_optuna_sweeper` directory:\n\n```commandline\npython example/multi-objective.py --multirun\n```\n\nFor problems with trade-offs between two different objectives, there may be no single solution that simultaneously minimizes both objectives. Instead, we obtained a set of solutions, namely [Pareto optimal solutions](https://en.wikipedia.org/wiki/Pareto_efficiency), that show the best trade-offs possible between the objectives. In the following figure, the blue dots show the Pareto optimal solutions in the optimization results.\n\n![Pareto-optimal solutions](/plugins/optuna_sweeper/multi_objective_result.png)\n\n## EXPERIMENTAL: Custom-Search-Space Optimization\n\nHydra's Optuna Sweeper allows users to provide a hook for custom search space configuration.\nThis means you can work directly with the `optuna.trial.Trial` object to suggest parameters.\nTo use this feature, define a python function with signature `Callable[[DictConfig, optuna.trial.Trial], None]`\nand set the `hydra.sweeper.custom_search_space` key in your config to target that function.\n\nThe callback path is selected by configuration. When using an execution\nwhitelist, authorize that path from trusted Python code:\n\n```python\n@hydra.main(\n config_path=\"custom-search-space\",\n config_name=\"config\",\n execution_whitelist=\"custom-search-space-objective.configure\",\n)\ndef multi_dimensional_sphere(cfg: DictConfig) -> float:\n ...\n```\n\nYou can find a full example in the same directory as before, where `example/custom-search-space-objective.py` implements a benchmark function to be minimized.\nThe example shows the use of Optuna's [pythonic search spaces](https://optuna.readthedocs.io/en/stable/tutorial/10_key_features/002_configurations.html) in combination with Hydra.\nPart of the search space configuration is defined in config files, and part of it is written in Python.\n\n
\n Example: Custom search space configuration\n\n ```yaml\n defaults:\n - override hydra/sweeper: optuna\n\n hydra:\n sweeper:\n sampler:\n seed: 123\n direction: minimize\n study_name: custom-search-space\n storage: null\n n_trials: 20\n n_jobs: 1\n\n params:\n x: range(-5.5, 5.5, 0.5)\n y: choice(-5, 0, 5)\n # `custom_search_space` should be a dotpath pointing to a\n # callable that provides search-space configuration logic:\n custom_search_space: custom-search-space-objective.configure\n\n x: 1\n y: 1\n z: 100\n max_z_difference_from_x: 0.5\n ```\n ```python\n # example/custom-search-space-objective.py\n\n ...\n\n def configure(cfg: DictConfig, trial: Trial) -> None:\n x_value = trial.params[\"x\"]\n trial.suggest_float(\n \"z\",\n x_value - cfg.max_z_difference_from_x,\n x_value + cfg.max_z_difference_from_x,\n )\n trial.suggest_float(\"+w\", 0.0, 1.0) # note +w here, not w as w is a new parameter\n\n ...\n ```\n\n
\n\nThe method that `custom_search_space` points to must accepts both a DictConfig with already set options and a trial object which needs further configuration. In this example we limit `z` the difference between `x` and `z` to be no more than 0.5.\nNote that this `custom_search_space` API should be considered experimental and is subject to change.\n\n### Order of trial configuration\nConfiguring a trial object is done in the following sequence:\n - search space parameters are set from the `hydra.sweeper.params` key in the config\n - Command line overrides are set\n - `custom_search_space` parameters are set\n\nIt is not allowed to set search space parameters in the `custom_search_space` method for parameters which have a fixed value from command line overrides. [Trial.user_attrs](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.trial.Trial.html#optuna.trial.Trial.user_attrs) can be inspected to find any of such fixed parameters.\n\n\n---\nid: ray_launcher\ntitle: Ray Launcher plugin\nsidebar_label: Ray Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-ray-launcher)](https://pypi.org/project/hydra-ray-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-ray-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-ray-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-ray-launcher/month)](https://pepy.tech/project/hydra-ray-launcher)\n\nThe Ray Launcher plugin provides 2 launchers: `ray_aws` and `ray`.\n `ray_aws` launches jobs remotely on AWS and is built on top of [ray autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). `ray` launches jobs on your local machine or existing ray cluster.\n\n:::note Ray AWS support\nThe local `ray` launcher is supported as a normal Hydra plugin.\n\nThe `ray_aws` launcher is maintained on a best-effort basis. Historically, this path has required substantially more maintainer attention and infrastructure resources than other Hydra plugins. It depends on Ray autoscaler behavior and live AWS infrastructure, both of which are comparatively unstable external surfaces for Hydra to validate. Running reliable end-to-end coverage also has a real cloud-cost burden, which is difficult to justify within the project's limited maintenance budget.\n\nFixes for `ray_aws` are welcome from users who can validate them on AWS. PRs that change `ray_aws` behavior must include cheap local validation where possible and a clear report of real AWS testing for behavior that cannot be covered locally.\n\nIn the long term, if the `ray_aws` launcher becomes completely non-functional and there is no maintainer or user-contributor path to validate and repair it, support may be dropped entirely.\n:::\n\n### Installation\n\n```commandline\n$ pip install hydra-ray-launcher --upgrade\n```\n\n### Usage\nOnce installed, add `hydra/launcher=ray_aws` or `hydra/launcher=ray` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: ray_aws\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe `ray_pkg_version` resolver now takes installed distribution names instead of\nPython import names and reads their metadata without importing the module.\nFor example, replace `${ray_pkg_version:yaml}` with `${ray_pkg_version:PyYAML}`.\n`${ray_pkg_version:hydra}` remains an alias for `hydra-core`.\nPackages must be installed, including editable installs.\nAn importable source directory alone is insufficient. If metadata is unavailable,\ninstall the package or set its version explicitly in `env_setup.pip_packages`.\n\n### `ray_aws` launcher\n\n:::important\n`ray_aws` launcher is built on top of ray's [autoscaler sdk](https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html). To get started, you need to\n[config your AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).\n`ray autoscaler sdk` expects your AWS credentials have certain permissions for [`EC2`](https://aws.amazon.com/ec2) and [`IAM`](https://aws.amazon.com/iam). Read [this](https://github.com/ray-project/ray/issues/9327) for more information.\n:::\n\n`ray autoscaler sdk` expects a configuration for the EC2 cluster; we've schematized the configs in here\n\n
\n Discover ray_aws launcher's config\n\n ```commandline\n $ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n # @package hydra.launcher\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\n env_setup:\n pip_packages:\n omegaconf: ${ray_pkg_version:omegaconf}\n hydra_core: ${ray_pkg_version:hydra}\n ray: ${ray_pkg_version:ray}\n cloudpickle: ${ray_pkg_version:cloudpickle}\n pickle5: 0.0.11\n hydra_ray_launcher: 1.2.0.dev1\n commands:\n - conda create -n hydra_${python_version:micro} python=${python_version:micro} -y\n - echo 'export PATH=\"$HOME/anaconda3/envs/hydra_${python_version:micro}/bin:$PATH\"'\n >> ~/.bashrc\n ray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n upscaling_speed: 1.0\n max_workers: 1\n idle_timeout_minutes: 5\n docker:\n image: ''\n container_name: ''\n pull_before_run: true\n run_options: []\n provider:\n type: aws\n region: us-west-2\n availability_zone: us-west-2a,us-west-2b\n cache_stopped_nodes: false\n key_pair:\n key_name: hydra-${oc.env:USER,user}\n auth:\n ssh_user: ubuntu\n available_node_types:\n ray.head.default:\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n ray.worker.default:\n min_workers: 0\n max_workers: 2\n resources: {}\n node_config:\n InstanceType: m5.large\n ImageId: ami-0a2363a9cff180a64\n InstanceMarketOptions:\n MarketType: spot\n head_node_type: ray.head.default\n file_mounts: {}\n initialization_commands: []\n cluster_synced_files: []\n setup_commands: []\n head_setup_commands: []\n worker_setup_commands: []\n head_start_ray_commands:\n - ray stop\n - ulimit -n 65536;ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml\n worker_start_ray_commands:\n - ray stop\n - ulimit -n 65536; ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076\n run_env: auto\n stop_cluster: true\n sync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n sync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\n logging:\n log_style: auto\n color_mode: auto\n verbosity: 0\n create_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\n teardown_cluster:\n workers_only: false\n keep_min_workers: false\n ```\n
\n\n\n#### Examples\n\nThe following examples can be found here.\n\n
\n Simple app\n\n ```commandline\n $ python my_app.py --multirun task=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : task=1\n [HYDRA] #1 : task=2\n [HYDRA] #2 : task=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmpqqg4v4i7/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=3374) [__main__][INFO] - Executing task 1\n (pid=3374) [__main__][INFO] - Executing task 2\n (pid=3374) [__main__][INFO] - Executing task 3\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n
\n Upload & Download from remote cluster\n\n If your application is dependent on multiple modules, you can configure `hydra.launcher.sync_up` to upload dependency modules to the remote cluster.\n You can also configure `hydra.launcher.sync_down` to download output from remote cluster if needed. This functionality is built on top of `rsync`, `include` and `exclude` is consistent with how it works in `rsync`.\n\n ```commandline\n $ python train.py --multirun random_seed=1,2,3\n [HYDRA] Ray Launcher is launching 3 jobs,\n [HYDRA] #0 : random_seed=1\n [HYDRA] #1 : random_seed=2\n [HYDRA] #2 : random_seed=3\n [HYDRA] Pickle for jobs: /var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmptdkye9of/job_spec.pkl\n Cluster: default\n ...\n INFO services.py:1172 -- View the Ray dashboard at http://localhost:8265\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n (pid=1772) [__main__][INFO] - Start training...\n (pid=1772) [INFO] - Init my model\n (pid=1772) [INFO] - Created dir for checkpoints. dir=checkpoint\n Loaded cached provider configuration\n ...\n [HYDRA] Output: receiving file list ... done\n 16-32-25/\n 16-32-25/0/\n 16-32-25/0/checkpoint/\n 16-32-25/0/checkpoint/checkpoint_1.pt\n 16-32-25/1/\n 16-32-25/1/checkpoint/\n 16-32-25/1/checkpoint/checkpoint_2.pt\n 16-32-25/2/\n 16-32-25/2/checkpoint/\n 16-32-25/2/checkpoint/checkpoint_3.pt\n ...\n [HYDRA] Stopping cluster now. (stop_cluster=true)\n [HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)\n Destroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n ...\n No nodes remaining.\n\n ```\n
\n\n\n##### Manage Cluster LifeCycle\nYou can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:\n\n- Default setting (no need to specify on commandline): delete cluster after job finishes remotely:\n ```commandline\n hydra.launcher.stop_cluster=true\n hydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\n hydra.launcher.teardown_cluster.workers_only=false\n hydra.launcher.teardown_cluster.keep_min_workers=false\n ```\n\n- Keep cluster running after jobs finishes remotely\n ```commandline\n hydra.launcher.stop_cluster=false\n ```\n\n- Power off EC2 instances and control node termination using `hydra.launcher.ray.cluster.provider.cache_stopped_nodes`\nand `hydra.launcher.teardown_cluster.workers_only`\n\n | cache_stopped_nodes | workers_only | behavior |\n |---------------------|--------------|----------|\n | false | false | All nodes are terminated |\n | false | true | Keeps head node running and terminates only worker node |\n | true | false | Keeps both head node and worker node and stops both of them |\n | true | true | Keeps both head node and worker node and stops only worker node |\n\n- Keep `hydra.launcher.ray.cluster.min_workers` worker nodes\nand delete the rest of the worker nodes\n ```commandline\n hydra.launcher.teardown_cluster.keep_min_workers=true\n ```\n\nAdditionally, you can configure how to create or update the cluster:\n\n- Default config: run setup commands, restart Ray and use\nthe config cache if available\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=false\n hydra.launcher.create_update_cluster.restart_only=false\n hydra.launcher.create_update_cluster.no_config_cache=false\n ```\n\n- Skip restarting Ray services when updating the cluster config\n ```commandline\n hydra.launcher.create_update_cluster.no_restart=true\n ```\n\n- Skip running setup commands and only restart Ray (cannot be used with\n`hydra.launcher.create_update_cluster.no_restart`)\n ```commandline\n hydra.launcher.create_update_cluster.restart_only=true\n ```\n\n- Fully resolve all environment settings from the cloud provider again\n ```commandline\n hydra.launcher.create_update_cluster.no_config_cache=true\n ```\n\n\n##### Configure Ray Logging\nYou can manage Ray specific logging by configuring the flags provided by the plugin:\n\n- Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode\n ```commandline\n hydra.launcher.logging.log_style=\"auto\"\n hydra.launcher.logging.color_mode=\"auto\"\n hydra.launcher.logging.verbosity=0\n ```\n\n- Disable pretty-print\n ```commandline\n hydra.launcher.logging.log_style=\"record\"\n ```\n\n- Disable color mode\n ```commandline\n hydra.launcher.logging.color_mode=\"false\"\n ```\n\n- Increase Ray logging verbosity\n ```commandline\n hydra.launcher.logging.verbosity=3\n ```\n\n### `ray` launcher\n\n`ray` launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing `ray` launcher's configuration here\n `~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml`\n\n The example application starts a new ray cluster.\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-16-28\n[HYDRA] Initializing ray with config: {}\nINFO services.py:1164 -- View the Ray dashboard at http://127.0.0.1:8266\n[HYDRA] #0 :\n(pid=97801) [__main__][INFO] - Executing task 1\n```\n\nYou can run the example application on your existing ray cluster as well by overriding `hydra.launcher.ray.init.address`:\n```commandline\n$ python my_app.py --multirun hydra/launcher=ray hydra.launcher.ray.init.address=localhost:6379\n[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-13-32\n[HYDRA] Initializing ray with config: {'num_cpus': None, 'num_gpus': None, 'address': 'localhost:6379'}\nINFO worker.py:633 -- Connecting to existing Ray cluster at address: 10.30.99.17:6379\n[HYDRA] #0 :\n(pid=93358) [__main__][INFO] - Executing task 1\n```\n\n### Configure `ray.init()` and `ray.remote()`\nRay launcher is built on top of [`ray.init()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init)\nand [`ray.remote()`](https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote).\nYou can configure `ray` by overriding `hydra.launcher.ray.init` and `hydra.launcher.ray.remote`.\nCheck out an example config.\n\n\n---\nid: rq_launcher\ntitle: RQ Launcher plugin\nsidebar_label: RQ Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-rq-launcher)](https://pypi.org/project/hydra-rq-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-rq-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-rq-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-rq-launcher/month)](https://pepy.tech/project/hydra-rq-launcher)\n\nThe RQ Launcher plugin provides a launcher for distributed execution and job queuing based on [Redis Queue (RQ)](https://python-rq.org).\n\nRQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a [Redis server](https://redis.io/topics/quickstart). When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database.\n\n\n### Installation\n```commandline\npip install hydra-rq-launcher --upgrade\n```\nUsage of this plugin requires a [Redis server](https://redis.io/topics/quickstart).\n\nNote that RQ does [not support Windows](https://python-rq.org/docs/#limitations).\n\n### Usage\nOnce installed, add `hydra/launcher=rq` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: rq\n```\n\nThe default configuration is as follows:\n\n```yaml title=\"$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher\"\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_rq_launcher.rq_launcher.RQLauncher\nenqueue:\n job_timeout: null\n ttl: null\n result_ttl: null\n failure_ttl: null\n at_front: false\n job_id: null\n description: null\nqueue: default \nredis:\n host: ${oc.env:REDIS_HOST,localhost}\n port: ${oc.env:REDIS_PORT,6379}\n db: ${oc.env:REDIS_DB,0}\n password: ${oc.env:REDIS_PASSWORD,null}\n ssl: ${oc.env:REDIS_SSL,False}\n ssl_ca_certs: ${oc.env:REDIS_SSL_CA_CERTS,null\n mock: ${oc.env:REDIS_MOCK,False}\nstop_after_enqueue: false\nwait_polling: 1.0\n```\n\nFurther descriptions on the variables can be found in the plugin config file, defined here. There are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\n\nThe plugin is using environment variables to store Redis connection information. The environment variables `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, and `REDIS_PASSWORD`, are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through `REDIS_SSL` and `REDIS_SSL_CA_CERTS`; see [redis-py](https://github.com/andymccurdy/redis-py#ssl-connections) documentation.\n\nFor example, they might be set as follows when using `bash` or `zsh` as a shell:\n\n```commandline\nexport REDIS_HOST=\"localhost\"\nexport REDIS_PORT=\"6379\"\nexport REDIS_DB=\"0\"\nexport REDIS_PASSWORD=\"\"\n```\n\nEnable SSL by setting the relevant environment variables. e.g:\n```commandline\nexport REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n```\n\nAssuming configured environment variables, workers connecting to the Redis server can be launched using:\n\n```commandline\nrq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB \\\n -S hydra_plugins.hydra_rq_launcher.serializer.CloudpickleSerializer\n```\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py --multirun task=1,2,3,4,5` will enqueue five jobs to be processed by worker instances:\n\n```text\n$ python my_app.py --multirun task=1,2,3,4,5\n\n[HYDRA] RQ Launcher is enqueuing 5 job(s) in queue : default\n[HYDRA] Sweep output dir : multirun/2020-06-15/18-00-00\n[HYDRA] Enqueued 13b3da4e-03f7-4d16-9ca8-cfb3c48afeae\n[HYDRA] \t#1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] \t#2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] \t#3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] \t#4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] \t#5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n```\n\nNote that any dependencies need to be installed in the Python environment used to run the RQ worker. Workers must use Hydra's cloudpickle serializer so that job results are serialized compatibly with the RQ launcher.\n\nThe [RQ documentation](https://python-rq.org/) holds further information on [job monitoring](http://python-rq.org/docs/monitoring/), which can be done via console or [web interfaces](https://github.com/nvie/rq-dashboard), and provides [patterns](https://python-rq.org/patterns/) for worker and exception handling.\n\n\n---\nid: submitit_launcher\ntitle: Submitit Launcher plugin\nsidebar_label: Submitit Launcher plugin\n---\n\nimport GithubLink,{ExampleGithubLink} from \"@site/src/components/GithubLink\"\n\n[![PyPI](https://img.shields.io/pypi/v/hydra-submitit-launcher)](https://pypi.org/project/hydra-submitit-launcher/)\n![PyPI - License](https://img.shields.io/pypi/l/hydra-submitit-launcher)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hydra-submitit-launcher)\n[![PyPI - Downloads](https://api.pepy.tech/badge/hydra-submitit-launcher/month)](https://pepy.tech/project/hydra-submitit-launcher)\n\nThe Submitit Launcher plugin provides a [SLURM](https://slurm.schedmd.com/documentation.html) Launcher based on [Submitit](https://github.com/facebookincubator/submitit).\n\n### Installation\n```commandline\npip install hydra-submitit-launcher --upgrade\n```\n\n\n### Usage\nOnce installed, add `hydra/launcher=submitit_slurm` to your command line. Alternatively, override `hydra/launcher` in your config:\n\n```yaml\ndefaults:\n - override hydra/launcher: submitit_slurm\n```\nThere are several standard approaches for configuring plugins. Check [this page](../patterns/configuring_plugins.md) for more information.\nNote that this plugin expects a valid environment in the target host. Usually this means a shared file system between\nthe launching host and the target host.\n\nThe Submitit Plugin implements 2 different launchers: `submitit_slurm` to run on a SLURM cluster, and `submitit_local` for basic local tests.\n\n
\n Discover the SLURM Launcher parameters (Expand)\n\n ```yaml title=\"$ python your_app.py hydra/launcher=submitit_slurm --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: null\n gpus_per_node: null\n tasks_per_node: 1\n mem_gb: null\n nodes: 1\n name: ${hydra.job.name}\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.SlurmLauncher\n partition: null\n qos: null\n comment: null\n constraint: null\n exclude: null\n gres: null\n cpus_per_gpu: null\n gpus_per_task: null\n mem_per_gpu: null\n mem_per_cpu: null\n account: null\n signal_delay_s: 120\n max_num_timeout: 0\n python: null\n additional_parameters: {}\n array_parallelism: 256\n setup: null\n srun_args: null\n use_srun: true\n ```\n
\n
\n Discover the Local Launcher parameters (Expand)\n\n ```yaml title=\"$ python example/my_app.py hydra/launcher=submitit_local --cfg hydra -p hydra.launcher\"\n # @package hydra.launcher\n _target_: hydra_plugins.hydra_submitit_launcher.submitit_launcher.LocalLauncher\n submitit_folder: ${hydra.sweep.dir}/.submitit/%j\n timeout_min: 60\n cpus_per_task: 1\n gpus_per_node: 0\n tasks_per_node: 1\n mem_gb: 4\n nodes: 1\n name: ${hydra.job.name}\n ```\n
\n\n
\nYou can set all these parameters in your configuration file and/or override them in the command-line:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.timeout_min=3\n```\nSet `hydra.launcher.tasks_per_node=null` to omit `--ntasks-per-node` from the\ngenerated Slurm submission.\n\nSet `hydra.launcher.use_srun=false` to run Python directly in the batch script\ninstead of through `srun`. The default is `true`. When disabled, Python runs\nonce on the batch node, and `srun_args` is ignored; Slurm does not automatically\nlaunch the other requested tasks.\n\nSet `hydra.launcher.python` to use a Python executable other than the one\nrunning Hydra:\n\n```text\npython foo.py --multirun hydra/launcher=submitit_slurm hydra.launcher.python=/opt/venv/bin/python\n```\n\nFor more details, including descriptions for each parameter, check out the config file.\nYou can also check the [Submitit documentation](https://github.com/facebookincubator/submitit).\n\n\n**Caution**: use of `--multirun` is required for the launcher to be picked up.\n\n### Example\n\nAn example application using this launcher is provided in the plugin repository.\n\nStarting the app with `python my_app.py task=1,2,3 --multirun` (see [Multi-run](../tutorials/basic/running_your_app/2_multirun.md) for details) will launch 3 executions (you can override the launcher to run locally for testing by adding `hydra/launcher=submitit_local`):\n\n```text\n$ python my_app.py task=1,2,3 --multirun\n[HYDRA] Sweep output dir : multirun/2020-05-28/15-05-22\n[HYDRA] #0 : task=1\n[HYDRA] #1 : task=2\n[HYDRA] #2 : task=3\n```\nYou will be able to see the output of the app in the output dir:\n```commandline\n$ tree\n.\n├── 0\n│   └── my_app.log\n├── 1\n│   └── my_app.log\n├── 2\n│   └── my_app.log\n└── multirun.yaml\n\n$ cat 0/my_app.log\n[2020-05-28 15:05:23,511][__main__][INFO] - Process ID 15887 executing task 1 ...\n[2020-05-28 15:05:24,514][submitit][INFO] - Job completed successfully\n```\n\n\n# Hydra example config source\nUse this as the template a Hydra config source plugin\n\nConfig source plugins are allowing Hydra to recognize other search path schemas in addition to the built in \n`file://` (which provides access to configs in the file system) and \n`pkg://` (which provides access to configs installed with a Python package) \n\nThis config source hard codes all the responses so it's not very useful.\nPlease base your tests on the data in hydra_root/tests/test_apps/config_source_test/dir.\n\nAll config sources need to pass the ConfigSourceTestSuite tests, which are expecting those specific responses.\nWhen implementing a new config source, be sure to run it through the test suite to ensure it always behaves the same\nas the other config sources.\n\n\n# Hydra example plugin\nthis plugin is not very useful, but demonstrates the plugin discovery capability of Hydra.\n\nCore plugins (Plugins that are developed jointly with Hydra) lives in the plugins subdirectory inside the Hydra repo.\nThird party plugins can live anywhere (public or private Github repos, Organizations in-house SCM etc)\n\n\n# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Launcher for Hydra.\nThe configuration for this launcher is in packages with the plugin:\n\n```yaml title=\"hydra_plugins/example_launcher_plugiun/conf/hydra/launcher/example.yaml\"\n_target_: hydra_plugins.example_launcher_plugin.example_launcher.ExampleLauncher\nfoo: 10\nbar: abcde\n```\nThe example application is overriding the Launcher used by Hydra.\nWhen the launcher is initialized, its \"using\" the foo and bar parameters.\n\nOutput of the example application:\n```text\n$ python example/my_app.py --multirun db=postgresql,mysql\n[2019-10-22 19:45:05,060] - Example Launcher(foo=10, bar=abcde) is launching 2 jobs locally\n[2019-10-22 19:45:05,060] - Sweep output dir : multirun/2019-10-22/19-45-05\n[2019-10-22 19:45:05,060] - #0 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n\n[2019-10-22 19:45:05,135] - #1 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n```\n\n\n# Hydra example plugin via `Plugins.register`\nThis plugin is not very useful, but it demonstrates how to register a plugin using the `Plugins.register` method.\n\n\n# Hydra example SearchPath plugin\n\nThis plugin provides an example for how to write a SearchPathPlugin that can manipulate the search path.\nTypical use cases includes:\n * A framework that wants to allow user code to discover its configurations and be able to compose with them.\n * A plugin that wants to extend Hydra or another plugin by providing additional configs in existing config groups like `hydra/launcher`.\n * A plugin that can replace the default configuration of another plugin or of Hydra itself by prepending its configurations before those that it want to replace.\n \nSearchPath plugins are discovered and enabled automatically once they are installed.\nYou can use `python foo.py --info` to see the search path and the installed plugins.\n\n\n# Hydra example Launcher plugin\n\nThis plugin provides an example for how to write a custom Sweeper for Hydra.\nThe provided example has a custom configuration for the sweeper that takes overrides a few parameters:\n```yaml\n_target_: hydra_plugins.example_sweeper_plugin.example_sweeper.ExampleSweeper\n# max number of jobs to run in the same batch.\nmax_batch_size: null\nfoo: 10\nbar: abcde\n```\n\n#### Example app using custom sweeper:\n```text\n$ python example/my_app.py -m db=mysql,postgresql\n[2019-11-14 11:42:47,941][HYDRA] ExampleSweeper (foo=10, bar=abcde) sweeping\n[2019-11-14 11:42:47,941][HYDRA] Sweep output dir : multirun/2019-11-14/11-42-47\n[2019-11-14 11:42:47,942][HYDRA] Launching 2 jobs locally\n[2019-11-14 11:42:47,942][HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[2019-11-14 11:42:48,011][HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n```\n\n\n# Hydra Ax Sweeper\nProvides a [`Ax Sweeper`](https://ax.dev/) based Hydra Sweeper supporting parallel execution.\n\nHydra 1.4 will include the final first-party release, based on the existing\nimplementation. The plugin code will be removed in the Hydra 1.5 line, and no\nfirst-party releases will be published for Hydra 1.5 or later. Existing PyPI\nreleases will remain available. See the [retirement issue](https://github.com/hydra-ecosystem/hydra/issues/3506)\nfor the schedule and invitation for community ownership in a separate repository.\n\nSee [website](https://hydra.cc/docs/plugins/ax_sweeper/) for more information\n\n\n# Hydra colorlog\nAdds colorlog colored logs for `hydra/job_logging` and `hydra/hydra_logging`.\n\nSee [website](https://hydra.cc/docs/plugins/colorlog) for more information\n\n\n# Hydra Joblib Launcher\nProvides a [`Joblib.Parallel`](https://joblib.readthedocs.io/en/latest/parallel.html) based Hydra Launcher supporting parallel execution.\n\nSee [website](https://hydra.cc/docs/plugins/joblib_launcher) for more information\n\n\n# Hydra Nevergrad Sweeper plugin\n\nProvides a mechanism for Hydra applications to use [Nevergrad](https://github.com/facebookresearch/nevergrad) algorithms for the optimization of the parameters of any experiment.\n\nSee [website](https://hydra.cc/docs/plugins/nevergrad_sweeper) for more information\n\n\n# Hydra Optuna Sweeper\n\nProvides an [Optuna](https://optuna.org) based Hydra Sweeper.\n\nSee [website](https://hydra.cc/docs/plugins/optuna_sweeper/) for more information.\n\n\n## Setting up a new testing AMI for ray launcher.\n\nTo run the tool:\n\n- Make sure the dependencies in `setup_integration_test_ami.py` matches exactly ray launcher's `setup.py`.\n- Install AWS CLI, check AWS documentation for more details.\n- Before running the tool, set up your aws profile with admin access to the Hydra test AWS account.\n```\nAWS_PROFILE=jieru python create_integration_test_ami.py\n```\nYou will see a new AMI created in the output\n```commandline\nec2.Image(id='ami-0d65d5647e065a180') current state pending\n...\n```\nSometimes it could take hours for a new AMI to be created. Proceed to the next step once the \nAMI becomes available.\n\n- Run the tests locally with the new AMI:\n ```shell\n AWS_RAY_AMI= pytest ../tests/ray_aws_launcher_tests_disabled.py\n ```\n- Debug if needed.\n- Create a PR and make sure all CI pass!\n\n\n# Hydra Ray Launcher\nProvides a [`Ray`](https://docs.ray.io/en/latest/) based Hydra Launcher supporting execution on AWS.\n\nSee [website](https://hydra.cc/docs/plugins/ray_launcher) for more information\n\n\n# Hydra RQ Launcher\nProvides a [Redis Queue (RQ)](https://python-rq.org) launcher for Hydra supporting distributed execution and job queuing.\n\nSee [website](https://hydra.cc/docs/plugins/rq_launcher) for more information\n\n\n# Hydra Submitit Launcher\nProvides a [`Submitit`](https://github.com/facebookincubator/submitit) based Hydra Launcher supporting [SLURM ](https://slurm.schedmd.com/documentation.html).\n\nSee [website](https://hydra.cc/docs/plugins/submitit_launcher) for more information\n\n\n# configen\n\nAutomatically generates Structured Configs that can be used with hydra.utils.instantiate()\n\nThis is optional at two levels:\n1. Structured Configs are optional, one can use Hydra without them.\n2. One can manually code these dataclasses. The advantage of this tool is that it does the work automatically.\n\n# Setup\nConfigen requires config file per project. The config indicates what classes to generate code for, where to put\nthe generated code etc.\nConfigen will suggest creating a config on the first run:\n```\n$ configen\n[2020-08-14 12:06:11,359][configen.configen][ERROR] -\nUse --config-dir DIR --config-name NAME\ne.g:\n\tconfigen --config-dir conf --config-name configen\n\nIf you have no config dir yet use init_config_dir=DIR to create an initial config dir.\ne.g:\n\tconfigen init_config_dir=conf\n```\n\nThis will generate a basic config similar to:\n```yaml\n$ cat conf/configen.yaml\ndefaults:\n - configen_schema\n - _self_\n\nconfigen:\n # output directory\n output_dir: ${hydra:runtime.cwd}/example\n\n header: |\n # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n # Generated by configen, do not edit.\n # See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n # fmt: off\n # isort:skip_file\n # flake8: noqa\n\n module_path_pattern: 'config/{{module_path}}.py'\n\n # list of modules to generate configs for\n modules:\n - name: configen.samples.my_module\n # for each module, a list of classes\n classes:\n - User\n - Admin\n```\n\nConfigen comes with a few samples [classes](configen/samples) that are being processed by the default config.\nFor example:\n```python title=\"configen/samples/my_module.py\"\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n\n\nclass User:\n def __init__(self, age: int, name: str):\n self.age = age\n self.name = name\n\n def __repr__(self):\n return f\"User: name={self.name}, age={self.age}\"\n\n\nclass Admin(User):\n def __init__(self, private_key: str, age: int, name: str) -> None:\n super().__init__(age, name)\n self.private_key = private_key\n\n def __repr__(self):\n return (\n f\"Admin: name={self.name}, age={self.age}, private_key={self.private_key}\"\n )\n```\n\nRunning configen with this config directory:\n```\n$ configen --config-dir conf --config-name configen\n[2020-08-14 12:44:54,990][configen.configen][INFO] - configen.samples.my_module.configen.samples.my_module -> /home/omry/tmp/configen/example/config/configen/samples/my_module.py\n```\n\nWill result in a file `example/config/configen/samples/my_module.py` like:\n```python\n# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved\n# Generated by configen, do not edit.\n# See https://github.com/hydra-ecosystem/hydra/tree/main/tools/configen\n# fmt: off\n# isort:skip_file\n# flake8: noqa\n\nfrom dataclasses import dataclass, field\nfrom omegaconf import MISSING\n\n\n@dataclass\nclass UserConf:\n _target_: str = \"configen.samples.my_module.User\"\n age: int = MISSING\n name: str = MISSING\n\n\n@dataclass\nclass AdminConf:\n _target_: str = \"configen.samples.my_module.Admin\"\n private_key: str = MISSING\n age: int = MISSING\n name: str = MISSING\n```\n\nThe generated code can be used by a Hydra application to instantiate the user object.\nSee the [example application](example/my_app.py).\n\n\n# Hydra Landscape tools\n\nThese tools support discovery, analysis, review, and publication of projects in\nthe [Hydra Landscape](../../website/docs/landscape.mdx). They do not approve\nprojects automatically. Inclusion and featured status are maintainer decisions.\n\nThe tracked files under this directory are reusable tooling and durable human\ndecisions. Large crawls, AI output, refreshed GitHub metadata, and generated\nreview queues remain under `temp/hydra-dependents/`.\n\nInstall the Python 3.10 compatibility dependency when needed:\n\n```bash\n.venv/bin/pip install -r tools/landscape/requirements.txt\n```\n\n`data/decisions.json` is the canonical source for both curation decisions and\nthe public listing of every included project. Do not edit\n`website/src/data/landscape.json` directly; website commands regenerate it from\nthe decision ledger.\n\n## Pipeline\n\n1. Collect mechanical Hydra usage evidence from the dependency crawl:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_usage.py\n ```\n\n2. Route projects for review, optionally using the locally authenticated Codex\n CLI to analyze a resumable batch:\n\n ```bash\n .venv/bin/python tools/landscape/analyze_hydra_projects.py\n .venv/bin/python tools/landscape/analyze_hydra_projects.py --ai\n ```\n\n Analyze explicit repositories with repeated `--repo owner/name` arguments.\n The default AI model is `gpt-5.6-terra` with medium reasoning effort.\n\n3. Refresh current GitHub maintenance metadata:\n\n ```bash\n .venv/bin/python tools/landscape/refresh_landscape_metadata.py\n ```\n\n4. Build the evidence-backed human review queue:\n\n ```bash\n .venv/bin/python tools/landscape/build_landscape_review.py\n ```\n\n5. Record maintainer decisions in `data/decisions.json`. Every included\n decision must contain its complete public `listing`. Regenerate the public\n data directly when needed:\n\n ```bash\n .venv/bin/python tools/landscape/build_public_landscape.py\n ```\n\nThe public generator reads no crawl, AI, review, or live GitHub data. It writes\n`website/src/data/landscape.json` deterministically from the decision ledger.\nThe website's `start`, `build`, and `deploy` commands run it automatically.\n\n## Tests\n\nRun the focused suite with:\n\n```bash\nPYTHONPATH=tools/landscape .venv/bin/pytest tools/landscape\n```\n\n\nStandalone Hydra related tools\n\n\n"}