https://hydra.cc/assets/js/d8462e79.c45f8d03.js

1"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2846],{48903(e,n,i){i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>t,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"advanced/terminology","title":"Terminology","description":"This page describes some common concepts in Hydra, most of which are covered in greater details throughout the documentation.","source":"@site/versioned_docs/version-1.1/advanced/terminology.md","sourceDirName":"advanced","slug":"/advanced/terminology","permalink":"/docs/1.1/advanced/terminology","draft":false,"unlisted":false,"editUrl":"https://github.com/hydra-ecosystem/hydra/edit/main/website/versioned_docs/version-1.1/advanced/terminology.md","tags":[],"version":"1.1","frontMatter":{"id":"terminology","title":"Terminology"},"sidebar":"docs","previous":{"title":"Optuna Sweeper plugin","permalink":"/docs/1.1/plugins/optuna_sweeper"},"next":{"title":"Hydra\'s command line flags","permalink":"/docs/1.1/advanced/hydra-command-line-flags"}}');var a=i(11684),o=i(32435);const r={id:"terminology",title:"Terminology"},t=void 0,c={},l=[{value:"Input Configs",id:"input-configs",level:2},{value:"Config files",id:"config-files",level:3},{value:"Structured Config",id:"structured-config",level:3},{value:"Other configs",id:"other-configs",level:2},{value:"Overrides",id:"overrides",level:2},{value:"Defaults List",id:"defaults-list",level:2},{value:"Config Group",id:"config-group",level:2},{value:"Config Group Option",id:"config-group-option",level:2},{value:"Package",id:"package",level:2},{value:"Package directive",id:"package-directive",level:3},{value:"Example of Core Concepts",id:"example-of-core-concepts",level:2},{value:"Output config",id:"output-config",level:3},{value:"Config Search Path",id:"config-search-path",level:2},{value:"Plugins",id:"plugins",level:2}];function d(e){const n={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsxs)(n.p,{children:["This page describes some common concepts in Hydra, most of which are covered in greater details throughout the documentation.\nExamples of many of the following concepts are in the ",(0,a.jsx)(n.a,{href:"#example-of-core-concepts",children:"Examples section"}),"."]}),"\n",(0,a.jsx)(n.h2,{id:"input-configs",children:"Input Configs"}),"\n",(0,a.jsxs)(n.p,{children:["Input configs are building blocks used to construct the ",(0,a.jsx)(n.a,{href:"#output-config",children:"Output Config"})," consumed by the application.\nThey can be grouped by placing them in ",(0,a.jsx)(n.a,{href:"#config-group",children:"Config Groups"}),"."]}),"\n",(0,a.jsx)(n.h3,{id:"config-files",children:"Config files"}),"\n",(0,a.jsxs)(n.p,{children:["Config files are form of input configs in ",(0,a.jsx)(n.a,{href:"https://yaml.org/",children:"YAML"})," format. They can exist in the file system or\nin a Python module."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",metastring:'title="Example config file',children:"user:\n  name: James Bond\n  age: 7\n"})}),"\n",(0,a.jsx)(n.h3,{id:"structured-config",children:"Structured Config"}),"\n",(0,a.jsx)(n.p,{children:"This term has two common meanings:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["A class decorated with ",(0,a.jsx)(n.a,{href:"https://docs.python.org/3/library/dataclasses.html",children:"@dataclass"})," or ",(0,a.jsx)(n.a,{href:"https://www.attrs.org/en/stable/",children:"@attr.s"}),", or an instance of such a class which is intended to be used as config."]}),"\n",(0,a.jsx)(n.li,{children:"A Config object initialized from a class or object as defined in 1. Structured Configs provide additional type information that enables static and runtime type checking."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"The two primary patterns for using Structured Configs are:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["As an ",(0,a.jsx)(n.a,{href:"#input-configs",children:"Input Config"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"As a schema validating Config Files and command line arguments."}),"\n"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-python",metastring:'title="Example Schema"',children:"@dataclass\nclass User:\n  name: str\n  age: int\n"})}

1),"\n",(0,a.jsx)(n.h2,{id:"other-configs",children:"Other configs"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Primary Config"}),": The input config named in ",(0,a.jsx)(n.a,{href:"/docs/1.1/tutorials/basic/your_first_app/config_file",children:(0,a.jsx)(n.strong,{children:"@hydra.main()"})})," or in the ",(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/compose_api",children:(0,a.jsx)(n.strong,{children:"Compose API"})}),".\n",(0,a.jsx)(n.strong,{children:"Output Config"}),": A config composed from the ",(0,a.jsx)(n.a,{href:"#input-configs",children:"Input Configs"})," and ",(0,a.jsx)(n.a,{href:"#overrides",children:"Overrides"})," by ",(0,a.jsx)(n.strong,{children:"@hydra.main()"}),", or the Compose API."]}),"\n",(0,a.jsx)(n.h2,{id:"overrides",children:"Overrides"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/override_grammar/basic",children:"Overrides"})," are strings that can be used to manipulate the config composition process.\nThis includes updating, adding and deleting config values and ",(0,a.jsx)(n.a,{href:"#defaults-list",children:"Defaults List"})," options."]}),"\n",(0,a.jsxs)(n.p,{children:["Overrides can be used in the command line and in the ",(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/compose_api",children:"Compose API"}),".\nIn the examples below, ",(0,a.jsx)(n.code,{children:"key=value"})," is an override:"]}),"\n",(0,a.jsxs)("div",{className:"row",children:[(0,a.jsx)("div",{className:"col col--6",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-shell",metastring:'title="Override in the command line"',children:"$ python my_app.py key=value\n\n"})})}),(0,a.jsx)("div",{className:"col col--6",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-python",metastring:'title="Override used in the Compose API"',children:'cfg = compose(config_name,\n              overrides=["key=value"])\n'})})})]}),"\n",(0,a.jsx)(n.h2,{id:"defaults-list",children:"Defaults List"}),"\n",(0,a.jsxs)(n.p,{children:["A list in an ",(0,a.jsx)(n.a,{href:"#input-configs",children:"Input Config"})," that instructs Hydra how compose the config."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",metastring:'title="Defaults List in a YAML config"',children:"defaults:\n  - db: mysql      # An overridable defaults list entry\n  - schema/school  # A non-overridable defaults list entry\n"})}),"\n",(0,a.jsx)(n.h2,{id:"config-group",children:"Config Group"}),"\n",(0,a.jsxs)(n.p,{children:["A Config Group is directory in the ",(0,a.jsx)(n.a,{href:"#config-search-path",children:"Config Search Path"})," that contains ",(0,a.jsx)(n.a,{href:"#input-configs",children:"Input Configs"}),".\nConfig Groups can be nested, and in that case the path elements are separated by a forward slash ('/') regardless of the operating system."]}),"\n",(0,a.jsx)(n.h2,{id:"config-group-option",children:"Config Group Option"}),"\n",(0,a.jsx)(n.p,{children:"An Input Config in a Config Group. When used in a Defaults List, a Config Group Option can be a single Input Config, or a list of Input Configs from the same Config Group."}),"\n",(0,a.jsx)(n.h2,{id:"package",children:"Package"}),"\n",(0,a.jsxs)(n.p,{children:["A Package is the path to node in a config. By default, the Package of a Config Group Option is derived from the Config Group.\n",(0,a.jsx)(n.em,{children:"e.g:"})," Configs in ",(0,a.jsx)(n.strong,{children:"mi6/agent"})," will have the package ",(0,a.jsx)(n.strong,{children:"mi6.agent"})," by default."]}),"\n",(0,a.jsx)(n.h3,{id:"package-directive",children:"Package directive"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/overriding_packages#overriding-the-package-via-the-package-directive",children:"Package Directive"})," specifies the root ",(0,a.jsx)(n.a,{href:"#package",children:"Package"})," of a ",(0,a.jsx)(n.a,{href:"#input-configs",children:"Config File"}),". It can appear at the top of YAML config file."]}),"\n",(0,a.jsx)(n.h2,{id:"example-of-core-concepts",children:"Example of Core Concepts"}),"\n",(0,a.jsx)(n.h3,{id:"output-config",children:"Output config"}),"\n",(0,a.jsxs)("div",{className:"row",children:[(0,a.jsx)("div",{className:"col col--4",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",metastring:'title="config.yaml"',children:"defaults:\n - mi6/agent: james_bond\n\n"})})}),(0,a.jsx)("div",{className:"col col--4",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",metastring:'title="mi6/agent/james_bond.yaml" {1}',children:"# @package bond.james\ncodename: '007'\n\n"})})}),(0,a.jsx)("div",{className:"col col--4",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",metastring:'title="Output config" {1,2}',children:"bond:\n  james:\n    codename: '007'\n"})})})]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"#input-configs",children:"Input Configs"}),": ",(0,a.jsx)(n.strong,{children:"config.yaml"}),", ",(0,a.jsx)(n.strong,{children:"mi6/agent/james_bond.yaml"})]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"#config-group",children:"Config Group"}),": mi6/agent"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"#config-group-option",children:"Config Group Option"}),": james_bond"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"#package",children:"Packages"}),": ",(0,a.jsx)(n.strong,{children:"<empty>"}),", ",(0,a.jsx)(n.strong,{children:"mi6"}),", ",(0,a.jsx)(n.strong,{children:"mi6.agent"}),", ",(0,a.jsx)(n.strong,{children:"mi6.agent.codename"})]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"#package-directive",children:"Package directive"}),": ",(0,a.jsx)(n.strong,{children:"# @package bond.james"}),", overriding the default Package for the containing Input Config"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"config-search-path",children:"Config Search Path"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/search_path",children:"Config Search Path"})," is a list of paths that are searched in order to find configs. It is similar to\nthe Python ",(0,a.jsx)(n.a,{href:"https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH",children:"PYTHONPATH"}),"."]}),"\n",(0,a.jsx)(n.h2,{id:"plugins",children:"Plugins"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.a,{href:"/docs/1.1/advanced/plugins/overview",children:"Plugins"})," extend Hydra's capabilities. Hydra has several plugin types, for examples Launcher and Sweeper."]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},32435(e,n,i){i.d(n,{R:()=>r,x:()=>t});var s=i(12888);const a={},o=s.createContext(a);function r(e){const n=s.useContext(o);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function t(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);